Testing in the shadow DOM

In web apps, a shadow DOM creates a hidden DOM tree of elements that is attached to an element in the main DOM tree. Developers use shadow DOMs as a way to isolate web components, making them easier to share across different frameworks, such as React or Vue.js. Shadow DOMs pose a unique challenge for test automation because elements in a shadow DOM cannot be found using traditional search methods.

This article outlines mabl’s approach to finding and testing elements in the shadow DOM.

How mabl finds shadow DOM elements

When you record a step within a shadow DOM, the mabl Trainer checks whether one of the target element’s ancestors is a shadow root. A shadow root is the root node of the hidden shadow DOM subtree, represented by #shadow-root in the page’s HTML. If the Trainer does identify a shadow root, it records that element as a “shadow parent” and adds an extra find strategy to the step.

During execution, mabl searches for the shadow parent, and then it implements its additional strategies to find the correct element in the shadow DOM tree. To check whether a step in a cloud run targeted an element with a shadow DOM, you can check the mabl Activity Logs for that step.

Test step logs on shadow DOM activity

If the target element is within a shadow DOM, output logs will indicate that mabl is looking for a “shadow parent”.

Shadow DOM indicator

In the Trainer, steps that target elements in a shadow DOM have a shadow DOM indicator in the lower right corner.

DOM warning indicator

If a recorded step shows the “DOM Warning” indicator, it means that mabl couldn’t uniquely identify the shadow root. This situation can happen if the web component lacks attributes to be identified by. In this case, you can use a CSS query to pierce the shadow DOM and identify the target element with greater confidence. For more information, refer to the article on custom find steps.

DOM warning icon

Slot elements

In some cases, the text within a web component comes from a slot element instead of from the innerText attribute. If the web component uses text from a slot element, the Trainer includes a “slotText” option for assertions and Configure Find.

If you assert on the text of an element in a shadow DOM and observe that its innerText value is empty or incomplete, try updating the assertion property to slotText.

A slotText assertion in the mabl Trainer

For more information on slot elements, you can refer to the MDN guide.

Limitations

Keep in mind the following limitations when training against shadow DOM elements:

• Testing closed shadow DOMs is not supported. Only open shadow DOMs are supported.
• Elements within a shadow DOM tree cannot be targeted with XPath.
• While Configure Find can specify attributes for an element within a shadow DOM, it cannot include attributes for the shadow root itself.
• During execution, mabl can auto-heal for elements within an element, but it cannot auto-heal on the shadow parent itself.
• In cloud run output, shadow DOM trees are not included in the HTML shown in the DOM tab.