Test Utils plugin configuration options
testUtils plugin accepts one configuration option: captureOTP (boolean, default false) - enables OTP capture for testing verification flows.
Better Auth · Plugins · all subjects
test utils plugin
23 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Test Utils plugin purpose and scope
The Test Utils plugin provides helpers for writing integration and E2E tests against Better Auth. It includes factories, database helpers, authentication helpers, and OTP capture functionality. The plugin is designed for test environments only and does not add public routes, but exposes privileged helpers on ctx.test.
Test Utils installation in test-only auth config
Import testUtils from 'better-auth/plugins' and add it to the plugins array in a separate test-only auth config file (such as auth.test.ts) to preserve type inference for ctx.test without adding the plugin to production auth config. Access test helpers via const ctx = await auth.$context; const test = ctx.test;
Test Utils production safety
testUtils() does not register HTTP routes or API endpoints and does not create a public auth bypass on its own. However, it adds privileged server-side helpers on ctx.test that can create sessions, persist users and organizations, and delete records directly through the auth context. When captureOTP: true is enabled, the plugin also installs a verification hook and stores OTPs in memory. The recommended setup is to keep testUtils out of production auth config and use it from a separate test-only auth instance.
Test Utils TypeScript type inference caveat
Better Auth infers plugin helpers best from statically defined plugin arrays. If testUtils() is conditionally spread into plugins (such as based on NODE_ENV), TypeScript can stop inferring ctx.test correctly. Unconditionally including testUtils() can preserve static type inference, but avoid using ctx.test in production code paths.
createUser factory method
The createUser factory creates a user object with default values that can be overridden. It does not write to the database. Example: test.createUser() generates a user with defaults like id, email (user-xxx@example.com format), name (Test User), emailVerified (true), etc. Overrides can be passed: test.createUser({ email: 'alice@example.com', name: 'Alice', emailVerified: false })
createOrganization factory method
The createOrganization factory creates an organization object. It is only available when the organization plugin is installed. Example: test.createOrganization({ name: 'Acme Corp', slug: 'acme-corp' })
saveUser database helper
The saveUser helper persists a user object to the database. Example: const user = test.createUser({ email: 'test@example.com' }); const savedUser = await test.saveUser(user);
deleteUser database helper
The deleteUser helper deletes a user from the database. Example: await test.deleteUser(user.id);
saveOrganization database helper
The saveOrganization helper persists an organization object to the database. It is only available with the organization plugin. Example: const org = test.createOrganization({ name: 'Test Org' }); const savedOrg = await test.saveOrganization(org);
deleteOrganization database helper
The deleteOrganization helper deletes an organization from the database. It is only available with the organization plugin. Example: await test.deleteOrganization(org.id);
addMember database helper
The addMember helper adds a user as a member of an organization. It is only available with the organization plugin. Example: const member = await test.addMember({ userId: user.id, organizationId: org.id, role: 'admin' });
login auth helper
The login helper creates a session for a user and returns session details, headers, cookies, and token. It accepts userId and an optional session object for fields configured through session.additionalFields or a plugin's session schema. Example: const { session, user, headers, cookies, token } = await test.login({ userId: user.id, session: { providerToken: 'test-token' } }); Returns: session (session object with userId, token, etc.), user (user object), headers (headers object with session cookie for fetch/Request), cookies (cookie array for Playwright/Puppeteer), token (session token string).
getAuthHeaders auth helper
The getAuthHeaders helper returns a Headers object with the session cookie set. It is useful for making authenticated requests. Example: const headers = await test.getAuthHeaders({ userId: user.id }); Can be used with auth API: const session = await auth.api.getSession({ headers }); Or with fetch: const response = await fetch('/api/protected', { headers });
getCookies auth helper
The getCookies helper returns an array of cookie objects compatible with browser testing tools like Playwright and Puppeteer. It accepts userId and an optional domain parameter (defaults to baseURL domain). Example: const cookies = await test.getCookies({ userId: user.id, domain: 'localhost' }); Each cookie object contains: name (cookie name, e.g., 'better-auth.session_token'), value (cookie value), domain (cookie domain), path (cookie path, defaults to '/'), httpOnly (whether cookie is HTTP-only), secure (whether cookie requires HTTPS), sameSite (SameSite attribute: 'Lax', 'Strict', or 'None').
OTP capture functionality
When captureOTP: true is set in testUtils options, the plugin passively captures OTPs as they are created. This allows retrieval of OTPs in tests without needing to mock email or SMS sending. OTP capture is passive and does not prevent OTPs from being sent via the configured sendVerificationOTP function; it simply stores a copy for test retrieval.
getOTP helper method
The getOTP helper retrieves a captured OTP by identifier (email or phone number). Example: After sending OTP via await auth.api.sendVerificationOTP({ body: { email: 'user@example.com', type: 'sign-in' } }), retrieve it with: const otp = test.getOTP('user@example.com'); Returns the OTP string (e.g., '123456').
clearOTPs helper method
The clearOTPs helper clears all captured OTPs from memory. Example: test.clearOTPs(); Useful for cleaning up between test cases in beforeEach hooks.
Auth helpers session parameter behavior
Auth helpers (login, getAuthHeaders, getCookies) accept an optional session object for fields configured through session.additionalFields or a plugin's session schema. Supplied values override defaults; omitted fields keep their defaults. Standard session fields such as id, userId, token, and timestamps are ignored.
Integration test example with Vitest
Example integration test using Vitest with testUtils: import { describe, it, expect, beforeAll } from 'vitest'; import { auth } from './auth'; import type { TestHelpers } from 'better-auth/plugins'; describe('protected route', () => { let test: TestHelpers; beforeAll(async () => { const ctx = await auth.$context; test = ctx.test; }); it('should return user data for authenticated request', async () => { const user = test.createUser({ email: 'test@example.com' }); await test.saveUser(user); const headers = await test.getAuthHeaders({ userId: user.id }); const session = await auth.api.getSession({ headers }); expect(session?.user.id).toBe(user.id); await test.deleteUser(user.id); }); });
E2E test example with Playwright
Example E2E test using Playwright with testUtils: import { test, expect } from '@playwright/test'; import { auth } from './auth'; test('dashboard shows user name', async ({ context, page }) => { const ctx = await auth.$context; const testUtils = ctx.test; const user = testUtils.createUser({ email: 'e2e@example.com', name: 'E2E User' }); await testUtils.saveUser(user); const cookies = await testUtils.getCookies({ userId: user.id, domain: 'localhost' }); await context.addCookies(cookies); await page.goto('/dashboard'); await expect(page.getByText('E2E User')).toBeVisible(); await testUtils.deleteUser(user.id); });
OTP verification test example
Example OTP verification test with captureOTP: import { describe, it, expect, beforeAll, beforeEach } from 'vitest'; import { auth } from './auth'; import type { TestHelpers } from 'better-auth/plugins'; describe('OTP verification', () => { let test: TestHelpers; beforeAll(async () => { const ctx = await auth.$context; test = ctx.test; }); beforeEach(() => { test.clearOTPs(); }); it('should verify email with captured OTP', async () => { const email = 'otp-test@example.com'; const user = test.createUser({ email, emailVerified: false }); await test.saveUser(user); await auth.api.sendVerificationOTP({ body: { email, type: 'email-verification' } }); const otp = test.getOTP(email); expect(otp).toBeDefined(); await auth.api.verifyEmail({ body: { email, otp } }); await test.deleteUser(user.id); }); });
Test Utils configuration with captureOTP enabled
Example configuration of testUtils with captureOTP enabled and emailOTP plugin: import { betterAuth } from 'better-auth'; import { testUtils, emailOTP } from 'better-auth/plugins'; export const auth = betterAuth({ plugins: [ testUtils({ captureOTP: true }), emailOTP({ async sendVerificationOTP({ email, otp }) { /* email sending logic */ } }) ] });