Additionally using such a version control system is almost essential if you are working as a team on the same test automation project.

Using Subversion with Ranorex projects

Therefore we recommend to use a source versioning system like SVN (which integrates in Ranorex Studio), having the advantages of

• making the history of all changes made to your project visible
• providing backup functionality
• preventing security issues on network shares (source code checked out locally)

to name some of them.

The following paragraphs will explain how to

• set up Ranorex for a better Subversion experience,
• check out a repository to your local drive,
• commit a project to your repository
• and the two different versioning models available with Subversion

Before starting with the Ranorex specific part of this blog post I would recommend to have a look at the book Version Control with Subversion to get a complete overview about version control (and learn things such as how to set up a SVN server).

Setting up Ranorex for a better Subversion experience

Before performing all the subversion specific update/commit stuff, you should adjust the subversion settings as described in Noam Kfirs blog post “Better Ranorex Studio settings for Subversion”.

To do so open the Tools Options dialog and check the option “Automatically add new files” in Subversion Options area

Check "Automatically add new files"

and uncheck the option “Automatically copy/move log files to the project reports directory” in Ranorex Log Viewer area.

Uncheck "Automatically copy/move log files to the project reports directory"

In the Subversion Options area at the Tools Options dialog you can also choose the SVN version you are using (1.6 or 1.7).

Checking out a repository to your local drive

Please note that it’s necessary to have access to a SVN-Server and a repository located on this SVN-Server to perform the following steps. Therefore please have a look at the book Version Control with Subversion or contact your system administrator. If you do not want to host your own SVN-Server you can also use a free source code hosting service as listed at this wikipedia article. It’s also possible to create your own repository without the use of a SVN-Server. This can be done using e.g. TortoiseSVN; for a step-by-step description see this blog post.

After making sure that you have  access to the repository for your Ranorex test solutions, first of all you have to check out the repository to a local folder (called “working copy”) on your hard drive to put your solutions into it.

Open the Subversion Checkout dialog…

… and check out your repository to a local directory

Commit a project to your repository

After doing so, generate a new solution into the working copy directory you’ve just made a checkout to.

The generated files have automatically been added to your repository, since you have set the option “Automatically add new files” before.

Project View

To commit the changes to your repository simply right-click on your solution file and choose “Commit…” from the context menu.

Commit changes

Versioning models

The basic problem of sharing files is that changes made by one team member might be accidentally overwritten by another as sketched in following figure:

The modified version File’ of File is overwritten by the modified version File’’

To overcome this issue you can follow two different approaches:

The “Lock-Modify-Unlock”-approach:

Tester2 will not overwrite changes of Tester 1 as the file is locked

The “Copy-Modify-Merge”-approach:

Tester1 merges his changes with the changes of Tester2

The “Copy-Modify-Merge” approach is the default used by Subversion. As all checked in files are text based files there should be no problems with using the “Copy-Modify-Merge” method. Even the XML-files should be understandable easily. So, in case of a conflict you should be able to determine which differences to accept or to decline.

Merging Test Suite file

Of course you can also use the Lock-Modify-Unlock model, if you do not want to merge the files manually.

Locking Test Suite file

By following the mentioned steps and looking up unclear topics in the book Version Control with Subversion there should nothing stand in your way using version control with your Ranorex projects.

This blog post will show you how to record your automated tests using a browser and then automatically execute the recorded tests with different browsers. With Ranorex v3.2 (and higher) you can run your tests in Internet Explorer, Mozilla Firefox, Google Chrome and Apple Safari.

Run one Ranorex Test Script in different Browser (Cross-Browser Testing)

• Sample Test Suite Project
• Cross-Browser Test

Sample Test Suite Project

To demonstrate how to perform a multiple browser test, we will generate a small sample which enters data in our VIP Database Test Web Application, a small web application having the same functionality as the VIP Database you might know from our user guide.

First of all we’ll create a Test Case holding two Recordings, one for opening and one for closing the browser as setup and teardown modules.

Now we add a “OpenBrowser” action to the OpenBrowser Module with “http://www.ranorex.com/web-testing-examples/vip/” as Url and e.g. “IE” as browser.

As next step we add a recording module validating the status String on connecting and disconnecting.

The recording module simply

• validates, that the status text equals “Online”,
• disconnects,
• validates, that the status text equals “Offline”,
• connects again,
• confirms to connect in the pop up window
• and validates, that the status text equals “Online” again.

Make sure that the RanoreXPath of your App Folder does not include any browser specific equation like “browsername=…”.

Make also sure to have two repository items representing the connection status text, one for “Online” and one for “Offline”. This allows you to overcome issues with delaying validation steps. In our application it takes some time that the status text changes from “connecting…” to “Online”. To make the Validation work, we can simply add the actual validation into the RanoreXPath and only validate the existence of the status text in our web page. By doing so, we are using the search timeout of the repository item to wait for the status text to change.

