{ "doc": { "id": "ui-coverage/guides/ignore-elements", "title": "Ignore elements in UI Coverage reports", "description": "Exclude third-party widgets, chat launchers, cookie banners, and other out-of-scope elements from Cypress UI Coverage with elementFilters, so your coverage score and untested-elements list stay focused on real gaps.", "section": "ui-coverage", "source_path": "/llm/markdown/ui-coverage/guides/ignore-elements.md", "version": "29f95bf8bb06f320986f3749f5bf09a35a409eab", "updated_at": "2026-09-04T10:49:54.630Z", "headings": [ { "id": "ui-coverage/guides/ignore-elements#ignore-elements", "text": "Ignore elements", "level": 1 }, { "id": "ui-coverage/guides/ignore-elements#when-to-ignore-an-element", "text": "When to ignore an element", "level": 2 }, { "id": "ui-coverage/guides/ignore-elements#step-1-find-the-elements-to-ignore", "text": "Step 1: Find the elements to ignore", "level": 2 }, { "id": "ui-coverage/guides/ignore-elements#from-the-cloud-ui", "text": "From the Cloud UI", "level": 3 }, { "id": "ui-coverage/guides/ignore-elements#with-an-ai-agent", "text": "With an AI agent", "level": 3 }, { "id": "ui-coverage/guides/ignore-elements#step-2-add-an-elementfilters-rule", "text": "Step 2: Add an elementFilters rule", "level": 2 }, { "id": "ui-coverage/guides/ignore-elements#exclude-everything-inside-an-iframe-or-shadow-dom", "text": "Exclude everything inside an iframe or shadow DOM", "level": 3 }, { "id": "ui-coverage/guides/ignore-elements#keep-specific-elements-out-of-a-broad-exclusion", "text": "Keep specific elements out of a broad exclusion", "level": 3 }, { "id": "ui-coverage/guides/ignore-elements#exclude-an-area-for-your-teams-runs-only", "text": "Exclude an area for your team's runs only", "level": 3 }, { "id": "ui-coverage/guides/ignore-elements#exclude-elements-from-your-markup-instead", "text": "Exclude elements from your markup instead", "level": 3 }, { "id": "ui-coverage/guides/ignore-elements#step-3-validate-the-result", "text": "Step 3: Validate the result", "level": 2 }, { "id": "ui-coverage/guides/ignore-elements#see-also", "text": "See also", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Ignore elements" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "UI Coverage tracks every " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/interactivity.md", "children": [ { "type": "text", "value": "interactive element" } ] }, { "type": "text", "value": " your application renders during a run, including plenty you never intend to test: a third-party chat launcher, the buttons in a cookie banner, a test-only debug toolbar. Each of these counts as an untested element, drags down your score, and buries the real coverage gaps under noise you can't act on." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Excluding those elements is what makes the report trustworthy. Once the elements your team isn't responsible for are gone, every remaining untested element is a genuine decision, and your score reflects coverage of the UI you actually own. This guide walks through finding those elements and excluding them." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Excluding removes an element from the report and the score entirely, whether a test touched it or not. If your goal is different, such as combining repeated elements so they count as one or renaming an element, see " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/overview.md#Which-option-do-I-need", "children": [ { "type": "text", "value": "Which option do I need?" } ] }, { "type": "text", "value": ". To exclude whole pages instead of individual elements, use " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/guides/ignore-views-and-links.md", "children": [ { "type": "text", "value": "`viewFilters`" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "When to ignore an element" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Reach for an exclusion when an untested element isn't a gap you'd ever close:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Third-party widgets you don't control, such as chat launchers, cookie consent banners, analytics or session-replay overlays, feedback and survey popups, social share buttons, and A/B-testing toolbars. Your team isn't responsible for testing them, so they shouldn't count as gaps." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Out-of-scope controls you've deliberately decided not to test, such as a test-only debug panel, an internal admin toggle, or a decorative control that triggers no behavior." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Elements inside an embed you don't own, such as a payment iframe, an embedded media player, a maps widget, or a third-party sign-in form rendered in an iframe or shadow DOM." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If an element is a real part of your product that you haven't tested yet, don't exclude it. That's a gap worth keeping. See " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/guides/identify-coverage-gaps.md", "children": [ { "type": "text", "value": "Identify coverage gaps" } ] }, { "type": "text", "value": " for how to close it instead." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Step 1: Find the elements to ignore" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Start from a recorded run and collect the elements that don't represent real gaps, along with a stable way to match each one. Do this in the Cypress Cloud UI, or have an AI agent shortlist candidates for you through Cypress Cloud MCP." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "From the Cloud UI" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Open the run's UI Coverage tab and scan the Untested elements section for entries that don't represent real gaps:" } ] }, { "type": "list", "ordered": true, "start": 1, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Look for untested elements your tests will never interact with, like the examples above." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Expand an element to see its selector, and note a stable way to match it: an `id`, a `data-*` attribute, a class, or a container it lives in." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Prefer a selector that matches a whole family at once (a third-party widget and everything inside it) over listing each element individually." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "With an AI agent" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If you use an AI coding assistant, " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/integrations/cloud-mcp.md", "children": [ { "type": "text", "value": "Cypress Cloud MCP" } ] }, { "type": "text", "value": " lets it pull the same report into your editor and shortlist exclusion candidates, so you can skip the manual scan. See " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/work-with-ai-agents.md", "children": [ { "type": "text", "value": "Work with AI agents" } ] }, { "type": "text", "value": " for setup and more prompts." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Find elements to ignore with your AI assistant" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Shortlists untested elements worth excluding, with a suggested selector for each." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Using Cypress Cloud MCP, pull the UI Coverage report for the latest run on this branch. First, list all of the untested interactive elements. Then, from that list, give me a second list of the ones that look like third-party widgets or out-of-scope controls worth excluding, such as chat launchers, cookie banners, analytics overlays, and embeds. For each element you suggest excluding, include a stable CSS selector I can drop into an elementFilters rule to exclude it and everything inside it." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Treat the agent's list as a shortlist, not a decision: you still confirm which entries are genuinely out of scope versus a real gap before excluding them." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Step 2: Add an elementFilters rule" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Open the App Quality tab in your project settings in Cypress Cloud and add an " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementfilters.md", "children": [ { "type": "text", "value": "`elementFilters`" } ] }, { "type": "text", "value": " rule. Each rule pairs a CSS selector with `include: false` to exclude the elements it matches. Here, a support chat widget rendered by a third party is removed so it stops counting as an untested element:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"elementFilters\": [\n {\n \"selector\": \"#intercom-container, #intercom-container *\",\n \"include\": false,\n \"comment\": \"Third-party support chat, not part of our app\"\n }\n ]\n}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Two things decide whether a rule matches:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The selector must match the interactive elements themselves, not just a container around them. A rule with the selector `#intercom-container` matches only that one `
`, not the buttons inside it. To exclude everything within a container, include its descendants with a descendant selector such as `#intercom-container *`, as above." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The first matching rule wins. Rules are evaluated top to bottom, and each element is decided by the first rule whose selector matches it. List specific rules before general ones." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Exclude everything inside an iframe or shadow DOM" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Third-party embeds often render inside an iframe or shadow DOM. Pair a wildcard selector with `documentScope` to remove the entire embed at once. The `documentScope` selector matches the iframe or shadow-DOM host in its parent document:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"elementFilters\": [\n {\n \"selector\": \"*\",\n \"include\": false,\n \"documentScope\": [\"iframe[title='Secure payment']\"],\n \"comment\": \"Embedded third-party payment form\"\n }\n ]\n}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "For content nested more than one level deep, list one selector per host from outermost to innermost. See the " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementfilters.md#Options", "children": [ { "type": "text", "value": "`documentScope` reference" } ] }, { "type": "text", "value": " for details." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Keep specific elements out of a broad exclusion" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Because the first matching rule wins, an `include: true` rule placed before a broader exclude rule protects the elements it matches. This is useful when a third-party container also holds elements you do want to test, such as your own navigation links inside a vendor toolbar:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"elementFilters\": [\n {\n \"selector\": \"nav a\",\n \"include\": true,\n \"comment\": \"Keep our nav links despite the vendor exclusion below\"\n },\n {\n \"selector\": \"[data-vendor] a\",\n \"include\": false,\n \"comment\": \"Ignore links rendered by the vendor toolbar\"\n }\n ]\n}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "On its own, an `include: true` rule changes nothing, since everything is included by default. It only matters as an exception ordered ahead of an exclude rule. For the full evaluation model, see " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementfilters.md#How-are-elementFilters-rules-applied", "children": [ { "type": "text", "value": "How are elementFilters rules applied?" } ] }, { "type": "text", "value": "." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Setting `elementFilters` at the root of your configuration affects both UI Coverage and Cypress Accessibility. To exclude elements for UI Coverage only, nest the property under a `uiCoverage` key. Note that `include: true` exceptions have no effect in Cypress Accessibility. See " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementfilters.md#Scope", "children": [ { "type": "text", "value": "Scope" } ] }, { "type": "text", "value": "." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Exclude an area for your team's runs only" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A root-level rule changes the report for everyone. When several teams share one Cypress Cloud project, that's often too broad: an area that's noise for your team may be exactly what another team is responsible for testing. Excluding it at the root would erase it from the other team's report too." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Use a " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/profiles.md", "children": [ { "type": "text", "value": "`profiles`" } ] }, { "type": "text", "value": " override to scope the exclusion to your own runs. A profile applies its `config` only to runs recorded with a matching " }, { "type": "link", "title": null, "url": "/llm/markdown/app/references/command-line.md#cypress-run-tag-lt-tag-gt", "children": [ { "type": "text", "value": "`--tag`" } ] }, { "type": "text", "value": ", so your team tags its runs and gets a report that drops what it doesn't own, while every other team's runs keep the base configuration." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "For example, the Account team doesn't own the support-chat widget, so its runs exclude it, but the Support team's runs (and the default report) still count it:" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"elementFilters\": [\n {\n \"selector\": \"#analytics-overlay, #analytics-overlay *\",\n \"include\": false,\n \"comment\": \"Analytics overlay, noise for every team\"\n }\n ],\n \"profiles\": [\n {\n \"name\": \"aq-config-team-account\",\n \"config\": {\n \"elementFilters\": [\n {\n \"selector\": \"#analytics-overlay, #analytics-overlay *\",\n \"include\": false,\n \"comment\": \"Repeat base rules — a profile replaces the base list, it doesn't merge\"\n },\n {\n \"selector\": \"#support-chat-widget, #support-chat-widget *\",\n \"include\": false,\n \"comment\": \"Account team doesn't own support chat, so it isn't a gap for us\"\n }\n ]\n }\n }\n ]\n}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "The Account team records with the matching tag, and only those runs pick up the extra exclusion:" } ] }, { "type": "code", "lang": null, "meta": null, "value": "cypress run --record --tag \"aq-config-team-account\"" }, { "type": "paragraph", "children": [ { "type": "text", "value": "A profile's `elementFilters` replaces the base list rather than merging with it, so repeat every base rule the tagged run still needs, as the example does for the analytics overlay. See " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/profiles.md", "children": [ { "type": "text", "value": "`profiles`" } ] }, { "type": "text", "value": " for merge behavior and how a tag selects a profile." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Exclude elements from your markup instead" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "When the team that owns the markup also owns the decision to exclude an element, you can do it in application code instead of Cloud configuration. Add " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/interactivity.md#Overriding-interactive-elements-with-data-cy-ui-interactive", "children": [ { "type": "text", "value": "`data-cy-ui-interactive=\"exclude\"`" } ] }, { "type": "text", "value": " to a single element, or `data-cy-ui-interactive=\"exclude-all\"` to a container to also exclude everything inside it:" } ] }, { "type": "code", "lang": null, "meta": null, "value": "\n\n\n\n
\n \n \n
" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Prefer `elementFilters` when you want to manage exclusions centrally in Cypress Cloud without changing application code, or when the team that manages configuration isn't the team that owns the markup." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Step 3: Validate the result" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "After saving, you don't need to rerun your tests. Open a recent run, go to its Properties tab, and use the regenerate button to reprocess it with your new configuration. In the regenerated report, confirm that:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "The excluded elements no longer appear in the Untested elements list." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Your coverage score reflects only the elements you intend to test." } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "If an element you excluded still appears, see " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/faq.md#Why-isnt-my-UI-Coverage-elementFilters-rule-excluding-an-element", "children": [ { "type": "text", "value": "Why isn't my elementFilters rule excluding an element?" } ] }, { "type": "text", "value": ". As your application grows, new third-party or out-of-scope elements may show up; update your filters when they do to keep reports actionable." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "See also" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/elementfilters.md", "children": [ { "type": "text", "value": "`elementFilters` configuration" } ] }, { "type": "text", "value": ": the full reference for options, rule ordering, and validation." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/guides/ignore-views-and-links.md", "children": [ { "type": "text", "value": "Ignore views and links" } ] }, { "type": "text", "value": ": exclude entire pages, and the links pointing to them, with " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/viewfilters.md", "children": [ { "type": "text", "value": "`viewFilters`" } ] }, { "type": "text", "value": "." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/guides/reduce-noise.md", "children": [ { "type": "text", "value": "Reduce noise" } ] }, { "type": "text", "value": ": consolidate repeated elements and stabilize dynamic identities instead of removing them." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/profiles.md", "children": [ { "type": "text", "value": "`profiles` configuration" } ] }, { "type": "text", "value": ": apply a different set of exclusions per run tag, so shared projects can report per team." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/guides/identify-coverage-gaps.md", "children": [ { "type": "text", "value": "Identify coverage gaps" } ] }, { "type": "text", "value": ": find the real gaps that remain once the noise is gone." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/interactivity.md", "children": [ { "type": "text", "value": "Interactivity" } ] }, { "type": "text", "value": ": which elements UI Coverage tracks, and the `data-cy-ui-interactive` markup attribute." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/overview.md", "children": [ { "type": "text", "value": "Configuration overview" } ] }, { "type": "text", "value": ": where to set configuration and how to regenerate reports." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/faq.md", "children": [ { "type": "text", "value": "UI Coverage FAQ" } ] }, { "type": "text", "value": ": common questions about excluding elements and scores." } ] } ] } ] } ] }, "token_estimate": 2240 }