Mock Mode

Why mock mode exists

Mock mode lets you iterate on the WhatsApp Web Server API, WebSocket flows, and UI integrations without scanning QR codes or managing WhatsApp sessions. Behind the scenes a Mock Service Worker (MSW) server stands in for the Evolution API and serves deterministic responses for the endpoints used during development.

Use it when you need to:

• Demo product flows without real devices
• Develop or debug front-end features asynchronously
• Capture logs or experiment with API changes without touching production accounts

Running with MSW handlers

cd apps/whatsapp-web-server
pnpm dev

You’ll be prompted with an interactive menu to select between:

• Real Evolution API — connects to the actual Evolution API service
• Mock Evolution API — uses MSW handlers for local development

Use arrow keys to navigate and press Enter to confirm your selection.

During startup in mock mode, you should see the banner Evolution API mock mode ENABLED confirming that MSW handlers are active. Requests continue to use fetch under the hood, but are intercepted by the worker so no real Evolution API calls are made.

Handler coverage

Handlers exist for the instance, profile, message, reaction, audio, sticker, contact, and group APIs commonly needed for manual testing. Each handler registers itself with the mock registry. When USE_EVOLUTION_MOCK=true, the fetch helper checks this registry and throws a descriptive error if you call an endpoint that is missing a mock handler. That safeguard prevents silent fallbacks to the real Evolution API while keeping existing mocked endpoints functional.

If you add a new Evolution API endpoint, define its MSW handler in apps/whatsapp-web-server/src/mocks/handlers.ts. The helper will register it automatically so that mock mode continues to work.

Switching between real and mock modes

The unified pnpm dev command presents an interactive menu on startup:

1. Run pnpm dev in the whatsapp-web-server directory
2. Select your desired mode using arrow keys
3. Press Enter to start the server

You can also force a specific mode by setting the environment variable:

• USE_EVOLUTION_MOCK=false — forces real Evolution API mode (bypass interactive prompt)
• USE_EVOLUTION_MOCK=true — forces mock mode (bypass interactive prompt)

Mock mode is automatically disabled when NODE_ENV=production even if the environment variable is set.

To change modes, stop the running process (Ctrl+C) and restart pnpm dev to select a different option.

Troubleshooting checklist

• Seeing network calls to the real API? Ensure the banner prints on startup and confirm USE_EVOLUTION_MOCK resolves to true.
• Getting Missing Evolution API mock handler errors? Add or update the corresponding handler in src/mocks/handlers.ts so the registry can validate it.
• Responses look stale? Restart pnpm dev:mock to reset in-memory mock state within the MSW server.

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 the live Evolution API before shipping changes.