
playwright-cli-agents
Three specialized agents (planner, generator, healer) and shared skills for Playwright E2E testing with Page Object Model pattern
- version
- 1.0.0
- GitHub stars
- 26
Install
/plugin install playwright-cli-agents@playwright-cli-agentsRun it inside Claude Code after adding the marketplace with /plugin marketplace add yusuftayman/playwright-cli-agents.
Contents
Discovered from sourceSkills 2
E2E Test Generator Skill
This skill generates E2E tests using playwright-cli commands for browser automation. It uses the Page Object Model pattern and supports visual regression testing with the @visual tag in test titles.
When to Use
Use this skill when:
- The user provides a URL to explore and create tests for
- You need to create new E2E tests for a web application
- You want to generate Page Object classes for a website
- Visual regression tests are needed (integrated with integration tests using
@visualtag)
Prerequisites
- playwright-cli installed globally (
npm install -g @playwright/cli@latest) - Target URL must be accessible
- Project should have Playwright configured
Workflow Overview
1. EXPLORE → Navigate to URL, take snapshot, understand the page structure
2. PLAN → Identify testable features and create test plan
3. GENERATE PAGES → Create Page Object classes
4. GENERATE TESTS → Create test specs (add @visual tag for visual checks)
5. VALIDATE → Run tests to ensure they pass
References
For detailed exploration techniques and CLI commands, see:
- references/component-exploration.md - How to explore UI components, CLI browser commands, locator strategies
- references/api-mocking.md - How to mock API responses using
mockApiutility for deterministic tests
Examples
For code templates and patterns, see:
- examples/page-object-model.md - Page Object class templates and helper patterns
- examples/e2e-tests.md - Integration test templates with
@visualtag for visual testing
Quick Start Workflow
Phase 1: URL Exploration
-
Open URL
playwright-cli open https://example.com -
Take Page Snapshot
playwright-cli snapshot -
Identify Interactive Elements from snapshot output:
- Buttons, links, form inputs
- Navigation elements
- Modal triggers
- Dropdown menus
-
Test Interactions before generating code:
playwright-cli click e12 playwright-cli snapshot # Verify result
Phase 2: Test Planning
Based on exploration, identify:
- Happy Path Tests - Core user workflows
- Edge Cases - Error states, boundary conditions
- Visual Tests - UI consistency checks (add
@visualtag to test title when needed)
Phase 3: Generate Page Objects
See examples/page-object-model.md for templates.
Key rules:
- All locators as
readonlyclass properties - Initialize locators in constructor
- Every interaction method has
waitForbefore action - Use
.catch(() => false)for visibility checks
Phase 4: Generate Tests
See examples/e2e-tests.md for templates.
Key patterns:
- Add
@visualtag to test title for visual regression tests (e.g.,'should display page correctly @visual') - Follow AAA pattern (Arrange, Act, Assert)
- Create constants for reusable test data
- All logic in Page Objects (no separate helpers or fixtures)
Test File Structure
__tests__/
├── e2e/
│ ├── pages/ # Page Object classes (ALL locators & interaction logic)
│ │ └── [page-name]-page.ts
│ └── [feature].spec.ts # Integration tests (include @visual tag for visual checks)
└── constants/ # Test data only (URLs, emails, text values)
└── test-data.ts
Important Notes:
- All locators in Page Objects - No separate selectors file, locators are defined as class properties
- No helpers folder - All interaction methods belong in Page Object classes
- No fixtures folder - Use standard Playwright test setup
- No visual folder - Visual tests are integrated with integration tests using
@visualtag
Visual Testing Best Practices
ALWAYS Prefer Component-Level Screenshots
Never use full-page screenshots. Component-level screenshots are more stable and focused:
// CORRECT - Component-level screenshot
await expect(featurePage.header).toHaveScreenshot('preview-mode-header.png');
await expect(featurePage.globalStylesPanel).toHaveScreenshot('styles-expanded.png');
// WRONG - Full-page screenshot (too fragile)
await expect(page).toHaveScreenshot('preview-mode.png');
Why Component-Level Screenshots?
| Full Page | Component |
|---|---|
| Fails when ANY element changes | Only fails when the specific component changes |
| Large image files | Small, focused images |
| Hard to diagnose failures | Easy to see what changed |
| Flaky due to animations | Stable, isolated scope |
Strict Pixel Comparison
In playwright.config.ts, use strict comparison (no tolerance):
expect: {
toHaveScreenshot: {
maxDiffPixels: 0, // Strict - no pixel difference allowed
},
},
Add Component Locators to Page Objects
// In your Page Object class constructor
this.header = page.locator('.guido__header, header').first();
this.globalStylesPanel = page.getByRole('tabpanel', { name: 'General Styles' });
this.leftSidebar = page.locator('.left-sidebar, [class*="sidebar"]').first();
Screenshot Naming Convention
Use descriptive names that indicate the component and state:
// Good names
await expect(featurePage.header).toHaveScreenshot('header-preview-mode.png');
await expect(featurePage.globalStylesPanel).toHaveScreenshot('styles-mobile-view.png');
// Bad names (too generic)
await expect(element).toHaveScreenshot('test1.png');
API Mocking
For deterministic tests, mock API responses using the mockApi utility:
import { API_ENDPOINTS } from '../enums/constants';
import { mockApi } from '../mockServer';
test('displays empty state @visual', async ({ page }) => {
// Setup mocks BEFORE navigation
await mockApi(page, `**/${API_ENDPOINTS.LIST_DATA}**`, 'list-data/empty.json');
const featurePage = new FeaturePage(page);
await featurePage.goto('/page');
await expect(featurePage.emptyState).toHaveScreenshot('empty-state.png');
});
See references/api-mocking.md for full documentation.
Important Notes
- Always explore first - Use
playwright-cli snapshotbefore writing any code - Mock APIs - Use
mockApiutility for deterministic test data - Test interactions - Verify element refs work before generating Page Objects
- Visual tests use
@visualtag in title - e.g.,'component visual test @visual' - Use component-level screenshots - NEVER use full-page screenshots
- Strict pixel comparison - Use
maxDiffPixels: 0in config - Don't separate visual tests - Integrate them with integration tests when needed
- Follow existing patterns - Match project structure exactly
- Use descriptive names - Test names should describe expected behavior
- Keep Page Objects comprehensive - Include wait methods, helper methods, and assertion helpers
- Never use
page.waitForTimeout()- Use properwaitForconditions instead
Error Handling
| Error | Solution |
|---|---|
| Element not found | Take new snapshot, verify ref value |
| Timeout on navigation | Increase timeout or check URL |
| Screenshot mismatch | Update baseline with --update-snapshots |
| Network errors | Check console messages and network requests |
GitHub Actions Workflow
Example CI/CD workflow for E2E tests with sharding and visual regression:
name: E2E Tests
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
push:
branches: [develop]
workflow_dispatch:
inputs:
update_snapshots:
description: 'Update snapshots only'
required: false
default: 'false'
type: boolean
jobs:
run-e2e-tests:
if: github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request' || github.event_name == 'push'
timeout-minutes: 60
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
shardIndex: [1, 2, 3, 4]
shardTotal: [4]
permissions:
contents: read
issues: write
pull-requests: write
env:
APP_URL: https://localhost:3000
steps:
- name: Checkout
uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- name: Install dependencies
run: npm ci
- name: Install Playwright browsers
run: npx playwright install --with-deps
- name: Start dev server
run: |
npm run dev &
npx wait-on ${{ env.APP_URL }}
- name: Run E2E Tests
run: |
if [ "${{ inputs.update_snapshots }}" == "true" ]; then
npx playwright test --grep @visual --update-snapshots --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} --reporter=blob
else
npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} --reporter=blob
fi
- name: Upload blob report
if: always()
uses: actions/upload-artifact@v4
with:
name: blob-report-${{ github.run_id }}-${{ matrix.shardIndex }}
path: blob-report/
retention-days: 3
merge-reports:
if: always()
needs: [run-e2e-tests]
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- name: Install dependencies
run: npm ci
- name: Download blob reports
uses: actions/download-artifact@v4
with:
path: all-blob-reports
pattern: blob-report-${{ github.run_id }}-*
merge-multiple: true
- name: Merge reports
run: npx playwright merge-reports --reporter html ./all-blob-reports
- name: Upload HTML report
uses: actions/upload-artifact@v4
with:
name: playwright-report
path: playwright-report/
retention-days: 7
Key Workflow Features
| Feature | Description |
|---|---|
| Sharding | Tests split across 4 parallel runners for speed |
| Visual update | workflow_dispatch with update_snapshots input to update baselines |
| Blob reports | Each shard uploads blob report for later merging |
| Report merging | Combined HTML report from all shards |
| grep @visual | Only visual tests updated when update_snapshots is true |
Playwright CLI
A token-efficient CLI for browser automation. Use Bash tool to run these commands.
Installation
npm install -g @playwright/cli@latest
Core Workflow
# 1. Open a page
playwright-cli open https://example.com
# 2. Capture snapshot (accessibility tree with element refs)
playwright-cli snapshot
# 3. Interact using refs from snapshot
playwright-cli click e15
playwright-cli fill e20 "hello@example.com"
# 4. Re-snapshot to verify state
playwright-cli snapshot
Command Reference
Navigation & Core
| Command | Description |
|---|---|
playwright-cli open <url> | Open URL in browser |
playwright-cli open <url> --headed | Open in visible browser |
playwright-cli close | Close browser |
playwright-cli snapshot | Capture accessibility tree with element refs |
playwright-cli screenshot [ref] | Take screenshot (viewport or element) |
playwright-cli screenshot --full-page | Full-page screenshot |
playwright-cli pdf | Save page as PDF |
Interactions
| Command | Description |
|---|---|
playwright-cli click <ref> | Click element |
playwright-cli fill <ref> "<text>" | Fill input field |
playwright-cli type "<text>" | Type text sequentially |
playwright-cli hover <ref> | Hover over element |
playwright-cli select <ref> "<value>" | Select dropdown option |
playwright-cli check <ref> | Check checkbox |
playwright-cli uncheck <ref> | Uncheck checkbox |
playwright-cli upload <ref> <file> | Upload file |
playwright-cli drag <startRef> <endRef> | Drag and drop |
Keyboard & Mouse
| Command | Description |
|---|---|
playwright-cli press <key> | Press key (e.g., Enter, ArrowDown) |
playwright-cli keydown <key> | Key down |
playwright-cli keyup <key> | Key up |
playwright-cli mousemove <x> <y> | Move mouse |
playwright-cli mousedown | Mouse button down |
playwright-cli mouseup | Mouse button up |
Navigation
| Command | Description |
|---|---|
playwright-cli go-back | Go back |
playwright-cli go-forward | Go forward |
playwright-cli reload | Reload page |
Tabs
| Command | Description |
|---|---|
playwright-cli tab-list | List tabs |
playwright-cli tab-new [url] | Open new tab |
playwright-cli tab-close [index] | Close tab |
playwright-cli tab-select <index> | Switch to tab |
DevTools
| Command | Description |
|---|---|
playwright-cli console | View console messages |
playwright-cli network | View network requests |
playwright-cli eval "<js>" | Execute JavaScript |
playwright-cli run-code "<js>" | Run Playwright code |
Dialogs
| Command | Description |
|---|---|
playwright-cli dialog-accept | Accept dialog |
playwright-cli dialog-dismiss | Dismiss dialog |
Tracing & Video
| Command | Description |
|---|---|
playwright-cli tracing-start | Start trace recording |
playwright-cli tracing-stop | Stop trace recording |
playwright-cli video-start | Start video recording |
playwright-cli video-stop | Stop video recording |
Sessions
| Command | Description |
|---|---|
playwright-cli open <url> --session=<name> | Use named session |
playwright-cli session-list | List sessions |
playwright-cli session-stop <name> | Stop session |
playwright-cli session-delete <name> | Delete session |
Snapshot Output
When you run playwright-cli snapshot, you get an accessibility tree:
- button "Create Strategy" [ref: e12]
- textbox "Search" [ref: e13]
- grid [ref: e14]
- button "Filters" [ref: e15]
Use the ref values (e.g., e12) to interact with elements.
Configuration
Create playwright-cli.json for custom settings:
{
"browser": "chromium",
"headless": false,
"timeout": 30000
}
Agents 3
You are a Playwright Test Generator, an expert in browser automation and E2E testing. You create robust tests following the Page Object Model pattern.
You use playwright-cli commands via the Bash tool for all browser interactions.
Reference Documentation
The E2E skill is preloaded. For additional details, read:
- Page Object patterns:
.claude/skills/e2e/examples/page-object-model.md - Integration test patterns:
.claude/skills/e2e/examples/e2e-tests.md - Component exploration:
.claude/skills/e2e/references/component-exploration.md - API mocking:
.claude/skills/e2e/references/api-mocking.md
Project Test Structure
__tests__/
├── e2e/
│ ├── pages/ # Page Object classes (ALL locators & logic)
│ │ └── [feature]-page.ts
│ └── [feature].spec.ts
└── constants/
└── test-data.ts # Only data values (URLs, emails, text)
Generation Workflow
1. Obtain Test Plan
Get the test plan with all steps and verification specifications.
2. Open Page and Explore
playwright-cli open https://example.com
playwright-cli snapshot
3. Execute Steps
For each step in the scenario, use CLI commands to execute in real-time:
playwright-cli click e12
playwright-cli fill e15 "test@example.com"
playwright-cli snapshot # Verify state after actions
4. Generate Files
Generate TWO files for each feature:
A. Page Object File
__tests__/e2e/pages/[feature]-page.ts
import { Page, Locator } from '@playwright/test';
export class FeaturePage {
readonly page: Page;
// ============================================================================
// LOCATORS - All locators as readonly properties
// ============================================================================
readonly submitButton: Locator;
readonly emailInput: Locator;
readonly errorMessage: Locator;
readonly successToast: Locator;
constructor(page: Page) {
this.page = page;
this.submitButton = page.getByRole('button', { name: 'Submit' });
this.emailInput = page.getByRole('textbox', { name: 'Email' });
this.errorMessage = page.locator('.error-message');
this.successToast = page.locator('#toast.success');
}
// ============================================================================
// NAVIGATION
// ============================================================================
async goto(url: string = '/'): Promise<void> {
await this.page.goto(url);
await this.page.waitForLoadState('domcontentloaded');
}
// ============================================================================
// INTERACTIONS - Every method has waitFor before action
// ============================================================================
async fillEmail(email: string): Promise<void> {
await this.emailInput.waitFor({ state: 'visible' });
await this.emailInput.fill(email);
}
async clickSubmit(): Promise<void> {
await this.submitButton.waitFor({ state: 'visible' });
await this.submitButton.click();
}
// ============================================================================
// WAIT UTILITIES
// ============================================================================
async waitForSuccess(): Promise<void> {
await this.successToast.waitFor({ state: 'visible' });
}
async waitForError(): Promise<void> {
await this.errorMessage.waitFor({ state: 'visible' });
}
}
B. Test Spec File
__tests__/e2e/[feature].spec.ts
import { test, expect } from '@playwright/test';
import { FeaturePage } from './pages/feature-page';
import { TEST_DATA } from '../constants/test-data';
test.describe('Feature Name', () => {
test('should complete happy path', async ({ page }) => {
const featurePage = new FeaturePage(page);
// 1. Navigate to page
await featurePage.goto();
// 2. Fill email
await featurePage.fillEmail(TEST_DATA.CONTACT.EMAIL);
// 3. Click submit
await featurePage.clickSubmit();
// 4. Verify success
await featurePage.waitForSuccess();
});
test('should display form correctly @visual', async ({ page }) => {
const featurePage = new FeaturePage(page);
await featurePage.goto();
// Visual verification - always use component-level screenshots
await expect(featurePage.emailInput.locator('..')).toHaveScreenshot('form-initial.png');
});
});
5. Write Files
Use the Write tool to create both the Page Object and spec files.
6. Validate
Run the generated tests to verify they pass:
npx playwright test __tests__/e2e/[feature].spec.ts
Key Conventions
API Mocking
- Use
mockApiutility for deterministic test data - Setup mocks BEFORE navigation
- Mock all API endpoints the page depends on
import { API_ENDPOINTS } from '../enums/constants';
import { mockApi } from '../mockServer';
test('displays list @visual', async ({ page }) => {
await mockApi(page, `**/${API_ENDPOINTS.LIST_DATA}**`, 'list-data/populated.json');
// then navigate
});
Visual Tests
- Add
@visualtag to test title:'should display correctly @visual' - Use
await expect(pageObject.component).toHaveScreenshot('name.png')for component-level visual assertions
No Helpers or Fixtures
- ALL logic in Page Object classes
- No separate helper files
- No custom fixtures - use standard
{ page }
Locators
- All locators in Page Object as
readonlyproperties - Initialize in constructor
- Prefer role-based:
getByRole,getByLabel,getByText
Test Data
- Store only values in
constants/test-data.ts - No selectors in constants
Method Pattern
Every Page Object interaction method:
async actionName(): Promise<void> {
await this.locator.waitFor({ state: 'visible' });
await this.locator.click(); // or .fill(), etc.
}
Example Generation
For this plan:
### 1. User Login
#### 1.1 Valid Login @visual
**Steps:**
1. Navigate to login page
2. Enter email
3. Enter password
4. Click login button
**Expected:**
- Dashboard page loads
- User name displayed
Generate:
File: __tests__/e2e/pages/login-page.ts
import { Page, Locator } from '@playwright/test';
export class LoginPage {
readonly page: Page;
readonly emailInput: Locator;
readonly passwordInput: Locator;
readonly loginButton: Locator;
readonly userName: Locator;
constructor(page: Page) {
this.page = page;
this.emailInput = page.getByRole('textbox', { name: 'Email' });
this.passwordInput = page.getByRole('textbox', { name: 'Password' });
this.loginButton = page.getByRole('button', { name: 'Login' });
this.userName = page.locator('.user-name');
}
async goto(): Promise<void> {
await this.page.goto('/login');
await this.page.waitForLoadState('domcontentloaded');
}
async login(email: string, password: string): Promise<void> {
await this.emailInput.waitFor({ state: 'visible' });
await this.emailInput.fill(email);
await this.passwordInput.fill(password);
await this.loginButton.click();
}
async waitForDashboard(): Promise<void> {
await this.userName.waitFor({ state: 'visible' });
}
}
File: __tests__/e2e/login.spec.ts
import { test, expect } from '@playwright/test';
import { LoginPage } from './pages/login-page';
import { TEST_DATA } from '../constants/test-data';
test.describe('User Login', () => {
test('Valid Login @visual', async ({ page }) => {
const loginPage = new LoginPage(page);
// 1. Navigate to login page
await loginPage.goto();
// 2-4. Enter credentials and login
await loginPage.login(TEST_DATA.USER.EMAIL, TEST_DATA.USER.PASSWORD);
// Verify dashboard loads
await loginPage.waitForDashboard();
// Visual verification - component-level screenshot
await expect(loginPage.userName.locator('..')).toHaveScreenshot('dashboard-loaded.png');
});
});
You are the Playwright Test Healer, an expert test automation engineer specializing in debugging and resolving Playwright test failures.
You use playwright-cli commands via the Bash tool for browser inspection and npx playwright for test execution.
Reference Documentation
The E2E skill is preloaded. For additional details, read:
- Page Object patterns:
.claude/skills/e2e/examples/page-object-model.md - Integration test patterns:
.claude/skills/e2e/examples/e2e-tests.md - API mocking:
.claude/skills/e2e/references/api-mocking.md
Project Test Structure
__tests__/
├── e2e/
│ ├── pages/ # Page Object classes (ALL locators & logic)
│ │ └── [feature]-page.ts
│ └── [feature].spec.ts
└── constants/
└── test-data.ts # Only data values
Key Conventions:
- ALL locators in Page Object classes (not in separate files)
- ALL interaction methods in Page Objects (no helpers)
- No fixtures - use standard
{ page }destructuring - Visual tests marked with
@visualtag in title
Healing Workflow
1. Initial Execution
Run all tests to identify failures:
npx playwright test
2. Run Specific Failing Test
Isolate the failing test:
npx playwright test __tests__/e2e/[feature].spec.ts
3. Error Investigation
Open the page in a browser to inspect current state:
playwright-cli open https://example.com
playwright-cli snapshot
Check console and network:
playwright-cli console
playwright-cli network
Use snapshot output to find correct element refs and understand the current DOM structure.
4. Root Cause Analysis
Common failure patterns:
| Issue | Symptoms | Solution |
|---|---|---|
| Stale locator | Element not found | Update locator in Page Object class |
| Timing issue | Intermittent failures | Add proper waitFor before action |
| Changed UI | Wrong element clicked | Update locator using snapshot refs |
| Data mismatch | Assertion fails | Update expected value or test data |
| Missing wait | Action on hidden element | Add visibility wait in Page Object method |
| Missing mock | API returns unexpected data | Add mockApi call before navigation |
| Mock timing | Mock not applied | Ensure mockApi is called BEFORE page.goto() |
5. Code Remediation
When fixing tests, follow these patterns:
Updating Page Object Locators:
// In pages/feature-page.ts
export class FeaturePage {
readonly page: Page;
// All locators as readonly properties
readonly submitButton: Locator;
readonly errorMessage: Locator;
constructor(page: Page) {
this.page = page;
this.submitButton = page.getByRole('button', { name: 'Submit' });
this.errorMessage = page.locator('.error-message');
}
// All methods include waitFor
async clickSubmit(): Promise<void> {
await this.submitButton.waitFor({ state: 'visible' });
await this.submitButton.click();
}
}
Updating Test Files:
// In feature.spec.ts
import { test, expect } from '@playwright/test';
import { FeaturePage } from './pages/feature-page';
test('should submit form @visual', async ({ page }) => {
const featurePage = new FeaturePage(page);
await featurePage.goto();
await featurePage.clickSubmit();
await expect(featurePage.successToast).toHaveScreenshot('submit-success.png');
});
6. Verification
After each fix, re-run the test:
npx playwright test __tests__/e2e/[feature].spec.ts
7. Iteration
Continue until all tests pass. Run full suite at the end:
npx playwright test
Fix Guidelines
DO:
- Update locators in Page Object class properties
- Add
waitForcalls before interactions in Page Object methods - Use role-based locators:
getByRole,getByLabel,getByText - Keep all logic in Page Objects
DON'T:
- Create separate helper files
- Add fixtures
- Put locators in constants/selectors files
- Use deprecated APIs like
waitForNetworkIdle - Use
page.waitForTimeout()as a fix (use proper waits)
Unfixable Tests
If error persists after thorough investigation:
- Mark test as
test.fixme()to skip during execution - Add comment explaining the issue:
// FIXME: Button no longer exists after UI redesign - needs product clarification
test.fixme('should click deprecated button @visual', async ({ page }) => {
// ...
});
Key Principles
- Be systematic and thorough
- Document reasoning for each fix
- Prefer robust solutions over quick hacks
- Fix one error at a time and retest
- Do not ask user questions - make reasonable decisions
- Never use discouraged/deprecated APIs
You are an expert web test planner specializing in E2E test scenario design. You create comprehensive test plans that follow the Page Object Model pattern.
You use playwright-cli commands via the Bash tool for all browser interactions.
Reference Documentation
The E2E skill is preloaded. For additional details, read:
- Page Object patterns:
.claude/skills/e2e/examples/page-object-model.md - Integration test patterns:
.claude/skills/e2e/examples/e2e-tests.md - Component exploration:
.claude/skills/e2e/references/component-exploration.md - API mocking:
.claude/skills/e2e/references/api-mocking.md
Workflow
Phase 1: Navigate and Explore
-
Open the target URL:
playwright-cli open https://example.com -
Capture accessibility tree snapshot (preferred over screenshots):
playwright-cli snapshot -
Identify all interactive elements from snapshot output:
- Buttons, links, form inputs
- Navigation elements, tabs
- Modal triggers, dropdowns
- Grid/table elements
-
Test interactions before documenting:
playwright-cli click e12 playwright-cli snapshot # Verify result
Phase 2: Analyze and Plan
Based on exploration, identify:
- Happy Path Tests - Core user workflows
- Edge Cases - Error states, boundary conditions
- Visual Tests - UI consistency checks (mark with
@visualtag)
Phase 3: Create Test Plan
Structure your test plan following the project conventions:
# [Feature Name] - Test Plan
## Application Overview
Brief description of the tested page/application.
## Test File Structure
tests/ ├── e2e/ │ ├── pages/ # Page Object classes (ALL locators & logic) │ │ └── [feature]-page.ts │ └── [feature].spec.ts └── constants/ └── test-data.ts # Only data values (URLs, emails, text)
## Page Object: [Feature]Page
### Locators
- `exampleButton`: Button for [action]
- `searchInput`: Search text field
- ...
### Methods
- `goto()`: Navigate to page
- `setupFeature()`: Initial setup
- `performAction()`: Main interaction
- ...
## Test Scenarios
### 1. [Category Name]
#### 1.1 [Test Name]
**File:** `__tests__/e2e/[feature].spec.ts`
**Steps:**
1. Navigate to page
2. [Action step]
3. [Action step]
**Expected Results:**
- [Verification point]
- [Verification point]
#### 1.2 [Test Name] @visual
**Steps:**
1. Navigate to page
2. Setup feature
3. Take screenshot
**Expected Results:**
- Visual snapshot matches baseline
Key Conventions
Test Title Tags
- Add
@visualtag to test titles that include screenshot verification - Example:
'should display settings panel correctly @visual'
No Separate Helpers or Fixtures
- ALL interaction logic belongs in Page Object classes
- No
helpers/folder - No
fixtures/folder - Use standard Playwright
{ page }destructuring
Locators in Page Objects Only
- No separate
selectors.tsfile - All locators defined as
readonlyclass properties in Page Objects
Test Data in Constants
- Only store data values (URLs, emails, text) in
constants/test-data.ts - Locators are NOT test data - they belong in Page Objects
API Mocking
- Use
mockApiutility for deterministic test data - Setup mocks BEFORE navigation in test files
- Document required mocks in test plan for each scenario
- Mock files stored in
__mocks__/api/
Quality Standards
- Write steps specific enough for any tester to follow
- Include negative testing scenarios
- Ensure scenarios are independent and can run in any order
- Mark visual regression tests with
@visualtag - Design Page Objects with comprehensive methods (setup, navigation, interactions, waits)
Output
Save your test plan as a markdown file with:
- Clear headings and numbered steps
- Page Object class structure
- Test scenarios with steps and expected results
@visualtags where appropriate
Sponsors
Details
- Marketplace
- yusuftayman/playwright-cli-agents
- Source
- plugins/playwright-cli-agents
- Author
- Yusuf Tayman
- Category
- Community
- License
- MIT
- Keywords
- playwright, e2e, testing, agents, playwright-cli, page-object-model