E2E Testing with Playwright

The panel ships with a Playwright test harness that gives every test a real, pre-authenticated session for a specific role — no OAuth, no login page, no browser cookies to manage manually.

How It Works

pnpm seed:test-users          # one-time: create test users in the dev DB
         ↓
nubx playwright test           # each run:
         ↓
global-setup.ts               # calls POST /api/auth/test-session per role
         ↓                    # saves signed session cookies to playwright/.auth/
playwright/.auth/superadmin.json
playwright/.auth/admin.json
playwright/.auth/user.json
         ↓
your spec runs                # Playwright injects the right cookie automatically
                              # no login needed inside the test

The test-session endpoint is guarded by NODE_ENV !== 'production' — it is never reachable in production.

Roles Available

Role	Email	Use For
`superadmin`	test-superadmin@test.local	Platform-level admin features
`admin`	test-admin@test.local	Org admin features
`user`	test-user@test.local	Standard member features

Writing a Test

1. Create the spec file

Place all E2E specs in frontend/solidstart/tests/e2e/. Follow the naming convention:

Single-role: <feature>.<role>.spec.ts — e.g. dashboard.superadmin.spec.ts
Multi-role: <feature>.multirole.spec.ts — when one test verifies permission differences across roles

// tests/e2e/dashboard.superadmin.spec.ts
import { test, expect } from '@playwright/test';

test('dashboard loads for superadmin', async ({ page }) => {
  await page.goto('/admin/dashboard', { waitUntil: 'commit' });

  await page.waitForTimeout(2000); // allow initial API calls to complete

  await expect(page.locator('h1')).toContainText('Dashboard');

  // Always assert no silent API errors at the end of each happy-path test
  await expect(page.locator('[data-testid="api-error-toast"]')).toHaveCount(0);
});

You do not need any login code inside the test. The session is injected automatically by Playwright’s storageState for the project you select at run time.

2. Run the test as a specific role

cd frontend/solidstart

# Run as superadmin
nubx playwright test tests/e2e/dashboard.superadmin.spec.ts --project=superadmin

# Run as admin
nubx playwright test tests/e2e/members.admin.spec.ts --project=admin

# Run all tests for a role
nubx playwright test --project=user

The --project flag selects which stored auth state (and which role) Playwright loads. No auth code is needed in the test itself.

The `[data-testid="api-error-toast"]` Contract

In dev mode the panel wraps globalThis.fetch and appends a visible <div data-testid="api-error-toast"> to the DOM whenever any request returns a status ≥ 400. Every happy-path test MUST assert this element has count 0:

await expect(page.locator('[data-testid="api-error-toast"]')).toHaveCount(0);

This ensures silent 4xx/5xx errors — which would normally be invisible — are caught by Playwright screenshots and fail the test explicitly.

Omitting this assertion means broken API calls can go undetected even on a green test run.

Before You Start: One-Time Setup

Seed test users

cd backend/bun
pnpm seed:test-users

This upserts the three test users with the correct platform roles and credential accounts. Safe to re-run — it uses upsert.

Set environment variables

Copy .env.test.example from the monorepo root to .env.test and fill in your local values:

# .env.test
SMOKE_API_BASE_URL=http://localhost:3100    # Bun backend
PLAYWRIGHT_BASE_URL=http://localhost:3000   # SolidStart panel dev server
TEST_SESSION_ENDPOINT=http://localhost:3100/api/auth/test-session

Running Smoke Tests First

Before running Playwright, run the API smoke test to catch any broken endpoints early:

cd backend/bun
pnpm smoke:api

Expected output:

🔍 Smoke testing http://localhost:3100

✓ Pre-flight: test session created

METHOD  PATH                      EXPECTED  ACTUAL    STATUS
────────────────────────────────────────────────────────────
GET     /                         200       200       ✓ PASS
GET     /health                   200       200       ✓ PASS
GET     /health/ready             200       200       ✓ PASS
GET     /api/v1/users/me          200       200       ✓ PASS
GET     /api/v1/organizations/me  200       200       ✓ PASS

5/5 passed
✅ All endpoints passed

If any endpoint fails here, fix it before running Playwright — E2E tests will fail for the same reason.

Agent Definition of Done

Before handing off any frontend feature, complete all steps and paste terminal output as proof:

Smoke tests pass → pnpm smoke:api exits 0
Playwright spec passes → nubx playwright test <spec> --project=<role> exits 0
No API error toasts → final assertion in spec confirms count 0

Do not hand off if any step fails.

Troubleshooting

Global setup fails: “Test user not found”

The test users haven’t been seeded yet. Run:

cd backend/bun && pnpm seed:test-users

The credential account for the test user is missing or has a stale password. Re-run the seed — it deletes and recreates credential accounts:

pnpm seed:test-users

Session returns 401 on protected endpoints

The cookie set by test-session needs to match the backend that the panel talks to. Make sure TEST_SESSION_ENDPOINT in .env.test points to the same Bun backend that the panel’s VITE_BETTER_AUTH_URL points to.

Auth state files are stale

Delete the auth directory and let global setup recreate it:

rm -rf frontend/solidstart/playwright/.auth/
nubx playwright test

Adding Features
Build Scripts
Backend: backend/bun/AGENTS.md — Definition of Done for backend changes
Frontend: frontend/solidstart/AGENTS.md — Naming convention and Definition of Done

Getting Started

Development

UI Components

E2E Testing with Playwright

E2E Testing with Playwright

How It Works

Roles Available

Writing a Test

1. Create the spec file

2. Run the test as a specific role

The `[data-testid="api-error-toast"]` Contract

Before You Start: One-Time Setup

Seed test users

Set environment variables

Running Smoke Tests First

Agent Definition of Done

Troubleshooting

Global setup fails: “Test user not found”

Session returns 401 on protected endpoints

Auth state files are stale

​E2E Testing with Playwright

​How It Works

​Roles Available

​Writing a Test

​1. Create the spec file

​2. Run the test as a specific role

​The [data-testid="api-error-toast"] Contract

​Before You Start: One-Time Setup

​Seed test users

​Set environment variables

​Running Smoke Tests First

​Agent Definition of Done

​Troubleshooting

​Global setup fails: “Test user not found”

​Global setup fails: “Sign-in failed”

​Session returns 401 on protected endpoints

​Auth state files are stale

​Related

E2E Testing with Playwright

How It Works

Roles Available

Writing a Test

1. Create the spec file

2. Run the test as a specific role

The `[data-testid="api-error-toast"]` Contract

Before You Start: One-Time Setup

Seed test users

Set environment variables

Running Smoke Tests First

Agent Definition of Done

Troubleshooting

Global setup fails: “Test user not found”

Global setup fails: “Sign-in failed”

Session returns 401 on protected endpoints

Auth state files are stale

Related