This will happen to you, probably in your first month. A test fails on the build server about once in ten runs. On your machine it passes every time. Someone re-runs the build, it goes green, and everyone moves on.
Do not move on. Playwright gives you a very strong tool for this, and most juniors do not know it exists.
Step 1. Turn on traces. A trace is a recording of everything the test did: every action, every network call, and a snapshot of the page at each step.
use: { trace: 'on-first-retry' },
This records a trace when a test fails and is retried. That is exactly the case you cannot reproduce.
Step 2. Open the trace from the failed run. Download it from your build server and open it:
npx playwright show-trace trace.zip
You now have a timeline of the test. Click any step and you see the page exactly as it was at that moment, plus the DOM and the network calls. This is the closest thing to being there when it failed.
Ask one question while you look at the failing step:
What is on this screen that I did not expect?
Usually the answer is right there. A spinner still turning. An empty table. A cookie banner over the button.
Step 3. Make it fail for you. If you still need to reproduce it locally, repeat the test:
npx playwright test contacts.spec.ts --repeat-each=20
Slowing the network in your browser dev tools also helps, because the build server is usually slower than your laptop.
Step 4. Fix the cause, not the symptom. Three usual causes:
- A value read into a variable instead of asserted with a retrying
expect. - Shared data. Another test left something behind. Give this test its own data.
- A real race in the app. The button is clickable before the handler is ready. Your user will hit this too. Report it.
What not to do: raise the timeout, or turn on more retries and move on. Both hide the failure. The bug stays in the app, and now it is invisible.
Remember this: open the trace first. It usually answers the question in two minutes.
Reference: Trace viewer.