Run automated Selenium JUnit tests

Create, export, and configure Selenium tests to run them from Rational Quality Manager


Version 4.0 of IBM® Rational® Quality Manager introduced the ability to create an automated JUnit Selenium test script. Much like running a Rational Functional Tester automated test remotely from Rational Quality Manager, you can now run Selenium tests. Test results are returned to Rational Quality Manager.

Selenium is an open source software testing framework designed for web applications. There are different components available:

  • The Selenium IDE, which you can use for recording and creating automated tests without knowledge of a specific scripting language.
  • The Selenium WebDriver API, which you can use to create tests by using a scripting language of your choice. Supported languages are Java, Ruby, Python, and C#. Because JUnit is a unit-testing framework for the Java programming language, and the tests are run from Rational Quality Manager using JUnit, Java is the language that any Selenium WebDriver tests must be written in to be supported.

Selenium also offers a wider range of browser support and can be deployed on Microsoft Windows, Linux, and Apple Macintosh platforms.

In this tutorial, the server running Rational Quality Manager also runs the Selenium tests. In a real test environment, you would run the Selenium tests from a different test workstation to the Rational Quality Manager server.

Configure Selenium tests

If you already have the Selenium IDE, Selenium WebDriver, and JUnit installed and working with an example of a JUnit WebDriver test, you can skip to the section called Generate a library of Selenium tests for execution.

If you are interested in Selenium but have never used it before, the next six sections will show you how to install it and create a simple test that can be run from Rational Quality Manager later in the tutorial. This is not a tutorial on how to create complex Selenium tests. It explains only how to create a test that will suffice in demonstrating the connection with Rational Quality Manager. Given that Selenium is an open source tool, there are plenty of resources available for learning how to use it to its full potential.

Download and install Selenium

  1. Download both the Selenium IDE and Selenium WebDriver from the SeleniumHQ website (see Resources). The Selenium IDE is a Mozilla Firefox add-on that will run from within the browser.

Make sure that you download the Selenium client driver for Java, not for any of the other available languages.

Figure 1. Select the Java driver
Selenium client driver download display
Selenium client driver download display
  1. After the .zip file has downloaded, extract it to a different location.
  2. Download JUnit from (see Resources). The Version 4 basic Java archive (JAR) file will suffice for this tutorial.
  3. Save this file in the same location where you extracted the Selenium-2 file.

The steps to install Selenium, JUnit, and the adapter must be repeated on any test computer that will be executing the tests.

Configure Eclipse

The steps in Eclipse need to be performed by anyone who is responsible for authoring or modifying any Selenium tests.

To view the test source code, make any changes, or run the test for debugging purposes, the test will need to be added to a Java IDE. In this tutorial, you will be using Eclipse. If you have IBM® Rational Team Concert™ installed as part of the Rational solution for Collaborative Lifecycle Management (CLM) solution, these steps can be carried out in the that IDE, because it is based on Eclipse. Using this rather than a standard Eclipse installation will give you the added benefit of storing the tests under source control. You can also use it to assign tasks to developers or testers for creating or enhancing tests. Other Java IDEs will work, but the configuration steps will be slightly different for them.

  1. Switch to the Java perspective by clicking Window > Open Perspective > Java.
  2. Create a new Java project. To start, select =File > New > Java Project.
  3. Give the project a meaningful name (SeleniumProject for this example), manually specify a location where the project files will be stored, and then click Finish.
Figure 2. Specify the name and location for this sample project
Properties specified in Eclipse
Properties specified in Eclipse
  1. In the Package Explorer on the left side, right-click the project, and create a new folder called libs.
  2. Copy the junit-4.jar file and Selenium-2 folder to the libs folder that you just created.
Figure 3. This is what your Package Explorer view should look like
tree view
  1. Next, the JARs that need to be added to the project class path, so they can be used within the tests. Right-click the project (in this case, SeleniumProject), and select Build Path > Configure Project Build Path.
  2. Select the Libraries tab, and then Add External JARs. Choose the junit-4.jar file.
  3. In the Selenium-2 folder, add the two Selenium JAR files, as well as all of the JAR files located in the libs folder. Click OK to confirm the addition.
  4. Now create a package hierarchy to contain the tests. (The benefit of doing this will be covered in more detail in the section titled Create the Selenium test in Rational Quality Manager.) Right click-the SeleniumProject in the Package Explorer, and create a new package called com.example.tests.

Create a sample Selenium test

You will now create a simple automated test to import into the project that you have just created. You will record the test, using the Selenium IDE, during which the test will perform a search on Google.

  1. To open the Selenium IDE window, inside Firefox, click the Firefox icon, and then Web Developer > Selenium IDE. Alternatively, you can open it using the keyboard shortcut Ctrl+Alt+S. A separate Selenium IDE window will open.
  2. In this window, set the Base URL to and ensure that the red Record button is selected.
  3. Navigate to the Base URL in the original Firefox window. After the Google page has loaded, enter a search term such as Rational Jazz and then click the Search button.
  4. Click the first result.
  5. Return to the Selenium IDE window, and stop the recording by clicking the red Record button again.

