Playwright tests that fail intermittently in continuous integration (CI) are usually revealing a reliability problem, not a need for more retries. The failure may come from tests sharing state, an assumption about timing or page state, or pressure on the CI runner. Preserve the failure report and trace, inspect what happened, then make a targeted change. Increasing workers or timeouts before that investigation can hide the symptom without fixing its cause.
Why do Playwright tests pass locally but fail in CI?
Local and CI runs differ in ways that can expose assumptions a test makes. Tests may run in a different order or with more parallel workers; the CI machine may have less available CPU or memory; and the application, data, or network may take a different amount of time to reach the expected state. These are possibilities to investigate, not diagnoses: the cause depends on the test and its CI environment.
As an Amazon Associate I earn from qualifying purchases.
Start with test independence. Playwright recommends that tests be independent and use their own state and data. A test that relies on another test having created a record, left a cookie, or preserved browser storage can pass in one run order and fail in another. Shared mutable data can also make parallel tests interfere with one another. See Playwright’s Best Practices.
Check which state the test depends on
- Test data: Does the test create or reset the records it needs, or assume another test did so?
- Cookies and browser storage: Could cookies, local storage, or session storage carry state from an earlier action or test?
- Execution order: Does the test pass only after another test runs first?
- Parallel activity: Could tests modify the same account, record, or other shared resource at the same time?
Where tests are intended to be independent, give each one the state and data it needs rather than relying on order or shared mutable state.
#1 Best Overall
How do I debug a flaky Playwright test?
Keep the CI HTML report and trace from the failing run before changing configuration. A trace lets you inspect action timing, DOM snapshots, and network requests together. Playwright recommends collecting a trace on the first retry in CI: this captures evidence when a test fails initially without tracing every test, which can add runtime and storage overhead. See Trace Viewer and Best Practices.
Configure a report and trace
One configuration pattern from Playwright combines CI-only retries, a single CI worker, an HTML report, and tracing on the first retry:
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 1 : undefined,
reporter: 'html',
use: {
trace: 'on-first-retry',
},
});This is an example, not a universal prescription: adapt retries and worker policy to your suite and runner. The Playwright configuration guide documents configuration options. If you do not use retries, consider retain-on-failure to retain traces for failed tests. Open an exported trace with npx playwright show-trace path/to/trace.zip; the command-line documentation describes the CLI.
Recommended Free Tools
Read the first failure against the trace
Begin with the first failure, not just the final retry result. Find the failed action and locator in the trace, then compare the action’s duration with the DOM snapshot and nearby network activity. Ask what the page showed when the test expected something else. This helps distinguish a wrong or missing user-visible state from data or navigation timing, or from possible runner pressure. A timeout message alone does not identify which of these occurred.
What do retries tell me?
Playwright classifies a test that fails initially and passes on retry as flaky. Retries are disabled by default. A retry that passes is useful evidence that the outcome is intermittent; it does not establish that the defect is fixed. Use the retry to collect a trace and understand what differed, rather than treating a green final result as proof the test is reliable. See Playwright’s retry documentation.
Keep retry-passing failures visible
If your team wants CI to fail when tests pass only after a retry, Playwright provides failOnFlakyTests. It was added in Playwright v1.52. Confirm your installed version before using it; the option is documented in the TestConfig API.
export default defineConfig({
failOnFlakyTests: !!process.env.CI,
});How many Playwright workers should I use in CI?
Begin with one worker when stability and reproducibility matter more than throughput. Playwright’s Continuous Integration guide says: “We recommend setting workers to “1” in CI environments to prioritize stability and reproducibility.” That is a recommendation, not a guarantee that one worker will resolve a flaky test.
Free tools Windows power users keep installed
One-click scans. No signup required.
More workers can increase resource contention, particularly when the CI agent has limited CPU or memory. Playwright also cautions that setting workers above the detected core count can cause unnecessary timeouts and failures. If you need more parallel execution, check the runner’s available resources and your tests’ behavior before raising the worker count. Sharding tests across multiple CI jobs is an alternative when the goal is machine-level parallelism.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Should I increase the Playwright timeout?
Only increase a timeout when the failure evidence shows that the specific operation legitimately needs more time. Playwright’s default test timeout is 30 seconds, according to its current Timeouts documentation. A larger limit can help an operation that is expected to run longer than its current allowance; it will not correct a locator pointing at the wrong state, dependent test data, or worker contention.
Playwright’s timeout guidance notes that flaky tests often require looking for a solution elsewhere rather than only changing low-level timeouts. Use the trace to determine whether the relevant action or navigation is progressing as expected and whether its actual duration justifies a change. If you configure a global test timeout for CI, keep it comfortably below the outer CI job timeout so Playwright can stop and report before the job is terminated. The next CI guide covers this consideration; because it is a versioned “next” page, check the documentation matching your installed version.
Quick Recap
A practical order for fixing intermittent CI failures
- Preserve evidence. Keep the failed CI run’s HTML report and trace. Use
trace: 'on-first-retry'when retries are enabled, or considerretain-on-failurewhen they are not. - Inspect the first failure. Correlate the failing action and locator with the trace’s timing, DOM snapshot, and network activity. Determine what the test expected and what the page actually showed.
- Check isolation. Verify that the test sets up its own data and does not depend on another test’s cookies, local or session storage, execution order, or shared mutable resources.
- Check runner capacity. Start with one CI worker for stability. Increase workers only after considering available CPU and memory and observing how the suite behaves; consider sharding for parallel throughput across jobs.
- Use retries to identify intermittent behavior. Treat a retry-passing test as flaky evidence to investigate. Consider
failOnFlakyTestsif you want CI to flag those tests, and verify that your Playwright version supports it. - Change timeouts only when justified. Increase the relevant timeout when the trace shows the operation needs more time, not simply because the test failed with a timeout.
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.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →
