How to Automate Shadow DOM in Selenium WebDriver

What Is Shadow DOM in Selenium?

Shadow DOM is a web standard that allows developers to encapsulate HTML elements inside a separate DOM tree attached to a host element.

In simple terms:

Main DOM → visible page, Shadow DOM → hidden, isolated mini-DOM.

Here is what that looks like in practice:

In this example, the <button id="submit"> inside the shadow root is invisible to driver.findElement(By.id("submit")). Selenium will throw NoSuchElementException because it only searches the regular DOM tree. That is exactly the situation many teams hit at the start.

Selenium cannot directly access elements inside a shadow root using traditional locators unless you explicitly traverse through the shadow host first. That is the core issue.

Why Selenium Fails With Shadow DOM?

When you run:

driver.findElement(By.id("login-button"));

Selenium searches the main DOM.

But if the element is inside #shadow-root (open), Selenium never sees it.

It is not broken. It is isolated by design.

Open vs Closed Shadow DOM

Shadow DOM has two modes, and this distinction is critical for automation.

Open Shadow DOM

Open mode (mode: 'open') exposes the shadowRoot property on the host element. JavaScript on the page, and Selenium, can access internal elements.

// Open: external code CAN access it
const shadowRoot = host.attachShadow({ mode: 'open' });
console.log(host.shadowRoot); // Returns the ShadowRoot object

Closed Shadow DOM

Closed mode (mode: 'closed') does not expose the shadowRoot property. It returns null. Neither getShadowRoot() nor JavaScriptExecutor can get through.

// Closed: external code CANNOT access it
const shadowRoot = host.attachShadow({ mode: 'closed' });
console.log(host.shadowRoot); // Returns null

What to do when you encounter closed Shadow DOM:

• Talk to the development team and ask for open mode or a testing API.
• Use Chrome DevTools Protocol (CDP) only if necessary, since it is browser-specific and fragile.
• Consider Playwright for shadow-heavy apps where deeper piercing is required.

For the rest of this guide, I focus on open Shadow DOM, which is what you will deal with in most real-world scenarios.

How to Access Shadow DOM in Selenium

There are two primary methods: getShadowRoot() (Selenium 4+) and JavaScriptExecutor (all versions). I'll also show a deep-piercing technique for nested trees and a reusable utility I use in every project.

Method 1: getShadowRoot() (Selenium 4+)

This is my preferred approach for most situations. Clean, readable, and works well for one or two levels of shadow nesting.

WebDriver driver = new ChromeDriver();
driver.get("https://bonigarcia.dev/selenium-webdriver-java/shadow-dom.html");

// Step 1: Find the shadow host in the regular DOM
WebElement shadowHost = driver.findElement(By.id("content"));

// Step 2: Get the shadow root
SearchContext shadowRoot = shadowHost.getShadowRoot();

// Step 3: Find elements inside using CSS selectors
WebElement textElement = shadowRoot.findElement(By.cssSelector("p"));
System.out.println(textElement.getText()); // "Hello Shadow DOM"

from selenium import webdriver
from selenium.webdriver.common.by import By

driver = webdriver.Chrome()
driver.get("https://bonigarcia.dev/selenium-webdriver-java/shadow-dom.html")

shadow_host = driver.find_element(By.ID, "content")
shadow_root = shadow_host.shadow_root
text_element = shadow_root.find_element(By.CSS_SELECTOR, "p")
print(text_element.text)  # "Hello Shadow DOM"

const { Builder, By } = require('selenium-webdriver');

let driver = await new Builder().forBrowser('chrome').build();
await driver.get('https://bonigarcia.dev/selenium-webdriver-java/shadow-dom.html');

let shadowHost = await driver.findElement(By.id('content'));
let shadowRoot = await shadowHost.getShadowRoot();
let textElement = await shadowRoot.findElement(By.css('p'));
console.log(await textElement.getText()); // "Hello Shadow DOM"

If the shadow root doesn't exist on the element, this throws NoSuchShadowRootException.

Method 2: JavaScriptExecutor

This works in Selenium 3 and 4. I reach for this when dealing with deeply nested shadow trees where chaining getShadowRoot() calls becomes unwieldy.

WebElement shadowHost = driver.findElement(By.id("content"));
JavascriptExecutor js = (JavascriptExecutor) driver;

SearchContext shadowRoot = (SearchContext) js.executeScript(
    "return arguments[0].shadowRoot", shadowHost
);

WebElement textElement = shadowRoot.findElement(By.cssSelector("p"));

shadow_host = driver.find_element(By.ID, "content")
shadow_root = driver.execute_script("return arguments[0].shadowRoot", shadow_host)
text_element = shadow_root.find_element(By.CSS_SELECTOR, "p")

let shadowHost = await driver.findElement(By.id('content'));
let shadowRoot = await driver.executeScript('return arguments[0].shadowRoot', shadowHost);
let textElement = await shadowRoot.findElement(By.css('p'));

