better-auth-playwright

Test data management for Better Auth and Playwright. Create users, sessions, and related resources in your E2E tests — with automatic cleanup.

Features

• Direct DB user creation — bypasses sign-up flow for fast tests (password hashing only when needed)
• Auto session cookies — sets session cookies on the Playwright browser context automatically
• Automatic cleanup — all test users are deleted after each test
• Plugin system — extend user creation with additional resources (orgs, API keys, etc.)
• Custom base test — works with framework-specific Playwright extensions (Nuxt, Next.js, etc.)

Install

npm install better-auth-playwright

Peer dependencies: better-auth (>=1.4.0) and @playwright/test (>=1.40.0).

Quick Start

1. Server Setup

Add testPlugin() to your Better Auth config. The plugin registers test-only endpoints that are protected by a shared secret — when no secret is configured, they return 404.

// auth.ts (server)
import { betterAuth } from 'better-auth'
import { testPlugin } from 'better-auth-playwright/server'

export const auth = betterAuth({
  // ... your config
  plugins: [
    testPlugin({
      secret: process.env.TEST_DATA_SECRET,
    }),
  ],
})

2. Playwright Setup

Create a test fixtures file that configures better-auth-playwright with the same secret:

// e2e/fixtures.ts
import { createTestFixtures } from 'better-auth-playwright'

export const test = createTestFixtures({
  secret: process.env.TEST_DATA_SECRET!,
})

export { expect } from 'better-auth-playwright'

3. Write Tests

Use the auth fixture to create users and get authenticated browser sessions:

// e2e/dashboard.spec.ts
import { expect, test } from './fixtures'

test('user can see the dashboard', async ({ page, auth }) => {
  const user = await auth.createUser()
  // Browser context now has session cookies set

  await page.goto('/dashboard')
  await expect(page.getByText(user.email)).toBeVisible()
})

API Reference

Server

testPlugin(options?)

Better Auth plugin that registers test data endpoints. Import from better-auth-playwright/server.

Option	Type	Default	Description
secret	string	process.env.TEST_DATA_SECRET	Secret required in X-Test-Secret header. If not set and env var is missing, endpoints return 404 (disabled).
plugins	TestDataPlugin[]	[]	Test data plugins that extend user creation with plugin-specific resources.

Registered endpoints:

Method	Path	Description
POST	/api/auth/test-data/user	Create a test user + session. Runs plugin hooks.
POST	/api/auth/test-data/delete-user	Delete a test user by email. Runs plugin cleanup in reverse order.
GET	/api/auth/test-data/capabilities	List installed test data plugins and detected Better Auth plugins.

All endpoints require the X-Test-Secret header and use isAction: false (not callable from the client SDK).

organizationTest(defaults?)

Test data plugin for the Better Auth organization plugin. Import from better-auth-playwright/server.

Creates an organization and membership when a test user is created. Automatically deletes the org on cleanup.

Option	Type	Default	Description
name	string	"{user.name}'s Org"	Organization name.
slug	string	Slugified email prefix	Organization slug.
role	'owner' | 'admin' | 'member'	'owner'	User's role in the org.
skip	boolean	false	Skip org creation entirely.

Returns { id, name, slug } or null if skipped.

Example with organization plugin:

// auth.ts (server)
import { betterAuth } from 'better-auth'
import { organizationTest, testPlugin } from 'better-auth-playwright/server'
import { organization } from 'better-auth/plugins'

export const auth = betterAuth({
  plugins: [
    organization(),
    testPlugin({
      secret: process.env.TEST_DATA_SECRET,
      plugins: [organizationTest()],
    }),
  ],
})

Playwright

createTestFixtures(config)

Creates a Playwright test object with an auth fixture. Import from better-auth-playwright.

Option	Type	Default	Description
secret	string	required	Secret that matches the server plugin's secret.
basePath	string	'/api/auth'	Base path for Better Auth endpoints.
test	TestType	@playwright/test's test	Custom base test to extend (see Custom Base Test).

Returns a Playwright test function with the auth fixture added.

auth.createUser(options?)

Create a test user and set session cookies on the current browser context.

Option	Type	Default	Description
email	string	Random test-*@test.local	User's email address.
name	string	Email prefix	User's display name.
password	string	none	Set a password (only needed if the test exercises the login form).
pluginData	Record<string, unknown>	{}	Plugin-specific options, keyed by plugin ID.

Returns a TestUser:

interface TestUser {
  id: string
  email: string
  name: string
  session: { id: string, token: string }
  plugins: Record<string, unknown>
}

auth.cleanup(email)

Delete a test user by email. Called automatically after each test for all users created during that test — you only need to call this manually for users created outside the fixture.

Writing Plugins

Create custom test data plugins to extend user creation for other Better Auth plugins:

import type { CreateUserContext, TestDataPlugin } from 'better-auth-playwright'

interface MyPluginOptions {
  someOption?: string
}

interface MyPluginResult {
  resourceId: string
}

export function myPlugin(): TestDataPlugin<'my-plugin', MyPluginOptions, MyPluginResult> {
  return {
    id: 'my-plugin', // Must match the Better Auth plugin ID

    async onCreateUser(ctx: CreateUserContext, options: MyPluginOptions) {
      // ctx.authContext — Better Auth context (access adapters, options, etc.)
      // ctx.user — the created user
      // ctx.session — the created session
      // ctx.request — the original request

      // Create your resources...
      return { resourceId: '...' }
    },

    async onDeleteUser(ctx, user) {
      // Optional: clean up resources when user is deleted
    },
  }
}

Then register it in the server plugin:

testPlugin({
  secret: process.env.TEST_DATA_SECRET,
  plugins: [myPlugin()],
})

Access plugin results in tests via user.plugins['my-plugin'].

Custom Base Test

If you use a framework-specific Playwright extension (like @nuxt/test-utils/playwright), pass its test function to preserve its fixtures:

import { test as nuxtTest } from '@nuxt/test-utils/playwright'
import { createTestFixtures } from 'better-auth-playwright'

export const test = createTestFixtures({
  secret: process.env.TEST_DATA_SECRET!,
  test: nuxtTest,
})

export { expect } from 'better-auth-playwright'

Credit

Built by the team behind Gaffer — test reporting and analytics for CI/CD.

License

MIT