Add End-to-End Tests with Playwright to Catch Bugs Before Users Do

Set up Playwright for our Next.js analytics dashboard. We need to test on Chromium, Firefox, and WebKit (our users report Safari bugs often). Configure it to: auto-start our dev server (npm run dev on port 3000), capture traces and screenshots only on failure (save CI storage), retry failed tests twice in CI, run tests in parallel locally but sequentially in CI (our CI runner is small). We use TypeScript.

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  workers: process.env.CI ? 1 : undefined,
  retries: process.env.CI ? 2 : 0,
  use: {
    trace: 'on-first-retry',       // Captures timeline, DOM, network — only when needed
    screenshot: 'only-on-failure',
    video: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
  webServer: {
    command: 'npm run dev',
    port: 3000,
    reuseExistingServer: !process.env.CI,
  },
});

Write e2e tests for our most critical flows. Our app is a B2B analytics dashboard. The critical flows are:

1. Login — email/password, should redirect to /dashboard, show user's name in header
2. Dashboard — load default dashboard, verify 4 KPI cards render with numbers (not loading spinners), date range picker works
3. Create report — click "New Report", select metrics (revenue, users, conversion), choose date range, generate report, verify chart renders
4. Filter and export — apply filters (date range, country, device), verify table updates, click Export CSV, verify download starts
5. Team invite — go to Settings > Team, enter email, select role, send invite, verify invite appears in pending list

Use page objects for each page. Use role-based locators (getByRole, getByLabel) not CSS selectors.

// tests/e2e/pages/dashboard.page.ts
import { type Page, type Locator } from '@playwright/test';

export class DashboardPage {
  readonly kpiCards: Locator;
  readonly dateRangePicker: Locator;
  readonly newReportButton: Locator;

  constructor(private page: Page) {
    this.kpiCards = page.getByRole('region', { name: /kpi/i });
    this.dateRangePicker = page.getByLabel('Date range');
    this.newReportButton = page.getByRole('button', { name: 'New Report' });
  }

  async verifyKPIsLoaded() {
    // Verify cards show numbers, not loading spinners
    for (const card of await this.kpiCards.all()) {
      await expect(card.getByRole('status')).not.toBeVisible();
      await expect(card.locator('[data-testid="kpi-value"]')).toHaveText(/\d/);
    }
  }
}

Add tests for error states and edge cases using API mocking. Test these scenarios:

1. Dashboard API returns 500 — should show error state with retry button
2. Dashboard API returns empty data — should show "No data for this period" message
3. Report generation takes more than 5 seconds — should show progress indicator
4. Export fails mid-download — should show error toast
5. Session expires while user is on dashboard — should redirect to login

Use Playwright's route mocking, don't hit real APIs for these tests.

// tests/e2e/flows/edge-cases.spec.ts
test('API error shows retry button that actually works', async ({ page }) => {
  let callCount = 0;
  await page.route('/api/dashboard', (route) => {
    callCount++;
    if (callCount === 1) return route.fulfill({ status: 500 });
    return route.continue(); // Second call succeeds
  });

  await page.goto('/dashboard');
  await expect(page.getByText('Something went wrong')).toBeVisible();
  await page.getByRole('button', { name: 'Retry' }).click();
  await expect(page.getByText('Something went wrong')).not.toBeVisible();
});

Add visual regression tests that catch unexpected CSS changes. Take screenshots of: the login page, the dashboard with KPI cards, a generated report with chart, and the settings page. Mock API responses to ensure consistent data for screenshots. Configure a 1% pixel diff threshold so minor anti-aliasing differences don't cause failures.

npx playwright test tests/e2e/visual --update-snapshots

Create a GitHub Actions workflow that runs the full Playwright suite on every PR to main. Cache the Playwright browsers between runs to speed up CI. Upload the HTML report as an artifact on failure so developers can debug. Add a PR comment that summarizes test results (passed/failed/skipped). The workflow should block merge if any test fails.

# .github/workflows/e2e.yml
name: E2E Tests
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - name: Cache Playwright browsers
        uses: actions/cache@v4
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ hashFiles('package-lock.json') }}
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/