Playwright E2E Testing

Setup verification

Before writing any tests, verify Playwright is installed:

# Check if playwright config exists
ls playwright.config.ts 2>/dev/null || ls playwright.config.js 2>/dev/null
# Check if @playwright/test is in devDependencies
grep -q "@playwright/test" package.json 2>/dev/null

If Playwright is NOT installed, run the setup script: bash scripts/setup-playwright.sh from this skill’s directory. Then adapt playwright.config.ts to the project’s specific dev server port and base URL.

Writing tests

File placement and naming

• Place tests in e2e/ at the project root (not inside src/)
• Name files descriptively: e2e/<feature>.spec.ts
• Group related tests in subdirectories: e2e/auth/login.spec.ts

Test structure pattern

import { test, expect } from '@playwright/test';

test.describe('Feature: <name>', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/relevant-route');
  });

  test('should <expected behavior> when <action>', async ({ page }) => {
    // Arrange: locate elements
    const element = page.getByRole('button', { name: 'Submit' });

    // Act: perform user actions
    await element.click();

    // Assert: verify outcomes
    await expect(page.getByText('Success')).toBeVisible();
  });
});

Locator priority (most to least preferred)

1. page.getByRole() — accessible roles: 'button', 'link', 'heading', 'textbox', 'checkbox'
2. page.getByText() — visible text content
3. page.getByLabel() — form labels
4. page.getByPlaceholder() — input placeholders
5. page.getByTestId() — data-testid attributes (add to components when other locators are ambiguous)
6. page.locator('css-selector') — last resort only

Never use fragile selectors like .css-1a2b3c or div > span:nth-child(3).

Handling async UI patterns

// Wait for loading states to resolve
await expect(page.getByRole('progressbar')).toBeHidden();

// Wait for network idle after navigation
await page.waitForLoadState('networkidle');

// Wait for specific API responses
const responsePromise = page.waitForResponse('**/api/artists');
await page.getByRole('button', { name: 'Search' }).click();
await responsePromise;

// Retry assertions (Playwright auto-retries expects)
await expect(page.getByText('Results')).toBeVisible({ timeout: 10000 });

Mocking API responses

test('displays artist data from API', async ({ page }) => {
  await page.route('**/api/artists*', async route => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ artists: [{ name: 'Test Artist', listeners: 50000 }] }),
    });
  });
  await page.goto('/dashboard');
  await expect(page.getByText('Test Artist')).toBeVisible();
});

Visual regression (when appropriate)

test('dashboard renders correctly', async ({ page }) => {
  await page.goto('/dashboard');
  await expect(page.getByRole('main')).toBeVisible();
  await expect(page).toHaveScreenshot('dashboard.png', { maxDiffPixelRatio: 0.01 });
});

Running tests

# Run all tests
npx playwright test

# Run specific file
npx playwright test e2e/dashboard.spec.ts

# Run with UI mode (interactive debugging)
npx playwright test --ui

# Run headed (visible browser)
npx playwright test --headed

# Run specific test by title
npx playwright test -g "should display search results"

# Update visual snapshots
npx playwright test --update-snapshots

# View HTML report after failures
npx playwright show-report

Debugging failures

1. Check the HTML report: npx playwright show-report
2. Run the failing test in UI mode: npx playwright test --ui -g "test name"
3. Add await page.pause() inside a test to open the inspector
4. Use trace viewer: ensure trace: 'on-first-retry' is in config, then open test-results/*/trace.zip

Test categories to cover for a dashboard/chat UI

For reference on which categories of tests to write, see references/test-categories.md.

Common mistakes to avoid

• Do NOT use page.waitForTimeout() — use proper assertions or waitFor patterns
• Do NOT hardcode viewport sizes — use config or test.use() for responsive tests
• Do NOT test implementation details — test user-visible behavior
• Do NOT write tests that depend on execution order between files
• Do NOT skip flaky tests — fix the root cause (usually a missing wait)
• Do NOT use force: true on clicks — if an element needs force-click, the test is wrong