qa-skills 3.0.0

package/skills/qa-playwright-py-writer/references/patterns.md

@@ -0,0 +1,212 @@
+# Playwright Python Patterns
+
+Common patterns for E2E testing with Playwright Python (sync and async API).
+
+## Sync vs Async API
+
+| API | Import | Use Case |
+|-----|--------|----------|
+| **Sync** | `from playwright.sync_api import Page, expect` | Default; simpler, pytest-playwright fixtures |
+| **Async** | `from playwright.async_api import Page, expect` | Async test suites; `playwright_pytest_asyncio = True` in pytest.ini |
+
+```python
+# Sync (default)
+def test_login(page: Page):
+    page.goto("/login")
+    page.get_by_label("Email").fill("user@example.com")
+    page.get_by_label("Password").fill("secret")
+    page.get_by_role("button", name="Sign in").click()
+    expect(page).to_have_url(re.compile(r".*dashboard"))
+
+# Async (requires playwright_pytest_asyncio)
+@pytest.mark.asyncio
+async def test_login_async(page: Page):
+    await page.goto("/login")
+    await page.get_by_label("Email").fill("user@example.com")
+    await page.get_by_role("button", name="Sign in").click()
+```
+
+## Pytest Fixtures (pytest-playwright)
+
+| Fixture | Scope | Description |
+|---------|-------|-------------|
+| `playwright` | Session | Playwright instance |
+| `browser_type` | Session | Chromium, Firefox, or WebKit launcher |
+| `browser` | Function | Browser instance |
+| `context` | Function | Browser context (isolated) |
+| `page` | Function | Page (tab) for tests |
+| `browser_context_args` | Function | Override context options |
+| `browser_name` | Session | `chromium`, `firefox`, or `webkit` |
+
+```python
+def test_with_page(page: Page):
+    page.goto("https://example.com")
+    assert page.title() == "Example Domain"
+
+def test_with_context(context: BrowserContext, page: Page):
+    # context and page are fresh per test
+    page.goto("/")
+```
+
+## Navigation
+
+| Pattern | Sync | Async |
+|---------|------|-------|
+| Go to URL | `page.goto("/login")` | `await page.goto("/login")` |
+| Go back | `page.go_back()` | `await page.go_back()` |
+| Reload | `page.reload()` | `await page.reload()` |
+| Wait for URL | `page.wait_for_url("**/dashboard")` | `await page.wait_for_url("**/dashboard")` |
+
+```python
+def test_navigates_after_login(page: Page):
+    page.goto("/login")
+    page.get_by_label("Email").fill("user@example.com")
+    page.get_by_label("Password").fill("secret")
+    page.get_by_role("button", name="Sign in").click()
+    page.wait_for_url(re.compile(r".*dashboard"))
+    expect(page).to_have_url(re.compile(r".*dashboard"))
+```
+
+## Forms
+
+| Pattern | Example |
+|---------|---------|
+| Fill text | `page.get_by_label("Name").fill("John")` |
+| Fill by role | `page.get_by_role("textbox", name="Email").fill("a@b.com")` |
+| Select dropdown | `page.get_by_label("Country").select_option("US")` |
+| Check checkbox | `page.get_by_role("checkbox", name="Subscribe").check()` |
+| Radio | `page.get_by_role("radio", name="Option A").check()` |
+| Submit | `page.get_by_role("button", name="Submit").click()` |
+
+```python
+def test_registration_form(page: Page):
+    page.goto("/register")
+    page.get_by_label("Email").fill("new@example.com")
+    page.get_by_label("Password").fill("SecurePass123")
+    page.get_by_role("checkbox", name="Terms").check()
+    page.get_by_role("button", name="Create account").click()
+    expect(page.get_by_text("Welcome")).to_be_visible()
+```
+
+## Assertions (expect)
+
+| Assertion | Example |
+|-----------|---------|
+| Visible | `expect(locator).to_be_visible()` |
+| Text | `expect(locator).to_have_text("Hello")` |
+| URL | `expect(page).to_have_url(re.compile(r".*dashboard"))` |
+| Count | `expect(locator).to_have_count(3)` |
+| Enabled | `expect(locator).to_be_enabled()` |
+| Checked | `expect(locator).to_be_checked()` |
+
+```python
+from playwright.sync_api import expect
+
+def test_homepage(page: Page):
+    page.goto("/")
+    expect(page.get_by_role("heading", name="Welcome")).to_be_visible()
+    expect(page.locator(".item")).to_have_count(5)
+```
+
+## Network Mocking (page.route)
+
+| Pattern | Example |
+|---------|---------|
+| Mock response | `page.route("**/api/users", lambda route: route.fulfill(status=200, body="[]"))` |
+| Abort request | `page.route("**/analytics", lambda route: route.abort())` |
+| Continue | `page.route("**/api/**", lambda route: route.continue_())` |
+| Unroute | `page.unroute("**/api/users")` |
+
+```python
+def test_empty_state(page: Page):
+    def handle_route(route):
+        route.fulfill(
+            status=200,
+            content_type="application/json",
+            body='{"items": []}'
+        )
+    page.route("**/api/items", handle_route)
+    page.goto("/items")
+    expect(page.get_by_text("No items found")).to_be_visible()
+```
+
+## File Upload
+
+| Pattern | Example |
+|---------|---------|
+| Single file | `page.get_by_label("Upload").set_input_files("fixtures/doc.pdf")` |
+| Multiple files | `page.get_by_label("Upload").set_input_files(["a.pdf", "b.pdf"])` |
+| Buffer | `page.get_by_label("Upload").set_input_files(FilePayload(name="test.txt", mime_type="text/plain", buffer=b"content"))` |
+
+```python
+from pathlib import Path
+
+def test_upload(page: Page):
+    page.goto("/upload")
+    page.get_by_label("Choose file").set_input_files(Path(__file__).parent / "fixtures" / "sample.pdf")
+    page.get_by_role("button", name="Upload").click()
+    expect(page.get_by_text("Upload complete")).to_be_visible()
+```
+
+## Iframe Handling
+
+| Pattern | Example |
+|---------|---------|
+| Frame locator | `frame = page.frame_locator('iframe[name="embed"]')` |
+| Interact in frame | `frame.get_by_role("button").click()` |
+
+```python
+def test_iframe_content(page: Page):
+    page.goto("/embed")
+    frame = page.frame_locator("iframe#widget")
+    frame.get_by_role("button", name="Submit").click()
+    expect(frame.get_by_text("Success")).to_be_visible()
+```
+
+## Multi-Tab / Popup
+
+| Pattern | Example |
+|---------|---------|
+| Wait for popup | `with page.expect_popup() as popup_info: page.get_by_role("link").click()` then `popup = popup_info.value` |
+| New page | `new_page = context.new_page()` |
+
+```python
+def test_opens_external_link(page: Page, context: BrowserContext):
+    with page.expect_popup() as popup_info:
+        page.get_by_role("link", name="External").click()
+    popup = popup_info.value
+    popup.wait_for_load_state()
+    expect(popup).to_have_url(re.compile(r"external\.com"))
+```
+
+## Page Object Model (POM)
+
+```python
+# pages/base_page.py
+from playwright.sync_api import Page
+
+class BasePage:
+    def __init__(self, page: Page, base_url: str):
+        self.page = page
+        self.base_url = base_url
+
+    def goto(self, path: str):
+        self.page.goto(f"{self.base_url}{path}")
+
+# pages/login_page.py
+from playwright.sync_api import Page
+from .base_page import BasePage
+
+class LoginPage(BasePage):
+    def __init__(self, page: Page, base_url: str):
+        super().__init__(page, base_url)
+
+    def login(self, email: str, password: str):
+        self.page.get_by_label("Email").fill(email)
+        self.page.get_by_label("Password").fill(password)
+        self.page.get_by_role("button", name="Sign in").click()
+
+    @property
+    def error_message(self):
+        return self.page.get_by_role("alert")
+```

