bobmatnyc Playwright E2E Testing Skill
progressive_disclosure: entry_point: summary: "Modern E2E testing framework with cross-browser automation and built-in test runner" when_to_use: - "When testing web applications end-to-end" - "When needing cross-browser testing" - "When testing user flows and interactions" - "When needing screenshot/video recording" quick_start: - "npm init playwright@latest" - "Choose TypeScript and test location" - "npx playwright test" - "npx playwright show-report" token_estimate: entry: 75-90 full: 4200-5200
Overview
Playwright is a modern end-to-end testing framework that provides cross-browser automation with a built-in test runner, auto-wait mechanisms, and excellent developer experience.
Key Features
- Auto-wait: Automatically waits for elements to be ready
- Cross-browser: Chromium, Firefox, WebKit support
- Built-in runner: Parallel execution, retries, reporters
- Network control: Mock and intercept network requests
- Debugging: UI mode, trace viewer, inspector
Installation
# Initialize new Playwright project
npm init playwright@latest
# Or add to existing project
npm install -D @playwright/test
# Install browsers
npx playwright install
Configuration
// 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 ? 1 : undefined,
reporter: 'html',
use: {
baseURL: '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'] },
},
{
name: 'Mobile Chrome',
use: { ...devices['Pixel 5'] },
},
],
webServer: {
command: 'npm run start',
url: 'http://localhost:3000',
reuseExistingServer: !process.env.CI,
},
});
Fundamentals
Basic Test Structure
import { test, expect } from '@playwright/test';
test('basic test', async ({ page }) => {
await page.goto('https://example.com');
// Wait for element and check visibility
const title = page.locator('h1');
await expect(title).toBeVisible();
await expect(title).toHaveText('Example Domain');
// Get page title
await expect(page).toHaveTitle(/Example/);
});
test.describe('User authentication', () => {
test('should login successfully', async ({ page }) => {
await page.goto('/login');
await page.fill('[name="username"]', 'testuser');
await page.fill('[name="password"]', 'password123');
await page.click('button[type="submit"]');
await expect(page).toHaveURL('/dashboard');
await expect(page.locator('.welcome-message')).toContainText('Welcome');
});
test('should show error for invalid credentials', async ({ page }) => {
await page.goto('/login');
await page.fill('[name="username"]', 'invalid');
await page.fill('[name="password"]', 'wrong');
await page.click('button[type="submit"]');
await expect(page.locator('.error-message')).toBeVisible();
await expect(page.locator('.error-message')).toHaveText('Invalid credentials');
});
});
Test Hooks
import { test, expect } from '@playwright/test';
test.describe('Dashboard tests', () => {
test.beforeEach(async ({ page }) => {
// Run before each test
await page.goto('/dashboard');
await page.waitForLoadState('networkidle');
});
test.afterEach(async ({ page }) => {
// Cleanup after each test
await page.close();
});
test.beforeAll(async ({ browser }) => {
// Run once before all tests in describe block
console.log('Starting test suite');
});
test.afterAll(async ({ browser }) => {
// Run once after all tests
console.log('Test suite complete');
});
test('displays user data', async ({ page }) => {
await expect(page.locator('.user-name')).toBeVisible();
});
});
Locator Strategies
Best Practice: Role-based Locators
import { test, expect } from '@playwright/test';
test('accessible locators', async ({ page }) => {
await page.goto('/form');
// By role (BEST - accessible and stable)
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
await page.getByRole('checkbox', { name: 'Subscribe' }).check();
await page.getByRole('link', { name: 'Learn more' }).click();
// By label (good for forms)
await page.getByLabel('Password').fill('secret123');
// By placeholder
await page.getByPlaceholder('Search...').fill('query');
// By text
await page.getByText('Welcome back').click();
await page.getByText(/hello/i).isVisible();
// By test ID (good for dynamic content)
await page.getByTestId('user-profile').click();
// By title
await page.getByTitle('Close dialog').click();
// By alt text (images)
await page.getByAltText('User avatar').click();
});
CSS and XPath Locators
test('CSS and XPath locators', async ({ page }) => {
// CSS selectors
await page.locator('button.primary').click();
await page.locator('#user-menu').click();
await page.locator('[data-testid="submit-btn"]').click();
await page.locator('div.card:first-child').click();
// XPath (use sparingly)
await page.locator('xpath=//button[contains(text(), "Submit")]').click();
// Chaining locators
const form = page.locator('form#login-form');
await form.locator('input[name="email"]').fill('user@example.com');
await form.locator('button[type="submit"]').click();
// Filter locators
await page.getByRole('listitem')
.filter({ hasText: 'Product 1' })
.getByRole('button', { name: 'Add to cart' })
.click();
});
Page Object Model
Page Class Pattern
// pages/LoginPage.ts
import { Page, Locator } from '@playwright/test';
export class LoginPage {
readonly page: Page;
readonly usernameInput: Locator;
readonly passwordInput: Locator;
readonly submitButton: Locator;
readonly errorMessage: Locator;
constructor(page: Page) {
this.page = page;
this.usernameInput = page.getByLabel('Username');
this.passwordInput = page.getByLabel('Password');
this.submitButton = page.getByRole('button', { name: 'Log in' });
this.errorMessage = page.locator('.error-message');
}
async goto() {
await this.page.goto('/login');
}
async login(username: string, password: string) {
await this.usernameInput.fill(username);
await this.passwordInput.fill(password);
await this.submitButton.click();
}
async expectErrorMessage(message: string) {
await this.errorMessage.waitFor({ state: 'visible' });
await expect(this.errorMessage).toHaveText(message);
}
}
// pages/DashboardPage.ts
export class DashboardPage {
readonly page: Page;
readonly welcomeMessage: Locator;
readonly logoutButton: Locator;
constructor(page: Page) {
this.page = page;
this.welcomeMessage = page.locator('.welcome-message');
this.logoutButton = page.getByRole('button', { name: 'Logout' });
}
async waitForLoad() {
await this.welcomeMessage.waitFor({ state: 'visible' });
}
async logout() {
await this.logoutButton.click();
}
}
// tests/auth.spec.ts
import { test, expect } from '@playwright/test';
import { LoginPage } from '../pages/LoginPage';
import { DashboardPage } from '../pages/DashboardPage';
test('successful login flow', async ({ page }) => {
const loginPage = new LoginPage(page);
const dashboard = new DashboardPage(page);
await loginPage.goto();
await loginPage.login('testuser', 'password123');
await dashboard.waitForLoad();
await expect(dashboard.welcomeMessage).toContainText('Welcome');
});
Component Pattern
// components/NavigationComponent.ts
import { Page, Locator } from '@playwright/test';
export class NavigationComponent {
readonly page: Page;
readonly homeLink: Locator;
readonly profileLink: Locator;
readonly searchInput: Locator;
constructor(page: Page) {
this.page = page;
const nav = page.locator('nav');
this.homeLink = nav.getByRole('link', { name: 'Home' });
this.profileLink = nav.getByRole('link', { name: 'Profile' });
this.searchInput = nav.getByPlaceholder('Search...');
}
async navigateToProfile() {
await this.profileLink.click();
}
async search(query: string) {
await this.searchInput.fill(query);
await this.searchInput.press('Enter');
}
}
User Interactions
Form Interactions
test('form interactions', async ({ page }) => {
await page.goto('/form');
// Text inputs
await page.fill('input[name="email"]', 'user@example.com');
await page.type('textarea[name="message"]', 'Hello', { delay: 100 });
// Checkboxes
await page.check('input[type="checkbox"][name="subscribe"]');
await page.uncheck('input[type="checkbox"][name="spam"]');
// Radio buttons
await page.check('input[type="radio"][value="option1"]');
// Select dropdowns
await page.selectOption('select[name="country"]', 'US');
await page.selectOption('select[name="color"]', { label: 'Blue' });
await page.selectOption('select[name="size"]', { value: 'large' });
// Multi-select
await page.selectOption('select[multiple]', ['value1', 'value2']);
// File uploads
await page.setInputFiles('input[type="file"]', 'path/to/file.pdf');
await page.setInputFiles('input[type="file"]', [
'file1.jpg',
'file2.jpg'
]);
// Clear file input
await page.setInputFiles('input[type="file"]', []);
});
Mouse and Keyboard
test('mouse and keyboard interactions', async ({ page }) => {
// Click variations
await page.click('button');
await page.dblclick('button'); // Double click
await page.click('button', { button: 'right' }); // Right click
await page.click('button', { modifiers: ['Shift'] }); // Shift+click
// Hover
await page.hover('.tooltip-trigger');
await expect(page.locator('.tooltip')).toBeVisible();
// Drag and drop
await page.dragAndDrop('#draggable', '#droppable');
// Keyboard
await page.keyboard.press('Enter');
await page.keyboard.press('Control+A');
await page.keyboard.type('Hello World');
await page.keyboard.down('Shift');
await page.keyboard.press('ArrowDown');
await page.keyboard.up('Shift');
// Focus
await page.focus('input[name="email"]');
await page.fill('input[name="email"]', 'test@example.com');
});
Waiting Strategies
test('waiting strategies', async ({ page }) => {
// Wait for element
await page.waitForSelector('.dynamic-content');
await page.waitForSelector('.modal', { state: 'visible' });
await page.waitForSelector('.loading', { state: 'hidden' });
// Wait for load state
await page.waitForLoadState('load');
await page.waitForLoadState('domcontentloaded');
await page.waitForLoadState('networkidle');
// Wait for URL
await page.waitForURL('**/dashboard');
await page.waitForURL(/\/product\/\d+/);
// Wait for function
await page.waitForFunction(() => {
return document.querySelectorAll('.item').length > 5;
});
// Wait for timeout (avoid if possible)
await page.waitForTimeout(1000);
// Wait for event
await page.waitForEvent('load');
await page.waitForEvent('popup');
});
Assertions
Common Assertions
import { test, expect } from '@playwright/test';
test('assertions', async ({ page }) => {
await page.goto('/dashboard');
// Visibility
await expect(page.locator('.header')).toBeVisible();
await expect(page.locator('.loading')).toBeHidden();
await expect(page.locator('.optional')).not.toBeVisible();
// Text content
await expect(page.locator('h1')).toHaveText('Dashboard');
await expect(page.locator('h1')).toContainText('Dash');
await expect(page.locator('.message')).toHaveText(/welcome/i);
// Attributes
await expect(page.locator('button')).toBeEnabled();
await expect(page.locator('button')).toBeDisabled();
await expect(page.locator('input')).toHaveAttribute('type', 'email');
await expect(page.locator('input')).toHaveValue('test@example.com');
// CSS
await expect(page.locator('.button')).toHaveClass('btn-primary');
await expect(page.locator('.button')).toHaveClass(/btn-/);
await expect(page.locator('.element')).toHaveCSS('color', 'rgb(255, 0, 0)');
// Count
await expect(page.locator('.item')).toHaveCount(5);
// URL and title
await expect(page).toHaveURL('http://localhost:3000/dashboard');
await expect(page).toHaveURL(/dashboard$/);
await expect(page).toHaveTitle('Dashboard - My App');
await expect(page).toHaveTitle(/Dashboard/);
// Screenshot comparison
await expect(page).toHaveScreenshot('dashboard.png');
await expect(page.locator('.widget')).toHaveScreenshot('widget.png');
});
Custom Assertions
test('custom matchers', async ({ page }) => {
// Soft assertions (continue test on failure)
await expect.soft(page.locator('.title')).toHaveText('Welcome');
await expect.soft(page.locator('.subtitle')).toBeVisible();
// Multiple elements
const items = page.locator('.item');
await expect(items).toHaveCount(3);
await expect(items.nth(0)).toContainText('First');
await expect(items.nth(1)).toContainText('Second');
// Poll assertions
await expect(async () => {
const response = await page.request.get('/api/status');
expect(response.ok()).toBeTruthy();
}).toPass({
timeout: 10000,
intervals: [1000, 2000, 5000],
});
});
Authentication Patterns
Storage State Pattern
// auth.setup.ts - Run once to save auth state
import { test as setup } from '@playwright/test';
const authFile = 'playwright/.auth/user.json';
setup('authenticate', async ({ page }) => {
await page.goto('/login');
await page.fill('[name="username"]', 'testuser');
await page.fill('[name="password"]', 'password123');
await page.click('button[type="submit"]');
await page.waitForURL('/dashboard');
// Save authentication state
await page.context().storageState({ path: authFile });
});
// playwright.config.ts
export default defineConfig({
projects: [
{
name: 'setup',
testMatch: /.*\.setup\.ts/,
},
{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
storageState: authFile,
},
dependencies: ['setup'],
},
],
});
// tests/dashboard.spec.ts - Already authenticated
test('view dashboard', async ({ page }) => {
await page.goto('/dashboard');
// Already logged in!
await expect(page.locator('.user-menu')).toBeVisible();
});
Multiple User Roles
// fixtures/auth.ts
import { test as base } from '@playwright/test';
type Fixtures = {
adminPage: Page;
userPage: Page;
};
export const test = base.extend<Fixtures>({
adminPage: async ({ browser }, use) => {
const context = await browser.newContext({
storageState: 'playwright/.auth/admin.json',
});
const page = await context.newPage();
await use(page);
await context.close();
},
userPage: async ({ browser }, use) => {
const context = await browser.newContext({
storageState: 'playwright/.auth/user.json',
});
const page = await context.newPage();
await use(page);
await context.close();
},
});
// tests/permissions.spec.ts
import { test } from '../fixtures/auth';
test('admin can access admin panel', async ({ adminPage }) => {
await adminPage.goto('/admin');
await expect(adminPage.locator('.admin-panel')).toBeVisible();
});
test('regular user cannot access admin panel', async ({ userPage }) => {
await userPage.goto('/admin');
await expect(userPage.locator('.access-denied')).toBeVisible();
});
Network Control
Request Mocking
test('mock API responses', async ({ page }) => {
// Mock API response
await page.route('**/api/users', route => {
route.fulfill({
status: 200,
contentType: 'application/json',
body: JSON.stringify({
users: [
{ id: 1, name: 'John Doe' },
{ id: 2, name: 'Jane Smith' },
],
}),
});
});
await page.goto('/users');
await expect(page.locator('.user-list')).toContainText('John Doe');
});
test('mock with conditions', async ({ page }) => {
await page.route('**/api/**', route => {
const url = route.request().url();
if (url.includes('/users/1')) {
route.fulfill({
status: 200,
body: JSON.stringify({ id: 1, name: 'Test User' }),
});
} else if (url.includes('/users')) {
route.fulfill({
status: 200,
body: JSON.stringify({ users: [] }),
});
} else {
route.continue();
}
});
});
test('simulate network errors', async ({ page }) => {
await page.route('**/api/data', route => {
route.abort('failed');
});
await page.goto('/data');
await expect(page.locator('.error-message')).toBeVisible();
});
Request Interception
test('intercept and modify requests', async ({ page }) => {
// Modify request headers
await page.route('**/api/**', route => {
const headers = route.request().headers();
route.continue({
headers: {
...headers,
'X-Custom-Header': 'test-value',
},
});
});
// Modify POST data
await page.route('**/api/submit', route => {
const postData = route.request().postDataJSON();
route.continue({
postData: JSON.stringify({
...postData,
timestamp: Date.now(),
}),
});
});
});
test('wait for API response', async ({ page }) => {
// Wait for specific request
const responsePromise = page.waitForResponse('**/api/users');
await page.click('button#load-users');
const response = await responsePromise;
expect(response.status()).toBe(200);
const data = await response.json();
expect(data.users).toHaveLength(10);
});
Test Organization
Custom Fixtures
// fixtures/todos.ts
import { test as base } from '@playwright/test';
type TodoFixtures = {
todoPage: TodoPage;
createTodo: (title: string) => Promise<void>;
};
export const test = base.extend<TodoFixtures>({
todoPage: async ({ page }, use) => {
const todoPage = new TodoPage(page);
await todoPage.goto();
await use(todoPage);
},
createTodo: async ({ page }, use) => {
const create = async (title: string) => {
await page.fill('.new-todo', title);
await page.press('.new-todo', 'Enter');
};
await use(create);
},
});
// tests/todos.spec.ts
import { test } from '../fixtures/todos';
test('can create new todo', async ({ todoPage, createTodo }) => {
await createTodo('Buy groceries');
await expect(todoPage.todoItems).toHaveCount(1);
await expect(todoPage.todoItems).toHaveText('Buy groceries');
});
Test Tags and Filtering
test('smoke test', { tag: '@smoke' }, async ({ page }) => {
await page.goto('/');
await expect(page).toHaveTitle('Home');
});
test('regression test', { tag: ['@regression', '@critical'] }, async ({ page }) => {
// Complex test
});
// Run: npx playwright test --grep @smoke
// Run: npx playwright test --grep-invert @slow
Visual Testing
Screenshot Comparison
test('visual regression', async ({ page }) => {
await page.goto('/dashboard');
// Full page screenshot
await expect(page).toHaveScreenshot('dashboard.png', {
maxDiffPixels: 100,
});
// Element screenshot
await expect(page.locator('.widget')).toHaveScreenshot('widget.png');
// Full page with scroll
await expect(page).toHaveScreenshot('full-page.png', {
fullPage: true,
});
// Mask dynamic elements
await expect(page).toHaveScreenshot('masked.png', {
mask: [page.locator('.timestamp'), page.locator('.avatar')],
});
// Custom threshold
await expect(page).toHaveScreenshot('comparison.png', {
maxDiffPixelRatio: 0.05, // 5% difference allowed
});
});
Video and Trace
// playwright.config.ts
export default defineConfig({
use: {
video: 'retain-on-failure',
trace: 'on-first-retry',
screenshot: 'only-on-failure',
},
});
// Programmatic video
test('record video', async ({ page }) => {
await page.goto('/');
// Test actions...
// Video saved automatically to test-results/
});
// View trace: npx playwright show-trace trace.zip
Parallel Execution
Test Sharding
// playwright.config.ts
export default defineConfig({
fullyParallel: true,
workers: process.env.CI ? 4 : undefined,
});
// Run shards in CI
// npx playwright test --shard=1/4
// npx playwright test --shard=2/4
// npx playwright test --shard=3/4
// npx playwright test --shard=4/4
Serial Tests
test.describe.configure({ mode: 'serial' });
test.describe('order matters', () => {
let orderId: string;
test('create order', async ({ page }) => {
// Create order
orderId = await createOrder(page);
});
test('verify order', async ({ page }) => {
// Use orderId from previous test
await verifyOrder(page, orderId);
});
});
CI/CD Integration
GitHub Actions
# .github/workflows/playwright.yml
name: Playwright Tests
on:
push:
branches: [main, master]
pull_request:
branches: [main, master]
jobs:
test:
timeout-minutes: 60
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Install dependencies
run: npm ci
- name: Install Playwright Browsers
run: npx playwright install --with-deps
- name: Run Playwright tests
run: npx playwright test
- uses: actions/upload-artifact@v4
if: always()
with:
name: playwright-report
path: playwright-report/
retention-days: 30
Docker
FROM mcr.microsoft.com/playwright:v1.40.0-jammy
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["npx", "playwright", "test"]
Debugging
UI Mode
# Interactive debugging
npx playwright test --ui
# Debug specific test
npx playwright test --debug login.spec.ts
# Step through test
npx playwright test --headed --slow-mo=1000
Trace Viewer
// Generate trace
test('with trace', async ({ page }) => {
await page.context().tracing.start({ screenshots: true, snapshots: true });
// Test actions
await page.goto('/');
await page.context().tracing.stop({ path: 'trace.zip' });
});
// View: npx playwright show-trace trace.zip
Console Logs
test('capture console', async ({ page }) => {
page.on('console', msg => console.log(`Browser: ${msg.text()}`));
page.on('pageerror', error => console.error(`Error: ${error.message}`));
await page.goto('/');
});
Best Practices
1. Use Stable Locators
// ✅ Good - Role-based, stable
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByLabel('Email').fill('test@example.com');
// ❌ Bad - Fragile, implementation-dependent
await page.click('button.btn-primary.submit-btn');
await page.fill('div > form > input:nth-child(3)');
2. Leverage Auto-Waiting
// ✅ Good - Auto-waits
await page.click('button');
await expect(page.locator('.result')).toBeVisible();
// ❌ Bad - Manual waits
await page.waitForTimeout(2000);
await page.click('button');
3. Use Page Object Model
// ✅ Good - Reusable, maintainable
const loginPage = new LoginPage(page);
await loginPage.login('user', 'pass');
// ❌ Bad - Duplicated selectors
await page.fill('[name="username"]', 'user');
await page.fill('[name="password"]', 'pass');
4. Parallel-Safe Tests
// ✅ Good - Isolated
test('user signup', async ({ page }) => {
const uniqueEmail = `user-${Date.now()}@test.com`;
await signUp(page, uniqueEmail);
});
// ❌ Bad - Shared state
test('user signup', async ({ page }) => {
await signUp(page, 'test@test.com'); // Conflicts in parallel
});
5. Handle Flakiness
// ✅ Good - Wait for network idle
await page.goto('/', { waitUntil: 'networkidle' });
await expect(page.locator('.data')).toBeVisible();
// Configure retries
test.describe(() => {
test.use({ retries: 2 });
test('flaky test', async ({ page }) => {
// Test with auto-retry
});
});
Common Patterns
Multi-Page Scenarios
test('popup handling', async ({ page, context }) => {
// Listen for new page
const popupPromise = context.waitForEvent('page');
await page.click('a[target="_blank"]');
const popup = await popupPromise;
await popup.waitForLoadState();
await expect(popup).toHaveTitle('New Window');
await popup.close();
});
Conditional Logic
test('handle optional elements', async ({ page }) => {
await page.goto('/');
// Close modal if present
const modal = page.locator('.modal');
if (await modal.isVisible()) {
await page.click('.modal .close-button');
}
// Or use count
const cookieBanner = page.locator('.cookie-banner');
if ((await cookieBanner.count()) > 0) {
await page.click('.accept-cookies');
}
});
Data-Driven Tests
const testCases = [
{ input: 'hello', expected: 'HELLO' },
{ input: 'World', expected: 'WORLD' },
{ input: '123', expected: '123' },
];
for (const { input, expected } of testCases) {
test(`transforms "${input}" to "${expected}"`, async ({ page }) => {
await page.goto('/transform');
await page.fill('input', input);
await page.click('button');
await expect(page.locator('.result')).toHaveText(expected);
});
}