Playwright Cheatsheet: Locators, Assertions, Fixtures and Traces

# Node / TypeScript — the canonical path
npm init playwright@latest
# → installs @playwright/test + Chromium, Firefox, WebKit binaries
# → scaffolds tests/, playwright.config.ts, .github/workflows/playwright.yml

npx playwright test                          # all browsers, all projects
npx playwright test --ui                     # interactive Trace + watch mode
npx playwright test login.spec.ts --headed   # see the browser
npx playwright test -g "checkout"            # filter by title (regex)
npx playwright test --workers=4              # parallel processes
npx playwright codegen example.com           # record a test from clicks

# Python — pytest plugin
pip install pytest-playwright
playwright install                           # download browser binaries
pytest --browser chromium --headed

# Reports
npx playwright show-report                   # open last HTML report
npx playwright show-trace trace.zip          # open a captured trace

// playwright.config.ts — the knobs you'll touch most
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? '50%' : undefined,

  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
    headless: true,
    trace: 'on-first-retry',        // capture network/DOM only on retries
    video: 'retain-on-failure',
    screenshot: 'only-on-failure',
    actionTimeout: 10_000,
    navigationTimeout: 30_000,
    locale: 'en-US',
    timezoneId: 'Europe/London',
    viewport: { width: 1280, height: 800 },
  },

  // Multi-browser fanout — each becomes its own report group
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
    { name: 'mobile-safari', use: { ...devices['iPhone 15'] } },
  ],

  // Boot the app before tests
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

// Intercept + stub a JSON API
await page.route('**/api/users/*', async route => {
  await route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify({ id: 42, name: 'Ana', plan: 'pro' }),
  });
});

// Modify an in-flight request (e.g. inject a header)
await page.route('**/api/**', async route => {
  const headers = { ...route.request().headers(), 'x-trace-id': 'abc' };
  await route.continue({ headers });
});

// Block a 3rd-party tracker entirely
await page.route('**/analytics.js', route => route.abort());

// Listen, don't intercept — read response bodies
page.on('response', async resp => {
  if (resp.url().includes('/api/orders'))
    console.log(resp.status(), await resp.json());
});

// Wait for a specific response (deterministic — beats waitForTimeout)
const [resp] = await Promise.all([
  page.waitForResponse(r => r.url().endsWith('/checkout') && r.status() === 200),
  page.click('button:has-text("Pay")'),
]);
expect((await resp.json()).orderId).toBeTruthy();

// Full login → cart → checkout flow with auto-wait + storage state reuse.
import { test, expect } from '@playwright/test';

// Reuse a logged-in session across tests
test.use({ storageState: 'storage/user.json' });

test('checkout flow', async ({ page }) => {
  await page.goto('/shop');                              // baseURL prepends

  // Add to cart
  await page.getByRole('button', { name: 'Add Mug' }).click();
  await expect(page.getByTestId('cart-count')).toHaveText('1');

  // Open cart drawer + go to checkout
  await page.getByRole('navigation').getByRole('link', { name: 'Cart' }).click();
  await page.getByRole('button', { name: /checkout/i }).click();

  // Fill the form by labels (a11y-friendly)
  await page.getByLabel('Card number').fill('4242 4242 4242 4242');
  await page.getByLabel('Expiry').fill('12/29');
  await page.getByLabel('CVC').fill('123');

  // Wait for the success response — deterministic
  const [resp] = await Promise.all([
    page.waitForResponse(r => r.url().endsWith('/checkout') && r.ok()),
    page.getByRole('button', { name: 'Pay' }).click(),
  ]);
  expect((await resp.json()).status).toBe('paid');

  // Web-first assertion — auto-retries until visible or test times out
  await expect(page.getByText('Thank you for your order')).toBeVisible();
});