Registry / testing / utam
library3.3.0jsnpmunverified

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 utam
INSTALL
IMPORT
SIG · UTAM
U
utam
testingjavascriptv3.3.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

utam
import { utam } from '@utam/core';
The global `utam` object is the entry point for loading generated Page Objects in tests. This is a runtime import from the `@utam/core` package.
HelloWorldPage
import HelloWorldPage from 'pageObjects/HelloWorldPage';
import { HelloWorldPage } from 'pageObjects/HelloWorldPage';
Generated Page Objects are typically default exports from their respective compiled modules, following a convention based on the JSON file structure. The path `pageObjects/HelloWorldPage` is illustrative and depends on your compiler configuration.
By
import { By } from '@utam/core';
`By` is a utility for constructing selectors, often used for dynamic element location or in imperative extensions within UTAM. It's a named export from `@utam/core`.

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.

/* // File: utam.config.json { "pageObjectsRootDir": "./src/main/utam", "outputDir": "./src/main/generated", "module": "esm" } // File: src/main/utam/helloWorld.utam.json { "root": true, "selector": { "css": "body" }, "elements": [ { "name": "welcomeText", "selector": { "css": "h1" }, "public": true, "type": "utam-core/element" }, { "name": "greetingButton", "selector": { "css": "button.greeting-btn" }, "public": true, "type": "utam-core/element" } ] } // CLI: First, compile the JSON page objects: npx utam -c utam.config.json */ // File: src/test/helloWorld.spec.ts (using WebdriverIO + wdio-utam-service) import { utam } from '@utam/core'; import HelloWorldPage from '../main/generated/helloWorldPage'; // Path depends on outputDir describe('Hello World UTAM Test', () => { let helloWorldPage: HelloWorldPage; beforeAll(async () => { // In a real WebdriverIO setup, this would be handled by wdio-utam-service // and browser.url() would be used before loading UTAM page objects. // For this example, we'll simulate page navigation. await browser.url('http://localhost:8080/hello'); // Navigate to the test page helloWorldPage = await utam.load(HelloWorldPage); }); it('should display the welcome text', async () => { const text = await helloWorldPage.getWelcomeText(); expect(await text.getText()).toBe('Welcome to UTAM!'); }); it('should interact with the greeting button', async () => { const button = await helloWorldPage.getGreetingButton(); await button.click(); // Assertions for the effect of clicking the button would go here // e.g., expect(await someOtherElement.getText()).toContain('Clicked'); }); });
Debug
Known issues
breakingUTAM's major versions are typically released three times a year, aligning with Salesforce's release cycle. Updating UTAM dependencies, especially `salesforce-pageobjects`, to match the current Salesforce release is crucial. Failure to do so can lead to UI test failures due to DOM changes not reflected in the Page Objects.
fix
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.
affects: >=1.0.0
gotchaBy default, the UTAM compiler will interrupt execution and throw an error on the first compilation error encountered in a JSON page object. This can be disruptive in large projects with many page objects.
fix
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.
affects: >=1.0.0
gotchaDebugging UTAM tests can be less intuitive than traditional code-based frameworks, as the core logic for element location and interaction is abstracted within compiled JSON page objects. Direct step-by-step breakpoints in IDEs might not always provide granular insights into the underlying UI interactions.
fix
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.
affects: >=1.0.0
gotchaUTAM utilizes a linting process during compilation to enforce best practices and identify potential issues like duplicate selectors or missing metadata. While warnings are informational, they can indicate fragile tests or design flaws.
fix
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.
affects: >=2.1.2
Errors
Common errors & fixes
Error Code 901: A non-root page object can't have a selector property. Either remove the selector property or add "root": true.
A non-root page object JSON file has been incorrectly marked with a 'selector' property.
fix
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.
Error Code 902: A root page object requires a selector property. Either add a selector property or remove "root": true.
A root page object JSON file is missing the mandatory 'selector' property.
fix
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.
Compilation failed: Input JSON files not found. Check 'pageObjectsRootDir' and 'pageObjectsFileMask'.
The UTAM compiler cannot find the source JSON page objects based on the configured paths and masks.
fix
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.
TypeError: Cannot read properties of undefined (reading 'load')
The `utam` runtime object (e.g., from `@utam/core`) is not properly initialized or imported in your test environment.
fix
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`.
Upgrade
Version history
3.3.0latest on npm
Audit
Dependencies
wdio-utam-serviceoptionalProvides an adapter for integrating UTAM Page Objects with WebdriverIO for JavaScript UI tests.
salesforce-pageobjectsoptionalContains pre-built UTAM Page Objects for standard Salesforce Lightning components, accelerating testing for Salesforce applications.
Agent activity
7 hits · last 30 days
node
6
Resources
utam — npm install utam · libregistry