IBM BluemixDevelop in the cloud at the click of a button!

Manually merge new Rational Functional Tester scripts into an existing automation suite

A case study using the Rational Software Architect automation suite as the application under test

This article explains the steps for manually merging Rational Functional Tester scripts and ways to adapt them. We use a case study of the Rational® Software Architect automation suite as an example.


Siddharth Kaushal (, System Test Engineer, IBM

author photoSiddharth Kaushal is a senior staff software engineer with more than eight years of experience in testing and software test automation tools, such as Rational Functional Tester, Selenium, Visual Studio Team Test, and Rational Robot. He has the following certifications: Sun Certified Java Programmer, QAI Global Institute Certified Software Tester, and International Software Testing Qualifications Board.

Amit Srivastava (, Staff Software Engineer, IBM

author photoAmit Srivastava is an IBM staff software engineer. He has been working with software test automation tools for seven years, including test automation projects using IBM Rational Robot and IBM Rational Functional Tester.

07 May 2013

Also available in Chinese

Before the beginning

Rational Functional Tester is a GUI-based automation and regression testing tool that is used for automation of test scenarios for many products across various organizations. Testing teams use it to create a set of automation scripts. Such a set is also known as an automation suite. Then they run those automation suites using varied automation frameworks. Some use standard frameworks built across Rational Functional Tester, and some create their own based on the need.

Teams working on different frameworks and using Rational Functional Tester sometimes face issues, which are either specific to their frameworks or common for most of the frameworks. However, there are certain issues that are so common that their solutions could help people in other organizations. One example is manually merging the automation scripts created by different members in different time zones and geographies, created in their own workspaces and following their own object maps.

Merging scripts seem like a simple process, but without a configuration management tool, it becomes a difficult job. You must make every script work as expected without changing the existing folder structure of the automation suite. But what if you need to change the folder structure?

This article will help you understand and overcome the issues that occur while manually merging or restructuring automation folders. We explain the use of these tips with real examples captured while automating Rational Software Architect productions. It is the application under test in these scenarios that use Rational Functional Tester for testing. When the Rational software System Verification Test (SVT) team ran into this problem, they had to explore various forums to find a working solution that works. The results of the research that solved the problem are the basis for this article.

So, with the real examples shared, this article will help reader to connect to their scenario with ease and thus it will help them to use the tips/tricks for manual merging of Rational Functional Tester scripts or restructuring automation folder structure.

This article also shows how to avoid the overhead of carrying the test object map files with the script during the merge by using Rational Functional Tester application programming interfaces (APIs).

What inspired this article

Rational Functional Tester has been successfully used to automate the GUI-based scenarios of Rational Software Architect. The automation suite was created with the help of the entire testing team. Because Rational Software Architect has extensive feature to test, the tester scripts created to automate the UI scenarios resulted in a test suite with more than 250 scripts. Nearly everyone from the test team owned some of the features and completed their parts. This increased the coverage but also increased the inconsistency in script formats. Some scripts followed the rule of using a definite folder structure, but for some, it changed a bit.

After the Rational Functional Tester scripts were created, the task was simple: merge the new scripts into the existing automation suite. This simple-looking task turned out to be the biggest challenge, and that inspired us to write this case study. The existing automation suite was created and maintained in a predefined folder structure. When we tried to merge new scripts with the old suite, a whole set of problems showed up, and it forced us to try multiple workarounds to make it work.

Stringent timelines and lack of tool expertise resulted in mostly object map-based scripts, which were prone to failure for any change in the object hierarchy. So we had to revisit all of the scripts and introduce the Rational Functional Tester find() API to find almost all of the objects. This became our second inspiration for writing this article.

In the sections that follow, we describe how to overcome any obstacles while manually merging Rational Functional Tester scripts into an existing automation framework, using our case study on Rational Software Architect automation suite.

Problems and solutions

In this section, we describe each problem and then the solution or ways to avoid that problem.

Problem 1. Unable to import the newly created scripts into a defined folder in automation suite

Rational Software Architect example

The Rational SVT team had a folder structure for keeping all of the scripts under testcases in this hierarchy:

For newly added features, we created new folders at the same level in Rational Functional Tester, and we tried to import newly created scripts at this level. However, Rational Functional Tester allowed import of the scripts only at root level, not into a specific folder (as shown in Figure 1).

Figure 1. Trying to import Rational Functional Tester scripts into a specific folder
import wizard screens


  1. Create a folder manually under workspace/resources/.../destination folder and workspace/.../destination folder. Note: Substitute your own information for words in italics.
  2. Now manually copy following files to the destination folder under this path: workspace/resources/.../destination folder.
    • *.rftdef
    • *.rftxmap
    • *Helper.class
    • *.java
  3. Similarly, copy the *.class and *.java files to the destination folder:workspace/.../destination folder
  4. Restart Rational Functional Tester and notice that the folders (along with the scripts) now where you want them (see Figure 2).
Figure 2. Manually copy and paste scripts into the correct folder
Script now shows in Rational Functional Tester

Problem 2. Compilation errors at script level resulting from changed package information and unorganized imports

Rational Software Architect example

The solution to Problem 1 resulted in this problem. After opening the scripts, we noticed compilation errors at the package level, as shown in Figure 3.

Figure 3. Script points to the wrong package
Compilation errors in the script


  1. Replace old package information with new package information by using the quick fix of choosing the organize imports option in the Rational Functional Tester editor.
  2. To remove compilation errors, right-click the project, and select reset Java build path (as shown in Figure 4).
Figure 4. Package information corrected in script
Compilation errors fixed in the script

Problem 3. Compilation error at script helper level because package information changed

Rational Software Architect example

After solving Problem 2, everything looked fine until we tried to play back the script. The playback failed due to old package information in the script Helper class (as shown in Figure 5). Ideally, we should have updated the script helper along with the script itself, but there was no compilation error displayed for the script helper, so we wrongly assumed that the script helper had been updated automatically.

Figure 5. Script Helper class points to the wrong package
Compilation error in the script helper

Open the script Helper class, and replace old package information with new package information to remove the compilation error (as shown in Figure 6).

Figure 6. Package information corrected in script helper
Compilation error fixed in the script helper

Problem 4. Runtime error due to the script name path at the script helper level

Rational Software Architect example

After solving Problem 3, we played back the script again, only to find a runtime error (as shown in Figure 7). Rational Functional Tester was not able to find the script definition file, which the software was still searching for at root level.

Figure 7. Script definition file was not found during playback
Runtime error shown in the console


  1. Open the script Helper class and search for the setScriptName() function call.
  2. Now update the script name parameter with the full path of the script (as shown in Figure 8).

This will help Rational Functional Tester find the script definition file during playback.

Figure 8. Script definition file path updated
Argument to setScriptName() function modified

Problem 5. Runtime error due to path of script file, data pool file, and object map file

Rational Software Architect example
After solving Problem 4, we played back the script again, but we found another runtime error (shown in Figure 9). Rational Functional Tester was not able to find the script file, data pool file, and object map file, but it was still searching at root level

Figure 9. Object Map file not found during playback
Runtime error in console due to missing files


  1. Open the script definition file (*.rftdef), and update the path of the script file, data pool file, and object map file (see Figure 10). This will help Rational Functional Tester find the required files during playback.
  2. Update tags as shown in code Listings 1, 2, and 3 to apply this solution.
Listing 1. Update the ScriptName tag (example)
Listing 2. Update the Map tag (example)
Listing 3. Update the Datapool tag (example)

The path of the verification point file (*.rftvp) should remain the same as it was in the newly created script.

Figure 10. Script definition file updated with the required path
Content of a sample script definition file

Problem 6. Object recognition failed due to a change in the object recognition or hierarchy

Rational Software Architect example
Based on their respective knowledge of Rational Functional Tester, different team members contributed to the automation suite. As a result, some scripts were more object map-dependent and prone to failure when there was any change in the object properties or hierarchy. These scripts started failing with a change in the IBM® Eclipse Software Development Kit level in a new Rational Software Architect release (see Figure 11).

Figure 11. SWTTree object not found during playback
Exception window during playback


  1. Use the find() API to find and act upon any vulnerable object, rather than using it according to the object map.
  2. Create a layer of abstraction on top of the recorded script to handle interactions with vulnerable objects.

We had three options to complete this task:

  • Write the abstraction layer from scratch to find out every vulnerable object, and then perform the action against it.
  • Reuse the existing classes and functions of IBM Business Logic Utilities Environment (BLUE) Test Automation (Blue Package or ITCL Framework) or classes and functions created by the Rational Software Architect automation testing team. Both were written using Rational Functional Tester exposed APIs.
  • Convert the existing objects to dynamic test objects, and select the application's root test object as the parent for anchoring.

Lack of resources, expertise levels, and the ease of use of the second and third options made us use those for our purpose. Reuse of existing code (as shown below in Figure 12) and dynamic test object conversion (as shown in Figure 13) helped us reach our target faster.

However, we are also providing the piece of code that we wrote to find one of the vulnerable objects, using one of the variations of find() API. The syntax is mentioned in Listing 4, and the sample code is shown in Listing 5. You can find other variants of the find() API in the Rational Functional Tester information center (cited in Resources). This gives you the option to choose the best possible solution for your situation.

Figure 12. Find misplaced object using existing classes
Screens show code to reuse to find an object
Listing 4. Syntax of one of find API variants
public TestObject[] find(Subitem properties)

The code in Listing 4 finds all candidates that match the given search criteria. These are valid values for the property subitems:

A name and value pair that represents a TestObject property.
Contains one or more properties that must be matched against the direct child of the starting TestObject.
Contains one or more properties that can be matched against any child of the starting TestObject.
Used to specify a sequential list of properties to match against. These subitems are valid for atList:
  • atChild
  • atDescendant
  • atProperty

The first list item is used as a match to get a list of candidates. Descendants of these candidates are then matched to get the next list item.

In Listing 5, recognition properties (of the object to be found) and their values are passed as parameters to find a specific child object of the root test object

Listing 5. Sample code to find/use the missing SWTTree object
RootTestObject root = getRootTestObject();
//Get all test objects of type JFrame (dialog) for RSx 9.0
TestObject[] tree_parent = root.
find(atDescendant(".class", "org.eclipse.swt.custom.CTabFolder",".tabs",
"{Project Explorer,Inheritance Explorer}"));
//Identifying tree under project explorer
TestObject[] tree_PE = tree_parent[0].find(atDescendant("class", 
//Getting hold of tree under project explorer as SWTTree object
SWTTree SWTTree_PE = new SWTTree(tree_PE[0]);

//Performing some actions on the SWTTree object"REST->Models->REST Service Model"));, atPath("REST->Models-
>REST Service Model"));

//Unregister after object is used
Figure 13. Convert an object to a dynamic test object
Wizard to insert a dynamic test object in script


This article helps you overcome most of the problems that might arise during either manual merging of Rational Functional Tester scripts into an existing automation suite or during restructure of an existing folder structure for automation. After reading through these solutions, which are based on a Rational Software Architect case study, you will be able to visualize similar problems more realistically and solve the problems easily.



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

ArticleTitle=Manually merge new Rational Functional Tester scripts into an existing automation suite