Shadow DOM
// Definition
An encapsulated DOM subtree attached to an element, whose internals are hidden from the main document's normal selectors — the technology behind web components. A `<custom-widget>` may contain a whole UI inside its shadow root that `document.querySelector` can't reach without explicitly crossing the boundary.
// Why it matters
Shadow DOM is a classic automation blocker — tests fail to find elements that are visibly right there, because they're sealed inside a shadow root. QA cares because more component libraries (and design systems) ship as web components, so knowing how to pierce the shadow boundary is increasingly necessary rather than exotic.
// How to test
// Normal selectors stop at the shadow boundary — opt in to cross it:
cy.get('custom-date-picker') // the host element
.shadow() // enter its shadow root
.find('[data-cy=day-15]') // now reachable
.click()
// Playwright pierces open shadow roots automatically with its default engine.// Common mistakes
- Trying normal selectors and concluding the element "isn't there"
- Assuming all shadow roots are pierceable (closed shadow roots are not)
- Not knowing a component uses shadow DOM until the locator mysteriously fails
// Related terms
DOM
The Document Object Model — a tree-shaped, in-memory representation of an HTML (or XML) document that the browser builds after parsing the page source. Each element becomes a node, and JavaScript (and test tools like Playwright and Selenium) interact with the page by traversing and manipulating this tree. Understanding the DOM is essential for writing stable locators: a query like `#submit-btn` targets the DOM node, not the raw HTML string.
Locator
A description of how to find an element on a page — by id, CSS, XPath, role, or test attribute. Modern frameworks prefer role and test-id locators because they're resilient to DOM changes.
Selector
A CSS or XPath expression that identifies one or more DOM elements. Often used interchangeably with 'locator', though locator is the broader concept.