playwright-e2e-testing

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: playwright-e2e-testing
description: 'Author and maintain versioned Playwright (@playwright/test) TypeScript UI specs for browser user flows. Use when asked to create, run, debug, or refactor E2E tests, form/navigation/auth flows, responsive checks, UI mocking, fixtures, Page Objects, or visual comparisons. Use api-testing for standalone REST/GraphQL contracts and playwright-cli for live browser sessions. Keywords: E2E spec, Playwright test, POM, fixtures, UI regression.'
license: 'Complete terms in LICENSE.txt'
---

# Playwright E2E Testing (TypeScript)

Comprehensive toolkit for end-to-end testing of web applications using Playwright with TypeScript. Enables robust UI testing, UI-dependent API setup, and responsive design verification following best practices.

> **Activation:** This skill is triggered when authoring or maintaining versioned Playwright UI specs and their test infrastructure.

## When to Use This Skill

- **Write E2E tests** for user flows, forms, navigation, and authentication
- **UI-dependent API setup** via the `request` fixture or network interception
- **Responsive testing** across mobile, tablet, and desktop viewports
- **Debug flaky tests** using traces, screenshots, videos, and Playwright Inspector
- **Setup test infrastructure** with Page Object Model and fixtures
- **Mock/intercept APIs** for isolated, deterministic testing
- **Visual regression testing** with screenshot comparisons

### Do NOT Use For

- Standalone API/contract testing with no browser (use `api-testing`).
- Driving a live browser interactively for exploration or debugging (use `playwright-cli`).
- Governing a large regression suite, tiers, or CI sharding strategy (use `playwright-regression-testing`).
- Selenium/Java browser automation (use `webapp-selenium-testing`).

## Prerequisites

| Requirement     | Details                                             |
| --------------- | --------------------------------------------------- |
| Node.js         | v18+ recommended                                    |
| Package Manager | npm, yarn, or pnpm                                  |
| Playwright      | `@playwright/test` package                          |
| TypeScript      | `typescript` + `ts-node` (optional but recommended) |
| Browsers        | Installed via `npx playwright install`              |

### Quick Setup

```bash
# Initialize new project
npm init playwright@latest

# Or add to existing project
npm install -D @playwright/test
npx playwright install
```

## First Questions to Ask

Before writing tests, clarify:

1. **App URL**: Local dev server command + port, or staging URL?
2. **Critical flows**: Which user journeys must be covered (happy path + error states)?
3. **Browsers/devices**: Chrome, Firefox, Safari? Mobile viewports?
4. **API strategy**: Real backend, mocked responses, or hybrid?
5. **Test data**: Seed data available? Reset/cleanup strategy?

---

## Core Principles

### 1. Test Runner & TypeScript

Always use `@playwright/test` with TypeScript for type safety and better IDE support.

```typescript
import { test, expect } from "@playwright/test";

test("user can login", async ({ page }) => {
  await page.goto("/login");
  await page.getByLabel("Email").fill("[email protected]");
  await page.getByLabel("Password").fill("password123");
  await page.getByRole("button", { name: "Sign in" }).click();
  await expect(page).toHaveURL(/.*dashboard/);
});
```

### 2. Locator Strategy (Priority Order)

Prefer role-based locators (`getByRole`) with accessible names, then label → placeholder → text → test ID → CSS (last resort). XPath is never used.

➡️ **Full priority hierarchy, role reference, and examples:** [Locator Strategies: Priority](./references/locator-strategies-priority.md) — the single source of truth.

### 3. Auto-Waiting & Web-First Assertions

Playwright auto-waits for elements. Never use `sleep()` or arbitrary timeouts.

```typescript
// [ok] Web-first assertions (auto-retry)
await expect(page.getByRole("