search

salesforce / utam-java-recipes

Examples of testing with UTAM Java
MIT License
18 stars 17 forks source link
utam

readme

utam-java-recipes

UI Test Automation Model (UTAM) is based on the popular Page Object model design pattern commonly used in UI tests. UTAM documentation is here.

Initial setup

This repository is a Maven project with examples of UTAM compiler setup and UI tests written with UTAM.

The project uses Java 11 and Maven 4.

  1. Clone the repository and install the Maven project.
git clone https://github.com/salesforce/utam-java-recipes.git
cd utam-java-recipes
mvn clean install
  1. Import this project as a Maven project in the IDE of your choice.

Dependency from Salesforce page objects

In the main pom.xml of this project you will notice dependency from Salesforce page objects:

<dependency>
    <groupId>com.salesforce.utam</groupId>
    <artifactId>salesforce-pageobjects</artifactId>
    <version>${salesforce.pageobjects.version}</version>
</dependency>

Dependency version should match the Salesforce application version that is deployed on the environment under test. In this repository version will always be pointing to the latest released Saleforce application deployed on production. If test environment is not yet updated, please find matching version in maven central

Dependency from UTAM framework

In the main pom.xml of this project you will notice dependency from utam-core, version should be latest and compatible with Salesforce page objects artifact (see previous section) if your tests use it:

<dependency>
   <groupId>com.salesforce.utam</groupId>
   <artifactId>utam-core</artifactId>
   <version>${utam.framework.version}</version>
</dependency>

utam-preview module has dependency from UTAM compiler, version should be same as for utam-core:

<dependency>
    <groupId>com.salesforce.utam</groupId>
    <artifactId>utam-compiler</artifactId>
    <version>${utam.framework.version}</version>
    <scope>runtime</scope>
    <type>jar</type>
</dependency>

Generate Page Objects

The utam-preview module is an example of page objects authoring and compilation. This module also contains Salesforce page objects for default org setup that can be used to build Salesforce UI tests.

IMPORTANT: Page objects and tests for the Salesforce UI are compatible with application Spring'24.

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.

To generate page objects, run this maven command from the project root:

mvn clean install

Run Salesforce Web UI tests

The utam-tests module contains examples of setup for UTAM page objects usage, test utilities, and Salesforce UI tests.

Preconditions:

The content of the file should look like this, where "sandbox" is the name of the environment. An env.properties file can reference more than one environment.

sandbox.url=https://sandbox.salesforce.com/
sandbox.username=my.user@salesforce.com
sandbox.password=secretPassword
# sometimes after login URL changes
sandbox.redirectUrl=https://lightningapp.lightning.test1234.salesforce.com/

In the login method inside a test, provide the prefix of your environment as a parameter. In this env.properties file, the prefix is sandbox.

TestEnvironment testEnvironment = getTestEnvironment("sandbox");

  @BeforeTest
  public void setup() {
    setupChrome();
    loginToHomePage(testEnvironment);
  }

To run tests in an IDE, for example in IntelliJ IDEA, click on the class or method and choose the option to run a particular test.

Salesforce UI test examples are located in the utam-tests module.

An example of UTAM setup for web tests is in the base class.

Run SFDX scratch org test

The force-app module contains custom components and permissions for a scratch org. It's a JavaScript module and isn't included in the Maven project.

Before running UI tests, you must complete these prerequisites.

Prerequisites

See Trailhead Quick Start: Lightning Web Components for Dev Hub and CLI setup information.

Scratch org setup

To set up a scratch org and login via URL, run the following commands from the project root:

  1. If you already had utam-recipes org, delete the previously created org 

    sfdx force:org:delete -u utam-recipes

  2. Create a scratch org and provide it with an alias utam-recipes:

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

  3. Push force-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

    Tip: if this step throws an error Permission set not found in target org, run sfdx plugins:install user and repeat steps 1-4.

  5. Generate a login URL for your scratch org:

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

    This command will print out JSON to your terminal. Copy result.url from the printed JSON and copy it to the env.properties file. 

    # scratch org can log in by URL
scratchOrg.sfdx.url=https://<scratch-org-name>.cs22.my.salesforce.com/secur/frontdoor.jsp?sid=<generated-sid>

    Tip: If you want to open the scratch org in your local browser, run sfdx force:org:open.

Run Salesforce Mobile test

System.setProperty("app.bundleid", "com.salesforce.chatter");
System.setProperty("ios.device", "iPhone 8 Plus");
System.setProperty("ios.app", getUserHomePath() + "SApp.app");

For an Android test, configure the application bundleid, the full path for the test application and application initial activity:

System.setProperty("app.bundleid", "com.salesforce.chatter");
System.setProperty("android.app", getUserHomePath() + "SApp.apk");
System.setProperty("app.activity", "com.salesforce.chatter.Chatter");