Additionally to the TestConnection recording, we will generate a recording for adding VIP’s to the database. This recording will be added to a new Test Case as we want to data driven add VIP’s and do not want to open and close the browser and testing the connection with each iteration of adding a new VIP.

The recording might look something like this:

As we want to make our test data driven, we have to add variables which can be bound with the data from our data source.

The key sequences for first and last name contain the variables $FirstName and $LastName.

To select the category, we have to add a SetValue action and set the TagValue to the variable $Category.

The gender can be set by adding a variable to the RanoreXPath of the corresponding repository item.

Additionally, we validate the VIP count against a variable $VIP_Count.

After generating the recording, we create a data source for the Test Case Add_VIP’s and bind the data tables to the variables of the recording AddVIP.

As last step we add a Close Application action to the CloseBrowser Module with the application folder of the web application as repository item.

Now we can execute our Test Suite Project, which:

• opens the web application in Internet Explorer in the setup region,
• performs connection tests,
• adds 3 VIPs following the data driven approach (the data for the 3 VIPs are stored in a simple data table),
• validates the count of the VIPs stored in the web application
• and closes the browser in the tear down region.

Cross-Browser Test

To perform these steps not only for IE but also for the other 3 browser which are supported, we first make the browser which will be started in the Recording “OpenBrowser” variable.

Therefore open the recording “OpenBrowser” and edit the browser which should be started. Now choose “As new Variable…” instead of “IE” and add a new Variable called BrowserName.

After that, add a new simple data table to the Test Case “Add_VIP_and_Validate”, holding the names of the different browsers and bind the data connector to the variable “BrowserName”.

After making the browser variable that way and binding this variable to a table holding all supported browser names, you can execute your test script for all supported browser.

The VIP database application, which is included in your Ranorex installation, is taken as a sample application in this blog to illustrate how to generate a recording and the associated repository without the use of the record button.

Manually generate a Ranorex Recording

• The Repository
• The Recording

The Repository

First of all you have to add a repository to your project (Project->Add->New Item->Repository).

To analyze your application and determine which UI elements are necessary for the recording, open Ranorex Spy.

Let’s have a look at text boxes within the application. By tracking the “first name” text box you will get following RanoreXPath:

You can now simply add this control to your repository by right clicking on it and choosing “Add to repository”.

If you’d like to directly add all available text boxes to your repository, you have to add a filter to your RanoreXPath. Therefore, open the Advanced RanoreXPath Editor by clicking on the magic wand which is placed next to the RanoreXPath and uncheck the check box for “controlname” to make the RanoreXPath not only fit to this particular text box with the control name “tbFirstName”.

By verifying your altered RanoreXPath, you will see that 5 elements have been found. To see which controls have been found, click on “Highlight”. As you can see, not only all text boxes, but also all labels fit this RanoreXPath as all of these elements are represented with the text adapter. To filter out only the text boxes – as you do not need the labels within our recording – just check the check box “controltypename” and choose “TextBox”. By verifying this RanoreXPath, you will see that only 2 elements have been found – the 2 available text boxes.

After filtering the needed controls (click OK to close the Advanced RanoreXPath Editor), you can add these controls to your repository by right clicking on the parent folder of the two fitting elements in Spy and choosing “Add Matching Children to Repository”.

To learn more about the RanoreXPath and the Advanced RanoreXPath Editor please have a look at following chapters of our user guide:

• RanoreXPath
• RanoreXPath Editor

After adding the relevant text boxes, let’s add the list items stored in the category list box to the repository. Therefore, track a list item, select the parent list node, right click and choose “Add to Repository (incl. children).

Now that you have the text boxes for first and last name and the list items for the different categories stored in our repository, let’s add the radio buttons for the gender and the add button to your repository.

After doing so, the repository should look something like this:

To make your repository hierarchy cleaner, you can add corresponding folders for each type of control (Add New Item -> Simple Folder):

The Recording

After adding the necessary controls to the repository, it’s time for creating a recording file (Project->Add->New Item->Recording).

Now you have to connect the newly created recording with the repository created before. This can be done by choosing the repository from the repository list:

After connecting the repository to the recording, you can start with adding actions to your recording table.

The first step which should be done is to start the application under test. Therefore add a “Run Application” action (Add New Action -> Run Application) and choose the executable of the VIP database application.

After that, set the first and last name of the VIP. To do so, you can simply drag & drop the wanted repository item from the repository to your recording. From the context menu that pops up choose “Key Sequence” to use the keyboard to set the value of the text box.

To select a category drag & drop the specific list item from your repository to your recording and choose “Invoke Action” as action type. As action name choose “Select” to select the given list item.

Choosing the gender can be handled the same way as choosing the category.

Pressing the add button can be performed by dragging & dropping the button from the repository to the recording and choosing “Mouse” as action type.

Finally, you can close the application by dragging & dropping the application folder from the repository to the recording and choosing “Close Application” as action type.

Voilà… a recording manually generated without using the record button.

As you can see, you can manually generate a recording from a repository which might be useful

