UTAM Testing

22/02/2023

UI Testing Automation Model, better known as UTAM, makes developers’ lives easier by providing a quality way to run E2E (End to End) tests on any kind of app. In this article, we are going to cover nearly every aspect of UTAM, including an example to make sure every tiny aspect of this amazing feature is well understood.

What is UTAM?

UTAM is a testing framework that enables us to automate the testing of User Interfaces (UI) of web applications. It is based on the popular Page Object Model design pattern, which is commonly used among UI tests. UTAM simplifies the process of creating test cases by allowing developers to author page objects in a JSON format using easy-to-understand UTAM grammar. The UTAM compiler then outputs well-formed Java or JavaScript page objects that are ready for integration into UI tests.

Purpose of UTAM

The main focus of UTAM is to automate the process of testing the user interface of Salesforce applications. Among other things, it provides a framework and methodology for designing, executing, and reporting on test cases. It is particularly useful for testing web applications built on our CRM platform as it can be integrated with other test automation tools and can help to improve the overall quality and reliability of the application. Moreover, it enables us developers to quickly identify and fix any issues that are found during testing, which can help to speed up the development process and reduce the risk of errors.

Main Advantages of using UTAM

There are many advantages of using UTAM, but here are some of them summarized:

UTAM enables end-to-end (E2E) testing, allowing the testing of an application even without complete access to its source code. For example, using UTAM, one can test a Salesforce application that integrates with an AppExchange package, without access to the source code of the Lightning Experience or the package, making it possible to test the application.
The creation of test cases is made easier by UTAM, which enables developers to write page objects in JSON format using the simple-to-understand UTAM grammar. The well-formed Java or Javascript page objects produced by the UTAM compiler can subsequently be integrated into UI testing.
Enhances test consistency and reliability: UTAM offers a consistent and reliable technique to test the user interface (UI) of web applications, which can aid in raising the application’s overall quality and dependability.
Test-driven development: UTAM supports Test-Driven Development (TDD), which aims to ensure that the code is tested before it is made available for use in production. This can assist to lower the chance of errors and raise the general caliber of the program.
Increases coverage: UTAM enables developers to generate a thorough set of test cases, increasing the application’s coverage and strengthening it.
Easy maintenance: UTAM Page objects are created in JSON format, making it simple for team members who aren’t technically savvy to maintain and update them.

The UTAM framework

As we have seen so far, the UTAM framework is a set of components that work together to provide a consistent and reliable way to test the UI of web applications. Some of the key components of this framework are:

UTAM grammar: a collection of guidelines for defining how page objects should be authored in JSON format. The development of test cases is made straightforward for developers, making it easy to understand.
UTAM compiler: its compiler converts JSON-formatted objects into well-formed Java or JavaScript page objects that may be used in UI tests.
Test Runner: executing test cases is the responsibility of the test runner. In order to increase the effectiveness of testing, it can be combined with other test automation technologies.
Test Reporters: test reporters are in charge of writing and creating test reports. These reports offer comprehensive details regarding the test outcomes, such as the number of test instances that succeeded, failed, or skipped.
Test Case Library: UTAM also comes with a collection of reusable, pre-built test cases that can speed up development.
UTAM Methodology: it provides a methodology that describes the best methods for creating, carrying out, and reporting on test cases. This methodology might aid in ensuring the consistency and dependability of the testing procedure.

Preparing UTAM for JavaScript: Installation and Setup

The first step in preparing UTAM for JavaScript is to install it. This can be done by running the following command in your terminal:

npm install utam

This command will install the UTAM package and its dependencies. Next, you will need to author your page objects in JSON format using UTAM grammar. This can be achieved by using a text editor or an IDE that provides JSON support. Once you have authored your page objects, you will need to compile them into JavaScript code, by running the following command in your terminal:

utam-compiler -f <path-to-page-objects> -l js

This command in specific will take your authored page objects and compile them into JavaScript code that can be used in your test classes.

Once your page objects have been compiled, you will need to integrate them with your test runner. This can be done by importing the page objects into your test files and using them in your test cases. You can make use of various test runners frameworks, such as Jest or Mocha.

