GitHub Actions

Pre-built GitHub Actions workflow for Wocha auth testing with the offline emulator and matrix framework support

This guide provides a reusable GitHub Actions pattern for running Wocha auth tests in CI. It starts the offline auth emulator, waits for readiness, runs your test suite, and tears down cleanly.

Composite action pattern

Create .github/actions/wocha-test/action.yml in your repository:

name: Wocha auth test setup
description: Start the Wocha auth emulator and export environment variables
 
inputs:
  port:
    description: Emulator listen port
    default: "4400"
  write-env:
    description: Write emulator vars to .env.local
    default: "false"
 
outputs:
  emulator-url:
    description: Base URL of the running emulator
    value: http://127.0.0.1:${{ inputs.port }}
 
runs:
  using: composite
  steps:
    - name: Start Wocha auth emulator
      shell: bash
      run: |
        npx @wocha/cli emulator --port ${{ inputs.port }} &
        echo "WOCHA_EMULATOR_PID=$!" >> $GITHUB_ENV
        echo "WOCHA_EMULATOR=true" >> $GITHUB_ENV
        echo "WOCHA_EMULATOR_URL=http://127.0.0.1:${{ inputs.port }}" >> $GITHUB_ENV
        echo "WOCHA_ISSUER=http://127.0.0.1:${{ inputs.port }}" >> $GITHUB_ENV
        echo "WOCHA_CLIENT_ID=wocha-emulator" >> $GITHUB_ENV
        echo "WOCHA_CLIENT_SECRET=wocha-emulator-secret-local-only" >> $GITHUB_ENV
 
        for i in {1..30}; do
          if curl -sf "http://127.0.0.1:${{ inputs.port }}/api/v1/health"; then
            echo "Emulator ready"
            exit 0
          fi
          sleep 1
        done
 
        echo "Emulator failed to start" >&2
        exit 1
 
    - name: Stop Wocha auth emulator
      if: always()
      shell: bash
      run: kill $WOCHA_EMULATOR_PID 2>/dev/null || true

Note: Composite actions cannot run background processes across steps. For production CI, use a workflow job step (see below) rather than stopping the emulator inside the composite action.

Recommended workflow

name: Wocha auth CI
 
on:
  push:
    branches: [main]
  pull_request:
 
env:
  WOCHA_EMULATOR_PORT: "4400"
 
jobs:
  auth-tests:
    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 $WOCHA_EMULATOR_PORT &
          echo "WOCHA_EMULATOR_PID=$!" >> $GITHUB_ENV
 
          for i in {1..30}; do
            curl -sf "http://127.0.0.1:$WOCHA_EMULATOR_PORT/api/v1/health" && exit 0
            sleep 1
          done
 
          echo "Emulator failed to start within 30s" >&2
          exit 1
 
      - name: Run auth tests
        env:
          WOCHA_EMULATOR: "true"
          WOCHA_EMULATOR_URL: http://127.0.0.1:${{ env.WOCHA_EMULATOR_PORT }}
          WOCHA_ISSUER: http://127.0.0.1:${{ env.WOCHA_EMULATOR_PORT }}
          WOCHA_CLIENT_ID: wocha-emulator
          WOCHA_CLIENT_SECRET: wocha-emulator-secret-local-only
        run: npm test
 
      - name: Stop emulator
        if: always()
        run: kill $WOCHA_EMULATOR_PID 2>/dev/null || true

Matrix testing across frameworks

Run the same auth smoke tests against multiple framework example apps:

jobs:
  framework-matrix:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        framework: [nextjs, react, express, sveltekit]
 
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-node@v4
        with:
          node-version: 22
 
      - name: Install example app
        working-directory: examples/${{ matrix.framework }}
        run: npm ci
 
      - name: Start emulator
        run: |
          npx @wocha/cli emulator --port 4400 &
          echo "WOCHA_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: Test ${{ matrix.framework }} example
        working-directory: examples/${{ matrix.framework }}
        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 $WOCHA_EMULATOR_PID 2>/dev/null || true

Cloud API tests with test-mode keys

When CI must hit the real Customer API, use a wocha_test_ key stored as a GitHub secret:

jobs:
  customer-api-tests:
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
 
      - run: npm ci
 
      - name: Run Customer API integration tests
        env:
          WOCHA_API_KEY: ${{ secrets.WOCHA_TEST_API_KEY }}
          WOCHA_TENANT_URL: https://your-tenant.wocha.ai
        run: npm run test:customer-api

Create the test key in the Console (Settings → API Keys → Test mode) or via the API with "mode": "test".

Reporting test results

Upload Playwright traces or JUnit reports as artefacts:

      - name: Run E2E tests
        env:
          WOCHA_EMULATOR: "true"
          WOCHA_EMULATOR_URL: http://127.0.0.1:4400
        run: npx playwright test
 
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

Troubleshooting

Symptom	Fix
Emulator not ready	Increase health-check retries; confirm port 4400 is free
OAuth redirect mismatch	Register `http://localhost:3000/api/auth/callback` or your CI app URL
Tests hit production	Set `WOCHA_EMULATOR=true` or use `wocha_test_` keys only
`@wocha/cli` not found	Add `@wocha/cli` to devDependencies or use `npx`