How to Use Cypress UI Coverage
Use Cypress Cloud UI Coverage to find untested interactive elements, tune noisy reports, and turn real gaps into focused tests.
Cypress UI Coverage shows which visible, interactive parts of an application Cypress tests exercised and which they missed. To use it, record a Cypress run to Cypress Cloud with Test Replay enabled, then open the run’s UI Coverage tab. You need Cypress v13 or later and UI Coverage enabled for your organization; no plugin, test changes, or code instrumentation are required for UI Coverage itself.
1. Check the requirements
Before recording a run, confirm each prerequisite:
- The project has at least one run recorded to Cypress Cloud.
- Test Replay is enabled for the run. Runs recorded with Test Replay off do not produce a UI Coverage report.
- The project uses Cypress v13 or later.
- UI Coverage is enabled for the organization.
The Cypress setup guide describes UI Coverage as not included in standard Cypress Cloud plans and points to a free trial. Plan and trial terms can change, so check the current options in Cypress Cloud before relying on access.
2. Record a qualifying Cypress run
Run the tests and record the results using your project’s Cypress record key:
npx cypress run --record --key <your-record-key>Use the equivalent Cypress command for your package manager if you run Cypress through Yarn, pnpm, or Bun. Keep the record key private; configure it through your CI secret store rather than committing it to source control. When the recorded run meets the requirements, Cypress Cloud generates a UI Coverage report automatically for the unique states reached in end-to-end and component testing.
Open the run in Cypress Cloud and select UI Coverage. Start with the overall score, then inspect the score for each view. The report lists tested and untested elements, provides DOM snapshots to locate untested elements, and identifies links to destinations the tests have not visited.
3. Interpret the report carefully
The overall score represents the share of interactive elements exercised by tests. It is a diagnostic of the UI surface captured in that run, not a measure of overall software quality and not source-code coverage.
Several counting rules affect what you see:
- Only visible elements count toward the total.
- Grouped elements count as one unit.
- Distinct link destinations count once. A link is considered tested if a test interacts with it or visits its destination.
Use the score to locate areas to investigate, rather than treating every view or every missing interaction as equally important.
4. Turn useful findings into tests
- Prioritize important views. Begin with views tied to key user tasks or business flows, especially when their score is low.
- Inspect the missing elements. Use the DOM snapshot to identify untested buttons, inputs, links, and controls.
- Decide whether each gap belongs to your app. Exclude reporting noise such as third-party chat launchers, cookie banners, or links to out-of-scope destinations. Do not dismiss an element just because it is inconvenient to test; decide whether it is an owned interaction that users rely on.
- Add a focused test for real gaps. Write a test for the specific interaction or destination. Cypress Test Generation may also be available to help address gaps.
- Record a later run and review again. Check that the interaction now appears as tested and that the gap stays closed.
This confirm, address, and verify loop helps keep the report actionable as the application changes.
5. Tune UI Coverage configuration
UI Coverage configuration is edited as JSON in Cypress Cloud under Project Settings → App Quality, not in the repository. Configuration is opt-in and can be introduced incrementally. Cypress says changes can be applied to historical runs by reprocessing them, so you may not need to rerun tests just to see the effect of a configuration change.
| Option | Use |
|---|---|
elementFilters |
Exclude specific elements from the report. |
viewFilters |
Exclude whole views and links to those views. |
views |
Group URLs into report views. |
elementGroups |
Count repeated controls as a group. |
elements |
Rename elements or stabilize their identity. |
significantAttributes and attributeFilters |
Control which attributes matter when matching elements. |
additionalInteractionCommands and allowedInteractionCommands |
Tune which commands count as interactions. |
profiles |
Apply configuration overrides based on run tags. |
Some settings are shared with Cypress Accessibility when defined at the configuration root. UI Coverage-only settings belong under uiCoverage. For relevant shared options, a nested value replaces the root value rather than merging with it; repeat shared rules under uiCoverage if they should apply there too. By default, only Admin users can edit configuration. A Cypress point of contact can enable editing for other users.
6. Optional CI enforcement
Once reports are stable and the team agrees which views and elements count, you can use the Results API in CI to compare runs or enforce a threshold. Treat enforcement as optional: first remove noise and verify that the score reflects owned, meaningful interactions. Cypress’s pull-request policy guide says its referenced helper requires Test Replay and a run recorded within the previous seven days.
UI Coverage versus code coverage
UI Coverage tells you which visible interactive UI elements tests touch. Code coverage tells you which source lines, branches, and functions execute; Cypress’s code coverage workflow uses source instrumentation and the @cypress/code-coverage plugin. The two views answer different questions and can complement each other. UI Coverage does not replace instrumented code coverage.
Common problems and fixes
| Symptom | Likely cause | What to do |
|---|---|---|
| No UI Coverage tab or report | The run was not recorded to Cypress Cloud, Test Replay was off, the project is below Cypress v13, or the organization does not have the feature enabled. | Check each prerequisite, then record a new qualifying run. Confirm current organization access and plan in Cypress Cloud. |
| Report is missing after a recorded run | The run may not meet the Test Replay or feature-enable requirements. | Verify Test Replay was enabled for that run and UI Coverage is enabled for the organization. |
| Score is unexpectedly low | Important interactions may be untested, or visible third-party widgets and out-of-scope links may be adding noise. | Inspect low-scoring views and DOM snapshots. Add tests for owned interactions; filter genuine noise with view or element configuration. |
| Elements appear duplicated or unstable | Repeated controls or changing attributes may be treated as separate element identities. | Review elementGroups, elements, significantAttributes, and attributeFilters to make grouping and matching reflect the UI. |
| A configuration rule seems ignored | A nested uiCoverage value may replace a shared root value instead of merging with it, or configuration may be edited in the wrong place. |
Edit JSON in Cypress Cloud under Project Settings → App Quality, and repeat shared rules in the nested list where needed. |
| CI helper does not enforce the expected result | The referenced pull-request helper requires Test Replay and a run from the previous seven days. | Confirm both conditions and consult the current Results API and pull-request policy documentation. |
Performance, reliability, and cost considerations
UI Coverage reports are generated for qualifying recorded runs and describe the unique states those tests reached. A run that never visits a view cannot establish coverage for that view. Keep the report tied to the exact run and test scope you are reviewing, and revisit it after meaningful UI or test changes.
Configuration can be applied to historical runs by reprocessing them, which can help you refine filters and grouping without rerunning tests solely for that purpose. For CI decisions, use a recent run; the documented pull-request helper has a seven-day run window. Availability and pricing depend on Cypress Cloud organization settings and current plan terms, so confirm them in the product.
Or skip the browser setup
If your task is to capture a page while investigating a UI gap, ScreenshotNeo provides a one-request website screenshot API and an MCP server. Its capture can help you inspect a page without setting up browser automation. It does not generate or replace Cypress UI Coverage reports.
See the ScreenshotNeo API documentation. Example request:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed; an MCP server lets AI agents take screenshots; and 1,000 screenshots a month are free with no card, with paid plans starting at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan and get 1,000 screenshots a month with no card.
FAQ
Does UI Coverage measure whether the application is correct?
No. It identifies visible interactive UI elements exercised by tests. A high score does not establish that interactions work correctly or that the application is free of defects.
Does it cover component tests as well as end-to-end tests?
Cypress says reports cover unique states reached in both end-to-end and component testing for a qualifying recorded run.
Can I change the report without rerunning tests?
Cypress says configuration changes can be applied to historical runs through reprocessing. To verify newly added test interactions, record a later run.
