Playwright error-context.md: what is in it and how to use it with AI agents

Where the file comes from

At the end of a test that has errors, Playwright builds an error context and writes it to error-context.md in the output folder of that test, the same folder where screenshots, videos and traces go (for example test-results/login-shows-error-chromium/error-context.md). It is attached to the test result as error-context with type text/markdown, so reporters that show attachments carry it.

In the terminal, the list and line reporters do not print the whole file. They print a pointer under the failure:

    Error Context: test-results/login-shows-error-chromium/error-context.md

That line is why people search for it: it shows up under every failure, and it is not obvious what the file is for.

What is inside

Playwright 1.63 writes these sections, in this order:

1. Instructions. Three lines addressed to an assistant: the test failed, explain why concisely following Playwright best practices, and provide a code fix if possible.
2. Test info. The full test name (file, describe blocks and title joined with >>) and its location, file:line:column.
3. Error details. Each error message in a code block, without color codes. When the failure came from an assertion that supplies its own context, such as an aria snapshot match, that context is added as YAML.
4. Page snapshot. An accessibility snapshot of the first open page, in YAML, taken after the failure and before the page was closed. It lists roles, names and text of what was on screen, which is often enough to see that the button had a different label or a dialog was in the way.
5. Test source. The source file around the line where the error was thrown: up to 100 lines above and below, with the failing line marked > and a caret under the error position.

Sections without data are left out. A test that failed before any page opened has no page snapshot; a failure without a usable stack has no source section. If there is no error message and no snapshot, no file is written.

Turning off the page snapshot

In 1.63, setting the environment variable PLAYWRIGHT_NO_COPY_PROMPT stops Playwright from taking the page snapshot for this file. The rest of the file is still written. The HTML reporter has a related noCopyPrompt option (or PLAYWRIGHT_HTML_NO_COPY_PROMPT) for its own report.

Using it with a coding agent

The file is built to be pasted, or read directly, by an AI assistant. Compared with the raw terminal output it is short, structured and has the page state, which an agent cannot otherwise see after the browser has closed. A practical loop:

1. Run the failing test: npx playwright test tests/login.spec.ts.
2. Give the agent the path printed after "Error Context:" and ask for the cause before any fix.
3. Check the proposed fix against the page snapshot: does the locator it suggests exist there?
4. Re-run the test, ideally with --repeat-each=5, so a fix that only hides a race is caught.

Be careful with the kind of fix agents tend to propose. A longer timeout, a waitForTimeout, a looser assertion or test.skip will make the file go away without fixing anything. The guide to reviewing AI-written Playwright tests lists what to look for.

Playwright also changes some behavior when it detects a coding agent. In 1.63 it checks the CLAUDECODE and COPILOT_CLI environment variables, and when either is set the HTML reporter does not try to open a browser at the end of the run. See why the HTML report did not open.

What to keep out of it

The page snapshot contains the text that was on the page: names, emails, order numbers, anything your test account could see. The source section contains your test code, including any value written in it. If test-results/ is uploaded as a CI artifact, everyone who can read the artifacts can read these files.

• Use test accounts with fake data, and never hard-code credentials in test files; read them from environment variables.
• Keep CI artifacts private and short-lived, or set PLAYWRIGHT_NO_COPY_PROMPT in CI if you do not need the snapshot there.
• Treat it like a trace. The guide to keeping secrets out of Playwright traces covers the same risks for traces and screenshots.

What one error context cannot tell you

The file is good at one question: why did this test fail just now? The questions after a red pull request are often different. Did my change cause it, or was it already failing on main? Has it failed like this before? An agent that reads one error context will try to fix the test even when the failure is a known flaky one that has nothing to do with the change.

TurnSignal answers those across runs: each failure is labelled new, also failing on main or known flaky, with the error, screenshot and trace one click away. Coding agents can ask the same questions through its MCP server before they change a test. See the docs.