UTAM JavaScript Recipes

This repository contains examples of how to test the Salesforce UI using the UTAM framework.

Note

This repository uses UTAM JavaScript. If you want to use UTAM with Java, visit the UTAM Java recipes repository.

Note

These recipes are designed to work with a generic Salesforce org. If your org has customizations, you might need to modify page objects or tests locally to avoid errors.

Important

This repository's page objects and UI tests are compatible with the Salesforce Spring'24 release.

Project structure

This repository contains two npm packages. Both packages demonstrate how to set up page object authoring and compilation.

1) utam-js-recipes package (project root)

This package contains:

• Custom components that can be deployed to a scratch org
• Page objects associated with those custom components
• UI tests
• Scripts that ease the initial setup

Here's an outline of the directory structure and 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

2) utam-preview package

This package contains the page objects used in the UI tests that interact with the Salesforce UI.

Both packages demonstrate how to setup page objects authoring and compilation.

Requirements

• Salesforce CLI
• Node >= 16
• Yarn >= 4

Initial setup

1) Clone the repository

Clone the utam-js-recipes repository:

$ git clone [email protected]:salesforce/utam-js-recipes.git
$ cd utam-js-recipes

2) Install dependencies

$ yarn install

3) Build the project

Execute yarn build to generate page objects:

$ yarn build

There are two types of tests in this project:

1. The first test (force-app/test/crud.spec.js) loads a provided URL and logs in through the standard login page before beginning the test.
2. The other test (force-app/test/sfdx-scratch-org.spec.js) runs against the custom app and components in this project by loading the app in a scratch org.

Both tests demonstrate how UTAM can be used to author and compile page objects, and how to integrate the UTAM runtime with WebdriverIO.

Dependency for Salesforce page objects

The package.json file contains a dependency for the salesforce-pageobjects package, which contains page objects from Salesforce. The package is available on npm.

Set up Salesforce Web UI tests

1) Create a .env file

We use a .env file to contain the URL and authentication credentials for test environments that we use.

Note

Do not commit your .env files. Those files contain sensitive credentials. The repository is set up so that we don't track those files by default.

Create a .env file by executing:

$ yarn create:env

This script creates a .env file located at the project root.

2) Configure your test environment variables

Open the .env file created during the previous step and configure your test environment credentials.

Here's a .env file that references a SANDBOX test environment. Each variable for the test environment starts with the test environment name followed by an underscore.

# Required variables
SANDBOX_URL=https://sandbox.salesforce.com/
[email protected]
SANDBOX_PASSWORD=strongPassword

# Optional variables
# sometimes after login URL changes
SANDBOX_REDIRECT_URL=https://lightningapp.lightning.test1234.salesforce.com/

# Used in force-app/test/record-update.spec.js
SANDBOX_ACCOUNT_ID=accountId
SANDBOX_CONTACT_ID=contactId

Replace SANDBOX with your test environment name.

A test references a test environment name in a call to the TestEnvironment constructor. For example:

const TEST_ENVIRONMENT_PREFIX = 'sandbox';
const testEnvironment = new TestEnvironment(TEST_ENVIRONMENT_PREFIX);

The environment name must be all uppercase in the .env file but the name is case insensitive in the JavaScript code. The environment name of sandbox in the test code matches the uppercase SANDBOX name in the .env file. A camel case environment name of sandboxOrg in the test code would match an uppercase SANDBOX_ORG name in the .env file.

Note

Add as many test environments as needed in your .env file. Just duplicate the variables and adjust the prefix and the values.

Alternatively, if you don't want to configure a .env file, you can prefix the test command with environment variables:

$ SANDBOX_URL=my-sandbox.com [email protected] SANDBOX_PASSWORD=password yarn test --spec force-app/test/record-*.spec.js

3) Update the Web UI tests

Open the Web UI test files located in:

• force-app/test/record-create.spec.js
• force-app/test/record-update.spec.js

For each test file, update the value of the TEST_ENVIRONMENT_PREFIX global variable located after the import statements:

// Assuming your test environment is sandbox (must match the prefix used in the .env file)
const TEST_ENVIRONMENT_PREFIX = 'sandbox';

For the force-app/test/record-update.spec.js file, update your .env file with the account and contact IDs of your test environment. That's how it looks like for an environment named sandbox:

SANDBOX_ACCOUNT_ID=XXXXXXXXXXXXXXXXXX
SANDBOX_CONTACT_ID=XXXXXXXXXXXXXXXXXX

Setup SFDX scratch org test

Prerequisites

Follow the steps in the Quick Start: Lightning Web Components Trailhead project. The steps include:

• Enable Dev Hub in your Trailhead Playground
• Install Salesforce CLI
• (Optional) Install Visual Studio Code
• (Optional) Install the Visual Studio Code Salesforce extensions, including the Lightning Web Components extension