• if you are working in teams and you are sharing one repository to keep the shared repository tidy.
• if your application under test is based on special technologies (e.g. using GDI plug-in to identify elements) and the RanoreXPaths of automatically generated repository items often need to be adjusted in order to make them work reliably.

Organizing a Test Automation Project with Ranorex Test Suite

• Different Views
• Separation of Modules
• Multiple Projects, One Solution
• Execution on Runtime Machines
• Working on the same solution with different users

Different Views

In order to perform professional testing of an extensive software product, it can be beneficial to separate the views of the testing process.

On the one hand there might be a team consisting of e.g. a Test Automation Engineer and some testers. This team is responsible for covering all conceivable work flows and dividing these workflows into small, reusable modules.

On the other hand there might be a tester. The tester, for his part, is responsible for testing specific work flows processed by the software under test. As the team already has provided all necessary modules, the tester only has to put the desired modules together, to fulfill the required work flow.

Different Views

Separation of Modules

As mentioned before, it is useful to separate specific work flows in small self-contained modules in order for them to be reused in different scenarios.

These modules can either be recordings or user code modules which will be prepared by a team to allow the tester a rapid generation of different workflows.

To allow a more general approach the team can add variables to the particular modules. The tester only has to provide values by parameters or a data source and to bind the specific columns of this data source to the specific variables.

For more details about data driven testing and parameter usage please have a look at following chapter in our user guide: Data-Driven Test Automation

Separation of Modules

Multiple Projects, One Solution

DLL Type Projects

To allow collaboration of a team and the tester, the team has to provide the generated modules to the tester.

This can be established by providing Ranorex Test Suite libraries holding specific test modules.

These libraries can be referenced in the Test Suite project of the tester and all modules held by these libraries will be available for the tester to add to his specific test cases.

These libraries include all recording and user code modules generated by the team as well as the repository holding the elements the modules are accessing.

Let’s have a look at Ranorex Studio and how such a test project with several Test Suite libraries would look like.

First of all the Test Suite libraries have to be referenced to make them reusable for the tester.

This can be done by opening the .Net Assembly Browser“ tab at the Add Reference” dialog (Project->Add Reference) and simply adding the generated DLL files. After this step the DLLs should be viewable in the reference list in the project view pad.

Reference list in Project View

The referenced Test Suite libraries are also viewable in the Ranorex Module pad with all their modules and variables.

Module Browser View

The tester can now simply drag and drop the individual modules from the module browser to his Test Suite to construct the specific test cases.

Drag/Drop Modules form Module Browser to Test Suite

EXE Type Projects

To handle different test scenarios you can add several Test Suite configurations for your Test Suite.

By modifying the Test Suite configurations, different test cases or folders in your Test Suite can be selected to be executed.

Have a look at following chapter of our user guide to learn more about Test Suite configurations: Running a Test Suite

If modifying the Test Suite configurations does not fulfill the requirements, it’s also possible to add several Test Suite projects to one solution.

Each of these Test Suite projects in a solution will then generate an executable.

Exe Type Projects

Ranorex Solution with several Test Suite Projects

Additional to the automatically generated ones you can add other project relevant files to your projects, like your application under test or files holding the test data provided by your data connectors.

To ensure that these files will be available within the test project by distributing it on other machines – as described in the next chapter – you have to open the properties tab of the added file and set the “Copy to output directory” option to “Always”.

Execution on Runtime Machines

The generated test projects can be distributed to every machine, which has at least the Ranorex Runtime License installed.

To execute a test project on a runtime machine, you have to copy the executable (*.exe), the Test Suite file (*.rxtst) and the used libraries (*.dll) to a folder on the machine.

These files are by default already in the output folder of your project.

There are two different methods of executing a test project on a runtime machine:

• Executing the test project via command line as described in following chapter in our user guide: Running Test via Command Line
• Executing the test project via the Ranorex Test Suite Runner as described in following chapter in our user guide: Ranorex Test Suite Runner

Execution on Runtime Machines

Working on the same solution with different users

As illustrated in this article, using libraries it is possible to share a whole Ranorex Solution between the team and several testers. The team provides libraries in form of DLLs which are referenced by the tester in the Test Suite project.
That means everybody (testers and team) is working on the same Ranorex Solution.

Working on same Ranorex Solution with different user

To make this scenario work comfortable, it’s recommended to use a source versioning system like SVN (which integrates in Ranorex Studio), having the advantages of

• making the history of all changes made on your project visible
• providing backup functionality
• preventing security issues on network shares (source code checked out locally)

to name some of them.

You can find some hints regarding Ranorex and SVN settings at this blog post.

Using source versioning system

By following the mentioned approaches it will be easy for you to organize a professional testing environment for your extensive software project.

To automate your application this way, you have to install the Adobe Debug Flash Player and use the new Ranorex Preloader for all Flash/Flex applications.

• Set up Preloader

Setting up the Ranorex Preloader:

