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
- For a Java maven project, see here. However, it's easier to copy a module with an example from the
utam-java-recipesrepository, which has configured the compiler and uses the maven plugin in
pom.xmlto run the compiler. Running
mvn clean installor other maven build commands generates Java classes in the configured output folder.
utam-js-recipesrepository, which has configured the compiler. Running
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:
- 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.
- Configure WedDriverIO to use UTAM
- Example WebDriverIO config
- Test examples
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.
README file explains how to set up necessary tools and where to find examples of mobile tests.