package/skills/qa-playwright-ts-writer/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: qa-playwright-ts-writer
+description: Generate Playwright E2E, component, and unit tests for TypeScript with auto-wait, multi-browser support, POM pattern, and live browser record mode via Playwright MCP.
+output_dir: tests/e2e
+---
+
+# QA Playwright TypeScript Writer
+
+## Purpose
+
+Write Playwright tests (E2E, component, unit) from test case specifications. Transform structured test cases into executable Playwright test files with auto-waiting, multi-browser support, Page Object Model, and optional live browser record mode.
+
+## Trigger Phrases
+
+- "Write Playwright tests for [feature/flow]"
+- "Generate E2E tests from test cases"
+- "Create Playwright tests with record mode"
+- "Add Playwright component tests for [component]"
+- "Playwright tests for [URL/flow]"
+- "Record browser interactions and generate test code"
+- "POM-based Playwright tests for [page]"
+- "Multi-browser Playwright tests"
+- "Heal my failing Playwright tests"
+
+## Three Modes
+
+| Mode | When to Use | Behavior |
+|------|-------------|----------|
+| **Record Mode** | User wants live browser capture | Use Playwright MCP (e.g., cursor-ide-browser) → navigate, interact, capture interactions → generate test code from recorded steps |
+| **Generate Mode** | Default; from test case specs | Read test cases (from qa-testcase-from-docs, qa-testcase-from-ui, qa-manual-test-designer) → generate Playwright code |
+| **Heal Mode** | Tests fail after changes | Delegate to **qa-test-healer** to auto-fix broken selectors, assertions, waits; mark unfixable as `test.fixme()` |
+
+## Test Types
+
+| Type | Scope | Approach |
+|------|-------|----------|
+| **E2E** | Full user flows, page navigation | page.goto, locators, assertions, network interception, multi-browser |
+| **Component** | Isolated component testing | @playwright/experimental-ct-react, ct-vue, ct-svelte; mount, interact, assert |
+| **Unit** | Pure functions, utilities | Use test runner for logic; Playwright optional for DOM utilities |
+
+## E2E Testing
+
+- **Navigation:** page.goto, page.goBack, page.reload
+- **Interactions:** click, fill, selectOption, check, hover, press
+- **Assertions:** expect(locator).toBeVisible, toHaveText, toHaveURL, etc.
+- **Network:** page.route for API mocking, request/response interception
+- **Multi-browser:** Chromium, Firefox, WebKit via projects in config
+- **Auto-wait:** Playwright auto-waits for elements; avoid page.waitForTimeout
+
+See `references/patterns.md` for navigation, forms, auth, file upload, drag-drop, iframes, multi-tab, API mocking, visual comparison.
+
+## Component Testing
+
+- **React:** `@playwright/experimental-ct-react` — mount components, pass props, assert
+- **Vue:** `@playwright/experimental-ct-vue` — mount, slots, provide/inject
+- **Svelte:** `@playwright/experimental-ct-svelte` — mount, component API
+
+Component tests run in isolated browser context; use `test` from `@playwright/experimental-ct-*`.
+
+## Page Object Model (POM)
+
+- **Base page:** Shared selectors, navigation helpers, common actions
+- **Page-specific:** Extend base; encapsulate page-specific locators and methods
+- **Component objects:** Reusable components (header, modal, form) as classes
+
+See `references/best-practices.md` for POM structure.
+
+## Key Patterns
+
+- **Structure:** test.describe / test / test.step for grouping
+- **Locators:** getByRole > getByTestId > getByText > getByLabel > CSS selector
+- **Assertions:** expect(locator).toBeVisible, toHaveText, toHaveURL, toHaveCount, etc.
+- **Network:** page.route(url, handler) for mocking; page.unroute to clear
+- **Fixtures:** test.extend for custom fixtures (auth, API client)
+- **Steps:** test.step('description', async () => { ... }) for trace grouping
+
+See `references/assertions.md` for full assertion reference.
+
+## Locator Priority
+
+1. **getByRole** — Accessibility-based; most resilient
+2. **getByTestId** — data-testid; explicit, stable
+3. **getByText** — Visible text; use for unique labels
+4. **getByLabel** — Form labels; good for inputs
+5. **CSS selector** — Last resort; brittle for dynamic content
+
+## Configuration
+
+- **playwright.config.ts** — projects (browsers), retries, workers, reporter, baseURL
+- **Global setup/teardown** — Auth state, DB seeding
+- **Test directory** — e2e/, tests/, or colocated
+
+See `references/config.md` for full config guide.
+
+## MCP Integration
+
+- **Context7 MCP** — Fetch Playwright documentation when needed
+- **Playwright MCP** (cursor-ide-browser, @playwright/mcp) — Record mode: navigate, snapshot, click, type; capture interactions → generate test code
+
+## Scope
+
+**Can do (autonomous):**
+- Generate Playwright E2E, component, unit tests from test case specs
+- Use Record Mode with Playwright MCP to capture and generate tests
+- Apply POM pattern, stable locators, auto-wait
+- Configure playwright.config.ts (projects, retries, reporter)
+- Use page.route for API mocking
+- Delegate to qa-test-healer when tests fail (Heal Mode)
+- Use Context7 MCP for Playwright docs
+
+**Cannot do (requires confirmation):**
+- Change production code structure
+- Add dependencies not in package.json
+- Override project Playwright config without approval
+- Navigate to URLs not provided (Record Mode)
+
+**Will not do (out of scope):**
+- Execute tests (user runs `npx playwright test`)
+- Write Jest/Vitest unit tests (use qa-jest-writer)
+- Modify CI/CD pipelines
+- Bypass security or access restricted areas
+
+## References
+
+- `references/patterns.md` — Navigation, forms, auth, file upload, drag-drop, iframes, multi-tab, API mocking, visual
+- `references/assertions.md` — Playwright assertion reference
+- `references/config.md` — playwright.config.ts, projects, reporter, setup
+- `references/best-practices.md` — POM, locators, flakiness, isolation, debugging
+
+## Quality Checklist
+
+- [ ] Auto-wait used; no page.waitForTimeout (use expect with timeout or waitFor)
+- [ ] No hardcoded waits; prefer expect auto-retry
+- [ ] POM pattern applied for page-specific logic
+- [ ] Stable locators (getByRole, getByTestId preferred)
+- [ ] Tests independent (no shared state, order-independent)
+- [ ] Proper teardown (fixtures, afterEach if needed)
+- [ ] Traceability to test case IDs where applicable
+- [ ] No hardcoded secrets (use env vars)
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| Element not found | Selector too specific, dynamic content | Use getByRole/getByTestId; add data-testid if needed |
+| Timeout | Element not ready, slow network | Increase expect timeout; use waitFor; check for overlays |
+| Flaky tests | Race conditions, shared state | Ensure test isolation; use auto-wait; avoid fixed delays |
+| Record mode empty | MCP not capturing steps | Verify Playwright MCP active; lock browser before actions |
+| Multi-tab fails | Wrong context | Use page.context().pages() or new context for new tab |
+| API mock not applied | Route registered after request | Call page.route before page.goto |
+| Component test fails | Missing mount setup | Check ct config; ensure component imported correctly |

