From qa-web-e2e
Authors Playwright E2E tests across Chromium, Firefox, WebKit - `npm init playwright@latest` scaffolding, `playwright.config.ts` projects per browser/device, accessibility-first locators (`getByRole`/`getByLabelText` per the e2e-selector convention), Page Object pattern, trace viewer for debugging, parallel + sharded execution, HTML reporter for CI. Per Playwright''''s docs: "an end-to-end test framework for modern web apps. It bundles test runner, assertions, isolation, parallelization and rich tooling.
How this skill is triggered — by the user, by Claude, or both
Slash command
/qa-web-e2e:playwright-testingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Per [pw-intro][pwi]:
Per pw-intro:
"Playwright Test is an end-to-end test framework for modern web apps. It bundles test runner, assertions, isolation, parallelization and rich tooling."
"The framework supports Chromium, WebKit, and Firefox across Windows, Linux, and macOS." (pw-intro)
browser-matrix-runner) - Playwright's three-engine support is the differentiator.selenium-testing).Per pw-intro:
npm init playwright@latest
The init prompts choose TypeScript/JavaScript, tests folder, GitHub Actions CI, and browser binaries.
What lands: playwright.config.ts + tests/example.spec.ts +
package.json updates.
import { test, expect } from '@playwright/test';
test('checkout flow happy path', async ({ page }) => {
await page.goto('/');
await page.getByRole('link', { name: /sign in/i }).click();
await page.getByLabel('Email').fill('[email protected]');
await page.getByLabel('Password').fill('test-password');
await page.getByRole('button', { name: /sign in/i }).click();
await expect(page.getByRole('heading', { name: /welcome/i })).toBeVisible();
await page.getByRole('link', { name: /shop/i }).click();
await page.getByRole('link', { name: /BOOK-001/i }).click();
await page.getByRole('button', { name: /add to cart/i }).click();
await expect(page.getByTestId('cart-count')).toHaveText('1');
});
Per e2e-selector-quality-critic:
prefer getByRole / getByLabelText / getByText over CSS class
/ XPath. Web-first assertions (await expect(...)) auto-wait
within the test timeout.
// tests/page-objects/CheckoutPage.ts
import { Page, expect } from '@playwright/test';
export class CheckoutPage {
constructor(private page: Page) {}
async signIn(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/i }).click();
}
async addToCart(sku: string) {
await this.page.getByRole('link', { name: new RegExp(sku, 'i') }).click();
await this.page.getByRole('button', { name: /add to cart/i }).click();
}
async expectConfirmation() {
await expect(this.page.getByRole('heading', { name: /order confirmed/i })).toBeVisible();
}
}
Tests import the Page Object:
test('checkout', async ({ page }) => {
const checkout = new CheckoutPage(page);
await checkout.signIn('[email protected]', 'pwd');
await checkout.addToCart('BOOK-001');
await checkout.expectConfirmation();
});
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
fullyParallel: true,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 4 : undefined,
reporter: [
['html'],
['junit', { outputFile: 'reports/junit.xml' }],
],
use: {
baseURL: process.env.BASE_URL || 'http://localhost:3000',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
},
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
],
});
trace: 'on-first-retry' captures rich debug info (DOM snapshots,
network, console) only when needed - avoids storage cost on
passing runs.
Per pw-intro:
# All tests, all browsers, headless, parallel
npx playwright test
# Specific browser
npx playwright test --project=chromium
# Headed (see the browser)
npx playwright test --headed
# UI Mode (watch + debug)
npx playwright test --ui
# Single test file
npx playwright test tests/checkout.spec.ts
# Single test by name
npx playwright test -g "checkout flow"
When a test fails, the trace contains everything needed to debug:
# After a failure
npx playwright show-trace test-results/<...>/trace.zip
The viewer shows:
For large suites:
# Run 4 of 4 shards (one per CI job)
npx playwright test --shard=1/4
npx playwright test --shard=2/4
# ... etc.
# CI matrix
strategy:
matrix:
shard: [1/4, 2/4, 3/4, 4/4]
runs-on: ubuntu-latest
steps:
- run: npx playwright test --shard=${{ matrix.shard }}
# .github/workflows/playwright.yml
jobs:
test:
timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v4
with: { node-version: '22' }
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
- uses: actions/upload-artifact@v4
if: always()
with:
name: playwright-report
path: playwright-report/
Per pw-intro: "The HTML Reporter provides a filterable dashboard showing results by browser, status (passed/failed/skipped), and flaky tests."
npx playwright show-report
For programmatic / CI consumption, the JUnit reporter (Step 4)
feeds junit-xml-analysis.
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| CSS-class / XPath selectors | Brittle to DOM changes. | getByRole / getByLabelText per e2e-selector-quality-critic. |
page.waitForTimeout(2000) | Flaky on slow CI; slow on fast. | Web-first assertions (auto-wait). |
| One mega-test that spans multiple flows | Failure mid-test obscures cause. | Per-flow tests; share setup via Page Objects. |
Skipping --with-deps in CI | Linux runner missing browser deps. | Always --with-deps (Step 8). |
trace: 'on' always | Wasted storage on passing runs. | trace: 'on-first-retry' (Step 4). |
browser-matrix-runner);
iOS Safari needs real-device testing.test-pyramid-balancer.npm init playwright@latest, three-engine support, CLI flags, HTML
Reporter.e2e-selector-quality-critic - selector convention.playwright-codegen-reviewer - sibling agent for codegen output review.browser-matrix-runner - cross-browser matrix.junit-xml-analysis - downstream JUnit XML parsing.npx claudepluginhub testland/qa --plugin qa-web-e2eProvides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.