playwright-pro

---
name: playwright-pro
description: Use when creating, fixing, or migrating Playwright tests; end-to-end testing; browser automation; or evaluating test coverage across frameworks.
category: Engineering
version: 1.0.0
tools: []
---

# Playwright Pro

**Tier:** POWERFUL  
**Domain:** Testing

Production-grade Playwright testing toolkit.

## Available Workflows

| Task | Workflow |
|---|---|
| Initialize | Detect framework, generate config, CI pipeline, first smoke test |
| Generate tests | From user story, URL, or component spec |
| Review tests | Validate quality and flag anti-patterns |
| Fix tests | Diagnose and repair failing or flaky tests |
| Migrate | Convert from Cypress or Selenium to Playwright |
| Coverage | Analyze what's tested vs. missing |
| Sync | Integrate with TestRail (read cases, push results) |
| Cross-browser | Run on BrowserStack, pull cross-browser reports |
| Report | Generate test report in preferred format |

## Quick Start

Recommended sequence:

1. Initialize — scaffolds config, CI pipeline, first smoke test
2. Generate — create tests from spec or URL
3. Review — validate quality and flag anti-patterns (always run after generate)
4. Fix — diagnose and repair failing/flaky tests (run when CI turns red)

## Golden Rules

1. `getByRole()` over CSS/XPath — resilient to markup changes
2. Never `waitForTimeout()` — use web-first assertions
3. `expect(locator)` auto-retries; `expect(await locator.textContent())` does not
4. Isolate every test — no shared state
5. `baseURL` in config — zero hardcoded URLs
6. Retries: `2` in CI, `0` locally
7. Traces: `'on-first-retry'` — rich debugging without slowdown
8. Fixtures over globals — use `test.extend()` for shared state
9. One behavior per test — multiple assertions fine
10. Mock external services only — never mock your app

## Locator Priority

```
1. getByRole()        — buttons, links, headings, form elements
2. getByLabel()       — form fields with labels
3. getByText()        — non-interactive text
4. getByPlaceholder() — inputs with placeholder
5. getByTestId()      — when no semantic option exists
6. page.locator()     — CSS/XPath as last resort
```

## What's Included

- 55+ test templates (auth, CRUD, checkout, search, forms, dashboard, accessibility)
- 3 specialized agents (architect, debugger, migration-planner)
- TestRail and BrowserStack integrations
- 6 reference docs: golden rules, locators, assertions, fixtures, pitfalls, flaky tests
- Migration guides for Cypress and Selenium