To learn more about JavaScriptExecutor, check out my blog on how to use JavaScriptExecutor in Selenium WebDriver.

Method 3: Deep Piercing with a Single JS Call

For deeply nested shadow trees (3+ levels), I write a single JavaScript command that traverses all levels without returning to the Selenium context between each one. Much more efficient than multiple round trips.

WebElement deepElement = (WebElement) ((JavascriptExecutor) driver).executeScript(
    "return document.querySelector('#host-level-1')" +
    ".shadowRoot.querySelector('#host-level-2')" +
    ".shadowRoot.querySelector('#host-level-3')" +
    ".shadowRoot.querySelector('#target-element')"
);

deep_element = driver.execute_script(
    "return document.querySelector('#host-level-1')"
    ".shadowRoot.querySelector('#host-level-2')"
    ".shadowRoot.querySelector('#host-level-3')"
    ".shadowRoot.querySelector('#target-element')"
)

Reusable Shadow DOM Utility

I never scatter shadow root traversal logic across individual test methods. Instead, I use this utility in every project:

public class ShadowDomUtils {

    public static WebElement findInShadowDom(WebDriver driver, String... selectors) {
        String script = "let el = document.querySelector(arguments[0]);";
        for (int i = 1; i < selectors.length; i++) {
            script += " el = el.shadowRoot.querySelector(arguments[" + i + "]);";
        }
        script += " return el;";
        return (WebElement) ((JavascriptExecutor) driver)
            .executeScript(script, (Object[]) selectors);
    }
}

// Usage: pierces through 2 shadow roots to reach target
WebElement target = ShadowDomUtils.findInShadowDom(
    driver, "#outer-host", "#inner-host", "#target-button"
);
target.click();

def find_in_shadow_dom(driver, *selectors):
    script = "let el = document.querySelector(arguments[0]);"
    for i in range(1, len(selectors)):
        script += f" el = el.shadowRoot.querySelector(arguments[{i}]);"
    script += " return el;"
    return driver.execute_script(script, *selectors)

# Usage
target = find_in_shadow_dom(driver, "#outer-host", "#inner-host", "#target-button")
target.click()

This utility has been the single most useful piece of code in my shadow DOM automation toolkit. Drop it into your framework and you'll never write raw shadow root traversal again.

Handling Nested Shadow DOM

Many modern web apps have shadow DOM elements nested inside other shadow DOM elements. Salesforce LWC can go 3 to 5 levels deep. I've seen teams struggle with this, so let me walk through it.

Using the Watir demo page as our example:

driver.get("http://watir.com/examples/shadow_dom.html");

// Level 1
WebElement shadowHost = driver.findElement(By.id("shadow_host"));
SearchContext shadowRoot = shadowHost.getShadowRoot();
String someText = shadowRoot.findElement(
    By.cssSelector("#shadow_content > span")).getText();

// Level 2
WebElement nestedHost = shadowRoot.findElement(
    By.cssSelector("#nested_shadow_host"));
SearchContext nestedRoot = nestedHost.getShadowRoot();
String nestedText = nestedRoot.findElement(
    By.cssSelector("#nested_shadow_content > div")).getText();

// Fluent chaining style (concise alternative):
String nestedText = driver.findElement(By.id("shadow_host"))
    .getShadowRoot()
    .findElement(By.cssSelector("#nested_shadow_host"))
    .getShadowRoot()
    .findElement(By.cssSelector("#nested_shadow_content > div"))
    .getText();

driver.get("http://watir.com/examples/shadow_dom.html")

shadow_host = driver.find_element(By.ID, "shadow_host")
shadow_root = shadow_host.shadow_root
some_text = shadow_root.find_element(
    By.CSS_SELECTOR, "#shadow_content > span").text

nested_host = shadow_root.find_element(
    By.CSS_SELECTOR, "#nested_shadow_host")
nested_root = nested_host.shadow_root
nested_text = nested_root.find_element(
    By.CSS_SELECTOR, "#nested_shadow_content > div").text

Check out my blog on Shadow Root in Selenium Java for more advanced nested shadow DOM patterns. The complete source code is also available on my GitHub repository.

Cross-Browser Shadow DOM Behavior

Shadow DOM behavior has been a source of test failures in my experience. Here's the current state:

Python gotcha: Python's Selenium 4.0 did NOT include shadow root support. You need Selenium 4.1+ for the shadow_root property. Also, ShadowRoot in Python only supports By.CSS_SELECTOR. Using By.ID or By.XPATH inside a shadow root will fail.

Real-World Shadow DOM Examples

Most tutorials use demo pages. Here are examples from real applications I've had to automate.

Chrome Browser Downloads Page

Chrome's internal pages use nested Shadow DOM extensively. I've automated these for testing browser extensions and download verification.

driver.get("chrome://downloads")

