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
- 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
- After the .zip file has downloaded, extract it to a different location.
- Download JUnit from junit.org (see Resources). The Version 4 basic Java archive (JAR) file will suffice for this tutorial.
- 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.
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.
- Switch to the Java perspective by clicking Window > Open Perspective > Java.
- Create a new Java project. To start, select =File > New > Java Project.
- Give the project a meaningful name (
SeleniumProjectfor 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
- In the Package Explorer on the left side, right-click the project, and create a new folder called
- 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
- 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.
- Select the Libraries tab, and then Add External JARs. Choose the junit-4.jar file.
- 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.
- 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
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.
- 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.
- In this window, set the Base URL to www.google.com and ensure that the red Record button is selected.
- Navigate to the Base URL in the original Firefox window. After the Google page has loaded, enter a search term such as
Rational Jazzand then click the Search button.
- Click the first result.
- 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
- 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.
- In the Selenium IDE, select File > Export Test Case As > Java/JUnit4/WebDriver, which is the supported type of Selenium test.
- 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
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.
- To refresh, click File > Refresh on the Eclipse menu or press F5.
- 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
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.
- To export the sample test, right-click SeleniumProject, and click Export.
- Expand the Java node, select the JAR File option, and click Next.
- 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
- 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.
- 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).
- 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.
- 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
cdcommand, 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.
- Add a semicolon (;) to the end of each line.
A completed example line should look like this:
- Then make sure to add these two JARs in the Selenium-2 directory as well as the junit jar and the Selenium tests jar:
- SelTest.jar (which was exported from Eclipse)
- Compact the list so that all of the file paths reside on just one line.
- Open the selenium.properties file that is stored in the RQMJUnitSeleniumAdapter folder.
- Paste in the list of file paths from the jars.txt file next to the com.ibm.rqm.selenium.seleniumClasspath= 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 selenium.properties 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
- Open a new command line, and navigate to the directory where the adapter was extracted by using the
- 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 https://clm.jkebanking.com:9443/qm -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.
- 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
- 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
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 selenium.properties 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
- Specify the Test Class as
Figure 11. JUnit Selenium script details example
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.
- 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
To add the test script to either a new test case or an existing one:
- 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
- Use the green plus sign Add Test Script icon to bring up a list of all test scripts in the Rational Quality Manager project.
- Find the correct test script in the list, check the box to select it, and then click OK.
- Save the test case.
- You can run it by selecting Run Test Script > Run.
- The next window asks you to specify details for the test case run.
- Make sure that the Selenium test script is the one being run.
- 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
- 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.
- Check the Rational Quality Manager and Rational Test Lab Manager pages on developerWorks for links to product documentation, articles, tutorials, courses, downloads, and other useful areas. Also, explore the Rational Quality Manager Information Center for technical details, check the Rational Quality Manager Roadmap for links to more resources, and browse the IBM Quality Management page to learn more about what else is available. For how-to tips, read these developerWorks articles by Michael Kelly:
- Lab Management using IBM Rational Test Lab Manager: Extending IBM Rational Quality Manager for collaborative, comprehensive test planning and test asset management (developerWorks, October 2008)
- Getting started with IBM Rational Quality Manager (developerWorks, December 2008)
- Managing your first project with IBM Rational Quality Manager (developerWorks, October 2008)
- Stay current with developerWorks technical events and webcasts focused on a variety of IBM products and IT industry topics.
- Improve your skills. Check the Rational training and certification catalog, which includes many types of courses on a wide range of topics. You can take some of them anywhere, any time, and many of the Getting Started ones are free.
Get products and technologies
- Download both the Selenium IDE and Selenium WebDriver from the SeleniumHQ website.
- Get Version 4 or later basic version of JUnit as a JAR file from the junit.org website.
- Download the free trial version of Rational Quality Manager, which includes Rational Test Lab Manager.
- Evaluate other IBM software in the way that suits you best: Download it for a trial, try it online, use it in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement service-oriented architecture efficiently.
- Get involved in the Rational Quality Manager forum on developerWorks, which also includes discussions and information from IBM about Rational Test Lab Manager, as well as the Using Quality Manager forum on Jazz.net
- Share your knowledge and help others who use Rational software by writing a developerWorks article. Find out what makes a good developerWorks article and how to proceed.
- Join the Rational community to share your Rational software expertise and get connected with your peers.
- Rate or review Rational software. It's quick and easy.
- Follow Rational software on Facebook, Twitter (@ibmrational), and YouTube, and add your comments and requests.