Org Setup

1. If you haven't already done so, authorize your hub org and provide it with an alias (myhuborg in the command below). Use the login credentials generated from your Trailhead Playground in the Prerequisites section above or your own Developer Edition org if you prefer:

   $ sfdx auth:web:login -d -a myhuborg

2. Create a scratch org and provide it with an alias (utam-js-recipes in the command below):

   $ sfdx force:org:create -s -f config/project-scratch-def.json -a utam-js-recipes

Note

If this step throws an error ERROR running force:org:create: You do not have access to the [ScratchOrgInfo] object, you must enable Dev Hub. To enable Dev Hub:

1. Log in to the org you authenticated against during step 1 in a web browser.
2. Click on the Setup icon in the upper right corner.
3. Click Setup.
4. Search for dev hub using the quick find search box on the left pane.
5. Click on the Dev Hub item under Development.
6. Click on the Enable Dev Hub toggle.
7. Create a scratch org using the sfdx force:org:create command mentioned previously

3. Push the app to your scratch org:

   $ sfdx force:source:push

4. Assign the utam permission set to the default user:

   $ sfdx force:user:permset:assign -n utam

Note

If this step throws an error Permission set not found in target org, run sfdx plugins:install user and repeat from step 3

5. Open the scratch org:

   $ sfdx force:org:open

If you need to recreate a scratch org:

• find created org sfdx force:org:list --all
• delete previously created org with sfdx force:org:delete. It will prompt you to delete the org from the list, or specify an org alias or email sfdx force:org:delete -u utam-js-recipes
• recreate scratch orgs (repeat steps starting from step 3)

Running UI tests

Execute all tests at once by running:

$ yarn test

This command runs all UI tests in the repository, namely all tests in force-app/test/ folder.

Run the Web UI test

These tests require login credentials to an existing org. Make sure that your test environment is set up as described in Set up Salesforce Web UI tests.

Run the Web UI tests against the environment you configured:

$ yarn test --spec force-app/test/record-create.spec.js
$ yarn test --spec force-app/test/record-update.spec.js

To run all tests related to records, run:

$ yarn test --spec force-app/test/record-*.spec.js

Note

CRUD tests will modify real records in the org so only sandbox or development-specific orgs should be used.

Run the local app in a scratch org test

These tests run under the assumption that the initial URL loaded contains an access token so no manual login is required. To generate such a URL, follow the Org Setup steps above and then run:

$ yarn generate:login

This command runs the sfdx command below and adds the generated URL to the .env file in the root of this project.

$ sfdx force:org:open -p /lightning -r

Finally, run tests:

$ yarn test --spec force-app/test/sfdx-scratch-org.spec.js

Run the test against the UTAM doc site

The repository contains a test against utam.dev. The test doesn't require any special setup. The instructions to run it are inside the test.

Run Salesforce Mobile test

• There are two sample tests under force-app/test/mobile: navigation.spec.js is against Community playground application and login.spec.js is against Salelsforce application.
• Follow the instructions at Get Started for Mobile to set up your local simulator/emulator.
• Make sure that Appium and node.js are installed on your machine.
• Update the wdio configuration file: For an iOS test, update wdio.conf.xx.ios.js ((wdio.conf.sapp.ios.js is for test against Salesforce App, and wdio.conf.mpcc.ios.js is for test against Community Playground App) file to configure the test device name(appium:deviceName), iOS version(appium:platformVersion), and the full path for the test application(appium:app):

'appium:deviceName': 'iPhone 12',
'appium:app': '<path to iOS test app>',
'appium:platformVersion': '15.2',

For an Android test, update the wdio.conf.xx.android.js (wdio.conf.sapp.android.js is for test against Salesforce App, and wdio.conf.mpcc.android.js is for test against Community Playground App) file to configure the test device name(appium:deviceName) and the full path for the test application(appium:app):

'appium:deviceName': 'emulator-5554',
'appium:app': '<path to Android test app>',

• Download the Salesforce application Build and Community playground application build for the Salesforce iOS and Android mobile application debug builds.
• Commands to execute a test: For iOS: yarn test wdio.conf.xx.ios.js (wdio.conf.sapp.ios.js is for test against Salesforce App, and wdio.conf.mpcc.ios.js is for test against Community Playground App) For Android: yarn test wdio.conf.xx.android.js (wdio.conf.sapp.android.js is for test against Salesforce App, and wdio.conf.mpcc.android.js is for test against Community Playground App)
• For a test on Android, make sure to start an emulator before the test run. Otherwise, you will get an error like this: "Error: Failed to create session. An unknown server-side error occurred while processing the command. Original error: Could not find a connected Android device in 20190ms.".
• Install the appropriate version of chromedriver based on the instructions on this site.