1. Install the Adobe Debug Flash Player on the machine on which you would like to record and execute Ranorex test scripts and for all browsers you would like to test with. The installers are available on Adobe’s download page; the following are the links to the Debug Player 10 for Internet Explorer and Firefox.
2. Download the Ranorex preloader package“RxPreloader.zip” (containing RanorexAutomation.swf and RanorexAutomation.swc”), save it to your local drive and extract it (in the following referred to as preloader location); in this example I will use “C:\FlashFlex\RanorexAutomation.swf” for the preloader location. Remember the location you placed the RanorexAutomation.swf file to, you will need it in the next steps!
3. Open your user profile directory %UserProfile%, e.g. by opening Windows Explorer and copying the string %UserProfile% into the address bar.
4. Create a new file called „mm.cfg” in your user profile directory and insert the following line of code, where “C:\FlashFlex\RanorexAutomation.swf” needs to be replaced by the preloader location from step 2:

   PreloadSwf= C:\FlashFlex\RanorexAutomation.swf

   Additional to this configuration entry you can enable the logging mechanisms of the Adobe Debug Flash Player, which might be helpful if you have any problems with this kind of instrumentation. In such a case you can then simply provide this logging information to our support team. To enable logging you have to add the following line of code to your “mm.cfg” file:

   TraceOutputFileEnable=1

   This additional configuration entry forces the Debug Player to create a log file at following location:
   C:\Users\username\AppData\Roaming\Macromedia\Flash Player\Logs

5. Open the following link and add the preloader location folder (from step 2), which contains the RanorexAutomation.swf file, to the trusted locations, for my example that is “C:\FlashFlex”:
   http://www.macromedia.com/support/documentation/en/flashplayer/help/settings_manager04a.html#119065

After performing these steps you should be able to automate any Flash/Flex based application without any modification to the application. To verify that everything went right, you can use Ranorex Spy and track some controls within a Flash/Flex application (e.g. this Flash example).

The new Ranorex Preloader can also be used as “Automation Lib” or as “Module” the same way as described in our Flash/Flex Technology instrumentation chapter within the Ranorex User Guide (use the .swf or .swc file stored in “RxPreloader.zip” instead of the files located in the Bin directory of your Ranorex installation):

• Automation Lib
• Module

Please note when using the Adobe Debug Flash Player you might get some error messages that are not shown by the normal Flash Player. These error messages are based on the fact that the Debug Player is more verbose regarding error handling than the normal Flash Player. The shown error messages are caused by the Flash application and are usually not referable to the Ranorex instrumentation.

Contents

• Walkthrough
• Summary

Walkthrough

The following is a walkthrough about how to keep Ranorex projects in TFS.

There are the following Team Foundation Server clients: the standalone Team Foundation Explorer and Visual Studio. I use Visual Studio 2010 in this blog.

In Visual Studio open the Team Explorer, right click, make a New Team Project and fill in the dialog that will pop up. I will add the Ranorex 3.0 samples to the new team project later.

After having made a new team project you will find Source Control underneath the new entry. Double-click on it to open the source control explorer. Instead of the Solution Explorer you can also use this view to work with TFS.

In Visual Studio make a blank solution by doing

• File / New / Project / Other Project Types / Visual Studio Solutions / Blank Solution

Then add Ranorex projects. I add the sample projects that come with Ranorex 3.0.

For example VIPTestSuite.csproj.

The Ranorex Project Format is still that of Visual Studio 2008. So there will be a conversion dialog. After conversion you will still be able to open it in Ranorex Studio 3.0.

You can add as many projects to the solution as you like. I have added four projects.

Right-click on the solution and choose Add Solution to Source Control … to add all projects to TFS.

The projects are added, but not yet checked in. You can right-click on the solution and choose Check In … from the context menu.
Or you can open the View / Other Windows / Pending Changes tool window.

Before you open and edit a project in Ranorex Studio you must check out the whole project. To do that right click on the project in the solution explorer and choose Check Out for Edit.

You can now make changes in Ranorex Studio. Check in using Visual Studio Solution Explorer or Source Control Explorer when you are done with them.

In Visual Studio you can look at the history of your changes.

Changesets will be listed in the history view.

Go to Changeset Details … to see individual files.

Compare with previous version to see the changes in a file.

Here is my change in the rxrec file.

Summary

This walkthrough showed how to use TFS with Ranorex Studio Projects. In a similar manner any other SCM tool can be used for Ranorex Studio projects:

• Add the project to SCM using an SCM specific client
• Before editing in Ranorex Studio, check out all files using the SCM specific client (or keep checked-out, i.e. writable, making this step unnecessary)
• Make changes to the Ranorex Studio projects
• Check in changes using the SCM specific client again

1. The Ranorex Studio Project and Solution format is that of Visual Studio. You might want to open a Ranorex Project in VS to commit it to Team Foundation Server (TFS) of which VS is a natural client. You can also use MSBuild to build the Ranorex Project.
2. The EXE or DLL that Ranorex produces is a .NET Assembly, which can be used in VS.
3. An EXE or DLL that Visual Studio produces can be referenced in Ranorex Studio.

