Test utilities - theAuth

@glinr/theauth-test-utils provides factories, mock servers, and assertion helpers so you can test auth-dependent code without a real database or network.

Install

pnpm add -D @glinr/theauth-test-utils

Factories

Factory functions create realistic mock entities with sensible defaults. Pass overrides for any fields relevant to the test.

import {
  createMockUser,
  createMockSession,
  createMockAgent,
  createMockPermission,
} from '@glinr/theauth-test-utils';

const user = createMockUser({ email: 'alice@example.com' });
const session = createMockSession({ user });
const agent = createMockAgent({ type: 'service', permissions: [] });
const perm = createMockPermission({ resource: 'files', actions: ['read', 'write'] });

Each call generates unique IDs, so you can create multiple entities in the same test without collisions.

Mock auth server

createMockAuthServer returns an in-memory AuthAdapter implementation with zero network or database calls. Use it in server-side unit tests that exercise code paths calling resolveUser, getUser, or syncUser.

import { createMockAuthServer, createMockUser } from '@glinr/theauth-test-utils';

const server = createMockAuthServer();
const user = createMockUser();

server.addUser(user);
server.setActiveUser(user.id);

const resolved = await server.resolveUser(new Request('https://example.com'));
// resolved.id === user.id

Per-request user override

Set the x-mock-theauth-user-id header on a Request to override the active user for that specific request only, without calling setActiveUser:

import { MOCK_USER_ID_HEADER } from '@glinr/theauth-test-utils';

const req = new Request('https://example.com', {
  headers: { [MOCK_USER_ID_HEADER]: user.id },
});

const resolved = await server.resolveUser(req);

Cleanup

afterEach(() => server.reset()); // clears the store and active session

Assertions

Three typed assertion helpers narrow ActionResult<T> (the result type used by @glinr/theauth-react, where a failure carries an error string) and throw descriptive errors on failure.

import {
  expectAuthenticated,
  expectUnauthenticated,
  expectPermissionDenied,
} from '@glinr/theauth-test-utils';

// Passes only when result.success === true
expectAuthenticated(result);
console.log(result.data); // typed

// Passes only when result.success === false
expectUnauthenticated(result);

// Passes only when result.success === false and error contains "permission" (case-insensitive)
expectPermissionDenied(result);

// Custom substring match
expectPermissionDenied(result, 'not allowed');

Mock React provider

For component tests, MockTheAuthProvider replaces <TheAuthProvider> with fixed values. It accepts user, session, isAuthenticated, isLoading, and optional signIn, signUp, signOut, and refresh overrides. The actions default to vi.fn() spies, so you can assert on calls.

import { MockTheAuthProvider, createMockUser, createMockSession } from '@glinr/theauth-test-utils';

const user = createMockUser();
const session = createMockSession({ user });

render(
  <MockTheAuthProvider user={user} session={session}>
    <ProfileButton />
  </MockTheAuthProvider>
);

The mock server itself has no dependencies. It matches the AuthAdapter interface structurally, so TypeScript will accept it anywhere an AuthAdapter is expected. The package entry point also exports MockTheAuthProvider, which imports vitest, react and @glinr/theauth-react (react and @glinr/theauth-react are optional peer dependencies), so use the package from a Vitest setup.

Error codes

How theAuth reports errors.

Database setup

In-memory SQLite for integration tests that need a real database.

Agent identity

Agent creation and permission checking to exercise in integration tests.

Hooks

Lifecycle hooks you can attach to your instance.

​Install

​Factories

​Mock auth server

​Per-request user override

​Cleanup

​Assertions

​Mock React provider

​Related

Error codes

Database setup

Agent identity

Hooks

Install

Factories

Mock auth server

Per-request user override

Cleanup

Assertions

Mock React provider

Related