package/skills/qa-playwright-ts-writer/references/assertions.md

@@ -0,0 +1,109 @@
+# Playwright Assertion Reference
+
+Playwright uses `expect` from `@playwright/test` with auto-retry and rich error messages.
+
+## Visibility & State
+
+| Assertion | Description | Example |
+|-----------|-------------|---------|
+| `toBeVisible()` | Element is visible | `expect(page.getByRole('heading')).toBeVisible()` |
+| `toBeHidden()` | Element is hidden | `expect(page.getByText('Loading')).toBeHidden()` |
+| `toBeAttached()` | Element is in DOM | `expect(locator).toBeAttached()` |
+| `toBeDetached()` | Element is not in DOM | `expect(locator).toBeDetached()` |
+
+## Text
+
+| Assertion | Description | Example |
+|-----------|-------------|---------|
+| `toHaveText(text)` | Exact text match | `expect(locator).toHaveText('Submit')` |
+| `toHaveText(regex)` | Regex match | `expect(locator).toHaveText(/Welcome, .+/)` |
+| `toContainText(text)` | Contains text | `expect(locator).toContainText('Error')` |
+| `toHaveValue(value)` | Input value | `expect(input).toHaveValue('typed')` |
+
+## URL & Navigation
+
+| Assertion | Description | Example |
+|-----------|-------------|---------|
+| `toHaveURL(url)` | Page URL | `expect(page).toHaveURL('/dashboard')` |
+| `toHaveURL(regex)` | URL regex | `expect(page).toHaveURL(/.*\/user\/\d+/)` |
+| `toHaveTitle(title)` | Page title | `expect(page).toHaveTitle('Dashboard')` |
+
+## Count & List
+
+| Assertion | Description | Example |
+|-----------|-------------|---------|
+| `toHaveCount(n)` | Number of matches | `expect(page.getByRole('listitem')).toHaveCount(5)` |
+| `toHaveLength(n)` | Array length (for locator.all()) | `expect(await locator.all()).toHaveLength(3)` |
+
+## Attributes & Properties
+
+| Assertion | Description | Example |
+|-----------|-------------|---------|
+| `toHaveAttribute(name, value?)` | Attribute exists/value | `expect(link).toHaveAttribute('href', '/about')` |
+| `toHaveClass(class)` | Has CSS class | `expect(btn).toHaveClass('active')` |
+| `toHaveCSS(name, value)` | CSS property | `expect(el).toHaveCSS('display', 'none')` |
+
+## Form Elements
+
+| Assertion | Description | Example |
+|-----------|-------------|---------|
+| `toBeChecked()` | Checkbox/radio checked | `expect(checkbox).toBeChecked()` |
+| `toBeEnabled()` | Element enabled | `expect(button).toBeEnabled()` |
+| `toBeDisabled()` | Element disabled | `expect(button).toBeDisabled()` |
+| `toBeEditable()` | Input is editable | `expect(input).toBeEditable()` |
+| `toBeEmpty()` | No text/children | `expect(div).toBeEmpty()` |
+
+## Soft Assertions
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `expect.soft()` | Continue on failure | `await expect.soft(locator).toBeVisible()` |
+| Collect failures | Run all, report at end | Use multiple `expect.soft` in sequence |
+
+```typescript
+test('validates form fields', async ({ page }) => {
+  await expect.soft(page.getByLabel('Email')).toBeVisible();
+  await expect.soft(page.getByLabel('Password')).toBeVisible();
+  await expect.soft(page.getByRole('button')).toBeEnabled();
+});
+```
+
+## Timeout
+
+| Pattern | Description | Example |
+|---------|-------------|---------|
+| `{ timeout: ms }` | Override default | `expect(locator).toBeVisible({ timeout: 10000 })` |
+| Config default | playwright.config.ts | `expect: { timeout: 5000 }` |
+
+## Negation
+
+| Pattern | Example |
+|---------|---------|
+| `not` | `expect(locator).not.toBeVisible()` |
+| `expect(locator).not.toHaveText('Error')` |
+
+## Screenshot Assertions
+
+| Assertion | Description | Example |
+|-----------|-------------|---------|
+| `toHaveScreenshot(name?)` | Visual regression | `await expect(page).toHaveScreenshot('home.png')` |
+| Options | mask, maxDiffPixels | `await expect(page).toHaveScreenshot({ mask: [locator] })` |
+
+## Common Patterns
+
+```typescript
+// Wait for element and assert
+await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+
+// Assert list length
+await expect(page.getByRole('listitem')).toHaveCount(3);
+
+// Assert input value
+await expect(page.getByLabel('Search')).toHaveValue('query');
+
+// Assert URL after action
+await expect(page).toHaveURL(/\/users\/\d+/);
+
+// Assert disabled state
+await expect(page.getByRole('button', { name: 'Submit' })).toBeDisabled();
+```

