What is UTAM?

In the Salesforce Spring 22 release, Salesforce made a new UI test automation framework called UTAM (UI Test Automation Model) generally available. It adopts the PageObject model design pattern often associated with Selenium, taking page objects a step further by creating abstractions of page components, allowing for more robust UI testing. UTAM page objects can describe a web page itself or a web component at a more granular level or even go as far as to tell the composition of web components that could exist on one or more web pages.

Using this approach, UTAM has decoupled a test case from a web page or a web component to increase the test robustness and reduce the cost and complexity of test case maintenance as Salesforce changes from release to release. The UTAM component definitions may require changes, allowing the test case(s) to be unchanged and therefore providing separation of concerns:

  • Reduce duplication of web components/page objects and provide individual reusable UTAM components that are easy to maintain.
  • Ensure each UTAM component is only concerned with a single set of cohesive responsibilities relating to a single web component to improve maintainability and stability.
  • Increase maintainability and extensibility to support custom Lightning web components.

UTAM can execute a test case using Selenium or WebDriver.io test automation frameworks.

UTAM testing can be applied to both Salesforce and non-Salesforce web pages, using either the Salesforce page objects supplied for the standard components or authoring your UTAM page objects to test custom components. Alternatively, you could also use UTAM page objects provided by other developers to test other web applications or technologies as the community grows and developers begin to share page objects to support web technologies or applications. Initially, UTAM supports Java and Javascript, with plans to expand to other languages.

The big bonus here is that the UTAM page objects will support mobile testing via the Java implementation (Javascript to follow), meaning one UTAM page object provides cross-platform support for desktop and mobile!

All of the standard Salesforce components are provided and supported by the UTAM project, removing the maintenance burden of keeping the UTAM page objects up to date. With this massive cost saver, UTAM has unified the test automation experience for desktop and mobile testing in a single page object that is reusable across multiple test cases. 

Where Did My UTAM Experience All Begin?

I met UTAM in 2019 while meeting with the lead developers and architects behind the UTAM project at Dreamforce 2019. I got more detailed knowledge about UTAM and its roadmap to understand how Provar could better support Lightning Web Components in the future.

What is a Lightning Web Component?

Taking a step back to understand Lightning Web Components, Lightning follows the Web Component standard, consisting of three technologies to create reusable and versatile components with encapsulated functionality:

  • Creating custom elements, seen when creating a custom Lightning Web Component, when rendered on the page in Salesforce, details appear in the DOM with a <c- pre-fix.
  • Using the Shadow DOM to encapsulate the content of the component without fear of collision with other parts of the document as it is rendered separately to the central part of the document and protects the components from being manipulated by arbitrary HTML, CSS, and Javascript.
  • HTML templates to define a structure for the component and then inject content into slots <slot> as desired.

A consequence of using the Shadow DOM is that traditional element locators, like Xpath or CSS, won’t work as they can’t penetrate the Shadow DOM and traverse the elements inside the shadow tree. Not all browsers support Shadow DOM, so Salesforce provides a polyfill to implement shadow DOM functionality within a browser rather than the native browser implementation, preventing non-XPath locators from working like CSS but still allowing direct access for XPath locators.

How Can UTAM Help to Support Tests for Lightning Web Components?

Developers who use an existing UI test automation framework, like Selenium, may find it challenging to test and maintain their tests as Salesforce continuously changes the DOM in every release and migrates pages from Aura to Lightning. Hence, the UTAM helps developers create test cases quicker for their Salesforce components and orgs. The UTAM project will provide page objects for the standard Lightning Web Components, allowing developers to focus more on the test case.

The UTAM project will eventually support 450+ page objects to cover the standard Salesforce components. It will continue to grow as Salesforce’s internal team transitions from its existing legacy testing framework to using UTAM. You’ll be using the same UATM page objects used by the internal Salesforce teams to create your test cases for UI test automation.

In short, the UTAM page object definition for standard Salesforce components will be generated for you, published as NPM or Maven artifacts, and made available via public repositories (NPM, MVN Central). For now, you’ll need to manually generate the page objects from the *.utam.json definitions. It will take some of the pain away from you as a developer, avoiding the need to generate the standard UTAM definitions provided by Salesforce to simplify and streamline building and maintaining UTAM page objects and focus more on the test case.

Using the UTAM page objects makes it easier to handle modifications by updating the page objects rather than rewriting the entire or part of the test case to support changes in the web application. It provides a lower cost of ownership for the developer, allowing more time to focus on test case maintenance.  

Information on the UATM framework can be found here, with a beginner’s guide and live examples to play around with via tutorials to get you started. You can also find boilerplate UTAM examples for you to get to grips with UTAM:

  • The Javascript example recipes are available here
  • The Java recipes are available here
  • You may also find it helpful to watch the Lightning Web Component demo from Dreamforce 2021 that covers UTAM here

In Summary

I recommend a Salesforce developer using Lightning Web Components to look at the UTAM because it could help streamline your development efforts. Please provide feedback to the UTAM team to help evolve the framework and build a community to create page objects to help UTAM realize its potential beyond the Salesforce web application.

Given the changes to the Salesforce technologies, Provar has enhanced its Lightning Web Components support using ProvarX to allow XPath locators to penetrate the Shadow DOM in native browser implementation or using the Salesforce polyfill. Provar will soon provide additional enhancements to cater to custom Lightning Web Components; get in touch to know more.

Click here to learn how Provar can help you and your global development teams.