@auth-gate/testing

Testing utilities for AuthGate — E2E helpers (Playwright/Cypress), in-memory billing test harness, and RBAC permission testing.

Installation

npm install -D @auth-gate/testing

Optional peer dependencies: @playwright/test >= 1.40, cypress >= 12, @auth-gate/billing >= 0.1.0, @auth-gate/rbac >= 0.1.0

Core API

import { AuthGateTest } from "@auth-gate/testing";

const testing = new AuthGateTest({
  apiKey: process.env.AUTHGATE_API_KEY!,
  baseUrl: process.env.AUTHGATE_URL!,
});

// Create a test user with an immediate session
const user = await testing.createUser({
  email: "[email protected]",
  password: "test-password-123",
  name: "Alice Test",
});
// Returns: { id, email, name, token, refreshToken, expiresAt }

// Create a new session for an existing user
const session = await testing.createSession(user.id);

// Create a test organization
const org = await testing.createOrg({ name: "Acme Corp" });

// Create a test role
const role = await testing.createRole({
  key: "editor",
  name: "Editor",
  permissions: ["documents:read", "documents:write"],
});

// Add a member to an organization
const member = await testing.addMember(org.id, user.id, "editor");

// Clean up all test users
const result = await testing.cleanup();
// { deleted: 3 }

Playwright

import { AuthGateTest } from "@auth-gate/testing/playwright";

// In your test setup
const testing = new AuthGateTest({
  apiKey: process.env.AUTHGATE_API_KEY!,
  baseUrl: process.env.AUTHGATE_URL!,
});

test("authenticated user sees dashboard", async ({ page }) => {
  const user = await testing.createUser({
    email: "[email protected]",
    password: "password123",
  });

  // Inject the session cookie
  await testing.injectSession(page, user);

  await page.goto("/dashboard");
  await expect(page.locator("h1")).toContainText("Dashboard");
});

test.afterAll(async () => {
  await testing.cleanup();
});

Cypress

import { AuthGateTest } from "@auth-gate/testing/cypress";

const testing = new AuthGateTest({
  apiKey: Cypress.env("AUTHGATE_API_KEY"),
  baseUrl: Cypress.env("AUTHGATE_URL"),
});

beforeEach(() => {
  cy.wrap(
    testing.createUser({
      email: "[email protected]",
      password: "password123",
    })
  ).then((user) => {
    testing.injectSession(user);
  });
});

afterEach(() => {
  cy.wrap(testing.cleanup());
});

Test Users

Test user emails must end with @test.authgate.dev. The OTP code for test users is always 000000.

import { TEST_EMAIL_DOMAIN, TEST_OTP_CODE } from "@auth-gate/testing";

// TEST_EMAIL_DOMAIN = "test.authgate.dev"
// TEST_OTP_CODE = "000000"

API Reference

AuthGateTest

| Method | Description | |--------|-------------| | createUser(options) | Create a test user with immediate session | | createSession(userId) | Create a new session for an existing user | | deleteUser(userId) | Delete a single test user | | cleanup() | Delete all test users in the project | | createOrg(options) | Create a test organization | | createRole(options) | Create a test role with permissions | | addMember(orgId, userId, roleKey) | Add a user to an organization |

Billing test utilities (@auth-gate/testing/billing)

In-memory billing harness for unit-testing subscription logic, entitlement checks, and usage-based billing.

npm install -D @auth-gate/testing @auth-gate/billing

import { createTestBilling } from "@auth-gate/testing/billing";
import { billing } from "./authgate.billing";

const t = createTestBilling({ billing });

t.subscribe("user_1", "pro");
t.reportUsage("user_1", "api_calls", 500);
t.advanceTime({ months: 1 });

const check = t.checkEntitlement("user_1", "api_calls");
// { type: "metered", allowed: true, limit: 100000, used: 0, remaining: 100000 }

RBAC test utilities (@auth-gate/testing/rbac)

Config builders, in-memory permission checker, and assertion helpers for RBAC configurations.

npm install -D @auth-gate/testing @auth-gate/rbac

import { defineRbac } from "@auth-gate/rbac";
import { RbacChecker, expectPermission, expectNoPermission } from "@auth-gate/testing/rbac";

const rbac = defineRbac({ /* ... */ });
const checker = new RbacChecker(rbac);

checker.hasPermission("admin", "documents:delete"); // true
checker.getPermissions("viewer"); // Set { "documents:read" }

expectPermission(rbac, "admin", "documents:write");
expectNoPermission(rbac, "viewer", "documents:delete");

License

MIT