How Cypress Test Replay Captures Canvas Elements
Cypress Test Replay can show canvas elements as they rendered in a recorded CI run. Learn where canvas capture is controlled, what it supports, and how to troubleshoot performance or missing content.
Cypress Test Replay lets you inspect canvas elements as they rendered during a recorded CI run. Canvas capture is controlled in Cypress Cloud project settings, in the Test Replay section below the main recording toggle. Cypress warns that capturing many or large canvases can be resource-intensive; if it affects test performance, disable canvas capture and compare runs in your own CI environment.
The documented behavior is the rendered canvas context visible during replay. Cypress’s public documentation does not explain the low-level capture mechanism or publish a canvas-specific overhead benchmark. This guide sticks to the supported behavior and the practical settings Cypress documents.
1. What Test Replay shows for canvas
Test Replay is a Cypress Cloud feature for examining recorded Cypress test runs. It provides a way to step through a run and inspect application state and related debugging data, including DOM, network activity, console output, JavaScript errors, and element rendering. Cypress lists canvas elements among the captured data.
For a canvas-based interface, replay can show the canvas as it rendered in the CI run. That can give useful visual context when debugging maps, charts, games, and other deeply interactive UIs. Cypress does not describe this as a separate canvas video, so treat it as rendered context within the replay rather than assuming a particular recording format.
Test Replay serves a different purpose from a screenshot assertion or visual testing workflow. A screenshot is an image snapshot whose result depends on a stable application state and consistent rendering environment. Replay provides a timeline of a recorded run with inspectable debugging data. See Cypress’s guides to Test Replay and visual testing.
2. Enable or disable canvas capture
- Open the project in Cypress Cloud.
- Open the project settings and locate the Test Replay section.
- Find the canvas capture setting beneath the main Test Replay recording toggle.
- Leave capture enabled when canvas visuals help debug failures. Disable it if your CI runs show a performance impact or you do not need canvas context.
- Compare representative runs with the setting enabled and disabled. Monitor your project’s test performance; Cypress does not publish a universal threshold for deciding when to turn it off.
These are Cypress Cloud project settings, not a JavaScript option to add to a test. The documented control is a project-level setting.
3. Choose the right setting for your project
| Choice | Useful when | Trade-off |
|---|---|---|
| Canvas capture enabled | Visual context from maps, charts, games, or other canvas interfaces helps diagnose CI failures. | Many or large canvases can make capture resource-intensive. |
| Canvas capture disabled | You do not need canvas visuals, or enabling capture affects your observed test performance. | Replay will not provide the canvas context you rely on for those investigations. |
Test with the workload that matters: canvas count and size vary by application, and Cypress provides no numeric estimate of canvas-specific overhead. Cypress also recommends disabling video recording when Test Replay is enabled to optimize performance. Decide whether your team needs video as a separate artifact, then compare the configuration in CI.
4. Support limits and missing canvas content
Cypress documents that Test Replay does not support shadow DOM canvases. The replay support documentation also lists broader limits, including test runs recorded below Cypress App v13 and Firefox or WebKit runs. Check the current Test Replay documentation for the full, up-to-date support matrix.
If canvas content is absent, check these points in order:
- Is it a shadow DOM canvas? Shadow DOM canvases are unsupported. Cypress also calls out unsupported shadow-root behavior involving manual slot assignment.
- Was the run recorded in a supported environment? Check the Cypress App version and browser against the current replay limitations.
- Is Test Replay recording enabled for the project? Verify the main recording toggle and the canvas capture setting in Cypress Cloud.
- Is the canvas present at the relevant point in the run? Replay reflects the recorded run; inspect the timeline around the point where the application should have rendered it.
- Does disabling canvas capture change performance? Compare runs with the setting on and off if resource use or test duration is a concern.
The documentation does not specify the internal capture mechanism. Avoid assuming that it uses a particular pixel readback, serialization method, instrumentation technique, or frame frequency.
5. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Canvas is missing in replay | The canvas is inside a shadow DOM, canvas capture is off, or the run falls outside documented support. | Check the canvas setting, shadow-root usage, Cypress App version, and browser support. |
| Replay capture affects test performance | The application has many or large canvases; capture can be resource-intensive. | Compare performance with canvas capture disabled. Cypress also recommends disabling video recording when Test Replay is enabled. |
| Canvas appears different from a local run | Replay shows what rendered in the recorded CI run; rendering conditions may differ between environments. | Reproduce with the same browser and CI conditions, and inspect the run’s state and events. For image-based visual checks, keep application state and rendering environment consistent. |
| Expected canvas debugging data is unavailable for a run | The browser or Cypress App version may not meet replay support requirements. | Review Cypress’s current Test Replay support limitations and record a supported run. |
6. A practical investigation workflow
- Use Test Replay to locate the point in the recorded CI run where the canvas should be visible.
- Inspect the surrounding application state and events to establish whether the UI reached the expected state.
- Confirm that the element is not a shadow DOM canvas and that the recording environment is supported.
- If the visual context is useful, keep canvas capture on. If performance is a concern, compare with it off and monitor the same CI workload.
- Consider video recording separately. Cypress recommends disabling video when Test Replay is enabled to optimize performance; retain it only if your workflow needs that artifact.
7. Or skip the browser setup
If you need a standalone screenshot of a page or a specific element for debugging or documentation, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It captures websites as PNG, JPEG, WebP, or PDF. It does not replace Test Replay’s recorded-run timeline or provide Cypress test state.
For a one-off page image, call the API with a URL. See the ScreenshotNeo API documentation for options and configuration.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, no card required.
8. FAQ
Does Test Replay capture every canvas frame?
Cypress documents that you can see canvas elements as they rendered in the recorded run. Its public documentation does not specify frame-by-frame capture behavior.
Can I configure canvas capture in Cypress test code?
The documented control is in Cypress Cloud project settings, beneath the main Test Replay recording toggle.
Is canvas capture always too expensive?
No universal cost is documented. Cypress warns that many or large canvases can be resource-intensive, so assess performance in your own CI environment.
Does a screenshot API provide the same information as Test Replay?
No. A screenshot API returns an image or PDF of a page. Test Replay is for examining a recorded Cypress run and its debugging data over time.
