@wocha/testing

Testing utilities for Wocha auth integrations. Bypass the hosted login flow in E2E tests, mock React auth state in component tests, and generate signed webhook payloads for handler testing.

Install

pnpm add -D @wocha/testing

Optional peers:

• @wocha/react — required for MockWochaProvider
• @wocha/nextjs — session cookies match its encryption format
• Playwright or Cypress — use the framework-specific subpath imports

E2E testing tokens (Next.js)

@wocha/nextjs stores sessions in an encrypted greet_session cookie. This package generates a valid StoredSession (with an HS256 access token JWT inside), encrypts it with the same AES-GCM scheme as the Next.js SDK, and sets it as a cookie so middleware and server components see an authenticated user — no hosted login redirect.

Important: Pass the same secret your app uses (WOCHA_CLIENT_SECRET or WOCHA_COOKIE_SECRET / sessionSecret in createWochaHandler).

Playwright

import { test, expect } from "@playwright/test";
import { setupGreetTestingToken } from "@wocha/testing/playwright";

test("authenticated dashboard", async ({ page }) => {
  await setupGreetTestingToken(page, {
    email: "[email protected]",
    orgId: "org_123",
    roles: ["admin"],
    permissions: ["documents:read"],
    sessionSecret: process.env.WOCHA_CLIENT_SECRET,
  });

  await page.goto("/dashboard");
  await expect(page.getByText("Welcome")).toBeVisible();
});

You can pass a BrowserContext instead of a Page:

await setupGreetTestingToken(context, { email: "[email protected]" });

Cypress

Register the custom command in cypress/support/e2e.ts:

import { registerGreetTestingCommands } from "@wocha/testing/cypress";

registerGreetTestingCommands();

Use it in specs:

describe("dashboard", () => {
  beforeEach(() => {
    cy.greetSignIn({
      email: "[email protected]",
      orgId: "org_123",
      sessionSecret: Cypress.env("WOCHA_CLIENT_SECRET"),
    });
  });

  it("loads for signed-in users", () => {
    cy.visit("/dashboard");
    cy.contains("Welcome").should("be.visible");
  });
});

Low-level API

Use these when you need full control (e.g. custom test servers):

import {
  createTestingSessionCookie,
  generateTestingAccessToken,
  buildTestingCookie,
} from "@wocha/testing";

// Encrypted cookie value + session object
const { name, value, accessToken, session } = await createTestingSessionCookie({
  email: "[email protected]",
  userId: "user_abc",
  orgId: "org_xyz",
  roles: ["member"],
  permissions: ["billing:view"],
  sessionSecret: process.env.WOCHA_CLIENT_SECRET,
});

// JWT only (e.g. API integration tests)
const token = generateTestingAccessToken({
  email: "[email protected]",
  orgId: "org_xyz",
});

Environment variables

| Variable | Purpose | |----------|---------| | WOCHA_TEST_TOKEN_SECRET | HS256 secret for test access tokens (default: built-in test secret) | | WOCHA_COOKIE_SECRET / WOCHA_CLIENT_SECRET | Session cookie encryption (must match your app) | | WOCHA_WEBHOOK_SECRET | Webhook signing secret for payload generator |

Mock React provider (component tests)

MockWochaProvider is a drop-in replacement for WochaProvider from @wocha/react. It wires the same context so hooks like useSession, useOrg, and usePermission work without OAuth.

import { render, screen } from "@testing-library/react";
import { useSession } from "@wocha/react";
import { MockWochaProvider, createMockUser } from "@wocha/testing";

function Profile() {
  const { data, status } = useSession();
  if (status !== "authenticated") return null;
  return <p>{data?.email}</p>;
}

test("renders authenticated user", () => {
  render(
    <MockWochaProvider
      user={createMockUser({ email: "[email protected]" })}
      org={{ orgId: "org_123" }}
    >
      <Profile />
    </MockWochaProvider>,
  );

  expect(screen.getByText("[email protected]")).toBeInTheDocument();
});

Props:

• session — partial session overrides
• user — partial user overrides
• org — { orgId, orgIds, slug, displayName, ... }
• isLoading, isAuthenticated, error, config

Mock data factories

import {
  createMockUser,
  createMockOrg,
  createMockSession,
} from "@wocha/testing";

const user = createMockUser({ email: "[email protected]", orgId: "org_1" });
const org = createMockOrg({ slug: "acme", displayName: "Acme Inc" });
const session = createMockSession({ user: { email: "[email protected]" } });

All factories accept partial overrides and generate realistic IDs by default.

Webhook payload generator

Generate signed webhook payloads compatible with @wocha/sdk/webhooks verification:

import { createTestWebhookPayload } from "@wocha/testing";

const { payload, headers } = createTestWebhookPayload("user.created", {
  secret: "whsec_test",
  data: { email: "[email protected]" },
});

const response = await fetch("http://localhost:3000/api/webhooks/wocha", {
  method: "POST",
  headers,
  body: payload,
});

Supported event types:

user.created, user.updated, user.deleted, user.login.succeeded, user.login.failed, user.mfa.enrolled, user.mfa.challenged, session.created, session.revoked, org.created, org.member.added, org.member.removed, connection.created, connection.deleted, application.created, application.deleted

Verify in tests:

import {
  createTestWebhookPayload,
  verifyTestWebhookSignature,
} from "@wocha/testing";

const { payload, headers } = createTestWebhookPayload("session.revoked");
expect(
  verifyTestWebhookSignature(payload, headers["X-Wocha-Signature"], "whsec_test"),
).toBe(true);

Or use the production SDK:

import { constructWebhookEvent } from "@wocha/sdk/webhooks";

const event = await constructWebhookEvent(
  payload,
  headers["X-Wocha-Signature"],
  "whsec_test",
);

Package exports

| Import | Use case | |--------|----------| | @wocha/testing | Mock provider, factories, tokens, webhooks | | @wocha/testing/playwright | setupGreetTestingToken(page, options) | | @wocha/testing/cypress | registerGreetTestingCommands(), cy.greetSignIn() |

Security note

Testing tokens and default secrets are for local/test environments only. Never enable test token generation in production. Use dedicated test tenants and rotate secrets if they are ever committed to source control.