In this blog I want to take advantage of the second point in this list. I show work flows to do unit testing in Visual Studio by referencing .NET Assemblies produced with Ranorex Studio.

Sample Project

public VIPUnitTest()
{
    Ranorex.Keyboard.AbortKey = System.Windows.Forms.Keys.Pause;
}

public interface ITestModule
{
    void Run();
}

public static void Start()
{
    TestModuleRunner.Run(Instance);
}

[TestMethod]
public void PlayRecordingModules()
{
    try
    {
        VIPTestSuite.RecorderModules.StartSystemUnderTest.Instance.SutPath
            = SutPath;
        VIPTestSuite.RecorderModules.StartSystemUnderTest.Start();
        VIPTestSuite.RecorderModules.AddVIP.Start();
        VIPTestSuite.RecorderModules.CloseApplication.Start();
    }
    catch (Ranorex.ValidationException)
    {
        Assert.Fail();
    }
}

[TestMethod]
public void PlayUserCodeModules()
{
    VIPTestSuite.RecorderModules.StartSystemUnderTest.Instance.SutPath
        = SutPath;
    Ranorex.Core.Testing.TestModuleRunner.Run(
        VIPTestSuite.RecorderModules.StartSystemUnderTest.Instance);
    Ranorex.Core.Testing.TestModuleRunner.Run(
        VIPTestSuite.RecorderModules.AddVIP.Instance);
    Ranorex.Core.Testing.TestModuleRunner.Run(
        VIPTestSuite.RecorderModules.CloseApplication.Instance);
}

[TestMethod]
public void Test_AddAndDeleteSingleVIP()
{
    int res = Ranorex.Core.Testing.TestSuiteRunner.Run(
        typeof(VIPTestSuite.VIPTestSuiteRepository),
        "/testcase:AddAndDeleteSingleVIP  /param:\"StartPath="
        +SutPath+"\"", Resources.VipTestSuite);
    Assert.AreEqual(res,0);//-1 is return on failure
}

import sys

def rxtst_to_cs(rxtst_file,cs_file):
    """collects all root testcases and
    creates a C# file with a partial class
    containing the corresponding test methods"""
    from xml.etree.ElementTree import ElementTree
    rxtst = ElementTree()
    rxtst.parse(rxtst_file);
    method_template = """

            [TestMethod]
            public void Test_{0}()
            {{
                int res = Ranorex.Core.Testing.TestSuiteRunner.Run(
                    typeof(VIPTestSuite.VIPTestSuiteRepository),
                    "/testcase:{0}  /param:\\"StartPath="
                    +SutPath+"\\"", Resources.VipTestSuite);
                Assert.AreEqual(res,0);//-1 is return on failure
            }}
    """
    methods = ""
    tests = rxtst.findall("content/testcase")
    methods += '\n'.join(
        [method_template.format(t.get("name")) for t in tests])
    tests = rxtst.findall("content/folder/testcase")
    methods += '\n'.join(
        [method_template.format(t.get("name")) for t in tests])
    tests = rxtst.findall("content/folder/folder/testcase")
    methods += '\n'.join(
        [method_template.format(t.get("name")) for t in tests])
    code_wrapping = """

    using System;
    using System.Text;
    using System.Collections.Generic;
    using System.Linq;
    using Microsoft.VisualStudio.TestTools.UnitTesting;
    using VIP_VS_Test.Properties;

    namespace VIP_VS_Test
    {{
        public partial class VIPUnitTest
        {{
            {0}
        }}
    }}
    """
    with open(cs_file,'w') as f:
        f.write(code_wrapping.format(methods))

if __name__ == "__main__":
    rxtst_to_cs(sys.argv[1],sys.argv[2])

To make automation available for Java AWT/Swing applications and applets in Ranorex, there is a new and currently experimental Java Plug-In available for download.

• Set up Java Plug-In
• Java Plug-In Example Project

Setting up the Java Plug-In

1. First of all close all Ranorex Tools, download the Ranorex 2.3.5 Java Plug-In (zip) (this requires Ranorex 2.3.5 or later) or the Ranorex 3.0 Java Plug-In (zip) and extract it.
2. Now you have to determine the path of your active Java runtime Environment to know where to copy the necessary files to. Open the Java Runtime Environment Settings which can be found in “Java Control Panel” (Control-Panel -> Java). There you can see the path of your Java Runtime Environment. If you have more than one Java Runtime Environment installed on your machine, check which one will be used to execute your Java applications by determining which one is activated. If you are using Windows XP SP2, please install Windows Update KB884020.
3. After identifying the path you have to copy each of the following files to its corresponding directory based on the root folder of your java runtime installation (e.g. “C:\Program Files (x86)\Java\jre6\”):
   • “accessibility.properties” to \lib
   • “RanorexAutomation.jar” to \lib\ext
   • “JavaHelper32/64.dll” to \bin