# Single JS call is cleanest for Chrome's deep nesting
search_input = driver.execute_script(
    "return document.querySelector('downloads-manager')"
    ".shadowRoot.querySelector('downloads-toolbar')"
    ".shadowRoot.querySelector('cr-toolbar')"
    ".shadowRoot.querySelector('#searchInput')"
)
search_input.send_keys("my-file.pdf")

Shoelace UI Components

Shoelace is a popular web component library. If your app uses Shoelace buttons or inputs, you need to pierce the shadow DOM:

// Clicking a Shoelace button
WebElement slButton = driver.findElement(By.cssSelector("sl-button"));
SearchContext buttonShadow = slButton.getShadowRoot();
buttonShadow.findElement(By.cssSelector("button.button")).click();

// Typing into a Shoelace input
WebElement slInput = driver.findElement(By.cssSelector("sl-input"));
SearchContext inputShadow = slInput.getShadowRoot();
inputShadow.findElement(By.cssSelector("input.input__control"))
    .sendKeys("Hello World");

# Clicking a Shoelace button
sl_button = driver.find_element(By.CSS_SELECTOR, "sl-button")
button_shadow = sl_button.shadow_root
button_shadow.find_element(By.CSS_SELECTOR, "button.button").click()

# Typing into a Shoelace input
sl_input = driver.find_element(By.CSS_SELECTOR, "sl-input")
input_shadow = sl_input.shadow_root
input_shadow.find_element(By.CSS_SELECTOR, "input.input__control") \
    .send_keys("Hello World")

Custom Video Players

Many custom video players use Shadow DOM for controls. Accessing play buttons or volume sliders requires shadow root traversal:

video_player = driver.find_element(By.CSS_SELECTOR, "custom-video-player")
player_shadow = video_player.shadow_root

play_button = player_shadow.find_element(By.CSS_SELECTOR, ".play-btn")
play_button.click()

Debugging Shadow DOM Elements

DevTools Tips

Enable full shadow DOM visibility: Open Chrome DevTools > Settings > Elements > check "Show user agent shadow DOM". This reveals shadow roots inside native elements like <input> and <video>.

Copy JS path (the biggest time-saver): Right-click any element inside a shadow root in the Elements panel > Copy > Copy JS path. Paste it into executeScript(). Done.

Verify from console before writing code:

let host = document.querySelector('#my-component');
console.log(host.shadowRoot);
// ShadowRoot object = open, accessible
// null = closed or no shadow root

Common Errors and Fixes

Handling Waits with Shadow DOM

Standard ExpectedConditions can't reach inside shadow roots. Here's the pattern I use:

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));

WebElement target = wait.until(d -> {
    try {
        WebElement host = d.findElement(By.id("shadow-host"));
        SearchContext root = host.getShadowRoot();
        return root.findElement(By.cssSelector("#target-element"));
    } catch (NoSuchElementException | NoSuchShadowRootException e) {
        return null;
    }
});

from selenium.webdriver.support.ui import WebDriverWait

def find_shadow_element(driver):
    try:
        host = driver.find_element(By.ID, "shadow-host")
        root = host.shadow_root
        return root.find_element(By.CSS_SELECTOR, "#target-element")
    except Exception:
        return False

element = WebDriverWait(driver, 10).until(find_shadow_element)

Selenium vs Playwright vs Cypress

I get asked this a lot. Here's my honest comparison:

Playwright's advantage: page.locator("#target-inside-shadow").click() just works, no shadow root traversal needed.

When Selenium is still the right choice: Broadest language support, largest community, most integrations, W3C standard. If your team already has a Selenium framework, adding shadow DOM handling with the techniques in this guide is straightforward. I still use Selenium for most of my projects.

5 Best Practices of Shadow Dom Automation

These are the five practices I've settled on after working with shadow DOM across multiple projects:

1. Always use CSS selectors inside shadow roots. XPath does not work. This is a W3C spec constraint, not a bug. I've seen teams waste hours trying to force it.

2. Build reusable utility methods. Don't scatter traversal logic across tests. Use the findInShadowDom() utility or encapsulate access in page objects.

3. Keep shadow root logic in page objects. The Page Object Model keeps tests clean:

public class SettingsPage {
    public void setUsername(String username) {
        WebElement host = driver.findElement(By.cssSelector("settings-panel"));
        host.getShadowRoot().findElement(By.cssSelector("input.username"))
            .sendKeys(username);
    }
}

// Test stays clean
settingsPage.setUsername("john.doe");

4. Use custom waits for dynamic shadow elements. Shadow DOM components often render asynchronously. Use the wait patterns from the debugging section above.

5. Test across browsers. Shadow DOM behavior still has edge cases across browsers, especially Safari. Run your shadow DOM tests on a cloud grid to catch these early. TestMu AI's Selenium Grid supports 3000+ browser and OS combinations for exactly this purpose.