Writing and maintaining end-to-end (E2E) tests is hard, but some tools can make a difference. In this post, I’ll share what Salesforce provides to streamline this process. We’ll go through a refresher on the UI Test Automation Model (UTAM), and we’ll take a look at two elements that make UTAM great for Salesforce E2E tests: the base page objects (PO) and the UTAM Chrome extension.

A brief refresher on UTAM

UTAM is an open-source solution built by Salesforce that lets you design E2E tests on any kind of app. UTAM works in conjunction with a test runner, and its key benefit is that it decouples test code from the DOM thanks to page objects (PO).

POs are written in JSON with a simple syntax to describe a subset of the page. They can refer to specific DOM elements and other POs. Once assembled, JSON PO definitions are compiled into JavaScript, TypeScript, or Java objects thanks to the UTAM compiler. These objects are then used in E2E tests.

The decoupling between the test code and the DOM allows you to reuse the PO and simplify maintenance across releases. For example, if the DOM of a page under test changes during a release (for example if a CSS class is renamed), you only need to update the related PO definition versus potentially multiple instances of that selector spread out across your test collateral.

Read this post for a more detailed overview of UTAM.

Explore UTAM base page objects

As we mentioned earlier, UTAM promotes the DRY (don’t repeat yourself) principle of engineering. Thanks to this architecture, Salesforce can ship a set of base page objects that cover Lightning Experience. As of the Winter ’24 release, there are 727 base page objects available on the Maven Central Repository and NPM. This list continues to grow as more and more Salesforce engineering teams use UTAM for their internal E2E tests.

Base POs represent internal components that compose the Lightning Experience. These range from low-level components (Lightning base components, such as an input or a combobox) to top-level components (the Org login screen, the app launcher, the navigation menu, list views, or record pages). Any Lightning Experience page is composed of tens if not hundreds of these components and their matching base POs.

This trove of base POs serves two main purposes: reuse and maintenance.

Base POs provide a set of ready-to-use building blocks for implementing Salesforce E2E tests by saving you the work of implementing your own PO manually by inspecting the DOM.

Base POs also spare you from the effort of maintaining the PO definitions between Salesforce releases. Our product teams update them whenever they introduce DOM changes across releases so that you don’t have to. All you have to do to upgrade for a Salesforce release is to simply fetch the latest base PO package.

While base POs are your best friends when building UTAM tests, it is challenging to navigate this growing number of resources because the majority of these POs refer to internal components that Salesforce developers don’t interact with programmatically. Thankfully, we released a tool that helps developers identify which PO they need to use to build their E2E tests.

Quickly navigate between page objects with the UTAM Chrome extension

The UTAM Chrome extension acts as a visual guide that helps you navigate the complexity of the pages that you are testing and lets you find the right PO to use for your tests. Using the tool is a three-step process:

1. Import the base PO package, and possibly your own custom PO as well.
2. Navigate to the page that you want to test and use the plugin to detect the root PO for the current page.
3. Drill down into the PO list to get to the part of the page that you want to access. The tool is smart enough to let you select POs that are compatible with each other.

During steps two and three, the tool highlights the page elements that are covered by the selected PO. For example, if you were to simulate the creation of a new Account record from a list view (clicking on the “New” button), this is what your screen would look like (notice the red border around the elements):

As you compose your chain of PO calls, the browser extension provides you with generated Java or JavaScript code to use in your tests. Once you’re done with your composition, simply copy/paste the generated code into your end-to-end test to save valuable time.

Closing words

This concludes our overview of UTAM and our tour of the tools that streamline its use. You had a glimpse at the trove of base POs that cover the Lightning Experience and the UTAM Chrome extension that will help you find and use the POs for your end-to-end tests. Check out the resources below, install the Chrome extension, and get started with UTAM and E2E tests.

Resources

• Some UTAM introduction resources
  • Run End-to-End Tests With UTAM blog post
  • Run End-to-End Tests With UTAM Quick Takes video
• The UTAM website for documentation, tutorials, and tools
• Example repositories:
  • UTAM JavaScript Recipes
  • UTAM Java Recipes
  • E-Bikes sample app
• UTAM page objects for Lightning base components:
  • NPM package (JavaScript)
  • Maven Central package (Java)
• UTAM Chrome extension

About the author

Philippe Ozil is a Principal Developer Advocate at Salesforce where he focuses on the Salesforce Platform. He writes technical content and speaks frequently at conferences. He is a full-stack developer and enjoys working on DevOps, robotics, and VR projects. Follow him on Twitter @PhilippeOzil or check his GitHub projects @pozil.