writing-playwright-tests

Playwright E2E Testing Skill

1. Selector Strategy Hierarchy

Use selectors in this priority order for maximum resilience:

// BEST: Explicit test identifiers
page.getByTestId('submit-button')

// GOOD: Semantic role-based (accessible)
page.getByRole('button', { name: 'Submit' })
page.getByRole('heading', { level: 1 })
page.getByRole('textbox', { name: 'Email' })

// GOOD: User-visible text
page.getByText('Welcome back')
page.getByLabel('Email address')
page.getByPlaceholder('Enter your email')

// ACCEPTABLE: When above options unavailable
page.locator('[data-cy="element"]')  // Cypress migration
page.locator('#unique-id')            // Stable IDs only

// AVOID: Brittle structural selectors
page.locator('.btn-primary')          // Classes change
page.locator('div > span:nth-child(2)') // Structure changes
page.locator('//div[@class="foo"]')   // XPath fragile

Adding Test IDs to Legacy Apps

When retrofitting, add data-testid attributes incrementally:

<!-- Before: Relies on brittle class selector -->
<button class="btn btn-primary submit-form">Submit</button>

<!-- After: Resilient test identifier -->
<button class="btn btn-primary submit-form" data-testid="contact-form-submit">Submit</button>

Naming convention for test IDs:

{component}-{element}-{qualifier}
contact-form-submit
user-list-row-{id}
modal-confirm-button
nav-menu-toggle

2. Page Object Model

Basic Page Object

// pages/login.page.ts
import { Page, Locator } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('Email');
    this.passwordInput = page.getByLabel('Password');
    this.submitButton = page.getByRole('button', { name: 'Sign in' });
    this.errorMessage = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }

  async expectError(message: string) {
    await expect(this.errorMessage).toContainText(message);
  }
}