After your page objects have been integrated with your test runner, you can execute your test cases by running the test runner. For instance, if you’re using Mocha test runner, you can run your test by executing the following command:

<span style="color: var(--hcb-color--text,#1f1e1e); font-family: var(--hcb-font-family,'Menlo','Consolas','Hiragino Kaku Gothic ProN','Hiragino Sans','Meiryo',sans-serif); font-size: var(--hcb-font-size,14px);">mocha <path-to-test-files></span>

Finally, you will need to create test reports. UTAM includes a test reporter that can be used to create detailed test reports. These reports provide information about the results of the tests, including the number of test cases that passed, failed, or skipped. In order to create a report, follow this command (here, we use mochawesome to create the report):

mochawesome-report -i <path-to-test-results> -o <path-to-report-output>

UTAM with JavaScript example

For this UTAM example, we decided to use a LWC that has a message property that is displayed in the template, along with two additional properties: inputValue and a button. If the user wants to enter a value, they can use inputValue, and by clicking the button they can save the new message they just entered. Jumping onto the test, it uses UTAM to create a Page Object for the component, setting the inputValue and clicking on the button to finally check that the correct message is being displayed properly in the template.

<template>
  <div class="message">{message}</div>
    <div class="input-container">
      <lightning-input type="text" label="Enter message" value={inputValue} onchange={handleChange}></lightning-input>
      <lightning-button label="Save" onclick={handleSave} class="slds-m-left_x-small"></lightning-button>
    </div>
  </div>
</template>

import { LightningElement, track } from 'lwc'

export default class MyLWC extends LightningElement {
  @track message = '';
  @track inputValue = '';

  handleChange(event) {
    this.inputValue = event.target.value;
  }

  handleSave() {
    this.message = this.inputValue;
    this.inputValue = '';
  }
};

import { createElement } from 'lwc';
import MyLWC from 'c/myLWC';
import { utam, createPageObject } from 'utam';

describe('MyLWC', () => {
  let element;
  let page;

 beforeEach(() => {
   element = createElement('c-my-lwc', { is: MyLWC });
   page = createPageObject(element);
   document.body.appendChild(element);
 });

afterEach(() => {
  document.body.removeChild(element);
});

it('displays the correct message', async () => {

  // set the inputValue
  page.setValue('.input', 'Hello World!');

  // click on the save button
  page.click('.save-button');

  // wait for the component to render
  await utam.flush();

 // check that the correct message is displayed
 const message = page.getTextContent('.message');
 expect(message).toBe('Hello World!');
});
});

UTAM Best Practices and Considerations

In this section, we are going to briefly cover some of the best practices and considerations you should keep in mind while developing and implementing UTAM Testing.

Keep Your Page Objects Simple and Focused: The Page Object Model design pattern, which UTAM is built on, encourages you to keep your page objects simple and targeted. As a result, it is simple to add new test cases and to maintain and understand them.
Distinct your test code from your page objects: UTAM recommends keeping the test code separate from the page objects. The test code can now be updated without affecting the page objects, and vice versa.
Use a consistent naming convention: A consistent naming scheme will make it simpler to comprehend the structure of your code for your page objects, test cases, and other relevant files.
Use a modular approach: Divide your tests into manageable, reusable modules that can be applied to a variety of test cases.
Utilize data-driven testing: Using various input data to evaluate an application is known as data-driven testing. With the help of UTAM, you can quickly parameterize your test cases and test an application with a variety of input data.
Use a version control system and CI/CD: UTAM recommends managing your code with a version control system like Git. This makes it simple to track changes to your code and interact with other developers.
Update dependencies frequently, and always use the most recent UTAM version in your codebase.

Summary

In conclusion, UTAM (Universal Test Automation Model) is a powerful testing framework that allows us, developers, to create more robust, maintainable, and scalable test automation solutions. By making use of the popular Page Object Model design pattern, UTAM makes it easy to author page objects in JSON format and allows for smooth integration with UI tests. The framework’s ability to run end-to-end tests, even if the developer does not have full access to the source code, makes it an invaluable tool for ensuring the reliability and quality of an application. Moreover, the framework’s support for both Java and JavaScript page objects allows for greater flexibility and adaptability in a variety of testing scenarios.