A test fails on the build server at three in the morning. It passes on your machine every time. In most tools this is where you start adding logs and guessing.
Playwright records the whole run, and the recording is good enough that guessing is usually unnecessary. This is the feature that most convinces teams to switch, so it is worth understanding properly.
Turn it on in playwright.config.ts:
export default defineConfig({
use: {
trace: 'on-first-retry',
},
});
on-first-retry means: run normally, and if a test fails and is retried, record that attempt in full. You get the evidence only when something went wrong, so you do not pay for it on every passing run.
Then open it:
npx playwright show-trace trace.zip
Here is what you get, and why it is better than a screenshot.
A filmstrip of the whole run. Screenshots at every step, so you can scrub to the moment things went wrong and see the page as it was.
Every action listed in order, with how long each took. A step that normally takes 100ms and took 4 seconds is usually your answer.
The DOM at each step. Not a picture, the actual tree. You can inspect elements at the moment of failure as if the page were still open. This is the part people do not believe until they use it.
Network requests, with status codes and timings. A 500 response two steps before your failure explains it.
Console output from the app, including JavaScript errors.
The other two artifacts are simpler:
use: {
screenshot: 'only-on-failure',
video: 'retain-on-failure',
}
Screenshots are cheap and worth having always. Video is heavier, and traces make it less necessary, because a trace shows more.
Three habits that make this pay off.
Upload traces from CI. They are written on the build machine and destroyed with it. Every CI system can keep them as build artifacts, and skipping that step means collecting evidence and throwing it away.
Read the trace before changing code. The temptation is to add a wait and re-run. The trace usually names the cause in under a minute, and the added wait would have hidden it.
Use --ui while writing tests. UI mode gives you the same view live, with the ability to step through and re-run single tests. It is the fastest way to write a locator that is right the first time.
Remember this: turn traces on, keep them from CI runs, and read one before you guess.
Reference: Trace viewer.