Testing

The emulator is a plain HTTP server, so it works with every WorkOS SDK – point the SDK’s base URL at the emulator instead of https://api.workos.com.

# Homebrew (macOS and Linux)
brew install workos/tap/workos-emulate

# npm, for JavaScript projects
npm install --save-dev @workos/emulate

# or run without installing
npx @workos/emulate

Self-contained binaries for macOS, Linux, and Windows are also attached to each GitHub release.

workos-emulate --seed workos-emulate.config.yaml

The emulator listens on http://localhost:4100 and accepts the API key sk_test_default by default. Use GET /health as a readiness check when starting it in the background:

workos-emulate --seed workos-emulate.config.yaml &
curl --retry 10 --retry-connrefused -fsS http://localhost:4100/health

Override the SDK’s base URL in your test configuration and use the SDK as normal, so that requests hit the emulator instead of the real API.

import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_test_default', {
  apiHostname: 'localhost',
  port: 4100,
  https: false,
});

The same pattern works for any language with a WorkOS SDK, as all of them expose a base URL override.

Tests should not depend on state left behind by earlier runs. Declare the users, organizations, roles, and permissions your tests need in a seed file, and the emulator recreates that exact world on every boot:

users:
  - email: alice@acme.com
    first_name: Alice
    password: test123
    email_verified: true

organizations:
  - name: Acme Corp
    domains:
      - domain: acme.com
        state: verified
    memberships:
      - email: alice@acme.com
        role: admin
        status: active

roles:
  - slug: admin
    name: Admin
    permissions: [posts:read, posts:write]

permissions:
  - slug: posts:read
    name: Read Posts
  - slug: posts:write
    name: Write Posts

Both organizations and users accept an optional id. Pin ids to match what your real WorkOS environment emits, so a backend whose database already references a real organization or user id lines up with the emulator – and stays stable across restarts.

For JavaScript test suites, createEmulator starts an emulator in-process on a random port, so parallel test files never collide:

import { createEmulator } from '@workos/emulate';

const emulator = await createEmulator({
  port: 0,
  seed: {
    users: [{ email: 'test@example.com', password: 'secret' }],
  },
});

// emulator.url and emulator.apiKey configure the code under test

emulator.reset(); // clear state between tests
await emulator.close();

Error hooks force the emulator to return non-200 responses so you can test how your app handles any rare WorkOS API failures. Register them in the seed file, over HTTP at runtime, or programmatically:

# Make user creation fail with a 422
curl -X POST http://localhost:4100/_emulate/hooks \
  -H "Content-Type: application/json" \
  -d '{"method":"POST","path":"/user_management/users","status":422}'

// Fail the first 3 requests, then let them through — exercises retry logic
emulator.addErrorHook({
  method: 'POST',
  path: '/user_management/users',
  status: 503,
  count: 3,
});

Hooks match a method and path (exact, prefix wildcard like /user_management/*, or *), return a status of your choosing with an optional custom body, and can auto-remove after count uses.

Register a webhook endpoint and every resource creation and authentication outcome fires a signed webhook, exactly like production – WorkOS-Signature: t=<timestamp>,v1=<hmac>, verifiable with the official SDKs’ constructEvent unchanged.

webhookEndpoints:
  - endpoint_url: http://localhost:5005/webhooks
    events: [] # an empty list subscribes to everything

Codes that WorkOS would deliver by email arrive in the webhook payload instead: magic_auth.created carries the Magic Auth code, password_reset.created the reset token, and email_verification.created the verification code. Your test can drive an entire login flow from webhooks alone, with no email provider in the loop.

Delivery is fire-and-forget with no retries, so poll your receiver in tests rather than asserting immediately. All events can also be queried at GET /events (filter with ?events[]=user.created).

By default the authorize endpoints immediately redirect back to your callback with a code – ideal for API-level tests. For browser tests, pass --interactive and the emulator serves a real login page instead:

test('sign-in flow', async ({ page }) => {
  await page.goto('http://localhost:3000/login');
  await page.click('text=Sign in');

  // The emulator serves the login page
  await page.fill('input[name="email"]', 'alice@acme.com');
  await page.click('button[type="submit"]');

  // Redirected back to your app with a valid session
  await expect(page).toHaveURL(/dashboard/);
});

This works in headless browsers and requires no dashboard configuration or real identity provider.

WorkOS tests AuthKit itself – the hosted UI, the token issuance, the protocol plumbing. Your job is the integration seam: the routes, session handling, and authorization logic you wrote. Focus your coverage there.

The OAuth callback is the front door of your integration. Verify that a valid code is exchanged for a session and the user lands where you expect:

• WorkOS can redirect back with an error parameter instead of a code (for example, when a user cancels). Your callback should show something sensible, not a stack trace.
• If you pass state, assert that a missing or tampered value is rejected.

Sessions fail in ways that only show up over time, so simulate time passing instead of waiting for it:

• An expired access token triggers a refresh and the request succeeds transparently.
• Your app stores the new refresh token after every refresh. Refresh tokens may rotate in production; the emulator always rotates them and invalidates the old one, so a client that keeps using a stale token fails locally instead of in production.
• Logout clears your session state and revokes the WorkOS session, not just one of the two.

Test your middleware or route guards from both sides: an unauthenticated request to a protected route is redirected or rejected, an authenticated request passes, and public routes stay public. These tests are cheap and catch the most embarrassing class of bug – a route that silently lost its protection.

If your app reads role, permissions, or custom claims from the access token, test the decisions your code makes with them:

• A user with the right permission gets through; one without it is denied.
• Users who belong to multiple organizations receive the organization_selection_required response – verify your app completes the selection flow instead of failing. The emulator reproduces this exactly as production does.
• If you use JWT templates, seed the same template into the emulator and assert your code reads the custom claims correctly.

Webhook endpoints are publicly reachable, so their tests are security tests:

• A request with a missing, malformed, or wrongly-signed WorkOS-Signature header is rejected.
• The same event delivered twice does not double-apply – deliveries are at-least-once, so handlers must be idempotent.
• Events arriving out of order (an organization_membership.updated before the user.created your handler expects) don’t crash or corrupt state.

The WorkOS API will occasionally be slow or unavailable, and your app’s behavior at that moment is a product decision worth pinning down in a test. Use error hooks to force each case:

• A 5xx or timeout during token refresh must not destroy the session – treat it as transient and retry, reserving sign-out for a terminal invalid_grant. See session resilience for the full pattern.
• Rate limits (429) and outages (503) are retried with backoff where you expect them to be.
• Validation errors (422) surface actionable feedback to the user rather than a generic failure.

The emulator covers unit, integration, and local end-to-end tests. For a final staging pass against the real API, you can set up a dedicated environment:

• Create a separate WorkOS environment for staging or CI so test data can’t leak into production and API keys stay scoped.
• Seed it from a declarative YAML file with workos seed in the WorkOS CLI, which can also tear everything down cleanly afterwards.
• Keep credentials in your CI secret store – sandbox API keys are still secrets.