# Testing Authentication

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

*Canonical: https://makerkit.dev/docs/void-cloudflare/authentication/testing*

---

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](./overview).

## Seed Users

```bash
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

```bash
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`:

| Helper | Does |
|---|---|
| `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 |

```ts {% title="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.