4. After that, copy the file “Ranorex.Plugin.Java.dll” into the Ranorex Plugin directory (“C:\Documents and Settings\All Users\Application Data\Ranorex2\Plugins” for Windows XP or “C:\ProgramData\Ranorex2\Plugins” for Vista, 7 for Ranorex 2.3. For Ranorex 3.0 choose the Ranorex3 folder instead of the Ranorex2 folder).
5. Start Ranorex Spy and check if the Java Plug-In was successfully loaded. Therefore, please open the About Dialog by clicking the Ranorex Logo and check if the Java Plug-In is loaded.



6. Start your Java application and Spy. Now you should be able to track the controls of your application under test.

Java Plug-In Example Project

After assuring that the Java plug-In is working as expected it’s now time to start with a simple test project on a Java application.

As application under test we will take a small unit converter test application which can be found here: Converter.jnlp.

Create a new Project in Ranorex Studio and start the application under test by adding following line of code in Program.cs before your recording will be started.

System.Diagnostics.Process.Start("..\\..\\Converter.jnlp");

After that copy the application to your project folder and manually start it.

Start a recording on the Application and:

• Slide the “Metric System” slider (marked in red) down.
• Validate the text held by the text field in the “U.S. System” area (marked in orange).
• Validate the slider value of the “U.S. System” slider (marked in green).
• Enter the “Metric System”, remove the given value and replace it with the value 100 (marked in yellow).
• Change the Unit held by the combo box in “Metric System” area from Centimeters to Meters (marked in blue).
• Validate that the text held by the text field in the “U.S. System” area equals to 3.937,01.
• Validate that the slider value of the “U.S. System” slider equals to 3.937.

After recording close the application under test, compile your project and start you compiled project.
Ranorex should be able to automate and validate this Java Swing Application and the generated Ranorex Test Report should look something like this:

Download the Java Plug-In Example Solution (JavaPluginExample.zip)

To make automation available for QT applications, an accessibility interface is provided by QT, which is based on different technologies for each platform QT is available on. In our case MSAA (Microsoft Active Accessibility) is used when working on a Microsoft Windows platform.

QT implements accessibility for most of its built-in widgets, but if you want to add this feature to your own widgets, you have to implement it yourself.

To illustrate the steps that have to be implemented to make a custom widget ready for automation, we want to extend an example widget which shows an analog clock. To provide accessibility for our clock widget, we need to implement an accessible interface for it and send accessible events from the widget when the time changes.

The sample project can be found at “AnalogClock.zip“ (contains a Microsoft Visual Studio project).

• QT Accessibility Architecture
• Implementing Accessibility
• Connecting Accessibility to our Custom Widget
• Let’s spy it out

QT Accessibility Architecture

The whole structure of the user interface you want to make accessible (“automatable”) is represented by a tree of accessible objects. All of these objects are derived from the class QAccesibleInterface which provides a wide range of predefined information (role, action and relation) that can be defined for these objects. (See QAccessible Class Reference)

So in our example the sub-tree architecture should look something like this:

Let’s have a look at this tree structure and the relationship between those tree items. We have the clock itself which is mapped as “clock”. And as child elements of the clock we have both the minute hand and the hour hand mapped as “slider”.

As you can see above, our clock consists of three accessible objects: the clock itself, as well as the hour and minute hands. We use an enum ClockElements to identify them. The code for this enumeration is shown later when we start to implement our accessibility interface for the clock widget.

Implementing Accessibility

To provide accessibility for our clock widget, we need to implement an accessible interface for it and send accessible events from the widget when the time changes. We will first take a look at the implementation of the interface.

Let’s start with the header file:

class AccessibleClock : public QAccessibleWidget
{
public:

	enum ClockElements {
		ClockSelf = 0,
		HourHand,
		MinuteHand
	};

	AccessibleClock(QWidget *widget, Role role = Client,
		const QString & name = QString());

	int childCount() const;
	QRect rect(int child) const;
	QString text(Text text, int child) const;
	Role role(int child) const;

private:
	AnalogClock *clock() const
	{ return qobject_cast(widget()); }

};

We extend the QAccessibleWidget class which inherits from QAccessibleInterface and helps us handling relationships and keeps track of events, roles, texts and bounding rectangles. Accessible interfaces for all subclasses of QWidget should use QAccessibleWidget as their base class.

Custom interfaces must implement states and give appropriate strings for the Text enum. This is implemented by the text and state functions. Our clock consists of three accessible objects: the clock itself, as well as the hour and minute hands. As described above we use the enum ClockElements to identify them. We also have to define the number of children held by our clock. That can be done with the function childCount. To define the bounding rects of our accessibility objects the function rect is used.

So let’s have a look at the implementation of all of those functions mentioned above, starting with the function which returns the number children our clock element has:

int AccessibleClock::childCount() const
{
	return 2;
}

We return “2″, one for the hour hand and one for the minute hand.

