Can run on: Windows

GUI Automation drives web, Windows and Java application interfaces through Windows-only automation APIs, so these steps require an agent running on Windows.

GUI: Switch Shadow Host

Description

Use the Switch Shadow Host step to switch the execution context between the main DOM and a Shadow DOM. Once you switch context, other Web steps—such as Click, Set Value, and Get Value—can locate and act on elements inside the Shadow DOM. The step supports both a single shadow host and nested (multi-level) shadow hosts.

The step moves the automation's search context from the main DOM to the shadow host's DOM. A Shadow DOM isolates part of a page—such as a custom web component—from the main document, so standard element search cannot see the elements inside the Shadow DOM. As a result, your steps can fail with an "element not found" error, even though the element is visible on the screen.

How to use the step

• Add a Switch Shadow Host step. List each shadow host element the automation must enter, starting with the outermost (top) host.
• Add your Web steps (Click, Set Value, Get Value, and so on) as usual, using normal locators for the elements inside the shadow root. The Web steps automatically search inside the shadow root you set in step.
• When you finish working with shadow elements, add a second Switch Shadow Host step in Default mode. Default mode returns the search context to the main document, so later steps search normally again.

Known limitations:

• Closed shadow roots aren't supported. No automation tool, including Selenium, can access a closed shadow root.
• Only CSS Selector, ID, Class Name, Name, and Tag Name locators work inside a shadow root. XPath and Link Text search across the whole page and can't cross into a shadow root.
• List the full host chain in a single step. To reach a deeper host, list the entire chain from the outermost host to the target host in one Switch Shadow Host step. For example, to reach profile-card inside <user-panel> inside <my-app>, list all three hosts—<my-app>, <user-panel>, <profile-card> in that one step.
• You can't create the chain by adding a separate step for each host. Each Switch Shadow Host step must repeat the full chain up to the host you want to reach, even if you already set part of the chain in an earlier step. The Switch Shadow Host step always starts its search from the main DOM, and each step's rows fully replace the previously active chain, so a partial chain like <profile-card> alone fails with a "host element not found" error. For example, to reach <my-app>, then <user-panel> inside <my-app>, then <profile-card> inside <user-panel>, one level at a time:

<my-app>
  #shadow-root
     <user-panel>
     #shadow-root
       <profile-card>
          #shadow-root
            <button id="save-btn">Save</button>

Switch Shadow Host step	Hosts to set	Result
Step 1	<my-app>	The step enters <my-app>
Step 2	<my-app>, <user-panel>	The step enters <user-panel> inside <my-app>
Step 3	<my-app>, <user-panel>, <profile-card>	The step enters <profile-card>inside <user-panel>, inside <my-app>,

• Cross-origin iframes inside a shadow root aren't reachable. Only same origin iframes work.
• Spy and Recording don't detect shadow elements. Add the Switch Shadow Host step manually when you automate elements inside a Shadow DOM.

Note

• Use CSS Selector or ID locators for shadow hosts and shadow elements.
• Only one shadow context can be active during a workflow run, and it is shared across all browser instances. For multi-browser workflows, add a Switch to Shadow Host step set to Default to clear the shadow context before interacting with a different browser.
• Default mode isn't required to change or go deeper into the chain. Setting a new, full chain automatically overrides the previous one. Use Default mode only to exit the shadow context and return to normal search in the main DOM.

Example:

The example shows how to click a button inside nested shadow hosts.

Suppose you want to click a login button that sits inside a <user-panel> component, which itself sits inside a <my-app> component:

<my-app>
  #shadow-root
    <user-panel>
      #shadow-root
        <button id="login-btn">Log in</button>

To reach the button:

• Add a Switch Shadow Host step with two rows, listed from the outermost host to the innermost:
  • Row 1: id = my-app
  • Row 2: CSS Selector = user-panel

See following image:

Figure: Switch Shadow Host step listing the shadow hosts in order.

• Add a Mouse Action step with Click action type and use a normal locator for the button, for example ID = login-btn, see following image:

Figure: Mouse Actions step using the ID locator for the button.

The automation enters my-app first, then enters user-panel inside my-app, and then finds the button inside user-panel.

Configurations

Field Name	Description
Step name	Specify a unique name for the step. The label identifies the step within the workflow and helps you reference it when debugging or linking steps.
Web Browser Name	Select the browser that the shadow context applies to (for example, BROWSER1), for workflows that use multiple browsers. The value must match the browser name specified in the Start Browser step. The field is mandatory.
Switch To	Select the operating mode: • Shadow-Host: Enters the shadow host(s). Selecting this option displays the Shadow Host Path table. • Default: Exits the shadow context and returns to the normal page.
Shadow Hosts (outermost -> innermost)	Add one row for each shadow host. List the hosts from the outermost (parent) to the innermost (child). For example: The following example shows a nested Shadow DOM structure with three shadow hosts: Host A, Host B, and Host C. Figure: A nested Shadow DOM structure with three shadow hosts. In the example, The Save button is inside all three nested shadow hosts. Add the shadow hosts to the Shadow Host Path table in order, starting with the outermost host (Host A) and ending with the innermost host (Host C).
Locator Type	Select the locator type used to identify the shadow host: • Id • Name • Tag Name • Class Name • CSS Selector Note: XPath and Link Text are not supported inside shadow roots.
Locator Value	Specify the locator value for the shadow host (for example, my-app) The field accepts variable or static values or previous step field.