Testing the user interface with the UI automation framework
After you develop an application, you can create tests to monitor the effectiveness of how your application UI works as end users access it. To create UI tests for your application, BMC Helix Platform provides an UI automation framework.
By using UI automation framework, you can create UI tests, run the tests, and view the test results. It simplifies tasks such as finding UI elements, interacting with all the UI elements for adequate test coverage, and so on. You can bundle all your UI tests with your application.
For example, you want to publish your application to Marketplace and BMC Cloud, but first you must submit the application to BMC for validation and approval. After you use the automation framework to test the application logic, use the UI automation framework to do the following tasks:
- Simulate and test end-user interaction with the application.
- Automate UI tests to find and interact with the UI elements.
- Bundle the UI tests with the application.
- Submit the test results with your application package.
UI automation framework capabilities
To assist you in automating test for the application user interface, the UI automation framework provides the following capabilities:
- Supports all UI elements based from BMC Helix Innovation Studio.
- Automatically loads Java classes for application pages (view definitions) by using the Page class loader utility.
- Enables behavior-driven development by using the JGiven framework, which distinguishes between test pre-condition, test steps, and test verification steps using given(), when() and then() keywords respectively, and makes the test script readable.
- Provides reusable utility methods, such as login functions and logout functions.
You can use the following browsers to run the UI automation framework:
- Mozilla Firefox 52.1.1 ESR
- Google Chrome version 68 to 70
UI automation framework guidelines and limitations
You can use the UI automation framework only when the following criteria are met:
- Application Under Test (AUT) of your application is developed by using BMC Helix Innovation Studio.
- Application is in the run-time phase. UI test of an application during design phase is not supported.
You must consider the following points while using the UI automation framework:
- For custom UI elements in your application, you need to provide the element classes to work with the custom elements.
- Page class loader utility only locates UI elements based from BMC Helix Platform only. It cannot identify the custom elements in your application.
Before you begin
To install the UI automation framework
BMC Helix Platform SDK consists of the UI automation framework that you can use to create automated tests for your applications. After you install BMC Helix Platform SDK and create an application using the Maven archetype, a Java project named ui-automation is included in your application. When you run the below Maven command from the ui-automation project, UI automation framework is installed automatically and added to local the Maven repository. This Maven project contains Java automated test layout that you can modify to create UI tests.
If you have created an application by using BMC Helix Platform SDK 19.8.0, perform the following step:
Execute the following command from the parent folder of you application project or /automation/ and /ui-automation/ project to run the pom.xml file.
mvn clean install
If you have created an application by using BMC Helix Platform SDK earlier than version 19.8.0, to install the UI automation project, see Upgrading BMC Helix Platform SDK to 20.02.0.
To access the UI automation Java project
The sample source code of ui-automation project is located in the /ui-automation/src/test folder. You can access the project by using an IDE such as Eclipse or IntelliJ IDEA.
- In Eclipse, select File > Import.
- Select Maven > Existing Maven Projects and click Next.
- Click Browse and import the pom.xml file of ui-automation project, and click OK.
To initially configure the UI automation Java project
Before you run the first UI automation test, configure the properties.config file in the ui-automation folder.
In the properties.config file, change the
nameparameter to the name of your developer instance.
#ServerInfoList #primaryServer name=developerxxxx.innovate.bmc.com rpc=0 tcp=0 dbadmin= dbpassword= jettyPort=0 protocol=https overlayOption= #End primaryServer
Change the developer username and password to the credentials that you use to access your Amazon instance environment.
#userInfo username=developer password=developer auth= locale=en_US #
Set the browser parameter to the browser value that you want to use to run the UI test cases.
# Browser to run UI tests. May be "FF" (firefox), "GC" (Chrome) and so on browser=FF #default timeout in seconds timeout=10 #pooling interval in seconds poolingInterval=2
Support for flexible driver executables is added, which enables users to use browser driver of any version. To use it, download and copy the drivers in the folder called drivers under the UI-automation and define the driver location in the properties.config file. Add the following property to the properties.config file:
# If you want to use drivers of your own choice, download them in the folder called drivers and define the below property. # If you do not want to use the drivers of your own choice, leave the driversLocation attribute as blank. # For example, driversLocation=drivers -> this will pick up drivers.exe from drivers folder under the ui-automation. # driversLocation= -> By default this is set to blank. It then picks up drivers bundled in the ui framework jars. These drivers are tested. driversLocation=
This feature is available only for Chrome browser.
To enable Mozilla Firefox 52.1.1 ESR to run the UI automation framework
and install it with the following options:
- Select the Custom installation option.
- Uncheck the Mozilla Maintenance Service check box.
- Navigate to C:\Users\*username*\AppData\Local\Mozilla\update\ and delete the folder present at this location.
- Set your permissions on the update folder to Write.
- In the update folder, right click, and open Properties.
- Select the Security tab, select the user (your username), and click Edit.
- Click Write and save the changes.
- Open the Mozilla Firefox browser and press Alt key.
- In the menu, navigate to Tools > Options > Advanced > Update and select Never check for updates (not recommended: security risk). (The Advanced tab is located in the left navigation.)
This disables the automatic and manual updates to Mozilla Firefox.
Restart Mozilla Firefox.
Creating, running, and bundling test cases
- To create a page class from a view definition
- To copy the page classes to the ui-automation project
- To create automation tests
- To run UI automation tests from the command line
- To run UI automation tests from Eclipse
- To review the UI automation test results
- To bundle the UI automation test cases with application
To create a page class from a view definition
Each UI page in an application corresponds to a view definition in BMC Helix Platform context. Use the Page class loader utility to automatically create a page class that includes the declaration for all of the view components (such as UI elements, record editor, and so on) in the view definition. The Page class loader utility is available in the BMC Helix Platform SDK.
Navigate to /projects/<projectName> and run the following command:
mvn clean install
This command creates all the all necessary libraries in your project.
Navigate to /projects/<projectName>/automation/target/ and run the following command:
java -cp <class path> com.bmc.rx.test.framework.util.CreateViewDefinitionSupportClass "developerxxxx.innovate.bmc.com" "https" "0" "<username>" "<password>" "<bundle name>" "<view definition name>" "<test package name>" "<inFile name>" "<export path>"
- You must run this utility on the BMC Helix Platform server where you developed your application.
- You must enter the administrator credentials to connect to the BMC Helix Platform server.
As shown in the following example, replace the parameters with the appropriate values.
java -cp com.example.taskmanager-lib-1.0-SNAPSHOT-automation-tests.jar;lib/*;%RX_SDK_HOME%/lib/* com.bmc.rx.test.framework.util.CreateViewDefinitionSupportClass "developerxxxx.innovate.bmc.com" "https" "0" "developer" "password" "com.example.taskmanager-app" "com.example.taskmanager-app:dummy View" "com.mycompany.app.pageclasses" "C:\\temp\types.csv" "C:\\temp\\test\\"
The class file is created and available in the mentioned folder. The following table describes the command parameters:
The class path must contain the following folder paths:
- Name of the JAR file in the automation project that contains the class required to create a Java class, such as com.example.taskmanager-lib-1.0-SNAPSHOT-automation-tests.jar
- Name of the /lib folder in the /target folder, such as lib/
- Name of the SDK library folder, such as %RX_SDK_HOME%/lib/
BMC Helix Platform server
Protocol to access your BMC Helix Platform server
Jetty port of your BMC Helix Platform server. Enter the Jetty port value as 0.
User name to connect to the BMC Helix Platform server.
BMC recommends that you use the tenant user account, instead of the developer account, to test the runtime behaviour of applications.
Password to connect to the BMC Helix Platform server.
Bundle name where your view definition is located.
view definition name
View definition that you want to convert to a Java class.
Note: If you pass this parameter value as a blank value, the Page class loader utility loads the page classes for all the view definitions.
test package name
Package name in which the classes created by the Page class loader utility are stored.
For example, if you provide the
test package nameas
com.mycompany.app.pageclasses, the classes created by the Page class loader utility contain the following declaration in the class code:
inFile name that is used to load the custom element
Note: The inFile name parameter is not implemented in BMC Helix Platform. You must provide the value C:\\temp\types.csv.
Path to the folder where you want to place the Java class file, such as C:\\temp\\test\\
Enter the export path with two double slashes ("\\") because one slash is used as an escape character.
To copy the page classes to the ui-automation project
After you create the page classes for a view definition by using the Page class utility, you must copy the page classes to the ui-automation project.
- By using an IDE such as Eclipse or IntelliJ IDEA, open the ui-automation project.
- Create a package structure same as the test package name that you provide when you run the Page class loader utility.
For example, if you provide the test package name value as com.mycompany.app.pageclasses, you must create the pageclasses folder in the com.mycompany.app folder.
- Copy all the view classes and the Record Editor classes created by the Page class loader utility in the test package (for example, com.mycompany.app.pageclasses).
- After you copy the classes, you may encounter some compilation errors. Fix the errors by using the following workarounds:
UI elements with same label are loaded with the same variable names in the generated class. This results to Java errors. In this case, you must rename the duplicate variable names in the Java classes.
Even if your view definition does not consist of a record editor, the Page class loader utility introduces an import statement in the view class to point to non-existent folder. You must comment such import statements.
To create automation tests
After you copy the page classes to the ui-automation project, you can start creating the test cases for your application.
The ui-automation project consists of the following folders:
|main||This folder contains the MainUIAutomationClass.java file that you can use to execute all the test scripts in the ui-automation project.|
This folder contains UIAutomationSuite.java file that you can use as a master test script where you can define all your test cases. The UIAutomationSuite.java file also contains sample test code.
This folder also contains the steps folder that consists of the following jGiven class templates:
For information about the UI automation framework methods, see UI automation framework methods and sample code.
To run UI automation tests from the command line
You can verify all the test classes or verify a specific test class.
- In a command prompt, navigate to to the ui-automation folder.
Run the test cases by issuing one of the followings commands:
To verify Command All test classes
mvn -Dit.test=* verify
A specific test case
mvn -Dit.test=<className>#<methodName> verify
mvn -Dit.test=TaskManager#VerifyTaskManagerCanCreateTaskAndAssociateWithGroup verify
To run UI automation tests from Eclipse
To create tests cases in Java, the UI automation framework utilizes the jGiven framework and the testNG framework. For more information, see and .
- Install .
- In Eclipse, test all the methods and classes.
- To test a method, select the method and debug it.
- To test a class, run the complete class.
- To test a method, select the method and debug it.
- View the test results in the Results of running class tab.
The following image illustrates a sample test result:
To review the UI automation test resultsWhen you run a test, a test report is created in the /ui-automation/target/jgiven-reports/html/ folder.
The following image illustrates a sample test report:
To bundle the UI automation test cases with application
After you create your UI test cases, you can bundle them with your application. To create the application bundle, run the the following command from your project folder:
mvn clean install
A ZIP file is generated that contains a JAR file of the test cases and your application.
End-to-end example of using the UI automation framework
The following steps describe the use of UI automation framework in a sample application, Task Manager. Task Manager is available as a Digital Service application and a smart library in BMC Helix Platform SDK.
The following video describes how to install BMC Helix Platform SDK and create a sample application. The video shows an older version of BMC Helix Platform. The previous product name was BMC Helix Innovation Suite. Although there might be minor changes in the UI, the overall functionality remains the same:
|2||and run a sample script.|
The following video describes how to get started with UI automation framework. The video shows an older version of BMC Helix Platform. The previous product name was BMC Helix Innovation Suite. Although there might be minor changes in the UI, the overall functionality remains the same:
The following video describes how to use the Page class loader utility. The video shows an older version of BMC Helix Platform. The previous product name was BMC Helix Innovation Suite. Although there might be minor changes in the UI, the overall functionality remains the same:
Copy the page classes, write test script for BMC Helix Innovation Studio based UI elements and custom UI elements.
The following video demonstrates the how to write test script BMC Helix Innovation Studio based UI elements and custom UI elements. The video shows an older version of BMC Helix Platform. The previous product name was BMC Helix Innovation Suite. Although there might be minor changes in the UI, the overall functionality remains the same:
The following video demonstrates the UI automation code overview. The video shows an older version of BMC Helix Platform. The previous product name was BMC Helix Innovation Suite. Although there might be minor changes in the UI, the overall functionality remains the same:
For more information on the tools, see in JGiven documentation and in Selenium documentation.