{"dataset":{"id":"00000000-0000-0000-0000-000000000032","slug":"playwright-best-practices","name":"Playwright best practices","description":"Source-linked guidance on Playwright test fundamentals: isolation and parallelism, resilient locators, auto-retrying assertions, fixtures, and trace-based debugging. Scoped to Playwright Test; not a general browser-automation corpus.","visibility":"public","version":1,"documentCount":5,"publisher":"Koskamo editorial","license":"Original summaries; linked sources retain their own terms.","reviewedAt":"2026-10-04T00:00:00.000Z","readOnly":true,"createdAt":"2026-10-04T00:00:00.000Z","updatedAt":"2026-10-04T00:00:00.000Z"},"total":5,"documents":[{"title":"Tracing and debugging with the Trace Viewer","sourceUrl":"https://playwright.dev/docs/trace-viewer","text":"The Playwright Trace Viewer is a GUI tool for exploring recorded traces after the script has run, and traces are a great way of debugging tests that fail on CI. Open a saved trace locally with npx playwright show-trace path/to/trace.zip, or in the browser at trace.playwright.dev, a statically hosted variant that loads the trace entirely in your browser and transmits no data externally; remote traces open directly from a URL, with CORS rules applying. Record a trace during development with --trace on — UI Mode traces each test automatically — and on CI set trace: 'on-first-retry' in playwright.config so a trace.zip is produced only for the first retry of a failed test; other options are 'on-all-retries', 'off', 'on' (not recommended, as it is performance heavy), and 'retain-on-failure'. The library API records manually via context.tracing.start({ screenshots: true, snapshots: true }) and context.tracing.stop({ path: 'trace.zip' }). Scope: Playwright. Reviewed October 4, 2026.","id":"playwright-best-practices:Tracing and debugging with the Trace Viewer","version":1,"createdAt":"2026-10-04T00:00:00.000Z","updatedAt":"2026-10-04T00:00:00.000Z"},{"title":"Fixtures for test environments","sourceUrl":"https://playwright.dev/docs/test-fixtures","text":"Playwright Test is based on test fixtures, which establish the environment for each test — giving the test everything it needs and nothing else — and are isolated between tests, so tests can be grouped by meaning instead of common setup. The built-in fixtures cover most needs: page provides an isolated page for the test run; context provides an isolated BrowserContext that the page belongs to; browser is a browser shared across tests to optimize resources; browserName reports the running browser, either chromium, firefox, or webkit; and request provides an isolated APIRequestContext instance. Tests receive fixtures by declaring them as arguments, as in test('basic test', async ({ page }) => ...). To create your own fixture, use test.extend() to create a new test object that includes it, such as a TodoPage page object — this replaces the manual beforeEach construction typical of traditional test styles. Scope: Playwright. Reviewed October 4, 2026.","id":"playwright-best-practices:Fixtures for test environments","version":1,"createdAt":"2026-10-04T00:00:00.000Z","updatedAt":"2026-10-04T00:00:00.000Z"},{"title":"Auto-retrying web-first assertions","sourceUrl":"https://playwright.dev/docs/test-assertions","text":"Playwright's expect function includes web-specific async matchers that auto-retry: the element is re-fetched and checked over and over until the condition is met or the timeout is reached, so the assertion waits for the application instead of racing it — await expect(page.getByTestId('status')).toHaveText('Submitted') re-tests the element until it shows 'Submitted' or times out. Because retrying assertions are async, they must be awaited. The auto-retrying matchers include toBeVisible, toBeHidden, toBeAttached, toBeChecked, toBeEnabled, toBeFocused, toBeInViewport, toHaveText, toContainText, toHaveAttribute, toHaveCount, and toHaveValue, among many others; generic matchers such as toEqual, toContain, and toBeTruthy cover non-web conditions. The assertion timeout defaults to 5 seconds and can be passed per assertion or configured once via the testConfig.expect value in the test config. Prefer these web-first assertions over manual sleeps for UI state — that preference is Koskamo editorial guidance. Scope: Playwright. Reviewed October 4, 2026.","id":"playwright-best-practices:Auto-retrying web-first assertions","version":1,"createdAt":"2026-10-04T00:00:00.000Z","updatedAt":"2026-10-04T00:00:00.000Z"},{"title":"Locators over brittle selectors","sourceUrl":"https://playwright.dev/docs/locators","text":"Locators are the central piece of Playwright's auto-waiting and retry-ability: a locator describes how to find elements on the page at any moment, and every action performs a fresh DOM lookup, so a re-render between a hover and a click still acts on the current element. Prioritize the built-in user-facing locators: page.getByRole() locates by explicit and implicit accessibility attributes and reflects how users and assistive technology perceive the page — pass the accessible name so the locator pinpoints the exact element, as in page.getByRole('button', { name: 'Sign in' }) — alongside page.getByText(), page.getByLabel(), page.getByPlaceholder(), page.getByAltText(), page.getByTitle(), and page.getByTestId() for the data-testid attribute, which can be configured. All locator-creating methods also exist on the Locator and FrameLocator classes, so locators chain to narrow matches, including inside frames. Use the code generator to produce a locator, then edit it as needed. Scope: Playwright. Reviewed October 4, 2026.","id":"playwright-best-practices:Locators over brittle selectors","version":1,"createdAt":"2026-10-04T00:00:00.000Z","updatedAt":"2026-10-04T00:00:00.000Z"},{"title":"Test isolation and parallelism","sourceUrl":"https://playwright.dev/docs/best-practices","text":"Test user-visible behavior rather than implementation details such as function names or CSS classes, because end users interact only with the rendered output. Make each test fully isolated: every test runs independently with its own local storage, session storage, data, and cookies, which improves reproducibility, eases debugging, and prevents cascading failures. Use beforeEach hooks for repeated setup such as navigating or signing in so no test relies on another, though a little duplication is acceptable when it keeps simple tests clearer; the signed-in state can also be reused across tests with a setup project. Playwright runs tests in parallel by default, while tests in a single file run in order in the same worker process; independent tests in one file can run in parallel via test.describe.configure({ mode: 'parallel' }), and the suite can be sharded across multiple machines with --shard=1/3. Scope: Playwright. Reviewed October 4, 2026.","id":"playwright-best-practices:Test isolation and parallelism","version":1,"createdAt":"2026-10-04T00:00:00.000Z","updatedAt":"2026-10-04T00:00:00.000Z"}]}