Testing Authentication

Seed users for local development and the helpers e2e specs use to sign up, verify, reset and sign in.

Local development signs in as seed users. E2E specs create their own users and build email links themselves, because the production preview sends no email.

This page is part of the Authentication documentation.

Seed Users

pnpm db:seed

This resets the local database, applies the migrations and creates five verified users, user1@makerkit.dev to user5@makerkit.dev, password testingpassword. They're defined in apps/web/db/seed-users.ts and written through Better Auth in apps/web/db/seed.ts. They never appear in migrations; never seed a deployed database.

E2E

pnpm test:e2e

The suite runs against the production preview with rate limits on and every optional sign-in method switched on (playwright.config.ts sets every key in SIGN_IN_METHOD_ENV, e.g. AUTH_MAGIC_LINK=true and fake Google keys, for the preview, whatever .env says; OAuth specs stop at the provider), and only against a local database (it refuses any other DATABASE_URL). Before the specs, it migrates the database, then creates the seed users if they're missing. It never resets the database: the one in apps/web/.env may be your own.

Helpers in apps/e2e/tests/utils/auth.ts:

HelperDoes
signUpVerifiedUser({ page, baseURL })Creates and verifies a new user and signs the page in
signUpUnverifiedUser({ page, baseURL })Creates a user who hasn't verified yet
verificationLink(email, callbackURL)The verification link Better Auth would email, signed with BETTER_AUTH_SECRET
passwordResetLink(email, callbackURL)The latest reset link for the address, read from the database
magicLink({ email, next, errorCallbackURL })The latest magic link for the address, read from the database
emailOtpCode(email)The latest sign-in code for the address, decrypted from the database with BETTER_AUTH_SECRET
seedUser()A seed user, to sign in as. Never change it: every worker shares it
uniqueEmail()A new address per test

apps/e2e/tests/auth/example.spec.ts

import { signUpVerifiedUser } from '../utils/auth';
import { expect, test } from '../utils/test';
test('a signed-in user sees home', async ({ page, baseURL }) => {
await signUpVerifiedUser({ page, baseURL: baseURL ?? '' });
await page.goto('/dashboard');
await expect(page.getByTestId('account-dropdown-name')).toBeVisible();
});

Rules for a new spec (the full list is in apps/e2e/AGENTS.md):

  • Import test from tests/utils/test, never @playwright/test (the lint fails otherwise). It gives each test its own client IP, so per-IP limits never mix tests. A page you open with browser.newPage passes extraHTTPHeaders: clientIpHeaders().
  • One page object per page, tests/<area>/<page>.po.ts, owning selectors and waits.
  • Wait for hydration before the first interaction on a page (clickWhenHydrated / fillWhenHydrated from tests/utils/hydration.ts).
  • baseURL ?? '' is safe: the config always sets use.baseURL.

Unit Tests

The Better Auth options, hooks and guards are tested through auth.handler and plain functions in packages/better-auth/src/__tests__/; the auth mailer in packages/better-auth/src/__tests__/queued-mailer.test.ts (its app binding in apps/web/config/__tests__/auth-mailer.server.test.ts), the rendered emails in apps/web/config/__tests__/emails.server.test.ts. URLs with a locale prefix (/it/dashboard) are covered there: with one locale, the app serves no prefixed URLs to test end to end.