package/skills/qa-playwright-ts-writer/references/best-practices.md

@@ -0,0 +1,191 @@
+# Playwright Best Practices
+
+Guidelines for maintainable, stable Playwright tests.
+
+## Page Object Model (POM)
+
+### Structure
+
+```
+pages/
+  BasePage.ts      # Shared navigation, common helpers
+  LoginPage.ts     # Login-specific locators and methods
+  DashboardPage.ts # Dashboard-specific
+components/
+  Header.ts       # Reusable header component
+  Modal.ts        # Reusable modal
+```
+
+### Base Page
+
+```typescript
+// pages/BasePage.ts
+import { Page } from '@playwright/test';
+
+export class BasePage {
+  constructor(protected page: Page, protected baseURL: string) {}
+
+  async goto(path: string) {
+    await this.page.goto(`${this.baseURL}${path}`);
+  }
+
+  getByTestId(id: string) {
+    return this.page.getByTestId(id);
+  }
+}
+```
+
+### Page-Specific Class
+
+```typescript
+// pages/LoginPage.ts
+import { Page } from '@playwright/test';
+import { BasePage } from './BasePage';
+
+export class LoginPage extends BasePage {
+  constructor(page: Page, baseURL: string) {
+    super(page, baseURL);
+  }
+
+  async login(email: string, password: string) {
+    await this.page.getByLabel('Email').fill(email);
+    await this.page.getByLabel('Password').fill(password);
+    await this.page.getByRole('button', { name: 'Sign in' }).click();
+  }
+
+  get errorMessage() {
+    return this.page.getByRole('alert');
+  }
+}
+```
+
+### Usage in Tests
+
+```typescript
+test('login flow', async ({ page }) => {
+  const loginPage = new LoginPage(page, baseURL);
+  await loginPage.goto('/login');
+  await loginPage.login('user@example.com', 'secret');
+  await expect(loginPage.errorMessage).not.toBeVisible();
+});
+```
+
+## Locator Strategies
+
+### Priority Order
+
+1. **getByRole** — Best for accessibility; resilient to DOM changes
+2. **getByTestId** — Explicit, stable; requires adding data-testid
+3. **getByText** — For unique visible text
+4. **getByLabel** — For form inputs with labels
+5. **CSS selector** — Last resort; brittle
+
+### Examples
+
+```typescript
+// Prefer
+page.getByRole('button', { name: 'Submit' })
+page.getByTestId('submit-btn')
+page.getByLabel('Email address')
+page.getByText('Welcome back')
+
+// Avoid when possible
+page.locator('.btn-primary')
+page.locator('#submit')
+page.locator('div > span:nth-child(2)')
+```
+
+## Avoiding Flakiness
+
+| Practice | Description |
+|----------|-------------|
+| **Auto-wait** | Playwright auto-waits; avoid `page.waitForTimeout` |
+| **Assert before act** | Use `expect` to wait for readiness before clicking |
+| **Stable selectors** | Prefer role/testid over CSS |
+| **Isolation** | Each test gets fresh context; no shared state |
+| **Deterministic data** | Use fixtures, mocks; avoid time-dependent data |
+| **No fixed delays** | Use `expect` with timeout or `waitFor` instead of `setTimeout` |
+
+### Anti-Patterns
+
+```typescript
+// BAD: Fixed delay
+await page.waitForTimeout(3000);
+
+// GOOD: Wait for element
+await expect(page.getByRole('heading')).toBeVisible();
+
+// BAD: Brittle CSS
+await page.locator('div.container > div:nth-child(2) button').click();
+
+// GOOD: Role or testid
+await page.getByRole('button', { name: 'Save' }).click();
+```
+
+## Test Isolation
+
+- Each test runs in a new browser context (default)
+- No shared cookies, localStorage, or session
+- Use `storageState` for auth when needed; create fresh per test or reuse via project
+- Clean up test data in `afterEach` if tests create DB records
+
+## Parallel Execution
+
+- `fullyParallel: true` — Run tests in parallel (default for many projects)
+- `workers` — Number of parallel workers; reduce in CI if flaky
+- Avoid shared resources (files, DB rows) that can conflict
+
+## Debugging
+
+| Tool | Use |
+|------|-----|
+| `--debug` | Pause and step through |
+| `--headed` | Run with visible browser |
+| `page.pause()` | Breakpoint in code |
+| Trace viewer | `npx playwright show-trace trace.zip` |
+| Screenshot on failure | `screenshot: 'only-on-failure'` |
+| Video on failure | `video: 'retain-on-failure'` |
+
+## Fixtures and test.extend
+
+```typescript
+import { test as base } from '@playwright/test';
+
+export const test = base.extend<{ authenticatedPage: Page }>({
+  authenticatedPage: async ({ page }, use) => {
+    // Login logic
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('secret');
+    await page.getByRole('button', { name: 'Sign in' }).click();
+    await page.waitForURL(/dashboard/);
+    await use(page);
+  },
+});
+
+test('authenticated flow', async ({ authenticatedPage }) => {
+  await authenticatedPage.goto('/settings');
+  // ...
+});
+```
+
+## test.step for Grouping
+
+```typescript
+test('checkout flow', async ({ page }) => {
+  await test.step('add item to cart', async () => {
+    await page.goto('/products/1');
+    await page.getByRole('button', { name: 'Add to cart' }).click();
+  });
+  await test.step('proceed to checkout', async () => {
+    await page.getByRole('link', { name: 'Cart' }).click();
+    await page.getByRole('button', { name: 'Checkout' }).click();
+  });
+  await test.step('complete payment', async () => {
+    await page.getByLabel('Card number').fill('4111111111111111');
+    await page.getByRole('button', { name: 'Pay' }).click();
+  });
+});
+```
+
+Steps appear in traces and reports for easier debugging.