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:

• If you have access to the HTML source, you can use the UTAM generator to generate JSON. This approach requires cloning and configuring the utam-js-recipes repository, which uses JavaScript. You will most likely need to edit the generated JSON to make it usable in your tests.
• Create the JSON file manually by following the steps here and by using the Page Object JSON Grammar spec. To learn the grammar interactively, use the interactive tutorials.

Step 2. Generate runnable page object code

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

• For a Java maven project, see here. However, it's easier to copy a module with an example from the utam-java-recipes repository, which has configured the compiler and uses the maven plugin in pom.xml to run the compiler. Running mvn clean install or other maven build commands generates Java classes in the configured output folder.
• For a JavaScript project, see here. However, it's easier to copy a module with an example from the utam-js-recipes repository, which has configured the compiler. Running utam -c utam-preview.config.js generates JavaScript classes and type definitions in the configured output folder.

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).

Java

Here are some helpful pointers for Java:

• The code snippet that creates UtamLoader
• An example of the base class in recipes
• Test examples in the recipes repository

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.

JavaScript

Here are some helpful pointers for JavaScript:

• The JavaScript UTAM implementation uses WebDriverIO as a test runner
• Configure WedDriverIO to use UTAM
• Example WebDriverIO config
• Test examples

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:

• JSON Grammar for JSON content supported in UTAM
• Browser extension to help you to know which page objects to use
• Mobile Inspector to help you to know which page objects to use for mobile hybrid applications
• Generate JSON page objects using the UTAM generator
• UTAM linting to set up static analysis and produce SARIF reports for your page object usage

Remember to use best practices:

• Explicit waits
• Tricks to check element presence
• Make sure page is loaded
• Drag and drop guide
• Working with slots
• Handle stale elements
• Working with frame/iframe

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.