This package provides “deep” querySelector functions that can pierce nested Shadow DOM roots without manually traversing the shadowRoot path, making it useful for automated testing of Web Components. It also includes integration plugins for tools like WebdriverIO, Puppeteer, Playwright, and Protractor, so you can use a custom selector strategy or selector engine to find elements inside Shadow DOM. It is intended for test environments and notes that production use is not advised.
Project status
- The project appears quiet or in maintenance mode, with the last upstream update on 2024-03-27, and no updates shown since then (as of 2026-09-10), so it is not evidence-supported as actively maintained.
- Update cadence is sporadic and long-term, with notable releases mostly clustered in 2018 to 2021 and then a long gap until 2024, suggesting a low ongoing release rate rather than a steady evolution.
AI summary generated
Recent updates
1.0.0
Release 1.0.0 is primarily a version and housekeeping update (switching the default branch to main, plus “fix linter issues”). However, the actual code diff also includes substantive behavioral changes to selector parsing and to how element collection handles empty or null selectors, plus new lint enforcement during build.
Features0.8.0
Version 0.8.0 adds support for using a combinator chain (notably the '>' combinator) in selectors to match elements across nested shadow roots. It also refactors selector normalization into a new module and introduces an optional caching mechanism for previously collected elements.
Features0.7.0
Release 0.7.0 adds WebdriverIO support by introducing a custom locator strategy plugin intended to pierce nested shadow DOM. Alongside the plugin, the README and WebdriverIO example scripts are updated/added, and the project adds WebdriverIO and Selenium standalone tooling for development.
Features0.6.1
This release introduces an experimental Puppeteer integration intended to support querying inside nested shadow roots via Puppeteer’s custom Query Handler API. It also updates the Puppeteer-based examples to use the new handler approach instead of manually injecting the UMD bundle into the page context.
Features0.6.0
Release 0.6.0 introduces an official Protractor plugin for the project, adding a new Protractor locator strategy named `by.shadowDomCss(selector)`. It also adds a Protractor end to end test and documentation showing how to enable the plugin.
Features0.5.0
Release 0.5.0 focuses on normalizing CSS selectors before they are processed for deep traversal into (nested) shadow roots. This adds a selector normalization step and includes tests for edge cases like spacing around attribute values.
Features0.4.2
Release 0.4.2 appears to be a very small metadata-only update. The code diff shows only version bumps plus additional npm package keywords, with no application logic changes.
0.4.0
Version 0.4.0 adds Playwright integration by introducing a Playwright selector engine wrapper that delegates to this library's deep shadow DOM query functions. The release also updates documentation and examples to show how to register and use the selector engine in Playwright.
Features0.3.3
Release 0.3.3 provides a small fix related to how querySelectorDeep traverses parent nodes when evaluating selectors through nested/shadow DOM boundaries. The published release notes only credit a PR and do not describe the behavior change in detail.
0.3.2
Release 0.3.2 contains minimal changes, with the only functional code change in `src/querySelectorDeep.js` adjusting the return value when no matching element is found. Release notes were not provided by the publisher, so the behavior change is not documented.