Skip to main content
O @zapo-js/fake-server é um servidor WhatsApp Web falso in-process que fala Noise XX/IK, X3DH + Double Ratchet, SenderKey de grupo, sincronização de app-state e upload/download de mídia sobre HTTPS auto-assinado — tudo o que um client conforme real vê no wire. Ele existe para você testar seu app end-to-end sem tocar no WhatsApp: sem número real ocupado, sem risco pra conta de produção, sem flakiness de rede real, CI-friendly.
Este guia tem como público autores de app — bots, CRMs, serviços de notificação, integrações — independente de a lib WhatsApp abaixo ser zapo-js, Baileys, whatsmeow ou outro client conforme. Para o uso interno da lib (suíte cross-check, benchmarks) veja Dev tools.

Funciona com qualquer lib WhatsApp

O fake server é uma implementação em nível de wire do protocolo WhatsApp. Não tem dependência de runtime em zapo-js — fala os mesmos bytes de Noise / Signal / app-state que os edges do próprio WhatsApp. Clients estritos (forks de Baileys, whatsmeow, entre outros) funcionam contra ele de saída:
  • A cadeia de cert Noise define notBefore / notAfter para clients que validam validade aceitarem como não-expirado.
  • O IQ de passive-set e a query <count> de prekey no encrypt são respondidos por default (clients não-zapo bloqueiam nos dois).
  • Após todo login o server envia <ib><offline count="0"/></ib> para clients de evento bufferizado darem flush.
  • Ids de mensagem do FakePeer são hex WA-style — sem @ que decoders binários estritos tokenizariam como JID.
Se seu app roda contra um edge WA real, deve rodar contra o falso trocando só URL / cert.

Instalação

zapo-js é peer dependency do fake server (importa as primitivas de Noise / Signal / crypto / proto por baixo em runtime), então precisa estar presente na árvore mesmo quando seu app é construído em cima de outra lib WhatsApp. Node.js >= 20.9.0.

Início rápido (programático)

A ligação zapo-js abaixo é como um app zapo-js se parece; para Baileys / whatsmeow, mantenha seu setup de client existente e sobrescreva apenas a URL do socket, o proxy de mídia e o Noise root CA para apontar pro fake server.
testHooks.noiseRootCa confia no certificado do fake server sem burlar a verificação — a checagem completa da cadeia continua rodando.

Simulando um peer

createFakePeer te dá um contato simulado com cripto Signal real. Empurre mensagens pro seu client com sendConversation / sendGroupConversation, e capture o que o seu client envia com expectMessage:
O peer executa um handshake X3DH real, faz ratchet a cada mensagem e valida MACs — então um bug no seu handling Signal aparece do mesmo jeito que apareceria contra o próprio WhatsApp.

Validando stanzas outbound

Para asserts que não precisam do ponto de vista de um peer (um <presence> que seu app enviou, um <receipt> que ele ackeou, um IQ que ele fez) inscreva-se em stanzas capturadas:
onCapturedStanza retorna uma função de unsubscribe; chame em afterEach para manter os testes isolados.

Isolamento multi-sessão

Rode muitas instâncias de app contra um único server sem cross-talk. Forneça um resolver sessionKey — o fake server roteia cada conexão autenticada pro próprio FakeServerSession (peers, grupos, prekeys, app-state, stanzas capturadas isolados):
O resolver roda uma vez por conexão, logo após a autenticação, então info.clientPayload está disponível para chavear por identidade de login. Handlers server-wide (server.registerIqHandler) continuam aplicando a toda sessão; os escopados por sessão (session.registerIqHandler) ficam locais.

Config programática

FakeWaServer.start(options) aceita: onPipeline(listener) fanout pra múltiplos subscribers e retorna uma função de unsubscribe; o clientPayload parseado da pipeline é exposto em WaFakeConnectionPipeline pra checagens de identidade. IQ handlers podem retornar null pra fall through pro próximo handler que casa (observe-then-delegate).

CLI standalone

O pacote traz um binário fake-wa-server. Rode uma vez que a dev dep estiver instalada:
O modo --pair <jid> conduz o pareamento QR pedindo no stdin o payload QR que o client mostra — pareie uma vez, depois reconecte contra o mesmo fake server para iterar.

Recipe de CI

Suba um server por arquivo de teste (ou por suíte), derrube no final. Providers memory no client mantêm cada teste hermético:
Combine o fake server com stores in-memory no client. Cada teste reseta — sem estado de pareamento vazando, sem malabarismo de fixture em disco.

Veja também

Dev tools

Benchmarks, suíte cross-check e o MCP dev-server — tooling interno da lib.

README do fake server

Referência completa de CLI e superfície de API.
Última modificação em 24 de julho de 2026