playwright

Playwright Test Writing

Overview

Write browser tests using @playwright/test, the official Playwright test runner. It provides auto-waiting, test isolation, built-in web assertions with auto-retry, and parallel execution out of the box.

Prefer @playwright/test for all testing scenarios. Use library mode (playwright) only for direct browser scripting needs: console error capture, network inspection, or custom automation outside a test context.

Project Setup

# Initialize Playwright in a project
npm init playwright@latest

# Or add to existing project
npm install -D @playwright/test
npx playwright install

Essential playwright.config.ts (for full multi-browser, reporter, and webServer config, see references/api-patterns.md):

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
});

Test File Structure

Tests follow the pattern: tests/<feature>.spec.ts

import { test, expect } from '@playwright/test';

test.describe('Feature Name', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/');
  });

  test('should perform expected behavior', async ({ page }) => {
    // Arrange
    const submitButton = page.getByRole('button', { name: 'Submit' });

    // Act
    await submitButton.click();

    // Assert
    await expect(page.getByText('Success')).toBeVisible();
  });
});

Always use the AAA pattern: Arrange (locate elements), Act (interact), Assert (verify outcome).

Locator Strategy (Precision Order)

Apply locators in strict priority order — always prefer the highest-precision option available:

Priority	Locator	When to Use	Stability
1	getByTestId('id')	Element has data-testid attribute	Highest — immune to text/structure changes
2	getByRole('role', { name })	Element has clear ARIA role and accessible name	Very high — maps from accessibility tree
3	getByLabel('label')	Form inputs with associated <label>	High — tied to label text
4	getByPlaceholder('text')	Input with placeholder text	Medium-high — placeholder may change
5	getByText('text', { exact: true })	Visible text content	Medium — text may change
6	page.locator('[data-attr="val"]')	Custom data attributes	Medium — depends on attribute stability
7	page.locator('css')	Last resort — specific CSS selector	Low — fragile to DOM restructuring