e2e-testing

name	E2E Testing
description	Run, debug, and fix Playwright E2E tests locally. Use when writing new E2E tests, debugging failing tests, or iterating on test fixes before pushing to CI.

Prerequisites

1. E2E Database

The E2E tests use a separate iota_erp_e2e database. Create it if missing:

# Check DB connection params from .env (DB_HOST, DB_PORT, DB_PASSWORD)
grep '^DB_' .env

# Create the database (adjust host/port from .env)
PGPASSWORD=postgres psql -U postgres -h localhost -p 5438 -c "CREATE DATABASE iota_erp_e2e;"

# Run migrations
just e2e migrate up

2. Start the E2E Server

The server must run with test endpoints enabled:

PORT=3201 ORIGIN='http://localhost:3201' DB_NAME=iota_erp_e2e ENABLE_TEST_ENDPOINTS=true \
  go run -tags e2e ./cmd/server/main.go

Or use just e2e dev (uses air hot-reload, same env vars).

Verify it's running:

curl -s -o /dev/null -w "%{http_code}" http://localhost:3201/login
# Should return 200

3. Stop the Server When Done

kill $(lsof -ti:3201) 2>/dev/null

Running Tests

# Run a specific test file
cd e2e && npx playwright test tests/roles/roles.spec.ts --reporter=line

# Run a specific test by line number
cd e2e && npx playwright test tests/roles/roles.spec.ts:26 --reporter=line

# Run all E2E tests (headless)
just e2e ci

# Run with Playwright UI (interactive debugging)
just e2e run

Debug Loop

When fixing a failing E2E test, follow this loop:

1. Reproduce locally first — never iterate via CI pushes
2. Run the specific failing test by line number for fast feedback
3. Check screenshots in e2e/test-results/ after failures
4. Check video recordings (.webm) for timing/animation issues
5. Read the error context file in test-results for DOM snapshots
6. Fix and re-run until the specific test passes
7. Run the full test file to catch regressions in serial tests
8. Then push to CI

# Quick iteration: run just the failing test
cd e2e && npx playwright test tests/module/test.spec.ts:LINE --reporter=line

# After fixing, run the full suite
cd e2e && npx playwright test tests/module/test.spec.ts --reporter=line

# View failure screenshot
# (path shown in test output, use Read tool to view)

Common Patterns

Dialog Confirmation Buttons

The <dialog> top-layer positioning confuses Playwright's elementFromPoint() hit testing in headless Chromium. The bottom action bar (sticky footer) intercepts pointer events even though the dialog is visually on top.

Workaround: After verifying the dialog is visible, trigger the htmx form submit directly instead of clicking the confirm button:

// Open the confirmation dialog
await page.locator('[data-test-id="delete-btn"]').click();

// Wait for dialog to appear
const dialog = page.locator('[data-test-id="delete-confirmation-dialog"]');
await expect(dialog).toBeVisible();

// Trigger htmx delete directly (bypasses dialog hit-test issue)
await page.evaluate(() => {
  const form = document.getElementById('delete-form') as HTMLFormElement;
  (window as any).htmx.trigger(form, 'submit');
});

await page.waitForURL(/\/expected-path$/);

Selectors

Prefer data-test-id attributes over text-based or structural selectors:

// Good
page.locator('[data-test-id="save-role-btn"]')
page.locator('[data-test-id="dialog-confirm-btn"]')

// Fragile
page.locator('button').filter({ hasText: /Save/i })
page.getByRole('button', { name: /confirm/i })

Waiting for Alpine.js

import { waitForAlpine } from '../../fixtures/auth';
await waitForAlpine(page);

Database Reset and Seeding

Tests use beforeAll to reset and seed:

import { resetTestDatabase, seedScenario } from '../../fixtures/test-data';

test.beforeAll(async ({ request }) => {
  await resetTestDatabase(request, { reseedMinimal: false });
  await seedScenario(request, 'comprehensive');
});

Test Structure

e2e/
├── fixtures/
│   ├── auth.ts          # login, logout, waitForAlpine helpers
│   └── test-data.ts     # resetTestDatabase, seedScenario
├── tests/
│   ├── roles/           # Role management tests
│   ├── users/           # User management tests
│   └── ...
├── playwright.config.ts # Playwright config (1280x720 viewport)
└── test-results/        # Screenshots, videos, traces from failures

Key Config

• Viewport: 1280x720 (Desktop Chrome)
• Test timeout: 60s
• Retries in CI: 2 (none locally by default)
• Workers: 1 (serial execution for data-dependent tests)
• Base URL: http://localhost:3201