When employing XLT Script Developer you usually resort to automated or manual scripting to drive your testing. Sometimes though you will face a very specific or complex task that can not be expressed that easy with the standard scripting capabilities of Script Developer. For these types of scenarios Script Developer provides the option to integrate a custom Java module. With custom modules you have the full power of your Java runtime and are able to achieve virtually any testing objective.
The following blog post will describe a small custom Java module we created and used recently. By this example we will explain when to choose this route and demonstrate the creation and execution of Java modules. Ultimately you will be able to add Script Developer’s custom module option to your testing arsenal.
What is a custom Java module and why use it?
With custom modules you trade the simplicity and support net of XLTs scripting capabilities with the full power (and responsibilities) of your Java runtime environment. That means a custom module is not scripted like your normal test case, but written in Java. Script Developer itself will ignore custom modules during script execution. The custom Java module will be shown in your Script Developer test suite as a proxy module only. To execute test cases that reference custom Java modules, you need to run your suite in a Java based execution environment like Eclipse (JUnit), Ant or Maven.
There will be occasions where the scripting functionality does not suffice a task due to it’s complex nature, but which can be accomplished easily with a few lines of Java code. Preferring a custom module over scripting is typical in the following problem domains:
- Complex calculations and validations
- Database lookups
- File I/O
- Visual Assertion
The custom module described in this article implements a specific execution flow, which is not expressible with direct scripting: Usually, the commands of a test case are executed consecutively. As soon as one of them does not succeed, the entire test is marked as failed and test execution stops. Subsequent test cases will not be started, as they might fail due to the already identified erroneous behaviour of the object under test. With our custom Java module things will be different though.
The Localisation Verifier Module
The test objective of our Localisation Verifier module is to examine localised strings displayed on a webpage. In contrast to a normal test run, we do not want the execution to stop upon detecting a wrong string. Instead we want to log the problem to some user provided file and continue the test execution as expected. Due to a potentially high number but low severity of localisation issues, we do not break test case execution at each occurrence. The idea here is to identify all localisation issues visible in the page under test and deal with them after our test run has finished.
The Localisation Verifier module will take the following inputs to assess the page’s localisation:
- A dictionary containing all localised strings.
- Key of the string to verify (retrieved from the page).
- The displayed string to verify (retrieved from the page).
- Optionally, the log file where we record the localisation issue.
Regarding the localised strings, we will employ simple Java Properties files. More than one dictionary file is allowed, i.e. one file per language. The custom module will keep track of the individual localisation dictionaries. Within Script Developer it will be easy to switch among different languages by maintaining one or more variables which point to the localisation Properties files.
The key used is to identify the string we want to look up in the localisation. It has to be unique and is used among the different languages. The key-value pairs of a dictionary for the English language (Strings_EN.properties) might look like the following example.
go_back_btn_ID = Go back
register_first_msg_ID = Please register first.
cart_empty_msg_ID = Your cart is empty.
Analogously, the German dictionary (Strings_DE.properties) is then composed of the following key-value pairs.
go_back_btn_ID = Gehe zurueck
register_first_msg_ID = Bitte legen Sie zuerst ein Konto an.
cart_empty_msg_ID = Ihr Warenkorb ist leer.
If the localised string is incorrect, it will be recorded to the given logfile together with the expected string as well as the localisation key and dictionary. Keys which can not be found are logged as well. In case no log is provided to the custom module, a default log file will be created.
Creating the Java Module
Create a custom Java module in Script Developer by right-clicking the package explorer and selecting New… and then Java Module.
You have to specify the Full Class Name of the custom module including its Java package. This tells XLT where to find the module relative to your suite’s source directory. (Please note: The Package text box above refers to the Script package. You are free to keep the Java source file of your custom module in a different Java package. Be sure to not confuse the two distinct package terms.)
Java Modules cannot be edited in Script Developer directly. Though you have to define the module’s parameters. We will provide the Localisation Verifier with the parameters explained in the previous chapter and as shown in the screenshot above.
Import your test suite containing the custom module as existing project into Eclipse. Create a Java source file for the custom module. Be sure to choose the proper name and package location, so it matches what was specified in the Full Class Name text box in Script Developer.
Next, we will have a brief look at the source code of our custom module. The class needs to implement the interface WebDriverCustomModule, which defines method execute.
public class JHelper_LocalizationVerifier implements WebDriverCustomModule
public void execute(final WebDriver webDriver, final String... parameters)
// Your custom module code here..
System.out.println("Exception: " + e.getMessage());
The module parameters defined in Script Developer will be provided as an array of strings to the execute method. The value of the first parameter specified in Script Developer will be passed as the first string of parameters. Additionally, you will be able to access the utilised implementation of WebDriver. This way you can deal with elements of the current page or instruct related actions.
The remaining implementation of our Localisation Verifier module is pretty straightforward: It loads and keeps track of the individual localisations, looks up the string keys and compares the contained values with the strings found on the page. If the string comparison fails, a log entry is created at the desired log file location.
The custom module is called within a test case of our suite. It will not break test case execution as explained earlier. For the sake of clarity this article omits some implementation details of the module. Be sure to look through the accompanying test suite including the module’s source code.
Executing the Java Module
Our custom Java module will be called from within a test case. Running the test case in Script Developer will simply ignore our custom module during execution. Instead you have to run the test case in Eclipse (via JUnit), Ant, Maven or similar.
Enable the Generate JUnit wrapper class for test cases option in Script Developer’s global settings. This will create a wrapper class (minimal Java class with JUnit annotations) for each test case, which references its underlying test script.
Upon running the test case wrapper class in a Java environment, the commands of the referenced test script are executed by XLT and our custom Java module will be called as part of the process.
If the concept of wrapper classes is new to you, we suggest to read one of the articles on our blog, where this is explained in more detail. One example is available here in chapters Test Case Configuration and Test Case Execution.
We hope that this article has put you in a good position to decide when and how custom modules can be a weapon of choice. There might come a day when a dedicated Java module will save time and effort in your XLT-based testing. Feel free to use the provided example suite and source code as playground for further experiments.
What custom modules are you creating? Would you like to see more about Java modules in the future? Let us know in the comments. As always, your feedback is appreciated!