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

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

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

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.

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

Clone the utam-js-recipes repository:

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

$ yarn install

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.

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

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

Create a .env file by executing:

$ yarn create:env

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

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.

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

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

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

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

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

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)

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.

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

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

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.

• 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.