Playwright Test Recorder Guide

Master Playwright's codegen command, write resilient selectors, handle authentication state, and ship reliable end-to-end tests to CI.

Recording Your First Test

Playwright's codegen command opens a browser and records every interaction as runnable test code in real time.

# Install Playwright (first time)
npm init playwright@latest

# Record against your local dev server
npx playwright codegen http://localhost:3000

# Record with Firefox
npx playwright codegen --browser firefox https://example.com

# Record and save authentication state (cookies, localStorage)
npx playwright codegen --save-storage=auth.json https://example.com/login

Selector Priority — Most to Least Resilient

Complete Test with Auto-Waiting

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

test.describe('Login flow', () => {
  test('successful login redirects to dashboard', async ({ page }) => {
    await page.goto('/login');
    await page.getByLabel('Email').fill('[email protected]');
    await page.getByLabel('Password').fill('secret123');
    await page.getByRole('button', { name: 'Sign in' }).click();

    // Auto-wait for navigation — no sleeps needed
    await page.waitForURL('/dashboard');
    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
  });

  test('invalid credentials shows error', async ({ page }) => {
    await page.goto('/login');
    await page.getByLabel('Email').fill('[email protected]');
    await page.getByLabel('Password').fill('wrongpass');
    await page.getByRole('button', { name: 'Sign in' }).click();

    await expect(page.getByText('Invalid credentials')).toBeVisible();
    await expect(page).toHaveURL('/login');
  });
});

Authentication State Reuse

// global-setup.ts — logs in once, saves session
import { chromium } from '@playwright/test';
export default async function globalSetup() {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('/login');
  await page.getByLabel('Email').fill(process.env.TEST_USER!);
  await page.getByLabel('Password').fill(process.env.TEST_PASS!);
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.waitForURL('/dashboard');
  await page.context().storageState({ path: 'playwright/.auth/user.json' });
  await browser.close();
}

// playwright.config.ts
export default defineConfig({
  globalSetup: './global-setup.ts',
  projects: [
    { name: 'authenticated', use: { storageState: 'playwright/.auth/user.json' } },
  ],
});

GitHub Actions CI Setup

# .github/workflows/playwright.yml
name: Playwright E2E Tests
on: [push, 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
      - run: npx playwright install --with-deps
      - run: npx playwright test --workers=4
        env:
          TEST_USER: ${{ secrets.TEST_USER }}
          TEST_PASS: ${{ secrets.TEST_PASS }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-html-report
          path: playwright-report/
          retention-days: 14

Common Pitfalls

• Using waitForTimeout — Fixed sleeps make tests flaky; use auto-waiting assertions instead
• Hardcoded CSS selectors — They break on styling changes; prefer getByRole or getByLabel
• Logging in before every test — Use storageState reuse; auth per-test multiplies runtime
• Missing --with-deps in CI — Playwright browsers need OS-level deps; always use --with-deps on Linux
• No artifacts on failure — Always upload playwright-report as a CI artifact for visual debugging
• Testing implementation details — Assert visible outcomes (text, URL, ARIA state), not internal state