A browser test passes on your laptop and fails in CI: collect a trace before changing anything

Capture the failing run before theorising

When a browser test passes locally and fails in CI, the temptation is to lengthen waits until it goes green. Collect evidence first. Playwright's trace viewer records each action of a test and lets you step through them, inspecting the log, the source, the network calls, errors and console output, with an interactive snapshot of the page as it was at each step. The default configuration records a trace on the first retry of a failing test and sets two retries in CI and none locally. The best-practices page prefers traces to videos and screenshots for debugging in CI, and warns against recording a trace for every test because of the performance cost.

• Download the trace from the failed run and open it with the viewer, instead of re-running blind.
• Look at the first action whose result differs from your local run, not at the last line of the error.

List the differences that could matter

Compare the two environments on the points a browser test can feel. The operating system may differ, since CI commonly uses Linux and developers use something else. The browser versions installed may differ. Parallelism may differ: the documentation's own example uses two workers in CI and the default count locally, so two machines can load the application differently. The data may differ: a shared staging environment is not your local database. The network may differ: calls to outside services that work from your office may be blocked or slow from the runner. Each is a hypothesis you can test by changing that one thing.

• Run the suite locally with the CI's worker count.
• Run it locally against the same staging data CI uses.
• Check the same browser and operating system, for example by running the CI image locally.

Read the trace for the first divergence

In the trace, step to the action that failed and look at the page snapshot beside it. Is the element missing, covered by a banner or still loading? Check the network tab for a failed or slow request, and the console tab for an error the page raised. A request that returned an error in CI but not locally points at data or configuration. A banner or dialog that appears only in CI points at an environment difference in the application. An element that is present but arrives late points back at the waiting guide. If the test failed and then passed on retry, Playwright reports it as flaky, in its own category, and the trace from the first retry is the evidence to read.

• Write down what the trace shows before you decide what to change.
• Change one thing, push it and repeat the run several times, not once.

What does not fit, and how the paid job is accepted

If a whole workflow fails the same way each time with a command or dependency error, that is a job repair. If one test fails alone for a reason in the application, it is a bug fix. For three critical flows, the browser smoke suite job proves each test in the pull request job: 20 consecutive passing runs with retries disabled for the check, a trace or screenshot attached on any failure, and a deliberate break per flow that makes its test fail. The runs use a staging or preview copy and test accounts, never production. Send the flow names and the CI service in the first enquiry; do not send code, keys or customer data.