Mock Mode

Why mock mode exists

Mock mode lets you build and validate product flows without a live WAHA backend or a paired WhatsApp device. When enabled, the server starts an in-process MSW interceptor that mocks WAHA HTTP endpoints with deterministic, relational fixtures.

Use it when you need to:

• Demo product flows without real devices
• Develop or debug front-end features asynchronously
• Validate webhook/SSE event handling with repeatable payloads

Enable mock mode

USE_WAHA_MOCK is the only mock-mode toggle.

cd apps/whatsapp-web-server
USE_WAHA_MOCK=true pnpm dev

Or use the dedicated script:

cd apps/whatsapp-web-server
pnpm dev:mock

On startup, you should see:

• WAHA mock mode ENABLED (USE_WAHA_MOCK=true)
• Mocking WAHA API host: ...

These logs confirm that WAHA requests are intercepted locally.

What is mocked

Mock handlers cover the WAHA endpoints used by whatsapp-web-server routes and middleware, including:

• Session lifecycle (/api/sessions, /api/sessions/:session, /api/:session/auth/qr)
• Chats and messages (/api/:session/chats, /api/:session/chats/:chatId/messages)
• Contacts and groups (/api/contacts/all, /api/:session/groups/:id)
• Send/mutate operations (sendText, sendImage, sendFile, sendVideo, sendVoice, reaction, mark-read, profile status)

Fixtures are hand-authored and deterministic (no random generation for core records), and stay relationally consistent across sessions, chats, contacts, groups, and messages.

Webhook and SSE simulation

State mutations emit webhook-shaped events through the existing webhook event store used by SSE subscribers. Simulated flow includes:

• session.status
• message.any
• message.ack
• message.reaction

This allows client SSE consumers to observe realistic event ordering without an external WAHA webhook source.

Automated checks

From repository root:

pnpm --filter whatsapp-web-server test:coverage

This includes Vitest coverage over:

• src/mocks/state.ts
• src/mocks/handlers.ts

For an end-to-end SSE order check (authenticated request flow):

pnpm --filter whatsapp-web-server e2e:sse:event-order -- --base-url http://localhost:3000 --account-number 0

The script subscribes to /webhooks/sse, sends a message, applies a reaction, and asserts event ordering for message.any, message.ack, and message.reaction.

It uses JWT_TOKEN from the environment when provided; otherwise, it generates a development JWT locally.

Strict unhandled-request policy

Unhandled requests to the configured WAHA host fail fast in mock mode.

If an endpoint is called without a mock handler, the server throws a descriptive error like:

Missing WAHA mock handler for <METHOD> <PATH>

Non-WAHA HTTP requests are not affected.

Switching back to real WAHA

Disable mock mode by setting:

• USE_WAHA_MOCK=false

or by omitting the variable entirely.

Troubleshooting checklist

• Missing handler error: add the endpoint handler to apps/whatsapp-web-server/src/mocks/handlers.ts.
• No SSE events: make sure your test action mutates state (send message, reaction, mark read, session lifecycle).
• State feels stale: restart pnpm dev:mock to reset in-memory state.

Files involved

• apps/whatsapp-web-server/src/mocks/fixtures.ts
• apps/whatsapp-web-server/src/mocks/state.ts
• apps/whatsapp-web-server/src/mocks/handlers.ts
• apps/whatsapp-web-server/src/mocks/webhooks.ts
• apps/whatsapp-web-server/src/mocks/setup.ts

Limitations

• Mock mode is meant for local development and manual QA; it is not packaged for production deployments.
• Failure scenarios such as timeouts or rate limiting are not simulated by default. Extend the MSW handlers if you need to rehearse those cases.
• Always verify critical workflows against live WAHA before shipping changes.