Free tools Windows power users keep installed
One-click scans. No signup required.
To test an element inside a web component’s shadow root, select the component host and chain Cypress’s .shadow() command before querying the element. Use includeShadowDom instead when a particular query—or your whole project—should search across shadow boundaries. Cypress leaves that option off by default.
Target one component with .shadow()
Start with a selector for the element that directly hosts the shadow root. Then enter that root and query within it:
As an Amazon Associate I earn from qualifying purchases.
cy.get('checkout-panel')
.shadow()
.find('button')
.click()Here, checkout-panel is the shadow host. The .shadow() query yields its shadow root, so the following .find() is scoped to that component rather than searching unrelated roots.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11You can also use .contains() after entering the root when the target is easier to identify by text:
cy.get('checkout-panel')
.shadow()
.contains('Continue')
.click().shadow() must receive a DOM element that is itself a shadow host. It is not a command to call directly from cy; first yield the host with a query such as cy.get(). Cypress retries while waiting for the host, its shadow root, and any chained assertions. Its timeout is governed by defaultCommandTimeout.
Choose between explicit traversal and includeShadowDom
| Approach | Scope | Use it when |
|---|---|---|
.shadow() |
Enters the root of the named host in the command chain. | The test should make clear which component boundary it crosses. |
{ includeShadowDom: true } on a query |
Lets that query include matching content across shadow boundaries. | One query should search more broadly without changing the project-wide convention. |
Global includeShadowDom configuration |
Enables shadow-boundary traversal for queries project-wide. | Broad traversal is an intentional, consistent test-suite convention. |
Cypress’s global includeShadowDom setting defaults to false. To opt in for a single query, pass the option to cy.get():
cy.get('.shadow-button', { includeShadowDom: true }).click()For the global setting, add includeShadowDom: true to the Cypress configuration for your project. Check the configuration reference for the format that matches your installed Cypress version. A global setting changes query behavior throughout the suite; it is not necessary just to reach one known component.
Understand what queries search
With shadow inclusion off, cy.contains() does not search inside shadow roots by default. You can opt in on the query or chain it from a particular root:
cy.get('checkout-panel')
.shadow()
.contains('Continue')Similarly, .find() does not cross a shadow boundary by default. If its current subject is already inside a shadow root, it searches that tree; to enter a host’s root explicitly, put .shadow() in the chain first. These defaults make the distinction useful: use explicit traversal for one component, and broad inclusion only when the test is intended to search more widely.
Diagnose a failing shadow-DOM query
If a command times out or cannot find the target, check the boundary and the element lifecycle in this order:
- Confirm the host selector. Make sure the query yields the component element that actually owns the shadow root, not a wrapper or a descendant outside it.
- Confirm a root is attached. A custom element may not have created its shadow root yet, or may not create one in the state under test. Cypress can retry while waiting, but it cannot find a root that never appears.
- Query after entering the root. For a targeted query, chain
.shadow()before.find()or.contains(). Without it or shadow inclusion, a query will not automatically cross the boundary. - Check the timeout condition. Cypress retries the host/root query and chained assertions until they pass or the command times out. If the component takes longer to render, review the applicable
defaultCommandTimeoutand the application’s readiness behavior.
Chrome click behavior
Cypress documents a specific caveat: in Chrome, cy.click() sometimes may not click the intended element in a shadow-root case because of ambiguity in the specification. Its example shows .click('top') as a workaround for that case. Treat it as a documented, narrow workaround—not a guarantee that this option fixes every shadow-DOM click failure.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Shadow DOM in Cypress UI Coverage
Cypress UI Coverage documentation says it identifies interactive elements inside shadow DOM and qualifies their identities with the host chain. That helps distinguish similarly named elements in coverage reporting. UI Coverage identification is separate from the selectors and traversal commands used in Cypress test code.
Or skip the browser setup
For a real website screenshot—not a Cypress test—you can request a capture with one GET call. The API returns an image or PDF; see the ScreenshotNeo API documentation for options.
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpScreenshotNeo is a website screenshot API and MCP server, not a replacement for Cypress’s shadow-root testing commands. It accepts cookie banners and removes known consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server gives AI agents screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month, with no card.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
