DOM stands for Document Object Model. It's a way of representing a structured document via objects. It is a cross-platform and language-independent convention for representing and interacting with data in HTML, XML, and others.

What is Shadow DOM?

Shadow DOM refers to the ability of the browser to include a subtree of DOM elements into the rendering of a document, but not into the main document DOM tree. Shadow DOM fixes CSS and DOM. It introduces scoped styles to the web platform. Without tools or naming conventions, you can bundle CSS with markup, hide implementation details, and author self-contained components in JavaScript.

It is very important to understand the DOM structure and terminologies used before you start working on identifying the locators for the element. 

• Shadow host: The regular DOM node that the shadow DOM is attached to.
  
• Shadow tree: The DOM tree inside the shadow DOM.
  
• Shadow boundary: The place where the shadow DOM ends, and the regular DOM begins.
  
• Shadow root: The root node of the shadow tree. It's what gets attached to an element to give that element it's shadow DOM. Technically it's a non-element node, a special kind of Document Fragment.

Record Shadow DOM elements using QaSCRIBE

Similar to other HTML elements, Shadow DOM  elements actions performed on HTML content that has Shadow DOM elements are recorded by QaSCRIBE except in few cases identified below: 

• Navigating HTML page using tabs. If you navigate between fields in the web page using tabs instead of using mouse, actions are not recorded
• Combination of Shadow DOM & iFrame. If the Shadow DOM is placed within an iFrame actions are not recorded by QaSCRIBE
• Actions performed on "Closed Shadow DOM" elements cannot be recorded by QaSCRIBe

In such cases you need to add instructions manually including locators.

This document contains syntax, description on how the locators are written in QaSCRIBE.

Types of Locators and Usage

To pierce through shadow nodes the locator should always be prefixed with ‘@shadowDOM@’ string to distinguish it with normal locators.

Mainly there are two types of locators:

• Default Locators
• Content Locators

Default Locators

The default locators are standard CSS selectors supported by the browser.

Syntax: @shadowDOM@ <CSS selector>
Example: 

• @shadowDOM@ div[class="widget-title"]
  
• @shadowDOM@ pebble-icon>icon
  
• @shadowDOM@ pebble-icon~[class="icon=class"]     

Content Locators

The content locators are Worksoft SaaS custom notation which deals with the element content than element information.

1. Contains
2. Exact Match
3. Starts With
4. Ends With

1.Contains:

The contains locator will pierce through all the Shadow DOM locators and will return the first element content that contains the given text.

Syntax:@shadowDOM@ [@contains="<text to match>"]
Example:@shadowDOM@ [@contains="Progress"]

2.Exact Match: The exactMatch locator will pierce through all the Shadow DOM locators and will return the first element content that exactly matches the given text.

Syntax: @shadowDOM@ [@exactMatch="<text to match>"]
Example:@shadowDOM@ [@exactMatch="Tasks Progress Summary"]

3.Starts With: The startsWith locator will pierce through all the Shadow DOM locators and will return the first element content that starts with the given text.

Syntax:@shadowDOM@ [@startsWith="<text to match>"]
Example:@shadowDOM@ [@startsWith="Tasks Progress"]

4.Ends With: The endsWith locator will pierce through all the Shadow DOM locators and will return the first element content that exactly matches the given text.

Syntax: @shadowDOM@ [@endsWith="<text to match>"]
Example:@shadowDOM@ [@endsWith="Progress Summary"]

In addition to the above content locators also support the following Parent,Adjacent,Sibling and Children

• Parent

The parent locator will select the exact parent of the selected element in the DOM within the Shadow level.

Syntax: @shadowDOM@ [@<type>="<text to match>"]:parent()
Example: @shadowDOM@ [@exactMatch="Audio"]:parent()

• Adjacent

The adjacent locator will select the next residing element of the selected element in the DOM within the Shadow level.

Syntax: @shadowDOM@ [@<type>="<text to match>"]:adjacent()
Example: @shadowDOM@ [@exactMatch="Audio"]:adjacent()

• Sibling

The sibling locator will select the elements residing beside the selected element with the CSS selector criteria mentioned in the DOM within the Shadow level.

Syntax: @shadowDOM@ [@<type>="<text to match>"]:sibling(<CSS selector>)
Example:@shadowDOM@ [@exactMatch="Audio"]:sibling(div[dom-if])

• Children

The children locator will select the elements residing inside the selected element(1 level) with the CSS selector criteria mentioned in the DOM within the Shadow level.

Syntax: @shadowDOM@ [@<type>="<text to match>"]:children(<CSS selector>) 
Example:@shadowDOM@ [@exactMatch="Audio"]:children(span[class="only-badge"])

Note: The Default CSS locators and the content locators should be separated with a space. Only double quotes should be used to define attributes values.

Do's and Don'ts:

Dos:

1. Always use double quotes for attribute locators and Content locators. [id="newId"], [@exactMatch="SKU"]
2. Always separate default CSS locators and Content locators with space.
3. Always use (~) siblings, (+) adjacent and (>) children only with CSS locators.
4. Always use :parent(), :sibling(<CSS locator>), :adjacent(), :children(<CSS locator>) only with Content locators

Don'ts:

1. Don't use CSS locators and Content locators without space. div[class="newclass"]>[@contains="SKU"]
2. Don't prefix Content locators with the tag name. span[@startsWith="text"]
3. Don't use Content selectors inside parent, sibling, adjacent and children selectors. [@startsWith="SKU"]:parent():sibling([@contains="SKU"])

CSS selectors limitations and Content selectors features:

1. By default there is no parent selector in CSS. :parent() selector can be used with content selectors which traverses one parent at a time.
2. By default CSS sibling selector(~) will only detect the following siblings. The content locator for : sibling(<CSS Selector>) will traverse all the siblings.

Note: Please follow the above-mentioned dos and don'ts to avoid any locator issues in the future when new features are added to the engine.