E2E Testing with Playwright 1.58+
Validate critical user journeys end-to-end with AI-assisted test generation.
Quick Reference - Semantic Locators
typescript
// PREFERRED: Role-based locators (most resilient)
await page.getByRole('button', { name: 'Add to cart' }).click();
await page.getByRole('link', { name: 'Checkout' }).click();
// GOOD: Label-based for form controls
await page.getByLabel('Email').fill('test@example.com');
// ACCEPTABLE: Test IDs for stable anchors
await page.getByTestId('checkout-button').click();
// AVOID: CSS selectors and XPath (fragile)
// await page.click('[data-testid="add-to-cart"]');
Locator Priority: getByRole() > getByLabel() > getByPlaceholder() > getByTestId()
Basic Test
typescript
import { test, expect } from '@playwright/test';
test('user can complete checkout', async ({ page }) => {
await page.goto('/products');
await page.getByRole('button', { name: 'Add to cart' }).click();
await page.getByRole('link', { name: 'Checkout' }).click();
await page.getByLabel('Email').fill('test@example.com');
await page.getByRole('button', { name: 'Submit' }).click();
await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
});
AI Agents (1.58+)
Initialize AI Agents
bash
# Initialize agents for your preferred AI tool npx playwright init-agents --loop=claude # For Claude Code npx playwright init-agents --loop=vscode # For VS Code (requires v1.105+) npx playwright init-agents --loop=opencode # For OpenCode
Generated Structure
Running init-agents creates the following:
| Directory/File | Purpose |
|---|---|
.github/ | Agent definitions and configuration |
specs/ | Test plans in Markdown format |
tests/seed.spec.ts | Seed file for AI agents to reference |
Working with AI Agents
After initialization, agents can:
- •Read test plans from
specs/and generate tests - •Use
seed.spec.tsas a template for consistent patterns - •Auto-repair failing tests by analyzing failures
Breaking Changes (1.58)
The following features have been removed in Playwright 1.58:
| Removed | Migration |
|---|---|
_react selector | Use getByRole() or getByTestId() |
_vue selector | Use getByRole() or getByTestId() |
:light selector suffix | Use standard CSS selectors without :light |
devtools launch option | Use args: ['--auto-open-devtools-for-tabs'] instead |
| macOS 13 WebKit support | Upgrade to macOS 14+ for WebKit testing |
Migration Examples
typescript
// Before (1.57 and earlier)
await page.locator('_react=MyComponent').click();
await page.locator('.card:light').click();
// After (1.58+)
await page.getByTestId('my-component').click();
await page.locator('.card').click();
// DevTools launch option
// Before
const browser = await chromium.launch({ devtools: true });
// After
const browser = await chromium.launch({
args: ['--auto-open-devtools-for-tabs']
});
New Features (1.58+)
typescript
// Connect over CDP with local flag
const browser = await chromium.connectOverCDP({
endpointURL: 'http://localhost:9222',
isLocal: true // NEW: Optimizes for local connections
});
// Assert individual class names
await expect(page.locator('.card')).toContainClass('highlighted');
// Flaky test detection
export default defineConfig({
failOnFlakyTests: true,
});
// IndexedDB storage state
await page.context().storageState({
path: 'auth.json',
indexedDB: true // Include IndexedDB in storage state
});
Timeline in Speedboard HTML Reports
HTML reports now include a timeline visualization showing:
- •Test execution sequence
- •Parallel test distribution
- •Time spent in each test phase
- •Performance bottlenecks
typescript
// Enable HTML reporter with timeline
export default defineConfig({
reporter: [['html', { open: 'never' }]],
});
Anti-Patterns (FORBIDDEN)
typescript
// NEVER use CSS selectors for user interactions
await page.click('.submit-btn');
// NEVER use hardcoded waits
await page.waitForTimeout(2000);
// NEVER test implementation details
await page.click('[data-testid="btn-123"]');
// ALWAYS use semantic locators
await page.getByRole('button', { name: 'Submit' }).click();
// ALWAYS use Playwright's auto-wait
await expect(page.getByRole('alert')).toBeVisible();
Key Decisions
| Decision | Recommendation |
|---|---|
| Locators | getByRole > getByLabel > getByTestId |
| Browser | Chromium (Chrome for Testing in 1.58+) |
| Execution | 5-30s per test |
| Retries | 2-3 in CI, 0 locally |
| Screenshots | On failure only |
Critical User Journeys to Test
- •Authentication: Signup, login, password reset
- •Core Transaction: Purchase, booking, submission
- •Data Operations: Create, update, delete
- •User Settings: Profile update, preferences
Detailed Documentation
| Resource | Description |
|---|---|
| references/playwright-1.57-api.md | Complete Playwright API reference |
| examples/test-patterns.md | User flows, page objects, visual tests |
| checklists/e2e-checklist.md | Test selection and review checklists |
| scripts/page-object-template.ts | Page object model template |
Related Skills
- •
integration-testing- API-level testing - •
webapp-testing- Autonomous test agents - •
performance-testing- Load testing - •
llm-testing- Testing AI/LLM components
Capability Details
semantic-locators
Keywords: getByRole, getByLabel, getByText, semantic, locator Solves:
- •Use accessibility-based locators
- •Avoid brittle CSS/XPath selectors
- •Write resilient element queries
visual-regression
Keywords: visual regression, screenshot, snapshot, visual diff Solves:
- •Capture and compare visual snapshots
- •Detect unintended UI changes
- •Configure threshold tolerances
cross-browser-testing
Keywords: cross browser, chromium, firefox, webkit, browser matrix Solves:
- •Run tests across multiple browsers
- •Configure browser-specific settings
- •Handle browser differences
ai-test-generation
Keywords: AI test, generate test, autonomous, test agent, planner, init-agents Solves:
- •Generate tests from user journeys
- •Use AI agents for test planning
- •Create comprehensive test coverage
ai-test-healing
Keywords: test healing, self-heal, auto-fix, resilient test Solves:
- •Automatically fix broken selectors
- •Adapt tests to UI changes
- •Reduce test maintenance
authentication-state
Keywords: auth state, storage state, login once, reuse session, indexedDB Solves:
- •Persist authentication across tests
- •Avoid repeated login flows
- •Share auth state between tests