Playwright for testers: UI and API automation from scratch

1. Choose the first scenario by risk, not convenience

Start with a short stable path and a clear oracle: sign-in, customer creation, or adding an item to cart. Do not begin with a long order flow containing ten integrations. Write down the manual scenario, preconditions, data, expected business effect, and cleanup.

Distribute checks by layer. Calculations and rules are cheaper below the UI; keep browsers for behavior that requires a page. One end-to-end test cannot replace API, permission, and persistence tests, while dozens of UI variants make a suite slow and brittle.

• The scenario carries business risk.
• The oracle is observable by another person.
• Data can be created and removed independently.
• No test depends on another test result.
• Failure is localized by steps and evidence.

2. Build a minimal Arrange, Act, Assert test

Playwright Test provides the runner, assertions, fixtures, parallelism, and reports. Structure a scenario as Arrange, Act, Assert: prepare the user and data, perform one business action, and verify the observable outcome. Name a test after the rule, not the click sequence.

Use web-first assertions that wait for the required state and report the actual one. Do not substitute waitForTimeout: a fixed sleep slows fast tests and remains too short on a slow CI worker.

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

test('manager converts a new lead into one customer', async ({ page }) => {
  await page.goto('/leads/42');
  await page.getByRole('button', { name: 'Convert lead' }).click();
  await expect(page.getByRole('heading', { name: 'Customer Alex' })).toBeVisible();
  await expect(page.getByText('Converted')).toBeVisible();
});

3. Select locators by the user-facing contract

Prefer getByRole, getByLabel, getByText, and an agreed getByTestId fallback. Roles and accessible names reflect what users and assistive technologies perceive. A long div:nth-child selector breaks after cosmetic markup changes.

A locator must be unique. If several Save buttons exist, narrow the region or give each a distinct name; do not call first() merely to make the test pass. A missing accessible name may be a product defect rather than a selector inconvenience.

// Maintainable: user-facing meaning
await page.getByRole('button', { name: 'Save customer' }).click();
await page.getByLabel('Email').fill('alex@example.test');

// Brittle: DOM structure
await page.locator('.card:nth-child(2) > div > button').click();

4. Isolate data with fixtures and API setup

Tests must not depend on order. Each test gets its own user or business context and creates only required data. Creating a lead through an API is faster and more reliable than repeating a UI form before every check. Keep UI for the behavior under test.

A fixture packages setup and teardown but should not hide half the business flow. Make data unique for parallel workers and remove it through a supported API or TTL. A shared production-like account quickly creates races and false failures.

test('owner sees the assigned customer', async ({ page, request }) => {
  const created = await request.post('/api/test/customers', {
    data: { name: 'Alex', owner: 'manager-a' }
  });
  const { id } = await created.json();
  await page.goto(`/customers/${id}`);
  await expect(page.getByText('Owner: manager-a')).toBeVisible();
});

5. Use APIRequestContext for setup and standalone API tests

Playwright can send HTTP requests in the same runner. Use it to arrange state, verify server contracts, or confirm a UI action through another channel. Status 200 is not business success: assert schema, values, persistence, permission, and side effects.

API tests explicitly own baseURL, authentication, and data. Avoid chains where one test produces state for the next. For negative cases verify no mutation after 4xx; for retries assert one final effect by business key.

test('duplicate conversion creates one customer', async ({ request }) => {
  const first = await request.post('/api/leads/42/convert');
  const second = await request.post('/api/leads/42/convert');
  expect([200, 201]).toContain(first.status());
  expect([200, 409]).toContain(second.status());
  const customers = await request.get('/api/customers?source_lead_id=42');
  expect((await customers.json()).data).toHaveLength(1);
});

6. Add Page Objects only for meaningful repetition

A Page Object stores locators and page actions, but it should not become a giant class containing every assertion. Tests should expose business intent; components hide stable mechanics. A reusable table or modal component is often more precise than a whole-page object.

Avoid premature abstraction. Three clear lines can beat a universal method with ten flags. Separate data, actions, and assertions, use TypeScript types, and do not swallow errors or retry inside helpers that hide defects.

class LeadPage {
  constructor(private page: Page) {}
  async convert() {
    await this.page.getByRole('button', { name: 'Convert lead' }).click();
  }
  customerHeading(name: string) {
    return this.page.getByRole('heading', { name });
  }
}

7. Use network control, visual checks, and accessibility deliberately

Route interception can reproduce a 500, timeout, or rare dependency response, but a mocked happy path does not prove integration. Separate real API contract tests from UI behavior under a controlled failure. Assert loading, retry, no duplicate action, and a useful user message.

Visual comparison detects unexpected pixel changes but requires stable fonts, viewports, and data. Accessibility scans find classes of violations but do not replace keyboard navigation and screen-reader semantics. These techniques complement functional assertions rather than replacing them.

await page.route('**/api/customers/42', route =>
  route.fulfill({ status: 503, body: JSON.stringify({ error: 'unavailable' }) })
);
await page.goto('/customers/42');
await expect(page.getByRole('alert')).toContainText('Try again');
await expect(page.getByRole('button', { name: 'Retry' })).toBeEnabled();

8. Diagnose flaky tests with traces and run them in CI

A flaky test alternates between pass and fail for the same code and expected state. Common causes are shared data, wrong waits, races, external dependencies, brittle locators, and leaked state. Retry collects another signal but does not fix the cause or turn a red suite into a healthy one.

In CI retain trace on first retry, screenshots and video by policy, HTML/JUnit reports, and sanitized network evidence. Split fast pull-request smoke from scheduled or pre-release regression. A failure should identify commit, browser, environment, test-data id, and the first useful stack frame.

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 4 : undefined,
  use: { baseURL: process.env.BASE_URL, trace: 'on-first-retry' },
  reporter: [['html'], ['junit', { outputFile: 'results.xml' }]],
});