Avnology ID
SDKsTypeScript SDKGuides

Testing

Test applications that use the TypeScript SDK with mocks, fixtures, and integration test helpers.

Testing

The SDK provides testing utilities for unit tests, integration tests, and end-to-end tests.

Mock client

Create a mock client that returns predefined responses without making HTTP requests.

import { createMockClient } from "@avnology/sdk-typescript/testing";

const mockClient = createMockClient({
  session: {
    id: "ses_test",
    active: true,
    identity: {
      id: "usr_test",
      email: "[email protected]",
      name: { first: "Test", last: "User" },
    },
    authenticatorAssuranceLevel: "aal1",
    expiresAt: new Date(Date.now() + 86400000).toISOString(),
  },
});

// All auth methods return the mock session
const session = await mockClient.login({ email: "[email protected]", password: "test" });
console.log(session.identity.email); // "[email protected]"

Override specific methods

import { createMockClient, MockError } from "@avnology/sdk-typescript/testing";

const mockClient = createMockClient({
  overrides: {
    login: async ({ email }) => {
      if (email === "[email protected]") {
        throw new MockError("AccountLockedError", { retryAfter: 300 });
      }
      return defaultSession;
    },
    "admin.listUsers": async () => ({
      users: [testUser1, testUser2],
      nextPageToken: null,
      totalSize: 2,
    }),
    "permissions.check": async ({ relation }) => {
      return relation === "admin";
    },
  },
});

Vitest example

import { describe, it, expect, beforeEach } from "vitest";
import { createMockClient } from "@avnology/sdk-typescript/testing";

describe("Dashboard", () => {
  let client: ReturnType<typeof createMockClient>;

  beforeEach(() => {
    client = createMockClient({
      session: {
        id: "ses_test",
        identity: { id: "usr_test", email: "[email protected]" },
        authenticatorAssuranceLevel: "aal1",
      },
    });
  });

  it("shows the user email", async () => {
    const session = await client.getSession();
    expect(session?.identity.email).toBe("[email protected]");
  });

  it("handles MFA requirement", async () => {
    const mfaClient = createMockClient({
      overrides: {
        login: async () => {
          throw new MockError("MfaRequiredError", {
            flowId: "flow_test",
            availableMethods: ["totp"],
          });
        },
      },
    });

    await expect(mfaClient.login({ email: "[email protected]", password: "p" }))
      .rejects.toThrow("MfaRequiredError");
  });
});

Integration testing

For integration tests against a real Avnology ID instance, use the test helpers to create and clean up test data.

import { AvnologyId } from "@avnology/sdk-typescript";
import { TestHelper } from "@avnology/sdk-typescript/testing";

const client = new AvnologyId({
  baseUrl: "http://localhost:4455",
  apiKey: "ak_test_...",
});

const helper = new TestHelper(client);

describe("User registration flow", () => {
  afterEach(async () => {
    await helper.cleanup(); // Deletes all test-created resources
  });

  it("registers and verifies a user", async () => {
    const user = await helper.createTestUser({
      email: `test-${Date.now()}@example.com`,
      password: "TestPassword123!",
      verified: true,
    });

    const session = await client.login({
      email: user.email,
      password: "TestPassword123!",
    });

    expect(session.identity.email).toBe(user.email);
  });
});

See also

On this page