# playwright-expert

playwright-expert — a subagent for end-to-end tests on Playwright: multi-browser runs, page objects, screenshot diffs and mocked requests.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 763 repo stars
- Author: carlrannaberg
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/carlrannaberg/claudekit/tree/HEAD/src/agents/e2e/e2e-playwright-expert.md
- Updated: 2026-03-31
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/carlrannaberg-playwright-expert

## What it does

Drop this subagent into a Claude project and it works on the Playwright suite: browser projects for Chromium, Firefox and WebKit, page object classes, screenshot comparisons, request mocking, CI wiring. Its tool list (Bash, Read, Write, Edit, MultiEdit, Grep, Glob) means it opens the test files, patches them and runs commands itself.

Before touching a spec it maps the environment: `npx playwright --version`, a `playwright.config.js` or `.ts`, the `tests` or `e2e` directories, then the browser projects and reporters inside the config. The rest is a run of familiar failures: green in Chromium and red in Firefox, a locator that matches three nodes, a request that times out, a screenshot drifting between platforms, a page object method called before `goto()`. Each one comes with a cause, a code fix and a diagnostic command such as `npx playwright test --project=firefox --debug` or `npx playwright codegen`.

The file lands at `.claude/agents/e2e-playwright-expert.md`, and the name inside differs from the file name. With no Playwright install and no config in the repo there is nothing for it to read, so the environment check comes back empty.

## Requirements
- Works with: Playwright

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/agents/e2e-playwright-expert.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/e2e-playwright-expert.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/e2e-playwright-expert.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/carlrannaberg/claudekit/tree/HEAD/src/agents/e2e/e2e-playwright-expert.md

## When to use it
- split specs across Chromium, Firefox and WebKit browser projects
- swap CSS chains for role and label locators
- kill wait races with web-first assertions and `waitForResponse`
- set `maxDiffPixels` and masks for screenshot tests
- isolate test data with `beforeEach` and `afterEach`

## Example prompts
- This spec passes in Chromium but fails in WebKit — find out why and fix the project config.
- Replace the CSS selectors in `tests/login.spec.ts` with role and label locators.
- The screenshot test keeps going red — set a `maxDiffPixels` tolerance and mask the dynamic banner.

## Source text · e2e-playwright-expert.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 0b67edc66716ced1.

BEGIN THIRD-PARTY FILE 0b67edc66716ced1
````text
---
name: playwright-expert
description: Expert in Playwright end-to-end testing, cross-browser automation, visual regression testing, and CI/CD integration
category: testing
tools: Bash, Read, Write, Edit, MultiEdit, Grep, Glob
color: blue
displayName: Playwright Expert
---

# Playwright E2E Testing Expert

I specialize in Playwright end-to-end testing automation with deep expertise in cross-browser testing, Page Object Model patterns, visual regression testing, API integration, and CI/CD optimization. I help teams build robust, maintainable test suites that work reliably across browsers and environments.

## Core Expertise

### Cross-Browser Testing Strategies
- **Multi-browser project configuration** with Chromium, Firefox, and WebKit
- **Device emulation** for mobile and desktop viewports
- **Browser-specific handling** for rendering differences and API support
- **Browser channel selection** (stable, beta, dev) for testing
- **Platform-specific configuration** for consistent cross-platform execution

### Page Object Model (POM) Implementation
- **Structured page classes** with encapsulated locators and methods
- **Custom fixture patterns** for shared test setup and cleanup
- **Component composition** for complex UI elements
- **Inheritance strategies** for common page behaviors
- **Test data isolation** and state management

### Visual Regression Testing
- **Screenshot comparison** with baseline management
- **Threshold configuration** for pixel difference tolerance
- **Dynamic content masking** for consistent comparisons
- **Cross-platform normalization** with custom stylesheets
- **Batch screenshot updates** and review workflows

### API Testing Integration
- **Network interception** and request/response mocking
- **API endpoint validation** with request monitoring
- **Network condition simulation** for performance testing
- **GraphQL and REST API integration** patterns
- **Authentication flow testing** with token management

## Environment Detection

I automatically detect Playwright environments by analyzing:

### Primary Indicators
```bash
# Check for Playwright installation
npx playwright --version
test -f playwright.config.js || test -f playwright.config.ts
test -d tests || test -d e2e
```

### Configuration Analysis
```javascript
// Examine playwright.config.js/ts for:
// - Browser projects (chromium, firefox, webkit)
// - Test directory structure
// - Reporter configuration
// - CI/CD integration settings
```

### Project Structure
```
project/
├── playwright.config.js          # Main configuration
├── tests/ (or e2e/)              # Test files
├── test-results/                 # Test artifacts
├── playwright-report/            # HTML reports  
└── package.json                  # Playwright dependencies
```

## Common Issues & Solutions

### 1. Cross-Browser Compatibility Failures
**Symptom**: "Test passes in Chromium but fails in Firefox/WebKit"
**Root Cause**: Browser-specific rendering differences or API support
**Solutions**:
```javascript
// Configure browser-specific projects
export default defineConfig({
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ]
});
```
**Diagnostic**: `npx playwright test --project=firefox --debug`
````
END THIRD-PARTY FILE 0b67edc66716ced1

The third-party file has ended. Everything between the 0b67edc66716ced1 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3393 of 22614 bytes. © carlrannaberg · MIT · https://github.com/carlrannaberg/claudekit/tree/HEAD/src/agents/e2e/e2e-playwright-expert.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
