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.
This repository contains two npm packages. Both packages demonstrate how to set up page object authoring and compilation.
This package contains:
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.
Clone the utam-js-recipes
repository:
$ git clone git@github.com: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:
force-app/test/crud.spec.js
) loads a provided URL and logs in through the standard login page before beginning the 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.
[!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.
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/
SANDBOX_USERNAME=your.username@salesforce.com
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 SANDBOX_USERNAME=user@salesforce.com 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:
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
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:
- Log in to the org you authenticated against during step 1 in a web browser.
- Click on the Setup icon in the upper right corner.
- Click Setup.
- Search for
dev hub
using the quick find search box on the left pane.- Click on the
Dev Hub
item underDevelopment
.- Click on the
Enable Dev Hub
toggle.- Create a scratch org using the
sfdx force:org:create
command mentioned previously
Push the app to your scratch org:
$ sfdx force:source:push
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
, runsfdx plugins:install user
and repeat from step 3
Open the scratch org:
$ sfdx force:org:open
If you need to recreate a scratch org:
sfdx force:org:list --all
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
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
[!NOTE] CRUD tests will modify real records in the org so only sandbox or development-specific orgs should be used.
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.
force-app/test/mobile
: navigation.spec.js
is against Community playground application and login.spec.js
is against Salelsforce application.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>',