Using Custom Modules with a Full-Duplex Protocol

Document created by Chris Sommerstad Employee on Jul 20, 2017Last modified by Avril Dsilva on Aug 10, 2017
Version 2Show Document
  • View in full screen mode

This article presents an example implementation of CloudTest's Custom Module feature with a full-duplex protocol—in this case the protocol used is the WebSocket protocol—in a test composition. This implementation was done in lieu of full support for WebSocket Recording (which was added in SOASTA 53,). The example provided below is a WebSocket example, however, the Custom Modules feature can be used with other, non-WebSocket, asynchronous protocols, such as UDP.

Additionally, it is also possible that having recorded a WebSocket test clip, a user may also want to use the simulated transaction or some other detail of the Custom Modules feature in tandem with a test clip based on a WebSocket Recording, and so the following content has not been fully deprecated.

This material is no longer the starting point for WebSocket testers. WebSocket testers should apprise themselves of both the WebSocket Recording feature and the WebSocket Support reference article before continuing with the following material.


By deploying Java JAR files whose code calls the Scripting Custom Module Java API into CloudTest, and then calling that module(s) from within a Composition, CloudTest users can accomplish tasks that cannot currently be done in a standard Composition.

The Java code is compiled into a JAR for use with CloudTest's Custom Module feature. This JAR can interact directly with the playing Composition’s environment via a CloudTest script (without having to return to the calling JavaScript).

Note: CloudTest provides two APIs that should not be confused; one is for Java and one for JavaScript. The JavaScript API is the basis for all of the CloudTest scripts used in test clips/compositions. The Scripting Custom Module Java API is used in all Java source code intended for use in association with a CloudTest script via the Custom Module panel in the Script Editor. Both APIs are used in the example WebSocket test composition described in this article.

  • The developer will create a CloudTest script—written using the JavaScript API—and then associate the JAR file(s) to it via the Custom Module panel.
  • The example in this article uses the open source Java-WebSocket open-source project, which can be downloaded here. The project contains a JAR (java_websocket.jar) file that is necessary for this example to work. Skip creating the sample test composition described in this article if you already have a JAR file to use. In which case, use the steps below as a basic workflow for creating your own test composition using a full-duplex protocol implementation.

Using the Scripting Custom Module Java API

The Custom Module feature permits users to create and add their own Java custom modules (such as a Jar file to a CloudTest environment).

Note:  In the real world, you'll create your own Java JAR to use. For demonstration purposes, the remainder of this article will use the Java-WebSocket project, alongside Java code that calls both it and the Scripting Custom Module Java API. Download the Java-WebSocket project, you'll need the java_websocket.jar it contains to follow along. If you have your own full-duplex implementation, use that instead.

  1. Using the WebSocketExample source code here as a model, create your own Java source code.

TIP:  Our example utilizes the Java-WebSocket open source project noted above, and includes two Java files— and In the, both the Java-WebSocket project and the Scripting Custom Module Java API are used. Your own project may include the following or additional steps but will be founded upon the providedCustom Module API used in tandem with a CloudTest script in the test composition.

  1. Use the execute method to call from the CloudTest Script in the composition; also passes in the SOASTA Custom Java API and the address of the WebSocket server.
  2. Uss the API to get the current Composition object.

  1. Create a WebSockets communication handler. In this example, the handler is defined in the above).
  2. Use SimulatedTransactionInfo to setup virtual messages.
  3. Use the Result object's postMessage method for each step in the communication. Simulated messages can be represented in the Result as if they were standard Messages in the Clip, and as such are included in the composition's statistics as if they were a standard Message. Java operations can be mixed in with regular Messages (or any other standard item) in a Clip.


Checking Composition Status using Flag Variables

The final step prior to uploading custom Java mode code for use with CloudTest should be to ensure that the Custom Module Java API's Composition flag variables—isAborting and isEnding—are used everywhere that is necessary.

For custom Java code, the Java programmer is responsible for checking these API flags, and the developer should ensure that their Java code will stop when the composition stops. There is no technique by which CloudTest can stop Java code from the outside.

IMPORTANT:  The custom Java code in use should be written to avoid infinite loops. Always add a check flag to see if the Java task should stop otherwise you can hang the composition. Inadequate use of the Composition flag variables in tandem with infinite loops can leave the programmer with no choice but to reboot the server in order to stop a Composition that contains custom module Java code that doesn't respond to an ended or aborted Composition.

