playwright

Playwright Best Practices

Playwright is the gold standard for reliable E2E testing. These rules ensure your tests are fast, stable, and easy to maintain, aligning with modern 2025 development standards for reliability, quality, and structure.

1. Always Use @playwright/test

Leverage the official test runner for built-in fixtures, isolation, and web-first assertions. Avoid the low-level playwright library for E2E tests.

❌ BAD: Using playwright directly

import { chromium } from 'playwright';
// ... manual browser/context setup and teardown
const browser = await chromium.launch();
const page = await browser.newPage();
// ...
await browser.close();

✅ GOOD: Using @playwright/test

import { test, expect } from '@playwright/test';
test('should navigate to home', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveTitle(/Home/);
});

2. Prioritize Robust Locators

Use Playwright's built-in Locators API, favoring user-facing attributes over brittle CSS selectors. This drastically improves test stability.

❌ BAD: Fragile, implementation-dependent selectors

await page.locator('div.container > ul > li:nth-child(2) > button').click();

✅ GOOD: Semantic, user-facing locators

await page.getByRole('button', { name: 'Add to Cart' }).click();
await page.getByLabel('Username').fill('testuser');
await page.getByTestId('product-item-123').click();

3. Embrace Web-First Assertions

Playwright's expect assertions automatically retry until conditions are met, eliminating manual waits and flakiness. Never use page.waitForTimeout().

❌ BAD: Manual, flaky waits and generic assertions

await page.waitForTimeout(2000); // 🚨 Flaky!
const title = await page.title();
assert.equal(title, 'My Page'); // 🚨 Not web-first

✅ GOOD: Reliable, auto-retrying assertions

await expect(page).toHaveTitle(/My Page/);
await expect(page.getByText('Welcome')).toBeVisible();
await expect(page.getByRole('checkbox')).toBeChecked();