Salesforce UI test automation

When to use

• A regression escaped Apex tests and Jest because it lives in the rendered page.
• A committed end-to-end suite is needed for a flow a user clicks through.
• An existing UI suite is flaky, slow, or authenticates by pasting a password into a config file.
• An Agentforce agent needs behavioural tests.
• Not for configuring an org through a browser - that is sf-setup-automation.
• Not for component-level assertions, which belong in sf-lwc-jest-testing.

Pick the tier that can actually catch the bug

A browser test is the most expensive assertion in the codebase. Work up the table, not down.

If a Jest test can fail on the bug, write the Jest test. Everything below assumes it cannot.

1. The UTAM stack, with versions

UTAM is Salesforce's UI Test Automation Model: page objects declared as .utam.json, compiled into JavaScript classes, driven by a runtime that resolves shadow DOM for you.

salesforce-pageobjects is the part that makes this viable: the Lightning shell, app navigation and Flexipage internals are already modelled, so your own page objects only describe your components. There is no @utam/cli package - the compiler is invoked as utam -c utam.config.js.

2. Project shape

utam.config.js - what to compile and where the classes land:

module.exports = {
    pageObjectsFileMask: ['force-app/**/__utam__/**/*.utam.json'],
    pageObjectsOutputDir: 'pageObjects',
    alias: { 'utam-sfdx/': 'utam-js-recipes/', 'utam-*/': 'utam-preview/' },
    lint: { printToConsole: false },
};

wdio.conf.js - the service, and the Salesforce page objects injected into the runtime:

const { UtamWdioService } = require('wdio-utam-service');

exports.config = {
    specs: ['force-app/test/**/*.spec.js'],
    capabilities: [{ browserName: 'chrome', 'goog:chromeOptions': { args: ['--no-sandbox', '--disable-dev-shm-usage', '--disable-gpu'] } }],
    services: [[UtamWdioService, { implicitTimeout: 0, injectionConfigs: ['salesforce-pageobjects/ui-global-components.config.json'] }]],
    framework: 'jasmine',
    waitforTimeout: 60 * 1000,
};

implicitTimeout: 0 is deliberate: UTAM waits on conditions, and an implicit wait on top of that turns one slow element into a multi-minute run. Full files and the npm scripts: references/utam-project.md.

3. Authenticate without a credential in the repo

Salesforce's own recipes get a login URL from the CLI and write it to .env - no password anywhere:

const getUrlCmd = 'sf org open -p /lightning -r --json';   // -r is --url-only
const { url } = JSON.parse(stdout).result;                  // frontdoor URL, single use

Two rules that follow from what that URL is. sf org open --url-only prints "This command will expose sensitive information that allows for subsequent activity using your current authenticated session", and the URL is minted single-use through /services/oauth2/singleaccess:

• Regenerate it per run. A stored URL is both a credential and, after one navigation, useless.
• .env holding it is gitignored, and the value never goes into a log line or a CI artefact.

In CI, run against a scratch org created for the job and deleted with it - see sf-scratch-orgs-sandboxes for the ephemeral-org script.

4. Page objects describe structure, specs describe behaviour

A page object is JSON: a root selector, elements typed by the page object that models them, and composed methods for multi-step interactions.

{
  "root": true,
  "selector": { "css": "body" },
  "elements": [
    { "name": "navigationBar", "type": "salesforce-pageobjects/global/pageObjects/appNav",
      "public": true, "selector": { "css": "one-appnav" } }
  ]
}

The spec then reads as navigation plus assertions, with waits expressed as conditions:

await browser.navigateTo(testEnvironment.sfdxLoginUrl);
const domDocument = utam.getCurrentDocument();
await domDocument.waitFor(async () => (await domDocument.getUrl()).includes('Hello'));
const appHomePage = await utam.load(HomePage);
const item = await (await (await appHomePage.getNavigationBar()).getAppNavBar()).getNavItem('Wire');
await item.clickAndWaitForUrl('lightning/n/Wire');

No CSS selector for a Lightning internal ever appears in a spec. When Salesforce restyles the shell, salesforce-pageobjects changes and your specs do not.

5. Agentforce agent tests

Agent behaviour is tested by definition, not by clicking: AiEvaluationDefinition metadata plus the CLI.

Details of the metadata type live in sf-agentforce-development.

Anti-patterns

Verification

npm run build                 # utam -c utam.config.js, then compile the page objects
npx wdio run wdio.conf.js --spec force-app/test/<one>.spec.js
sf apex run test --target-org <alias> --test-level RunLocalTests --code-coverage --result-format human
node "$CLAUDE_PLUGIN_ROOT/scripts/checks/vf-check.mjs" jest --changed
sf agent test run --target-org <alias>        # when the project has agents

A UI suite is healthy when the same spec passes twice in a row on a cold org, and its failure output names a condition that timed out rather than an element that vanished.

References

• references/utam-project.md - dependency table, the recipes' npm scripts verbatim, full wdio.conf.js and utam.config.js, page object grammar, CI layout.
• Sibling skills: sf-lwc-jest-testing (the tier below), sf-apex-testing, sf-scratch-orgs-sandboxes (ephemeral org for a run), sf-agentforce-development, sf-setup-automation (a browser for configuration, not for tests).
• UTAM recipes (source of every verbatim config here): https://github.com/salesforce/utam-js-recipes
• salesforce-pageobjects on npm: https://www.npmjs.com/package/salesforce-pageobjects
• sf org open flags and its security warning: https://github.com/salesforcecli/plugin-org/blob/main/messages/open.md
• sf agent test * commands: https://github.com/salesforcecli/plugin-agent