Your Selenium IDE window should now contain commands that look similar to those in Figure 4.

Figure 4. What your test recording should resemble
Selenium IDE after a sample test has been recorded
Selenium IDE after a sample test has been recorded
  1. You can verify that the recording has worked by clicking the Play button just below the Base URL field. To see the test playback in detail, you can slow the playback by using the slider on the left.

Export the Selenium test in the correct format

The Selenium IDE is designed for rapid creation of regression test suites. They can be created and played back within the tool as just demonstrated. To play the test back from Rational Quality Manager, the script needs to have been written in Java. Handily, the Selenium IDE has an Export function to export the recorded test to the correct Java format.

  1. In the Selenium IDE, select File > Export Test Case As > Java/JUnit4/WebDriver, which is the supported type of Selenium test.
  2. Give the test a meaningful name, such as ExampleSelTest, and save it as a java file in the SeleniumProject/src/com/example/test folder within the SeleniumProject that you created earlier.
Figure 5. How to export a Selenium test
menu path, as described, to export the test
menu path, as described, to export the test

View the created test in Eclipse

In Eclipse, by refreshing the Package Explorer, the Selenium Java test file that was just added into the project will be visible.

  1. To refresh, click File > Refresh on the Eclipse menu or press F5.
  2. Examine the com/example/tests package to see that the new test is now visible, and double-click it to open it.
Figure 6. What the new project should look like
How the Package Explorer will look after importing

To check that the test can be run correctly, you can run it from within Eclipse by selecting the ExampleSelTest Java file and clicking the Run As on the toolbar and then selecting JUnit Tests from the drop-down menu. You can also do that by right-clicking the actual test and then clicking Run As > JUnit Tests.

You should then see the test playback, and the same steps that were recorded in Firefox will be repeated.

Generate a library of Selenium tests to run

The Selenium test can now be run in Eclipse as a stand-alone JUnit test. To run it from Rational Quality Manager, it needs to be exported as a JAR file. Exporting will create a transportable and executable version of any Selenium test. You can create a library of tests in a JAR file and move that file to multiple test computers so they can be run there.

  1. To export the sample test, right-click SeleniumProject, and click Export.
  2. Expand the Java node, select the JAR File option, and click Next.
  3. The default options will be fine on the next form, but you will need to specify an export destination (see Figure 7).
Figure 7. Sample export form
Typical properties for exporting Selenium tests
Typical properties for exporting Selenium tests
  1. Click Finish to export the tests.

Configure and run the adapter

Now that you have created a library of multiple Selenium tests and it is ready to use, you must set up the Rational Quality Manager side. The first task is to configure the adapter that you will use to run the tests.

Configure the adapter

The adapter is included in any Rational Quality Manager installation, and it can be copied to any computer to allow Selenium tests to be run on different test computers. This is the location of the adapter:


JAZZ_INSTALL_DIRECTORY is the directory on the Rational Quality Manager server where Rational Quality Manager is installed.

  1. Either copy this file onto a chosen test computer or leave it on the same server if you are executing tests locally. (This example will use the same server).
  2. Unzip the file.

In the extracted adapter folder, a readme.txt file contains detailed information on how the adapter can be configured. This article is a guide for a simple startup. This example is for starting the adapter on Microsoft Windows, but the steps can be modified for a Linux system. The modifications are shown in the readme file.

When you start the adapter for the first time, it needs to be started from the command line with arguments. For a test to be run, a list of the absolute paths to all of the different JAR files that could be needed when running is required. There are a lot of JAR files in the Selenium-2/libs folder, so it saves time to use a command to add these entire file paths to a text file rather than do it manually.

  1. On the test computer where you are executing the Selenium tests, open a command window (Start > Run > cmd), navigate to the Selenium-2.x.x/libs folder using the cd command, and then enter: dir /S /B > jars.txt

This will create a text file called jars.txt in the libs directory that contains the file names and paths of the JAR files on separate lines.

  1. Add a semicolon (;) to the end of each line.

A completed example line should look like this:


  1. Then make sure to add these two JARs in the Selenium-2 directory as well as the junit jar and the Selenium tests jar:
    • Selenium-java-2.x.x.jar
    • Selenium-java-2.x.x-srcs.jar
    • junit-4.x.jar
    • SelTest.jar (which was exported from Eclipse)
  2. Compact the list so that all of the file paths reside on just one line.
  3. Open the file that is stored in the RQMJUnitSeleniumAdapter folder.
  4. Paste in the list of file paths from the jars.txt file next to the property, and remove # from the line if there.

This tells the adapter where to find the code that will be used when executing the test.

The file needs to be modified for every test computer that is running an adapter.

