{ "doc": { "id": "ui-coverage/get-started/setup", "title": "Get started with Cypress UI Coverage", "description": "Record a run with Test Replay, read your UI Coverage report, and tune it with App Quality configuration — no code changes or instrumentation required.", "section": "ui-coverage", "source_path": "/llm/markdown/ui-coverage/get-started/setup.md", "version": "fbc9225067c51c52ee13224e3b702cf8a025ec12", "updated_at": "2026-08-14T12:36:26.878Z", "headings": [ { "id": "ui-coverage/get-started/setup#get-started-with-ui-coverage", "text": "Get started with UI Coverage", "level": 1 }, { "id": "ui-coverage/get-started/setup#what-youll-need", "text": "What you'll need", "level": 2 }, { "id": "ui-coverage/get-started/setup#step-1-start-your-ui-coverage-trial", "text": "Step 1: Start your UI Coverage trial", "level": 2 }, { "id": "ui-coverage/get-started/setup#step-2-record-a-run-with-test-replay", "text": "Step 2: Record a run with Test Replay", "level": 2 }, { "id": "ui-coverage/get-started/setup#step-3-explore-your-ui-coverage-report", "text": "Step 3: Explore your UI Coverage report", "level": 2 }, { "id": "ui-coverage/get-started/setup#step-4-tune-your-reports-with-app-quality-configuration", "text": "Step 4: Tune your reports with App Quality configuration", "level": 2 }, { "id": "ui-coverage/get-started/setup#step-5-enforce-coverage-in-ci-optional", "text": "Step 5: Enforce coverage in CI (optional)", "level": 2 }, { "id": "ui-coverage/get-started/setup#next-steps", "text": "Next steps", "level": 2 }, { "id": "ui-coverage/get-started/setup#identify-coverage-gaps", "text": "Identify coverage gaps", "level": 3 }, { "id": "ui-coverage/get-started/setup#address-coverage-gaps", "text": "Address coverage gaps", "level": 3 }, { "id": "ui-coverage/get-started/setup#reduce-noise", "text": "Reduce noise", "level": 3 }, { "id": "ui-coverage/get-started/setup#compare-reports", "text": "Compare reports", "level": 3 }, { "id": "ui-coverage/get-started/setup#monitor-changes", "text": "Monitor changes", "level": 3 }, { "id": "ui-coverage/get-started/setup#work-with-ai-agents", "text": "Work with AI agents", "level": 3 }, { "id": "ui-coverage/get-started/setup#see-also", "text": "See also", "level": 2 } ] }, "chunks": [ { "id": "ui-coverage/get-started/setup#what-youll-need", "doc_id": "ui-coverage/get-started/setup", "heading": "What you'll need", "heading_level": 2, "content_markdown": "## What you'll need\n\nBefore you start, make sure you have:\n\n* **A Cypress project recording to [Cypress Cloud](/llm/markdown/cloud/get-started/introduction.md)** with a run or two already recorded.\n* **[Test Replay](/llm/markdown/cloud/features/test-replay.md) enabled** on the project. UI Coverage reports are built entirely from Test Replay data, so a run recorded with Test Replay off produces no report.\n* **Cypress v13 or later**, the minimum version that captures Test Replay data.\n* **UI Coverage enabled for your organization.** UI Coverage isn't included in standard Cloud plans. [Start a trial](#Step-1-Start-your-UI-Coverage-trial) to enable it for your projects.\n\nYou don't need to change your tests, add a plugin, or write any configuration to get a report. Configuration is opt-in and comes later, once you want to [sharpen the results](#Step-4-Tune-your-reports-with-App-Quality-configuration).\n", "section": "ui-coverage", "anchors": [ "what-youll-need" ], "path": "/llm/json/chunked/ui-coverage/get-started/setup.json", "token_estimate": 163 }, { "id": "ui-coverage/get-started/setup#step-1-start-your-ui-coverage-trial", "doc_id": "ui-coverage/get-started/setup", "heading": "Step 1: Start your UI Coverage trial", "heading_level": 2, "content_markdown": "## Step 1: Start your UI Coverage trial\n\nUI Coverage is enabled through a free trial. You'll get a personalized walkthrough that uses your **existing** recorded runs, so you can see exactly where your testing gaps are across your real projects before writing a single new test.\n\n[Request trial ➜](https://www.cypress.io/ui-coverage?utm_medium=get-started-page&utm_source=docs.cypress.io&utm_content=Request%20trial)\n", "section": "ui-coverage", "anchors": [ "step-1-start-your-ui-coverage-trial" ], "path": "/llm/json/chunked/ui-coverage/get-started/setup.json", "token_estimate": 67 }, { "id": "ui-coverage/get-started/setup#step-2-record-a-run-with-test-replay", "doc_id": "ui-coverage/get-started/setup", "heading": "Step 2: Record a run with Test Replay", "heading_level": 2, "content_markdown": "## Step 2: Record a run with Test Replay\n\nUI Coverage needs a run recorded to Cypress Cloud with Test Replay enabled. If you're already recording runs with Test Replay on, you can skip ahead to [Step 3](#Step-3-Explore-your-UI-Coverage-report) and open an existing run.\n\nTo record a new run, pass `--record` and your project's record key to `cypress run`:\n\n* npm\n* Yarn\n* pnpm\n* Bun\n\n```\nnpx cypress run --record --key \n```\n\n```\nyarn cypress run --record --key \n```\n\n```\npnpm cypress run --record --key \n```\n\n```\nbunx cypress run --record --key \n```\n\nNew to recording? Follow [Record a run to Cypress Cloud](/llm/markdown/cloud/get-started/setup.md) for the full setup, and confirm [Test Replay](/llm/markdown/cloud/features/test-replay.md) is enabled in your project settings.\n", "section": "ui-coverage", "anchors": [ "step-2-record-a-run-with-test-replay" ], "path": "/llm/json/chunked/ui-coverage/get-started/setup.json", "token_estimate": 163 }, { "id": "ui-coverage/get-started/setup#step-3-explore-your-ui-coverage-report", "doc_id": "ui-coverage/get-started/setup", "heading": "Step 3: Explore your UI Coverage report", "heading_level": 2, "content_markdown": "## Step 3: Explore your UI Coverage report\n\nAfter a run finishes recording, open it in Cypress Cloud and select the **UI Coverage** tab. A report is generated automatically for every recorded run, covering every unique state your tests reached, in both end-to-end and component testing.\n\nYour report answers four questions:\n\n* **What's my overall coverage?** The [coverage score](/llm/markdown/ui-coverage/faq.md#How-is-the-UI-Coverage-score-calculated) is the share of interactive elements your tests exercised.\n* **Which pages need the most attention?** Each [view](/llm/markdown/ui-coverage/core-concepts/views.md) (a page or state of your app) gets its own score, so you can rank pages and weigh each one against how critical it is to your users.\n* **What did my tests miss on a page?** Drilling into a view lists its untested [interactive elements](/llm/markdown/ui-coverage/core-concepts/interactivity.md#Interactive-Elements), each with a full-page, inspectable DOM snapshot showing exactly where it is.\n* **Which pages do my tests never reach?** [Untested links](/llm/markdown/ui-coverage/core-concepts/interactivity.md#Untested-Links) surface pages your tests link to but never visit, so you can see the flows your suite is missing entirely.\n\nThe UI Coverage tab: an overall coverage score, a per-view breakdown, and navigation to untested links, tested elements, and untested elements.\n\nStart with your lowest-scoring critical views. The [Identify coverage gaps](/llm/markdown/ui-coverage/guides/identify-coverage-gaps.md) guide walks through this workflow step by step, and [Address coverage gaps](/llm/markdown/ui-coverage/guides/address-coverage-gaps.md) shows how to close each gap, including generating a test for an untested element with [Test Generation](/llm/markdown/ui-coverage/faq.md#What-is-Test-Generation-in-Cypress-UI-Coverage).\n", "section": "ui-coverage", "anchors": [ "step-3-explore-your-ui-coverage-report" ], "path": "/llm/json/chunked/ui-coverage/get-started/setup.json", "token_estimate": 300 }, { "id": "ui-coverage/get-started/setup#step-4-tune-your-reports-with-app-quality-configuration", "doc_id": "ui-coverage/get-started/setup", "heading": "Step 4: Tune your reports with App Quality configuration", "heading_level": 2, "content_markdown": "## Step 4: Tune your reports with App Quality configuration\n\nYour first report is often noisier than the real gaps in your suite. Third-party widgets (chat launchers, cookie banners) count as untested elements, and links to pages you'll never test (identity providers, marketing sites) count against your score. A few lines of configuration remove that noise so every gap the report shows is a real one.\n\nConfiguration lives in Cypress Cloud, not in your repository. Open your project's **Project Settings**, select the **App Quality** tab, and edit the configuration as JSON. This example excludes a support chat widget and a third-party login page:\n\nApp Quality Config\n\n```\n{ \"elementFilters\": [ { \"selector\": \"#intercom-container, #intercom-container *\", \"include\": false, \"comment\": \"Support chat widget rendered on every page\" } ], \"viewFilters\": [ { \"pattern\": \"https://auth.mycompany.com/*\", \"include\": false, \"comment\": \"Third-party identity provider — not our app to test\" } ]}\n```\n\nAfter saving, you don't need to re-run your tests: reprocess any historical run from its **Properties** tab to see the effect of your change immediately. UI Coverage offers a full set of configuration options you can add incrementally:\n\n| Your goal | Use |\n| --- | --- |\n| Remove third-party widgets and other elements from the report | [`elementFilters`](/llm/markdown/ui-coverage/configuration/elementfilters.md) |\n| Remove entire pages, and links to them, from the report | [`viewFilters`](/llm/markdown/ui-coverage/configuration/viewfilters.md) |\n| Group related URLs into a single view | [`views`](/llm/markdown/ui-coverage/configuration/views.md) |\n| Combine repeated or related elements so they count as one | [`elementGroups`](/llm/markdown/ui-coverage/configuration/elementgroups.md) |\n| Rename or stabilize the identity of a single element | [`elements`](/llm/markdown/ui-coverage/configuration/elements.md) |\n| Prioritize your own attributes for identifying elements | [`significantAttributes`](/llm/markdown/ui-coverage/configuration/significantattributes.md) |\n| Stop dynamic or generated attributes from splitting an element | [`attributeFilters`](/llm/markdown/ui-coverage/configuration/attributefilters.md) |\n| Count a custom or plugin command as an interaction | [`additionalInteractionCommands`](/llm/markdown/ui-coverage/configuration/additionalinteractioncommands.md) |\n| Limit which commands count as coverage for specific elements | [`allowedInteractionCommands`](/llm/markdown/ui-coverage/configuration/allowedinteractioncommands.md) |\n| Apply different configuration to runs based on run tags | [`profiles`](/llm/markdown/ui-coverage/configuration/profiles.md) |\n\nSee the [Configuration overview](/llm/markdown/ui-coverage/configuration/overview.md) for how every option fits together, including which properties are [shared](/llm/markdown/ui-coverage/configuration/overview.md#Configuration-scope) with Cypress Accessibility.\n", "section": "ui-coverage", "anchors": [ "step-4-tune-your-reports-with-app-quality-configuration" ], "path": "/llm/json/chunked/ui-coverage/get-started/setup.json", "token_estimate": 456 }, { "id": "ui-coverage/get-started/setup#step-5-enforce-coverage-in-ci-optional", "doc_id": "ui-coverage/get-started/setup", "heading": "Step 5: Enforce coverage in CI (optional)", "heading_level": 2, "content_markdown": "## Step 5: Enforce coverage in CI (optional)\n\nOnce you trust your reports, you can hold the line on coverage automatically. The [Results API](/llm/markdown/ui-coverage/results-api.md) fetches a run's UI Coverage results in your CI job so your script can fail the build or [block a pull request](/llm/markdown/ui-coverage/guides/block-pull-requests.md) when coverage drops below a threshold you set. Enforcement is entirely opt-in and lives in your CI workflow.\n", "section": "ui-coverage", "anchors": [ "step-5-enforce-coverage-in-ci-optional" ], "path": "/llm/json/chunked/ui-coverage/get-started/setup.json", "token_estimate": 85 }, { "id": "ui-coverage/get-started/setup#next-steps", "doc_id": "ui-coverage/get-started/setup", "heading": "Next steps", "heading_level": 2, "content_markdown": "## Next steps\n\n* [\n \n ### Identify coverage gaps\n \n Go from a recorded run to a prioritized list of the untested buttons, forms, links, and pages in your application.\n \n ](/llm/markdown/ui-coverage/guides/identify-coverage-gaps.md)\n* [\n \n ### Address coverage gaps\n \n Close the gaps that matter by writing targeted tests or generating them directly from untested elements in the report.\n \n ](/llm/markdown/ui-coverage/guides/address-coverage-gaps.md)\n* [\n \n ### Reduce noise\n \n Group views and elements and tune attribute handling so your report reflects your app, not the framework.\n \n ](/llm/markdown/ui-coverage/guides/reduce-noise.md)\n* [\n \n ### Compare reports\n \n See exactly what a change did to your coverage by comparing any two runs in Branch Review.\n \n ](/llm/markdown/ui-coverage/guides/compare-reports.md)\n* [\n \n ### Monitor changes\n \n Track coverage over time and catch regressions as part of your CI/CD workflow with the Results API.\n \n ](/llm/markdown/ui-coverage/guides/monitor-changes.md)\n* [\n \n ### Work with AI agents\n \n Use Cypress Cloud MCP to pull scores, views, and untested elements from recorded runs and generate tests from your AI coding assistant.\n \n ](/llm/markdown/ui-coverage/work-with-ai-agents.md)\n", "section": "ui-coverage", "anchors": [ "next-steps" ], "path": "/llm/json/chunked/ui-coverage/get-started/setup.json", "token_estimate": 207 }, { "id": "ui-coverage/get-started/setup#see-also", "doc_id": "ui-coverage/get-started/setup", "heading": "See also", "heading_level": 2, "content_markdown": "## See also\n\n* [What is UI Coverage?](/llm/markdown/ui-coverage/get-started/introduction.md) explains the product and how it works at a glance.\n* [Interactivity](/llm/markdown/ui-coverage/core-concepts/interactivity.md) covers which elements are counted and which commands mark them tested.\n* [Views](/llm/markdown/ui-coverage/core-concepts/views.md) explains how the URLs your tests visit become views.\n* [Configuration overview](/llm/markdown/ui-coverage/configuration/overview.md) lists every App Quality configuration option and what each one does.\n* [Results API](/llm/markdown/ui-coverage/results-api.md) fetches a run's results in CI so you can enforce coverage standards.\n* [UI Coverage FAQ](/llm/markdown/ui-coverage/faq.md) answers common questions about scores, gaps, configuration, and troubleshooting.\n* [Troubleshooting](/llm/markdown/ui-coverage/troubleshooting.md) maps common report problems to their causes and fixes.\n", "section": "ui-coverage", "anchors": [ "see-also" ], "path": "/llm/json/chunked/ui-coverage/get-started/setup.json", "token_estimate": 127 } ] }