An example use of the Composition flag variable, isEnding, is shown below. This example appears in the file discussed above.

Uploading a Custom Module

Once your code is written, compile it into a JAR file for use in CloudTest. Then, use the Custom Module feature to add it to a CloudTest environment. To do so, open your CloudTest instance and use the followign steps to add it to your repository IIn this example, we are using two JAR files: java_websocket.jar (from the Java-WebSocket, dist folder) and our own compiled JAR, WebSocketsExample.jar.

Note: The Custom Modules feature is enabled per license. If you don't see Central > Custom Modules ask your SOASTA representative. This feature is not available in CloudTest Lite.

  1. Login to your CloudTest instance and navigate to Central > Custom Modules (under the Library node).
  2. Click the New icon.

Use the New Custom Module box for the remaining steps.

  1. In the New Custom Module box, click Choose File to select your Java code file. For example, java_websocket.jar.
  2. Assign a repository name. This will appear in the Central > Custom Modules list.
  3. Optionally, select a repository folder.

  1. Click OK to complete creation of the Custom Module.
  2. Repeat this step for any additional JAR files necessary to create your own scenario. In this example, we also uploaded WebSocketsExample.jar.

The Custom Modules list will show both of the new custom modules.

Note: The second JAR file uploaded in the above screenshot as a custom module (java_websocket.jar) is from the open source project.


Calling a Custom Module from a CloudTest Script

    1. Next, create a CloudTest script (from Central > Scripts) in your test that will call the new Custom Module.

In this example script, we will need the following lines of code:

    1. An import statement. In this case, we are using the websocketexample.
    2. A variable for the ID that we are generating.
    3. The execute method (mentioned above) to call the WebSocket server from the CloudTest script.
    4. A Result object call, this time from a CloudTest script (e.g. one written in JavaScript). In this case, the message will be "Example completed."

  1. Save the script before proceeding. Leave the script open in the Script Editor.

Associate the Custom Module with the Script

Next, we will create a binding of this script and the Custom Module we created above.

  1. With the script open in the Script Editor, click the Custom Modules button in the Script Editor.

When you do so, the Custom Modules panel opens on the right.

  1. Click Add Custom Modules.
  2. Use the Choose custom module box to navigate to the custom module created above. For example, /Documentation/WebSocketsExample.
  3. .

  1. Click OK and repeat, if necessary. In this example, there is a second custom module to associate with this script.

  1. Save the CloudTest script and give it a name before proceeding. For example, WebSocketsSample Script.

Use the Script in a Test Clip and Playing the Composition

The remaining steps are basic CloudTest test assembly steps.

  1. Create a test clip. For example, WebSocketsSample Clip. Refer to Creating a New Clip for steps.
  2. Create a group in the test clip, Group1.
  3. In Group1, add a second group, Group2.
  4. With the Clip Editor, lower panel Scripts tab shown, drag the script created above into Group2.

  1. Save the test clip and give it a name before proceeding. For example, WebSocketsSample Clip.
  2. From the Clip Editor toolbar, select Open in Test Composition.

  1. Click Save on the Composition Editor toolbar and give the new test composition a name. For example, WebSocketsSample Composition.
  2. Click the Play button on the Composition Editor toolbar. The composition begins to play and the Results tab appears showing the Result Details dashboard.

Examining Results

  1. Expand the Navigation Tree in the Result Details dashboard.
  2. Click the Foreground Transaction, and then click the Events List tab. This is a simulated transaction and it was defined in the WebSocketsExample.jar (shown in bold below):

// We'll put all of our "foreground work" into a Transaction in the Result.
SimulatedTransactionInfo simulatedTransactionInfo = result.createSimulatedTransactionInfo();
simulatedTransactionInfo.parentPathType = "Clip";
simulatedTransactionInfo.parentPath = "."; = "Foreground Transaction";
simulatedTransactionInfo.repeatIndex = -1;
simulatedTransactionInfo.deltaFromScheduledStart = 0;

  1. Examine the Events List results for each of the 3 messages in the test clip. Note how they relate to the simulated messages that were created in the WebSocketsExample.jar.

  1. Stop the test composition when ready.