The next function provides the bounding rectangles of our widget:

QRect AccessibleClock::rect(int child) const
{
	QRect rect;
	QPoint topLeft = clock()->mapToGlobal(QPoint(0,0));
	switch (child) {
		  case ClockSelf:
			  rect = clock()->rect();
			  break;
		  case HourHand:
			  rect = clock()->hourHandRect();
			  break;
		  case MinuteHand:
			  rect = clock()->minuteHandRect();
			  break;
		  default:
			  return QAccessibleWidget::rect(child);
	}
	return QRect(topLeft.x() + rect.x(), topLeft.y()
		+ rect.y(), rect.width(), rect.height());
}

As you can see, the child enumeration (or index) is an argument of  the rect() function, so we have to decide which rectangle to return. The rects of the clock and their hands are provided by our analog clock implementation. We only have to calculate the screen coordinates of our rectangles before returning them.

After that we want to define role and text of our analog clock and its child objects:

QAccessible::Role AccessibleClock::role(int child) const
{
	switch (child) {
		case ClockSelf:
			return Clock;
		case HourHand:
		case MinuteHand:
			return Slider;
		default:
			;
	}
	return QAccessibleWidget::role(child);
}

We have decided to use the role clock for our analog clock and the role slider for the clocks hands. You can find the specific roles at QAccessible::Role.

Now we have to define the values for description, name and value for each of our accessibility objects:

QString AccessibleClock::text(Text text, int child) const
{
	if (!widget()->isVisible())
		return QString();

	switch (text) {
		case Description:
			switch (child)
			{
				case ClockSelf:
					return "an Analog Clock";
				case HourHand:
					return "a Hour Hand";
				case MinuteHand:
					return "a Minute Hand";
			}
		case Name:
			switch (child)
			{
				case ClockSelf:
					return "Analog Clock";
				case HourHand:
					return "Hour Hand";
				case MinuteHand:
					return "Minute Hand";
			}
		case Value:
			switch (child)
			{
				case ClockSelf:
					return clock()->currentTime.toString();
				case HourHand:
					return QString("%1").arg(clock()->currentTime.hour());
				case MinuteHand:
					return QString("%1").arg(clock()->currentTime.minute());
			}

		default:
			return QString();
	}
	return QString();
}

After implementing an accessibility interface for our analog clock, we have to somehow inform the accessibility object about changes of state (in our case, when time passes). Therefore we have to hook in the timeout function of our analog clock which is connected to a timer which fires every minute. Here we have to call updateAccesibility to inform our accessibility objects about the new values:

void AnalogClock::timeout()
{
	currentTime = QTime::currentTime();
	QAccessible::updateAccessibility(this, 0, QAccessible::ValueChanged);
	update();
}

Connecting Accessibility to our Custom Widget

At this point we have implemented our accessibility interface and we update our state whenever the minute or hour hands move. The next step is to connect the accessibility implementation with the widget itself. This can be done by either implementing an accessibility plug-in or by implementing an interface factory. A plug-in is a class stored in a shared library that can be loaded at run-time. In our example, we choose to implement the interface factory. An explanation of how to implement the plug-in can be found at Accessibility in Qt.

To implement the factory we extend our main.cpp for the factory implementation and in the main function we are installing this factory:

QAccessibleInterface *clockFactory(const QString &classname, QObject *object)
{
	QAccessibleInterface *interface = 0;

	if (classname == "AnalogClock" && object && object->isWidgetType())
		interface = new AccessibleClock(static_cast(object));
	return interface;
}

int main(int argc, char *argv[])
{
	QApplication a(argc, argv);
	QAccessible::installFactory(clockFactory);
	AnalogClock analogClock;
	analogClock.show();
	return a.exec();
}

Our factory is a function pointer for a function that takes two parameters, a QString and a QObject. We check whether the widget an accessible interface is requested for is actually an AnalogClock. If it is, we create and return our custom interface for it.

Let’s spy it out

Now we have done everything needed to make our clock accessible. Let’s give it a try. Just compile your project and use Ranorex Spy on the application. You will see that our clock now will have a name, description, role and of course a value. The same applies to the two hands.

As you can see from our example, your custom QT widgets will no longer be an unautomatable black blox if you spend some time implementing basic accessibility. For more information on QT Accessibility, visit Accessibility in Qt.

Download the Sample Project “AnalogClock.zip“ (contains a Microsoft Visual Studio project).

• Element Browser
• General Layout of RanoreXPath
• Search for multiple button elements
• Identify a checkbox by its “checked” state
• Identify checkboxes by combining attributes
• Recognize related elements by using parent-operator
• Recognize elements by using preceding- and following-sibling
• Identify e-mail address fields using regular expressions
• Use RanoreXPath in user code items

Element Browser

Let’s have a look at the Element Browser to get a summary of RanoreXPath’s functionality before we get to the test automation code. Just start with browsing through the Element Browser identifying our AUT (application under test) and making the FlexObject located on the webpage our new root node (via context menu -> Set Element as Root):

