UTAM: a New Testing Framework for Salesforce Developers

Published by Simon Carter, March 2, 2022
Salesforce UTAM Explained by Provar | Approved Salesforce Testing Platform

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 describe 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+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 either 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 own UTAM page objects to test custom components. Alternatively, you could also use UTAM page objects provided by other developers if available for testing 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 both Java and Javascript with plans to expand to other languages in the future.

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 providing cross-platform support for both 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 first came across 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 give better support for 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 elements 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 main 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 difficult to test and maintain their tests as Salesforce continuously changes the DOM in every release and migrates pages from Aura to Lightning. Hence the introduction of the UTAM to help support developers create test cases quicker for their Salesforce components and orgs. To support this, the UTAM project will provide page objects for the standard Lightning Web Components which allows a developer to focus more on the test case.

The UTAM project will eventually provide support for 450+ page objects to cover the standard Salesforce components and will continue to grow as Salesforce’s internal teams transition from their existing legacy testing framework to using UTAM instead. Meaning 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 objects definition for standard Salesforce components will be generated for you and published as NPM or Maven artifacts and made available via public repositories (NPM, MVN Central). For the time being, you’ll need to manually generate the page objects from the *.utam.json definitions. This 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. This 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 beginners 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 Javascripts 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 would recommend a Salesforce developer using Lightning Web Components to look at the UTAM because it could help streamline your development efforts. Give 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 either in native browser implementation or using the Salesforce polyfill. Provar will soon be providing additional enhancements to cater for custom Lightning Web Components, get in touch to know more.

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

We use cookies to better understand how our website is used so we can tailor content for you. For more information about the different cookies we use please take a look at our Privacy Policy.

Scroll to Top