UTAM (UI Test Automation Model) is an open-source, Salesforce-developed framework for creating robust and maintainable UI end-to-end tests. It abstracts away underlying DOM complexities by using a JSON-based Page Object Model (POM) grammar, which is then compiled into runnable JavaScript or Java Page Objects. Currently at version 3.3.0, UTAM typically aligns its major releases with Salesforce's three annual releases, ensuring compatibility with the frequently evolving Salesforce Lightning Experience and its Lightning Web Components (LWC). Key differentiators include built-in support for Shadow DOM, reliance on CSS selectors to avoid fragile XPath locators, and a compiler that can generate 'self-healing' test interfaces that require fewer updates when minor DOM changes occur. It integrates seamlessly with popular test runners like WebdriverIO through dedicated service adapters, providing a declarative approach to UI test automation that enhances collaboration across development and QA teams.
npm install utamVerified import paths — ran on the pinned version, not inferred.
Demonstrates compiling a basic UTAM JSON page object and then using the generated TypeScript Page Object with `utam.load()` in a WebdriverIO test to interact with UI elements.
Ensure `utam` and `salesforce-pageobjects` dependencies are updated to versions compatible with your target Salesforce environment. Consult the `utam-js-recipes` or `utam` npm README for compatibility matrix.
Set the `interruptCompilerOnError` option to `false` in your `utam.config.json` to allow the compiler to process all page objects, combine errors into a single report (`utam.errors.txt`), and throw an error only at the end.
Utilize `console.log()` statements within your test code and leverage browser developer tools. For deeper inspection, understand how the UTAM compiler translates JSON into JavaScript/TypeScript, and examine the generated files to trace element interactions. The UTAM Chrome extension can also aid in mapping page objects to UI elements.
Regularly review the `utam-lint.sarif` report generated during compilation. Address linting warnings by refactoring JSON page objects or adjusting compiler linting rules in `utam.config.json` if a specific rule is not applicable to your project. Avoid disabling linting entirely (`disable: true`) as it can hide critical issues.
Either remove the `selector` property from the JSON page object if it's meant to be a component used within another page object, or add `"root": true` if it's intended to be a top-level page object.
For any page object with `"root": true`, a `selector` property (e.g., `"selector": { "css": "body" }`) must be defined to tell UTAM how to locate the root element on the page.Verify that `pageObjectsRootDir` in `utam.config.json` points to the correct base directory for your UTAM JSON files and that `pageObjectsFileMask` correctly specifies the glob pattern to match them (e.g., `['**/*.utam.json']`). Ensure the compiler is run from the correct working directory.
Ensure that `import { utam } from '@utam/core';` is present and that your test runner (e.g., WebdriverIO with `wdio-utam-service`) is correctly configured to initialize the UTAM runtime environment before tests execute. This typically involves `wdio-utam-service` setup in `wdio.conf.js`.