Only the FlexObject and its underlying elements are now visible and all other elements are filtered out.

General Layout of RanoreXPath

So let’s take a closer look at the RanoreXPaths in our AUT. The absolute RanoreXPath of our FlexObject should look something like this:

where dom, body and flexobject are adapters which specify the type or classification of the UI element followed by their attribute value comparison to identify the requested element. Basically a path consists of the following elements:

whereas the comparison operator can be more complex than a simple equality.

Search for multiple button elements

Assuming we want to show all of the buttons which are direct children of our earlier defined root node, just type

into the RanoreXPath edit field. What we have done is creating a relative path to all child nodes of our actual node which are buttons.

But what if we want to show all buttons contained in our flex object?

The solution is as follows:

What we now have done is creating a relative path to all descendant nodes of our actual nodes which are buttons, thus all buttons in all levels of the sub tree of the current element.

Identify a checkbox by its “checked” state

Another thing we can do is creating a path to a “checkbox “. To accomplish that we have to enable the checked attribute of a checkbox item in our AUT, so check “milk” (and uncheck the “send me coupons item”) in the Checkbox Control Example area. Now we have to validate which item of the checkbox control has its attribute “checked” set to true:

The only element now visible in our Element Browser should be the “milk” checkbox element:

Identify checkboxes by combining attributes

You can extend this example to e.g. not search for “eggs” but to find all other checked checkboxes in the container using the equality operator:

or only search for “milk” and “eggs” using the “or” instead of the “and” operator:

Recognize related elements by using parent-operator

Now let’s see if we can get the telephone number of Maurice Smith:

So the characters “..” reference the parent of the current result element. In our example that is the parent of the cell holding the text “Maurice Smith” (framed red), which is the 3rd row (framed blue). As we know that the second column of our table stores the telephone numbers, we can retrieve the desired cell by using its index “[2]” (framed green).

Recognize related elements by using preceding- and following-sibling

What if we have a telephone number and want to get the corresponding name and e-mail address? Therefore, we need to get the preceding cell:

The “preceding-sibling::cell” command delivers all preceding cells. In our case the result is the name (framed blue) corresponding to the given telephone number (framed red).

In contrast the “following-sibling::cell” command delivers all following cells. In our case that is the e-mail address (framed green) corresponding to the given telephone number (framed red).

Identify e-mail address fields using regular expressions

Additional to simple equality comparison, you can use regular expressions in attribute conditions. Assume we want to search for all cell adapters containing an email address in their text attribute. There are several ways how a regular expression which matches an email address could look like, for example “.+q.+\..+”. Now we can use this regular expression in our RanoreXPath:

The “~” operator instructs Ranorex to perform comparison using regular expressions. The “.” in our expression matches to every single character and the “+” defines that the character on its left should match one or more times. To escape special characters (like “.”), you need to precede the character with a backslash “\”. In our example every expression will match that contains the character “@” with one or more characters before and after it, followed by a “.” which in turn is followed by one or more characters. Have a look at RanoreXPath with regular expression for more examples of using regular expressions in RanoreXPath.

Use RanoreXPath in user code items

Now as we all know how powerful RanoreXPath is, let’s start applying our knowledge to a Ranorex project. First of all add our newly defined root – the flex object – to the repository of the project via drag and drop and rename it to “flex_object”. After that add a new user code item – let’s call it “moveToButtons” – to the recording and switch to code. Add following code to the just created method:

foreach(Ranorex.Button my_button in repo.flex_object.Find("./button"))
{
    my_button.MoveTo();
    Delay.Milliseconds(300);
}

Then build and run your project. As expected, the mouse cursor moves to all buttons which are direct child nodes of our root. In order to move to all visible buttons in the flex object, not only to direct child nodes, alter your code as follows:

foreach(Ranorex.Button my_button in repo.flex_object.Find(".//button[@visible=’True’]"))
{
    my_button.MoveTo();
    Delay.Milliseconds(300);
}

In our user code example we’ve only used relative paths till now, but of course it’s possible to use absolute paths, too. So let’s try to find out the e-mail address of Maurice Smith via an absolute path. The following code searches for Maurice’ email address (using the regular expression from our previous example) and writes the email address to the Ranorex Test Report:

Ranorex.Cell cell = "/dom[@page='FlexExample.html']/body/flexobject/container[@caption='DataGrid Control']/table/row/cell[@text='Maurice Smith']/../cell[@text~'.+@.+\..+']";
Report.Info("Info: ", cell.Text.ToString());

After building and executing the test, you should see the expected email address in your Ranorex Test Report.

So as you can see the RanoreXPath is very powerful at searching UI elements in your AUT without the use of programming skills. You can find every single UI element just by having knowledge about RanoreXPath modification and regular expressions. If you use the Ranorex Repository and the Ranorex Recorder you don’t even have to modify any code . For an overview of all relevant modifications of RanoreXPath visit the RanoreXPath User Guide.