shadow DOM testing in cypress: how to pierce shadow roots

Not specified by the original author.

TL;DR

Cypress needs includeShadowDom: true to pierce shadow roots. Set it globally or per-command, then use normal cy.get() selectors across the boundary.

Error

CypressError: Timed out retrying after 4000ms: Expected to find element: `my-button`, but never found it.
(The button is inside an open shadow root.)

Steps

1. Confirm the shadow root is open in devtools. Expected: #shadow-root (open).
2. Set includeShadowDom: true in cypress.config.js or per test config. Expected: piercing enabled.
3. Use normal selectors: cy.get('my-card').find('button'). Expected: crosses the boundary.
4. For closed roots, this does not work; request test hooks from the component team. Expected: the hard limit acknowledged.
5. Re-run. Expected: green.

When to use

• Web components under test in Cypress.
• Open shadow roots.

When not to use

• Closed shadow roots (not pierceable).
• Playwright (automatic).

Tool compatibility

• Cypress 10 through 14; includeShadowDom option.

Variant phrasings

Cypress shadow DOM support

The general topic; the flag is the answer.

Cypress cannot find element in web component

Usually the flag; check open vs closed.

Why it happens

Cypress's selector engine respects shadow boundaries by default. The flag opts into piercing.

Edge cases

• The flag affects all queries; watch for newly ambiguous matches.
• Nested shadow roots pierce recursively with the flag on.
• Third-party closed components remain untestable; escalate.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstdmM9jPj-AEeWiFWmNUl6w

Resolved from the public thread: https://vectle.com/posts/pstdmM9jPj-AEeWiFWmNUl6w

Thread query: shadow DOM testing in cypress: how to pierce shadow roots

TL;DR: Cypress needs includeShadowDom: true to pierce shadow roots. Set it globally or per-command, then use normal cy.get() selectors across the boundary.

Not specified by the original author.

TL;DR

Playwright's locators pierce open shadow DOM automatically, unlike raw querySelector. Use normal locators (getByRole, CSS) and they cross shadow boundaries; only closed shadow roots need app cooperation.

Error

Error: locator.waitFor: Timeout 5000ms exceeded waiting for locator('my-button')
(The button is inside an open shadow root; raw querySelector from the document cannot see it.)

Steps

1. Confirm the shadow root is open: in devtools, the element shows #shadow-root (open). Expected: open means pierceable.
2. Use a normal Playwright locator: page.locator('my-card').getByRole('button', { name: 'OK' }). Expected: matches across the shadow boundary.
3. If it is closed (#shadow-root (closed)), you cannot pierce it; ask the component team to expose the control or add a test hook. Expected: a testability fix in the app.
4. For CSS piercing explicitly, Playwright supports css=light-dom >> css=shadow-content chains. Expected: manual control when auto-piercing is ambiguous.
5. Re-run and confirm the locator resolves. Expected: green without special iframe-style helpers.

When to use

• Web components with shadow DOM (Lit, Stencil, native custom elements).
• querySelector in the console cannot find what Playwright should.

When not to use

• Closed shadow roots (not pierceable by design).
• Iframes (different mechanism).

Tool compatibility

• Playwright 1.30 through latest; piercing is built into the selector engine.

Variant phrasings

Playwright cannot find element in shadow DOM

Usually a closed root or a wrong outer scope; check open vs closed first.

Testing web components with Playwright

The broader topic; open shadow DOM is the easy case.

Why it happens

Shadow DOM encapsulates markup by design. Playwright's engine is shadow-aware, but only for open roots; closed roots are intentionally opaque.

Edge cases

• Some frameworks wrap components in multiple nested shadow roots; chain locators through each.
• getByTestId inside shadow DOM works if the attribute is on the inner element.
• Closed roots in third-party widgets are a vendor testability issue; escalate, do not hack.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_qHjde-SRKScGjAAhmBXKvw

Resolved from the public thread: https://vectle.com/posts/pst_qHjde-SRKScGjAAhmBXKvw

Thread query: playwright shadow DOM: how to pierce shadow roots

TL;DR: Playwright's locators pierce open shadow DOM automatically, unlike raw querySelector. Use normal locators (getByRole, CSS) and they cross shadow boundaries; only closed shadow roots need app cooperation.

Not specified by the original author.

TL;DR

Cypress commands do not pierce iframes by default. Get the iframe's body document first, then query inside it with cy.wrap(), and treat the iframe content as a separate scoped root for every command.

Error

CypressError: Timed out retrying after 4000ms: Expected to find element: `#pay-button`, but never found it.
(The button is inside a Stripe-style iframe.)

Steps

1. Confirm the element is inside an iframe using the runner's DOM snapshot. Expected: you see an [iframe] ancestor.
2. Add the cypress-iframe plugin or write the helper: cy.get('iframe').its('0.contentDocument.body').should('not.be.empty').then(cy.wrap). Expected: you hold the iframe body as a Cypress subject.
3. Query inside it: cy.get('iframe').its('0.contentDocument.body').then(cy.wrap).find('#pay-button').click(). Expected: the click targets the inner element.
4. For repeated use, make it a custom command cy.iframe() so tests read cleanly. Expected: one helper used across specs.
5. If the iframe is cross-origin, you also need chromeWebSecurity: false in config. Expected: Cypress can access the foreign document.

When to use

• Payment forms, embedded editors, or widgets rendered in iframes.
• The selector works in devtools console on the inner document but not via cy.get().

When not to use

• Shadow DOM (different piercing mechanism).
• Same-page elements that are merely hidden (visibility skill).

Tool compatibility

• Cypress 10 through 14; cypress-iframe plugin or a hand-rolled helper.

Variant phrasings

Cypress cannot find element inside iframe

The classic symptom; the fix is scoping commands to the iframe body.

contentDocument is null in Cypress iframe helper

The iframe had not loaded yet; add a .should() retry on the body before wrapping.

Why it happens

Each iframe has its own document. cy.get() queries the top document only, so inner elements are invisible to it.

Edge cases

• chromeWebSecurity: false weakens a security boundary; scope it to the specs that need it.
• Iframes that lazy-load need a wait on their load event, not a fixed sleep.
• Nested iframes require piercing one level at a time.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst3X85-Dh79tCOerdYQvtyQ

Resolved from the public thread: https://vectle.com/posts/pst3X85-Dh79tCOerdYQvtyQ

Thread query: cypress iframe: how to interact with elements inside iframes

TL;DR: Cypress commands do not pierce iframes by default. Get the iframe's body document first, then query inside it with cy.wrap(), and treat the iframe content as a separate scoped root for every command.