Skip to content

Code Reference

Key APIs

API Use
page.getByRole(role, opts) Primary locator strategy
page.getByLabel(text) Form fields
page.getByTestId(id) Test contract via data-testid (or configured attribute)
page.locator(selector) CSS / XPath fallback
locator.filter({ hasText, has, hasNot, hasNotText }) Narrowing
expect(locator).toBeVisible() etc. Web-first assertions
expect.poll(fn).toBe(value) Generic polling
expect(async () => ...).toPass() Block polling
test.extend({...}) Custom fixtures
test.use({ storageState }) Auth replay
page.route(url, handler) Network mocking
request.get/post/... API testing
page.pause() Inline debugger
test.step('label', async () => ...) Action grouping

Config Keys (E2E-Specific)

Key Default Purpose
expect.timeout 5000ms Web-first assertion polling budget
actionTimeout 0 Per-action timeout; falls back to test timeout
navigationTimeout 0 Per-navigation timeout
testIdAttribute data-testid What getByTestId reads
retries 0 Retries per test (use 2 in CI)
fullyParallel false Parallelize across all tests, not just files
forbidOnly false Error out if any test.only / describe.only reached the run — set !!process.env.CI

CLI

# Sharding
npx playwright test --shard=1/4

# Reports
npx playwright merge-reports --reporter=html ./all-blob-reports

# Debugging
npx playwright test --ui
npx playwright test --debug
PWDEBUG=1 npx playwright test
npx playwright codegen URL
npx playwright show-trace trace.zip

See Also