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 source appears quiet rather than actively maintained, with the last upstream push on 2024-03-27 and the provided update/release history ending in 2021-02-04 (1.0.0).
- Apparent update cadence is long and irregular, with several feature updates in 2018 to 2020 and then a large gap afterward (no evidence of frequent updates since 2021).
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.