This documentation supports the 20.02 version of BMC Helix Platform. 
To view an earlier version, select 19.11 from the Product version menu.

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

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.

  1. In Eclipse, select File > Import.
  2. Select Maven > Existing Maven Projects and click Next.
  3. 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.

  1. In the properties.config file, change the name parameter 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
  2. 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
    #
  3.  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  
  4. 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=

    Note

    This feature is available only for Chrome browser.

To enable Mozilla Firefox 52.1.1 ESR to run the UI automation framework

  1. Download Mozilla Firefox 52.1.1 ESR and install it with the following options:
    1. Select the Custom installation option.
    2. Uncheck the Mozilla Maintenance Service check box.
  2. Navigate to C:\Users\*username*\AppData\Local\Mozilla\update\ and delete the folder present at this location.
  3. Set your permissions on the update folder to Write.
    1. In the update folder, right click, and open Properties.
    2. Select the Security tab, select the user (your username), and click Edit.
    3. Click Write and save the changes.
  4. Open the Mozilla Firefox browser and press Alt key.
  5. 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.
  6. Restart Mozilla Firefox.

Creating, running, and bundling test cases

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.

  1. Navigate to /projects/<projectName> and run the following command:

    mvn clean install 

     This command creates all the all necessary libraries in your project.

  2.  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>"

    Notes

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

    ParameterDescription
    class path

    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

    Server host
    protocol

    Protocol to access your BMC Helix Platform server

    Jetty port

    Jetty port of your BMC Helix Platform server. Enter the Jetty port value as 0.

    username

    User name to connect to the BMC Helix Platform server.

    Important

    BMC recommends that you use the tenant user account, instead of the developer account, to test the runtime behaviour of applications. 

    password

    Password to connect to the BMC Helix Platform server.

    bundle nameBundle name where your view definition is located.
    view definition nameView 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 namePackage name in which the classes created by the Page class loader utility are stored.

    For example, if you provide the test package name as com.mycompany.app.pageclasses, the classes created by the Page class loader utility contain the following declaration in the class code:

    package com.mycompany.app.pageclasses;
    inFile name

    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.

    export path

    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.

  1. By using an IDE such as Eclipse or IntelliJ IDEA, open the ui-automation project.
  2. 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.
  3. 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).
  4. 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:

FolderDescription
mainThis folder contains the MainUIAutomationClass.java file that you can use to execute all the test scripts in the ui-automation project.
sample

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:

  • TestUIGivenState—Contains the functions that act as test pre-conditions
  • TestUIWhenStateContains the functions that act as actual test actions
  • TestUIThenStateContains the functions that act as actual test verification

 

For information about implementation of sample test scripts, see  Get started with UI automation framework and run a sample script.

For information about the UI automation framework methods, see UI automation framework methods and sample code.

Tip

 Extend the test class from the UIBaseTest class. The UIBaseTest class contains initialization and reusable functions such as login, logout, openApplication, and so on.

 To run UI automation tests from the command line

You can verify all the test classes or verify a specific test class.

  1. In a command prompt, navigate to to the ui-automation folder.
  2. Run the test cases by issuing one of the followings commands:

    To verifyCommand
    All test classes

    mvn -Dit.test=* verify

    A specific test case

    mvn -Dit.test=<className>#<methodName> verify
    For example,

    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 jGiven and  TestNG .

  1. Install TestNG Eclipse plugin .
  2. 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.

       
  3. 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 results

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

StepActionVideo
1

Install BMC Helix Platform SDK and create a sample application.

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:

https://youtu.be/gmk9TWHDC_E

2 Get started with UI automation framework 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:

https://youtu.be/wNsE9Vyk6-4

3Use the Page class loader utility.

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:

https://youtu.be/useIfB2k6UY

4Use the JGiven framework.

The following video describes how to use the JGiven 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:

https://youtu.be/4dPkFRR_Fdk

5

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:

https://youtu.be/5qiTgvfPAjg

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:

https://youtu.be/VhmeF21oV-4

For more information on the tools, see JGiven in JGiven documentation and Selenium in Selenium documentation.

Related topic

Testing application logic with the automation framework

Was this page helpful? Yes No Submitting... Thank you

Comments