Testing the user interface with the UI automation framework

To install the UI automation framework

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.

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:

   Parameter	Description
   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 name	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 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:

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.

 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 verify	Command
   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

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.