shadow-automation-selenium
A Java Selenium plugin for automating multi-level Shadow DOM and custom HTML tags in web applications.
What is shadow-automation-selenium?
Shadow Automation Selenium is a Java plugin that extends Selenium WebDriver to automate interactions with Shadow DOM elements and custom HTML tags. It solves the problem of Selenium's inability to access Shadow DOM, which is commonly used by modern frontend frameworks like Polymer for component encapsulation. The library provides methods to locate, wait for, and manipulate these otherwise inaccessible elements.
Java Selenium automation engineers and QA developers working on web applications that use Shadow DOM or custom HTML tags, particularly those built with Polymer or similar Web Components frameworks.
Developers choose this plugin because it seamlessly integrates into existing Selenium projects, requires minimal code changes, and provides a comprehensive set of utilities for handling Shadow DOM without needing complex workarounds or switching automation tools.
Overview
This project focuses on automation of multi-level shadow root dom using java selenium. You can embed this plugin in your java selenium project.
Use Cases
Best For
- Automating Polymer-based web applications with Shadow DOM
- Testing custom HTML elements that Selenium cannot identify directly
- Adding Shadow DOM support to existing Java Selenium frameworks
- Writing PageFactory-based tests for Shadow DOM components
- Handling nested Shadow DOM trees in multi-level component architectures
- Synchronizing tests with implicit or explicit waits for Shadow DOM elements
Not Ideal For
- Projects using Selenium in languages other than Java, unless adopting the separate Python library
- Web applications without Shadow DOM or custom elements, as the library adds unnecessary complexity
- Teams preferring Selenium 4's native Shadow DOM APIs to avoid third-party dependencies
- Scenarios requiring extensive, up-to-date documentation or large community support
Pros & Cons
Pros
Directly penetrates nested Shadow DOM trees using CSS or XPath selectors, solving Selenium's key limitation with frameworks like Polymer, as demonstrated by methods like findElement for elements under shadow-root.
Handles custom HTML tags like <paper-tab> that Selenium cannot identify, enabling automation of modern web components without workarounds.
Drops into existing Java Selenium projects via Maven/Gradle and works with PageFactory using @FindElementBy annotation, minimizing code changes.
Includes wait mechanisms, element checks (e.g., isVisible), and form interactions (selectDropdown), reducing the need for extra helper code in tests.
Cons
Primarily for Java; Python support is via a separate project (pyshadow), which may lag in updates or features, fragmenting cross-language teams.
Requires mastering specific CSS and XPath rules for Shadow DOM, such as using double slashes in XPath, which can be error-prone and less intuitive than standard Selenium.
Tightly tied to Selenium versions (e.g., 0.1.6 requires Java 11 and Selenium 4.16.1), risking breaks with updates and limiting backward compatibility.
Frequently Asked Questions
Related Projects
query-selector-shadow-domquerySelector that can pierce Shadow DOM roots without knowing the path through nested shadow roots. Useful for automated testing of Web Components. Production use is not advised, this is for test environments/tools such as Web Driver, Playwright, Puppeteer
cypress-litTest your Lit elements and native web components in cypress with all the modern browsers
capybara-shadowdomShadow DOM support for Capybara
W3C Webdriver conquering automation of Shadow DOMShadow DOM tree and its interaction with the W3C Webdriver
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.