If you are using an adapter on a remote Windows workstation to run tests; the (\) will need to be changed to (/) in the file paths. This can be completed using Find & Replace in your text editor. Forward slashes are used to reach network locations, whereas back slashes work for local machines.

Run the adapter

  1. Open a new command line, and navigate to the directory where the adapter was extracted by using the cd command again.
  2. Enter this command (replace anything in italics with your own information):-
start.bat -repository https://rqmserver:port/qm -userid userid –password password –
adapter adapter -projectArea projectArea -adapterName adaptername


rqmserver is the fully qualified host name of the Rational Quality Manager server.

port is the port where the Rational Quality Manager server is running.

userid is a registered user ID within Rational Quality Manager that has the license to run an adapter.

password is the password of the user ID used to log in.

adapter is a user-given adapter identifier. This value must be unique, because it is used by the Rational Quality Manager server to identify this adapter.

project area is the name or alias of the project that you are logging in to. If there are spaces in the project name, put the words within quotation marks.

adapter name is a user-given adapter name.

This example command uses the example JKEBanking project area:

start.bat -repository -user adapter -password 
adapter -adapter RQMSelAdapter -projectArea "JKE Banking (Quality Management)"

This adapter is using a user account created specifically for connecting adapters. This user, adapter, has the same password as the username, and it was assigned the Connector Client Access License within Rational Quality Manager. This is to avoid wasting a Quality Professional license for a constantly connected adapter workstation when all it will be doing is executing remote tests.

If the adapter fails to start, make sure that Java has been added to the path variable. For additional information on configuring the adapter or to troubleshoot, see the readme file.

Create the Selenium test in Rational Quality Manager

The final steps are to create the test assets within Rational Quality Manager that will point to a specific Selenium test in the JAR file, and run it through the adapter that you just configured and started. The test assets must be created by a user with a Quality Professional License.

Create a test script

To run a Selenium test from Rational Quality Manager, you need to create a corresponding test script in Rational Quality Manager.

  1. To create a test script, select the Construction tab and, from the drop-down menu, and select Create > Test Script.
Figure 8. Create a test script
Menu options, Test Script selected
Menu options, Test Script selected
  1. Give the test script a name, and use the drop-down menu to change the type to JUnit Selenium.
Figure 9. Create a JUnit Selenium type test script
JUnit Selenium selected as type
JUnit Selenium selected as type

Three fields are available to add options for the running of the test:

  • The first, Test Class, specifies which Selenium test will be run by this script. It is needed for the script to run.
  • The second, Classpath, specifies any JAR files that will be used by the Selenium test that are not specified in the file.
  • The last one, Java System Properties, is where any Java system arguments can be passed to the Java Virtual Machine (JVM).

The Selenium test example was created with a meaningful name and organized into a package. This means that a specific Selenium test can be selected to be run by a test script from a JAR file that contains a library of other Selenium Tests. In this example, only one Selenium test exists in the JAR file, so it seems trivial, but having multiple tests organized into different packages makes it quick and easy to create test scripts in Rational Quality Manager, which will run them.

Figure 10. Using one Selenium test library for multiple scripts
Test script, test case, Selenium test hierarchy
Test script, test case, Selenium test hierarchy
  1. Specify the Test Class as com.example.tests.ExampleSelTest.
Figure 11. JUnit Selenium script details example
Specifying the specific Selenium test to run
Specifying the specific Selenium test to run

As shown in the diagram in Figure 10, by changing the test class property in different scripts, a different test will be run from the same JAR file.

  1. Save the test script to finish.

Run the automated test

To run a test script. it needs to be within a test case and be started from there. Either create a new test case from the menu (Construction > Create > Test Case) or add the test script to an existing test case in a Rational Quality Manager project.

Figure 12. Create a new test case
Construction menu, test case selected under Create
Construction menu, test case selected under Create

To add the test script to either a new test case or an existing one:

  1. Open the test case, and navigate to the Test Scripts section on the left side of a test case summary.
Figure 13. Test Scripts section location
Test Scripts selected under Overview
  1. Use the green plus sign Add Test Script icon to bring up a list of all test scripts in the Rational Quality Manager project.
  2. Find the correct test script in the list, check the box to select it, and then click OK.
  3. Save the test case.
  4. You can run it by selecting Run Test Script > Run.
  5. The next window asks you to specify details for the test case run.
    1. Make sure that the Selenium test script is the one being run.
    2. Also, ensure that the adapter that was started earlier is running, as indicated by a green circle (see Figure 14).
Figure 14. Run test case parameters
Setting the parameters to run the test case
Setting the parameters to run the test case
  1. Click OK to run the test.

View the results

After the test has finished, a Show Results button should appear. Click that, and Rational Quality Manager will display the detailed log of the test run. A Pass or Fail verdict will be shown for the test, as well as other information, such as the test run time. This sample test example contained only one step, but a more complicated Selenium test would show a step-by-step guide of which verifications have passed and failed.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

Zone=Rational, DevOps
ArticleTitle=Run automated Selenium JUnit tests