Playwright

Playwright End-to-End Testing AI Skill Guide (Claude)

Overview & Engine Architecture

Playwright is a modern browser automation framework with first-class Test Runner (@playwright/test), auto-waiting locators, multi-browser projects (Chromium/Firefox/WebKit), and rich debugging via trace, video, and HTML report. Claude operates as a Principal QA Automation Engineer, specializing in resilient locators, fixtures, storageState auth, trace-on-failure CI, and parallel project matrices.

Playwright Test Architecture

┌─────────────────────────────────────────────────────────────┐
│                 Playwright Architecture                     │
│                                                             │
│  Test Runner                                                │
│  ├── playwright.config.ts projects/workers/retries          │
│  ├── Fixtures (page, context, custom)                       │
│  └── Reporters (list, html, github, blob)                   │
│                                                             │
│  Automation Engine                                          │
│  ├── Browser / Context / Page                               │
│  ├── Locators + auto-wait + web-first assertions            │
│  └── Network interception / routing                         │
│                                                             │
│  Diagnostics                                                │
│  ├── Trace Viewer / screenshots / video                     │
│  ├── UI mode / codegen / inspector                          │
│  └── CI artifacts                                           │
└─────────────────────────────────────────────────────────────┘

Operational Capabilities & Agent Directives

1. Role/Label Locators First: Prefer getByRole, getByLabel, getByTestId over CSS/XPath soup.
2. Web-First Assertions: Use expect(locator).toBeVisible() - not manual sleeps.
3. Isolate Auth: Reuse storageState for logged-in projects; avoid UI login in every test.
4. Trace on Retry: Capture traces for failed/retried tests in CI.
5. Deterministic Data: Seed test users/data; do not depend on volatile production content.

Production Spec + Config Snippets

tests/checkout.spec.ts:

// ==============================================================================
// Playwright Test: resilient checkout smoke with role locators
// ==============================================================================
import { test, expect } from "@playwright/test";

test.describe("checkout", () => {
  test("adds item and shows confirmation", async ({ page }) => {
    await page.goto("/products/demo-sku");
    await page.getByRole("button", { name: "Add to cart" }).click();
    await page.getByRole("link", { name: "Cart" }).click();
    await expect(page.getByRole("heading", { name: "Your cart" })).toBeVisible();

    await page.getByRole("button", { name: "Checkout" }).click();
    await page.getByLabel("Email").fill("qa+playwright@example.com");
    await page.getByLabel("Card number").fill("4242424242424242");
    await page.getByRole("button", { name: "Pay now" }).click();

    await expect(
      page.getByRole("heading", { name: /order confirmed/i })
    ).toBeVisible();
  });
});

playwright.config.ts excerpt:

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./tests",
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  reporter: [["list"], ["html", { open: "never" }]],
  use: {
    baseURL: process.env.BASE_URL || "http://127.0.0.1:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
  ],
  webServer: {
    command: "npm run dev",
    url: "http://127.0.0.1:3000",
    reuseExistingServer: !process.env.CI,
  },
});

CLI:

npx playwright install --with-deps
npx playwright test
npx playwright show-report
npx playwright test --ui

Technical Troubleshooting Matrix

Best Practices

1. One assertion intent per test; share journeys via fixtures.
2. Use test.step for readable traces.
3. Keep selectors in page objects only if they reduce duplication - don't over-abstract early.

Essential Paths

• playwright.config.ts
• tests/
• test-results/ / playwright-report/ (artifacts)

Agent Operational Directive

MANDATORY: Prefer role/label locators and web-first assertions. No hard-coded waitForTimeout sleeps. Enable trace-on-retry in CI and keep tests deterministic with seeded data.