Playwright Testing Best Practices

Selectors — Priority Order

Always prefer accessible selectors. In order of preference:

1. page.getByRole('button', { name: 'Submit' }) — best, mirrors user intent
2. page.getByLabel('Email address') — great for form inputs
3. page.getByText('Welcome back') — good for static text
4. page.getByPlaceholder('Enter email') — acceptable for inputs
5. page.getByTestId('submit-btn') — fallback when no semantic option exists

Never use:

• page.locator('.css-class') — breaks on styling changes
• page.locator('div > span:nth-child(2)') — extremely fragile
• page.locator('#generated-id') — breaks on framework changes

Waiting Strategy

Never use waitForTimeout. Always use condition-based waits:

// Wait for element
await expect(page.getByRole('heading')).toBeVisible();

// Wait for navigation
await page.waitForURL('**/dashboard');

// Wait for API response
const responsePromise = page.waitForResponse('**/api/data');
await page.getByRole('button', { name: 'Load' }).click();
await responsePromise;

// Wait for specific outcome after action (avoid networkidle — unreliable in SPAs)
await page.getByRole('button', { name: 'Submit' }).click();
await expect(page.getByText('Submitted successfully')).toBeVisible();

Mocking Network Requests

Use page.route() for API mocking:

// Mock success response
await page.route('**/api/users', route =>
  route.fulfill({ json: [{ id: 1, name: 'Test User' }] })
);

// Mock error response
await page.route('**/api/users', route =>
  route.fulfill({ status: 500, json: { error: 'Server error' } })
);

// Mock network failure
await page.route('**/api/users', route => route.abort());

// Mock slow response
await page.route('**/api/users', async route => {
  await new Promise(resolve => setTimeout(resolve, 3000));
  await route.fulfill({ json: [] });
});

Test Structure

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

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

  test('should display initial state correctly', async ({ page }) => {
    await expect(page.getByRole('heading', { name: 'Feature' })).toBeVisible();
  });

  test('should handle user interaction', async ({ page }) => {
    await page.getByRole('button', { name: 'Action' }).click();
    await expect(page.getByText('Result')).toBeVisible();
  });
});

Test Independence Rules

• Every test gets a fresh page via the fixture — never share page state
• Use test.beforeEach for common navigation, not for shared data setup
• If tests need specific data state, mock it per-test with page.route()
• Never use test.describe.serial unless tests truly cannot be parallelized
• Clean up any created resources in test.afterEach

Assertions — Use Specific Matchers

// URL assertions
await expect(page).toHaveURL('/dashboard');
await expect(page).toHaveTitle('Dashboard');

// Element visibility
await expect(locator).toBeVisible();
await expect(locator).toBeHidden();
await expect(locator).not.toBeVisible();

// Element state
await expect(locator).toBeEnabled();
await expect(locator).toBeDisabled();
await expect(locator).toBeChecked();
await expect(locator).toHaveAttribute('aria-expanded', 'true');

// Text content
await expect(locator).toHaveText('exact text');
await expect(locator).toContainText('partial text');

// Count
await expect(locator).toHaveCount(5);

// Input values
await expect(locator).toHaveValue('input value');

Common Test Patterns

Form Validation

test('should show validation errors for empty required fields', async ({ page }) => {
  await page.getByRole('button', { name: 'Submit' }).click();
  await expect(page.getByText('Email is required')).toBeVisible();
  await expect(page.getByText('Password is required')).toBeVisible();
});

Loading States

test('should show loading indicator during data fetch', async ({ page }) => {
  await page.route('**/api/data', async route => {
    await new Promise(r => setTimeout(r, 100));
    await route.fulfill({ json: { items: [] } });
  });
  await page.goto('/page');
  await expect(page.getByRole('progressbar')).toBeVisible();
  await expect(page.getByRole('progressbar')).toBeHidden();
});

Error States

test('should display error message on API failure', async ({ page }) => {
  await page.route('**/api/data', route =>
    route.fulfill({ status: 500, json: { error: 'Internal Server Error' } })
  );
  await page.goto('/page');
  await expect(page.getByRole('alert')).toContainText('Something went wrong');
});

Authentication Gates

test('should redirect to login when not authenticated', async ({ page }) => {
  await page.goto('/protected-page');
  await expect(page).toHaveURL(/.*login/);
});