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, paste the HTML source into the UTAM generator playground to generate JSON. 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 inpom.xml
to run the compiler. Runningmvn 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. Runningutam -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.