Authentication for E2E Testing

Most applications require login to access their features. The authentication system lets agents run E2E tests, capture screenshots, and explore your app as a logged-in user.

Why Authentication?

When agents need to test protected pages, capture screenshots of dashboards, or verify user-specific functionality, they must authenticate first. Without proper auth configuration, agents can only test public pages.

E2E Testing

Test user flows that require login — onboarding, settings, dashboards, and protected features.

Screenshots

Capture screenshots of authenticated pages for documentation, marketing, and visual regression testing.

QA Exploration

Let QA agents explore your app as a real user would, finding bugs in authenticated experiences.

Browser Debugging

Debug issues by having agents navigate to protected pages and inspect the live UI state.

Setup Auth Skill

The easiest way to configure authentication is using the setup-auth skill. It scans your codebase, detects your auth provider, and walks you through configuration:

@toolkit setup authentication for E2E tests

Provider Detection

The skill scans your codebase for auth libraries (NextAuth, Supabase Auth, Auth0, etc.) and identifies your provider.

Configuration Questions

You'll be asked about login URL, test credentials, and any provider-specific settings.

Config Generation

The skill writes the authentication block to your project.json.

Provider Matrix

Different auth providers require different authentication strategies. The toolkit includes specialized skills for each:

Provider	Method	Skill	Notes
Supabase	Email/Password	`auth-supabase-password`	Standard email/password login
Supabase	Passwordless OTP	`auth-supabase-otp`	Email code verification
NextAuth.js	Credentials	`auth-nextauth-credentials`	NextAuth credentials provider
Custom	Form-based	`auth-generic`	Any standard login form
API	Headless	`auth-headless`	Direct API + cookie injection (fastest)

Headless Authentication (Recommended)

When possible, use auth-headless for fastest test execution. It authenticates via direct API calls (method: api) or CLI commands (method: cli) and injects session cookies, skipping the UI login flow entirely. This is especially useful for large test suites.

Configuration

Authentication is configured in your project.json:

{
  "authentication": {
    "provider": "supabase",      // supabase | nextauth | custom
    "method": "email-password",  // provider-specific method
    "loginUrl": "/login",        // URL to the login page
    
    // Headless auth configuration
    "headless": {
      "enabled": true,           // Enable headless auth if supported
      "method": "api"            // api | cli
    },
    
    "credentials": {
      "email": "test@example.com",
      "password": "env:TEST_PASSWORD"  // Use env: prefix for secrets
    },
    
    // Optional: test user cleanup
    "cleanup": {
      "enabled": true,
      "retainDays": 1
    }
  }
}

Secrets with env: Prefix

Never hardcode passwords in project.json. Use the env: prefix to reference environment variables. The agent reads the value from your environment at runtime.

CLI Authentication Method

For projects with CLI tools that generate auth tokens (admin APIs, custom scripts), use the cli method:

{
  "authentication": {
    "headless": {
      "enabled": true,
      "method": "cli",
      "command": "pnpm cli auth:test-token --email $TEST_EMAIL",
      "responseFormat": "json",
      "tokenPath": "accessToken",
      "refreshTokenPath": "refreshToken",
      "sessionStorage": "localStorage"
    }
  }
}

Field	Required	Description
command	Yes	Shell command to run. Supports `$ENV_VAR` expansion.
responseFormat	No	Output format: `json` (default), `text`, or `env` (KEY=VALUE lines)
tokenPath	No	Dot-path to access token in JSON response (default: `accessToken`)
refreshTokenPath	No	Dot-path to refresh token in JSON response (optional)
sessionStorage	No	Injection target: `cookies`, `localStorage`, or `both` (default: `cookies`)

Acquisition Steps

The acquisition block documents how agents should obtain an authenticated session. This serves as both documentation and a fallback when automated auth fails:

{
  "authentication": {
    "acquisition": {
      "description": "Use CLI to get a test token, inject into localStorage",
      "steps": [
        "Ensure SUPABASE_SERVICE_ROLE_KEY is set in .env.local",
        "Run: pnpm cli auth:test-token --email $TEST_EMAIL",
        "Parse JSON output for accessToken and refreshToken",
        "Inject tokens into browser localStorage",
        "Navigate to /dashboard — session should be active"
      ],
      "fallbackToUI": true,
      "notes": "The CLI command requires the service role key. Token expires after 1 hour."
    }
  }
}

Tip: Even if you use headless auth, define acquisition steps as a fallback. When fallbackToUI is true, agents will automatically try UI-based login if the automated method fails.

How Agents Use Auth

Once configured, agents automatically authenticate when needed:

1. Skill Loading

When an agent needs to access a protected page, it loads the appropriate auth skill based on your authentication.provider and authentication.method.

2. Authentication Flow

The skill executes the login flow — either via UI automation (filling forms, clicking buttons) or headless API calls. Session cookies are captured.

3. Session Reuse

Authenticated sessions are cached and reused across tests in the same run, avoiding repeated logins.

4. Protected Access

With valid session cookies, the agent can navigate to any protected page, capture screenshots, run tests, and interact with authenticated features.

Test User Cleanup

E2E tests often create test users that need to be cleaned up. The test-user-cleanup skill handles this automatically:

{
  "authentication": {
    // ... other config ...
    
    "cleanup": {
      "enabled": true,
      "retainDays": 1,           // Keep users created in last N days
      "identifierPattern": "^e2e-.*@test\\.com$"  // Match test emails
    }
  }
}

When Cleanup Runs

Cleanup can be triggered manually or configured to run after test suites complete. It removes test users older than retainDays.

Safety Patterns

Use identifierPattern to ensure only test users are deleted. The regex must match the email or identifier of test accounts.

Use a Dedicated Test Database

Always run E2E tests against a staging or test database, never production. Configure separate environments in your project.json to ensure tests don't affect real users.