Proposed changes

In #12446 we implemented some building blocks that allow us to pierce through the ShadowDOM. This patch enhances on this effort and widens support for piercing to more crucial commands like getHTML. Users can now run snapshot tests that include the DOM structure of all underlaying Shadow Roots, e.g.:

await browser.url('https://sap.github.io/ui5-webcomponents/playground/iframe.html?viewMode=docs&id=main-button--button-overview')
await expect($('ui5-button')).toMatchInlineSnapshot(`
    <ui5-button icon="sap-icon://action" accessible-name="Button with Accessible Name" ui5-button="" has-icon="">
        Button Text
        <shadow-root>
            <button type="button" class="ui5-button-root" data-sap-focus-ref="" part="button" tabindex="0" aria-label="Button with Accessible Name" role="button">
                <ui5-icon class="ui5-button-icon" part="icon" name="sap-icon://action" accessible-role="presentation" ui5-icon="">
                    <shadow-root>
                    <svg class="ui5-icon-root" part="root" focusable="false" preserveAspectRatio="xMidYMid meet" xmlns="http://www.w3.org/2000/svg" role="presentation" aria-hidden="true" viewBox="0 0 512 512">
                        <g role="presentation">
                            <path d="M504 109q8 8 8 19t-8 19L395 249q-7 7-17 7-11 0-18.5-7.5T352 230q0-10 8-18l69-65h-52q-21 0-39.5 8T305 177t-22 33-8 40v76q0 11-7 18.5t-18 7.5-18.5-7.5T224 326v-76q0-32 12-60t32.5-49 48.5-33 60-12h38l-55-52q-8-8-8-18 0-11 7.5-18.5T378 0q10 0 17 7zm-50 194q11 0 18.5 7t7.5 18v62q0 38-26 64t-64 26H90q-38 0-64-26T0 390V90q0-38 26-64T90 0h137q11 0 18.5 7.5T253 26t-7.5 18-18.5 7H90q-17 0-28 11T51 90v300q0 17 11 28t28 11h300q17 0 28-11t11-28v-62q0-11 7-18t18-7z"></path>
                        </g>
                    </svg>
                    </shadow-root>
                </ui5-icon>
                <span class="ui5-button-text" id="ui5wc_1-content">
                    <bdi>
                    <slot></slot>
                    </bdi>
                </span>
            </button>
        </shadow-root>
    </ui5-button>
`)

When using web components we often see comments like <!--?lit$206212805$--><!--?lit$206212805$--> which are used to help the framework hydrate element correctly. Since these are not much helpful when snapshotting the DOM structure of elements, I also added an option that allows users to remove this.

Note: there is a lot more we can do to manipulate and clean up the DOM structure before returning the result. I was thinking of

• excludeElements: to remove elements from the snapshot that contain assets, e.g. like the SVG above
• excludeAttributes: to remove attributes from elements that contain random values, e.g. like the id attribute of .ui5-button-text above

I want to raise separate PRs for this.

Types of changes

This is a breaking change since we changed the interface of getHTML and now automatically pierce shadow roots which can impact users existing tests.

• Polish (an improvement for an existing feature)
• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update (improvements to the project's docs)
• Specification changes (updates to WebDriver command specifications)
• Internal updates (everything related to internal scripts, governance documentation and CI files)

Checklist

• I have read the CONTRIBUTING doc
• I have added tests that prove my fix is effective or that my feature works
• I have added the necessary documentation (if appropriate)
• I have added proper type definitions for new commands (if appropriate)

Backport Request

//: # (The current main branch is the development branch for WebdriverIO v9. If your change should be released to the current major version of WebdriverIO (v8), please raise another PR with the same changes against the v8 branch.)

• This change is solely for v9 and doesn't need to be back-ported
• Back-ported PR at #XXXXX

Further comments

n/a

Reviewers: @webdriverio/project-committers