Get Started

UI Test Automation Model (UTAM) is based on the popular Page Object model design pattern commonly used in UI tests. To use UTAM, a developer should build a page object for each UI component to encapsulate interactions in one place. UTAM provides a JSON grammar to write page objects and a compiler to generate runnable code in Java or JavaScript.

This article provides easy steps to get started with UTAM.

Step 1. Create a JSON page object

There are two ways to do it:

Step 2. Generate runnable page object code

To generate runnable Java or JavaScript code for page objects, configure the UTAM compiler in your project.

Step 3. Use UTAM page objects in a test

The first step is to create a UtamLoader object in your base test class. This step requires an instance of the driver (Selenium, Appium, or WDIO depending on the platform and language).


Here are some helpful pointers for Java:

Learn more about configurations specific to Java in the utam-java-recipes repo. The repo's README file explains how to set up tools and has examples of page objects, compiler setup, and tests.


Here are some helpful pointers for JavaScript:

Learn more about configurations specific to JavaScript in the utam-js-recipes repo. The repo's README file explains how to set up tools (Node and Yarn) and has examples of page objects and tests.

Step 4. More Documentation

Here's more documentation to check out:

Remember to use best practices:

If using JSON isn’t enough for your use case, learn about imperative extensions. But remember that using an imperative extension is an anti-pattern and is a last resort. We'd prefer that you request more features for the declarative language for your use case.

Learn about UTAM for Mobile

Compared to desktop tests, it's more complicated to set up tools (Node, Appium, Xcode, and Android Studio) in your development machine to execute a mobile test against your local iOS simulator or Android emulator. Fortunately, SFDX has a Mobile Extension Plug-In to help. Install it from SFDX CLI, and use it to check for the required Android and iOS configurations. If the mobile extension finds problems, the command output gives you hints for how to fix your environment. The mobile extension is a convenient way to set up mobile tools, but you don't have to use it.

To use UTAM to generate page objects for mobile native pages or components and run a test on iOS and Android platforms, consult either the Java or the JavaScript mobile setup guide.

Examples for Java are in the utam-java-recipes repo. Examples for JavaScript are in the utam-js-recipes. Each repo's README file explains how to set up necessary tools and where to find examples of mobile tests.