Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteiTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
A Playwright retry budget sets the maximum number of additional attempts after a test’s initial run. The default is zero; with retries: 2, a test can run once initially and up to two more times. To make a later pass useful rather than misleading, preserve evidence from each attempt and report whether the final result was passed, flaky, or failed.
What a retry budget means in Playwright Test
Retries are additional attempts after the first run, not a total-run limit. Playwright Test defaults to no retries. Configure the maximum in playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: 2,
});This allows the initial attempt plus as many as two retries. Retry configuration can also be scoped to a describe group or file. See the official retry documentation and TestConfig API for supported configuration and scope details.
The current TestConfig documentation describes retryStrategy: 'immediate' as the default: a failed test is retried when a worker is available. With 'isolated', retries wait until other tests finish and then run one by one in a single worker. Isolation can reduce interference between retried tests, but may increase total run time. Because strategy options can depend on Playwright version, check the documentation matching the version installed in your project before configuring them.
#1 Best Overall
How Playwright classifies retry results
Playwright’s final classification tells you whether a test passed immediately, needed another attempt, or continued to fail. A retry pass is not evidence that the first failure was meaningless; it is evidence that the test behaved differently across attempts.
| Result | What happened | What to preserve |
|---|---|---|
| Passed | The test passed on its initial attempt. | The successful attempt’s result and any configured artifacts. |
| Flaky | The initial attempt failed, but a retry passed. | The original failure evidence as well as the passing retry. |
| Failed | The test failed on the initial attempt and through all configured retries. | The outcome and evidence for each attempt that ran. |
The classifications are documented in Playwright’s retry guide. A green final outcome after a retry should not erase the initial failure from team reporting.
Identify the attempt and understand worker resets
Inside a test, testInfo.retry is 0 for the initial attempt and increments for each subsequent retry. TestInfo also exposes status and attachment methods; see the TestInfo API.
import { test, expect } from '@playwright/test';
test('checkout completes', async ({ page }, testInfo) => {
if (testInfo.retry > 0) {
// Add retry-specific setup only when it is appropriate.
}
await page.goto('/checkout');
await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
});A failed test causes Playwright Test to discard its worker process and browser, then start a new worker. A retry may therefore use a fresh worker and browser context, while external state—such as a test account or remote service—may persist. Clean up or reset that external state explicitly when the test depends on it. Retry-specific setup can be useful, but should not silently convert or conceal the first failure.
Choose artifact settings to capture the evidence you need
Capture settings answer two separate questions: which attempts produce artifacts, and which artifacts remain after the run. The appropriate choice depends on whether you need evidence of the initial failure, later retries, or both, as well as storage and runtime overhead.
| Capture choice | What it is for | Important limitation |
|---|---|---|
on-first-retry |
Records a trace on the first retry; useful when retry diagnostics are the priority. | It does not record the original failed attempt. With retries disabled, there is no retry on which to capture a trace. |
| Failure-retention trace modes | Options such as retain-on-failure, retain-on-first-failure, and retain-on-failure-and-retries can retain traces according to their configured failure and retry conditions. |
Choose the mode whose capture and retention behavior matches the attempts your receipt must explain. |
on-all-retries |
Records traces for retry attempts. | It does not, by itself, establish that the initial attempt was traced. |
| Screenshots and video | Separate artifact options can capture screenshots or video, including failure-focused configurations. | They have their own capture and retention settings; do not assume that enabling traces also enables them. |
Playwright documents trace modes including off, on, retain-on-failure, retain-on-first-failure, retain-on-failure-and-retries, on-first-retry, and on-all-retries. Consult the current configuration options for exact behavior and syntax. If the record needs to explain the initial failure, select a mode that captures and retains that first failed run, or state clearly that the original attempt has no trace. The Trace Viewer provides a graphical way to inspect recorded traces and replay action context.
Build a per-attempt failure receipt
Playwright does not provide a built-in object called a “failure receipt.” Treat it as a small reporting record assembled from test results, TestInfo, and artifacts that actually survived the configured retention rules. A receipt should keep each attempt’s details tied to that attempt, then report the final classification without discarding an earlier failure.
Free tools Windows power users keep installed
One-click scans. No signup required.
- Test identity: a stable test identifier, plus project or environment context.
- Attempt and outcome: the attempt number from
testInfo.retry, status or outcome, and elapsed time where available. - Failure details: the assertion or error message and relevant test or worker output.
- Artifact references: filenames or links for screenshots, video, and traces that were actually retained.
- Final classification: passed, flaky, or failed, while keeping the initial attempt’s failure evidence when a retry passes.
A custom reporter can process lifecycle events centrally. For example, an onTestEnd hook can collect results; TestInfo can supply attempt-specific context and attachments where appropriate. The Reporter API, TestInfo API, and artifact configuration describe the relevant interfaces. A reporter should link only to files that exist and remain available, not assume every attempt produced a trace.
Decide what your team needs to retain
Before setting a retry count or choosing capture modes, decide what failure investigation requires. A retry budget controls how many chances a test gets; it does not, on its own, preserve the information needed to diagnose why the test failed.
Quick Recap
- If the goal is to inspect retry behavior, capture retries and label each artifact by attempt.
- If the initial failure is important, select a trace retention mode that includes that failed run, rather than relying only on a retry-triggered trace.
- If retries are disabled, use a failure-retention mode rather than a retry-only trace mode.
- If storage or runtime overhead matters, choose capture settings deliberately and verify which attempts and files survive the run.
- If tests rely on remote or account state, make retry setup and cleanup explicit so a fresh worker does not create a misleading comparison.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
