CI/CD Testing

Run Wocha auth tests in CI with the offline emulator, test-mode API keys, and @wocha/testing

Wocha supports fully automated auth testing in CI pipelines without touching production tenants or live user data. Combine the offline auth emulator, test-mode API keys, and @wocha/testing utilities for reliable, repeatable builds.

Overview

Approach	Best for	Requires cloud
`wocha emulator`	OAuth flows, SDK integration tests, E2E	No
`wocha_test_` API keys	Customer API / management SDK tests against cloud	Yes (sandboxed)
`@wocha/testing`	Unit tests, component tests, webhook fixtures	No

Most teams use the emulator for auth flow tests and test-mode keys when CI must exercise the real Customer API.

Quick start: emulator in CI

The auth emulator runs entirely on the CI runner — no Docker, no internet, no cloud credentials.

# Start the emulator in the background
npx @wocha/cli emulator --port 4400 &
EMULATOR_PID=$!
 
# Point your app/tests at the emulator
export WOCHA_EMULATOR=true
export WOCHA_EMULATOR_URL=http://127.0.0.1:4400
export WOCHA_CLIENT_ID=wocha-emulator
export WOCHA_CLIENT_SECRET=wocha-emulator-secret-local-only
export WOCHA_ISSUER=http://127.0.0.1:4400
 
# Run your test suite
npm test
 
# Tear down
kill $EMULATOR_PID

Pre-seeded credentials:

Email: test@example.com
Password: password123

GitHub Actions example

name: Auth tests
 
on:
  push:
    branches: [main]
  pull_request:
 
jobs:
  test:
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
 
      - run: npm ci
 
      - name: Start Wocha auth emulator
        run: |
          npx @wocha/cli emulator --port 4400 &
          echo "EMULATOR_PID=$!" >> $GITHUB_ENV
          for i in {1..30}; do
            curl -sf http://127.0.0.1:4400/api/v1/health && break
            sleep 1
          done
 
      - name: Run tests
        env:
          WOCHA_EMULATOR: "true"
          WOCHA_EMULATOR_URL: http://127.0.0.1:4400
          WOCHA_CLIENT_ID: wocha-emulator
          WOCHA_CLIENT_SECRET: wocha-emulator-secret-local-only
          WOCHA_ISSUER: http://127.0.0.1:4400
        run: npm test
 
      - name: Stop emulator
        if: always()
        run: kill $EMULATOR_PID || true

See GitHub Actions integration for a reusable composite action and matrix testing across frameworks.

Using `@wocha/testing`

Install the testing utilities in your dev dependencies:

npm install -D @wocha/testing

Mock provider for React / Next.js

Wrap components under test with a mock auth context — no network calls required:

import { render, screen } from "@testing-library/react";
import { GreetTestingProvider } from "@wocha/testing";
 
test("shows dashboard for signed-in user", () => {
  render(
    <GreetTestingProvider user={{ id: "user_1", email: "test@example.com" }}>
      <Dashboard />
    </GreetTestingProvider>,
  );
 
  expect(screen.getByText(/welcome/i)).toBeInTheDocument();
});

Playwright / Cypress

Use session helpers to seed authenticated browser state without walking through OAuth on every test:

import { createTestingSession } from "@wocha/testing/playwright";
 
test("authenticated page", async ({ page, context }) => {
  await createTestingSession(context, {
    user: { id: "user_1", email: "test@example.com" },
  });
  await page.goto("/dashboard");
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
});

Webhook fixtures

Generate signed webhook payloads for handler unit tests:

import { generateWebhookFixture } from "@wocha/testing";
 
const fixture = generateWebhookFixture("user.created", {
  user_id: "user_123",
  email: "test@example.com",
});
 
// POST fixture.body to your handler with fixture.headers

Test-mode API keys in CI

Test-mode keys use the wocha_test_ prefix and are automatically scoped to your tenant's test environment. They cannot access live production data.

Create a test key

Via the Console → Settings → API Keys, choose Test mode when creating a key.

Via the Customer API:

curl -X POST "https://YOUR_TENANT.api.wocha.ai/v1/api-keys" \
  -H "Authorization: Bearer wocha_mgmt_YOUR_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI pipeline", "mode": "test", "scopes": ["users:read", "users:write"]}'

Store the returned wocha_test_… value as a CI secret (e.g. WOCHA_TEST_API_KEY).

Use in CI

- name: Run management API integration tests
  env:
    WOCHA_API_KEY: ${{ secrets.WOCHA_TEST_API_KEY }}
    WOCHA_TENANT_URL: https://your-tenant.wocha.ai
  run: npm run test:api

Test keys set testMode: true on the request context server-side, ensuring mutations and reads stay within the test environment.

Environment variable reference

Variable	Description
`WOCHA_EMULATOR`	Set to `true` to route SDK auth to the local emulator
`WOCHA_EMULATOR_URL`	Emulator base URL (default: `http://127.0.0.1:4400`)
`WOCHA_CLIENT_ID`	OAuth client ID (`wocha-emulator` for the CLI emulator)
`WOCHA_CLIENT_SECRET`	OAuth client secret
`WOCHA_ISSUER`	Overridden automatically when emulator mode is active
`WOCHA_TEST_API_KEY`	Convention for storing a `wocha_test_` key in CI secrets

Recommendations

Prefer the emulator for OAuth and SDK flow tests — it is faster and requires no secrets.
Use test-mode keys when CI must validate against the real Customer API (webhooks, org management, etc.).
Never commit secrets — use your CI provider's secret store for wocha_test_ and wocha_mgmt_ keys.
Wait for health — poll /api/v1/health before running tests against the emulator.
Isolate test data — test keys are scoped to the test environment; keep live keys out of CI entirely.

CI/CD Testing

On this page