Get Started

UI Test Automation Model (UTAM) provides a JSON grammar to write page objects. The UTAM compiler generates runnable code from the JSON page objects.

UTAM is agnostic to the application under test. It isn't specific to the Salesforce platform and it can generate executable page objects for any consumer.

UTAM doesn't include a test runner. To use UTAM page objects from UI tests, integrate it with your test automation framework.


Talk is cheap! The best way to get started is to play with the suite of interactive tutorials that we've built. Tinker with the JSON page objects and see how the generated JavaScript code changes. Tweak a test and see if it still runs successfully. The best way to understand a test is to break it and then fix it again!

To start coding in a playground, check out the Tutorials.

Get Started for JavaScript

After you become familiar with the JSON page-object grammar and tests in the tutorials, you're ready to use UTAM on your own machine.

Start with the utam-recipes-sfdx repo.

The repo's README file explains how to set up tools (Node and Yarn) and has examples of page objects and tests.

UTAM is flexible. It isn't tied to a particular test automation framework or language. This particular repo uses WebdriverIO and Jasmine.

WebDriverIO is a browser and mobile automation test framework for Node.js.

Jasmine is a behavior-driven development framework for testing JavaScript code. This repo uses a WebdriverIO Jasmine plugin that's an adapter for the Jasmine testing framework.

Understand the Recipe Repo Structure

Here's an outline of the directory structure of the repo. It lists a few of the important configuration files.

├── force-app // contains JSON page objects and tests
├── pageObjects (created after build)
├── package.json
├── utam.config.js
└── wdio.conf.js

The repo has a hello Lightning web component. The JSON page object is in a __utam__ folder beside the component source.

├── lwc
    ├── hello
         ├── hello.html
         ├── hello.js
         ├── hello.js-meta.xml
         └── __utam__
             └── hello.utam.json

UTAM Compiler Configuration

Add a dependency for the UTAM compiler to the package.json file in the root of your project.

Declare compiler options in the utam.config.json configuration file.

For more details on package.json and the compiler configuration file, see Compiler Setup.

UTAM and WebdriverIO Integration

For details, see WebdriverIO Integration.


The tests are in the test directory.

When you look at the test code, you see some standard Jasmine methods.

For more information, see Write Tests.

For a tutorial, see Tutorials: Write a Test.

Page Objects

The JSON page objects are under the lwc directory. Look for a __utam__ directory inside each component directory.

For more information on page objects, see Design Page Objects and Page Object JSON Grammar.

Get Started for Mobile

Compared to desktop, 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. This is a convenient way to set up mobile tools, but you don't have to use it.

To understand how to use UTAM to generate page objects for mobile native pages or components and run a test on iOS and Android platforms, see more detail in UTAM Mobile. Examples are in the utam-tests module in the utam-java-recipes repo. For setup instructions, see the README file.