e2e-testing

Constraints

• Apply @rules/code-testing/general.mdc for the deterministic-test contract: tests must be reliable, isolated, and free of arbitrary sleeps.
• GATED skill: proceed only when the consuming project already ships Playwright. Never install Playwright unprompted.
• Stable selectors over brittle ones: prefer role and data-testid over CSS/structure.
• No arbitrary waitForTimeout. Rely on auto-waiting locators and explicit conditions.

Use when

• Writing Playwright E2E browser tests for a Laravel app.
• Stabilizing flaky Playwright tests.
• Wiring Playwright into CI against the app under test.

Preconditions (run first, do not skip)

Check whether Playwright is actually present:

ls playwright.config.* 2>/dev/null
grep -q '@playwright/test' package.json 2>/dev/null && echo "playwright present"

• If neither a playwright.config.* file nor @playwright/test in package.json exists, STOP. Do not install Playwright. Defer to:
  • @skills/test-like-human/SKILL.md for manual, scenario-based testing, or
  • Pest feature tests / Laravel Dusk for browser coverage inside the PHP stack.
• Only when Playwright IS present, continue with the patterns below.

File organization

tests/
  e2e/
    auth/login.spec.ts
    features/search.spec.ts
  pages/
    ItemsPage.ts
  fixtures/
    auth.ts
playwright.config.ts

Page Object Model

Encapsulate page structure so specs read as behavior, not selectors.

import { Page, Locator } from '@playwright/test'

export class ItemsPage {
  readonly page: Page
  readonly searchInput: Locator
  readonly itemCards: Locator
  readonly createButton: Locator

  constructor(page: Page) {
    this.page = page
    // Prefer role/test-id selectors. data-testid is stable across restyles.
    this.searchInput = page.getByTestId('search-input')
    this.itemCards = page.getByTestId('item-card')
    this.createButton = page.getByRole('button', { name: 'Create' })
  }

  async goto() {
    await this.page.goto('/items')
  }

  async search(query: string) {
    await this.searchInput.fill(query)
    // Wait for the real response, not a fixed delay.
    await this.page.waitForResponse(r => r.url().includes('/items') && r.ok())
  }

  itemCount() {
    return this.itemCards.count()
  }
}