This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Desktop Companion User Guide

Real Load Desktop companion - Introduction

The Desktop Companion is a small application that allows you to manage some tasks related to the DKFQS Platform and the Real Load Portal.

In particular the desktop companion allows you to:

  • Generate HTTP Load Test scripts from HTTP archives (.har) files
  • Locally run the Real Load Proxy Recorder
  • Perform some basic editing of test scripts
  • Upload test scripts directly to the Real Load Portal
  • Manage AWS Measuring Agents (launch, terminate, register with Real Load Portal)

See sections below to learn more about the Desktop Companion.

1 - Release Notes

Desktop Companion change log

0.24 | 21 Mar 2022

0.23 | 25 Jan 2022

0.22 | 13 Dec 2021

0.21 | 9 Dec 2021

0.20 | 3 Dec 2021

  • Usability: Added help links to online documentation.
  • Usability: Added various configuration checks and related alert dialogs.
  • Usability: On exit, added alert in relation to running AWS EC2 instances.
  • Usability: List of AWS instances is updated via a background thread, periodically.
  • Usability: List of registered Measuring Agents is updated via a background thread, periodically.
  • Usability: The AWS region where an EC2 instance is launched is automatically added to “My Regions” list.
  • Installer: Created a Windows full installer that includes a JRE.
  • Bugfix: Fixed an issue with HAR files containing POST requests with no content type.
  • Bugfix: Updated JavaFX to v17
  • Download URL JAR: https://download.realload.com/desktop_companion/RealLoadDesktopCompanion-0.20.jar
  • Downalod URL Windows full installer: https://download.realload.com/desktop_companion/RLDTC_windows-x64_0_20.exe

0.10 | 8 Nov 2021

2 - Desktop Companion - Pre-requisites

Read this first.

Before running the Desktop Companion make sure you satisfy the following pre-requisites:

JRE 11 (Mandatory to execute JAR file)

The Desktop Companion is a Java application currently delivered as a .jar file. At this stage there is no full installer for the application, which means that as a pre-requisite to run the application you’ll need to install a Java 11 JRE.

While it should run on any systems that support Java 11 and FXML, it was only tested on the following platforms:

Operating System JRE 11 Vendor and Build JRE download link Comments
Windows 10 Microsoft “11.0.11” 2021-04-20 https://docs.microsoft.com/en-au/java/openjdk/download
Windows 11 Microsoft https://docs.microsoft.com/en-au/java/openjdk/download
Apple OS X Microsoft “build 11.0.13+8-LTS” https://docs.microsoft.com/en-au/java/openjdk/download

AWS API Security Credentials (Optional)

In order to use the AWS integration features, you’ll need to prepare Security Credentials with AWS IAM.

Seach for “IAM” in the AWS search bar and click on “Users”:

Then add a new user:

Enter a suitable user name and select “Access key” as the AWS credential type.

On the next page set an appropriate policy for the user. Usin the “AmazonEC2FullAccess” provides sufficinet permissions.

Skip the “Add tags” screen and go to the “Review” screen and click on “Create user”. Make sure the permissions you’ve assigned to the user appear on this screen.

Finally take a note of the Access Key ID and Secret Access Key as thess need to be configured in the Real Load Desktop Companion.

Real Load Portal User API Authentication Token (Optional)

In order to register with the Real Load portal the AWS EC2 instances you’ve launched, the Desktop Companion requires that you configure an authentication token.

To create an authentication token proceed as follows:

Login to the Real Load Portal and click on the User -> API Authenticaiton Tokens menu.

Then click on the “Add API Authentication Tokens” button and enter a suitable purpose description. Optionally you can restrict the src IP address from where this token can be used.

Take note of the authentication Token Value as you’ll need to configure it in the Desktop Companion.

3 - Desktop Companion - Download and run

Where to donwload the application from and how to run.

Downloading the full installer (Windows)

The full installer includes a JRE as well as the Desktop Companion application itself. This is the preferred method of deploying the application, as it avoids issues that might occur because of JRE customization, etc…

Additionally the application can be started from the Windows start menu, as any other application.

The latest version of the full installer can be downloaded from here: https://download.realload.com/desktop_companion/latest_win64

Downloading standalone JAR file only

You can download the latest version of the Desktop Companion as an executable .jar file from here: https://download.realload.com/desktop_companion/latest

There is no installer to be executed, the application can be launched by double clicking on the .jar file. If that doesn’t work, consider launching from the command line.

Windows: Launch from file explorer

If you’ve only got one JDK/JRE version installed on your Windows computer then it’s very likely that .jar files are associated with the correct JRE. In that case you should be able to launch the application by double clicking on the .jar file.

If the application doesn’t start it’s possible the .jar extensions is associated with the incorrect JRE or another application altogether. You can try to right click on the .jar file and the “Open with” from the context menu.

Then selecte the OpenJRE launcher:

… or alternatively navigate to the JRE 11 binary, as shown in this screenshot:

Similarly on Windows 11:

s

If the application doesn’t start, consider starting it from the command line as explained below.

Windows: Launch from command line

Open a Terminal window. First validate that the java binary in your path is a JRE 11 binary by running this command:

java -version

The output should indicate you’re running a JRE 11 binary, as shown here:

If the version of the JRE is 11 then you can run the following command from the folder where the Desktop Companion .jar file was downloaded:

java.exe -jar .\RealLoadCompanionFXML-0.1.jar

OS X: Launch from finder

If you only have JRE 11 installed on your Mac, you should be able to launch the application simply by double clicking on its icon:

Alternatively right-click on the icon and “Opne With” Jar Launcher.

If this doesn’t work, refer below on how to launch from the command line.

OS X: Launch from command line

Open a Terminal window. First validate that the java binary in your path is a JRE 11 binary by running this command:

java -version

The output should indicate you’re running a JRE 11 binary, as shown here:

If a different JRE version is returned (like for example a JRE 8 binary) then you’ll need to specify the full path to the java 11 command. For example, assuming you installed the Microsoft OpenJDK 11, you would typically find it at this location:

/Library/Java/JavaVirtualMachines/microsoft-11.jdk/Contents/Home/bin/java

To run the Desktop Companion, assuming the .jar file is present in the current directory, run the following command from a Terminal window:

/Library/Java/JavaVirtualMachines/microsoft-11.jdk/Contents/Home/bin/java -jar RealLoadCompanionFXML-0.1.jar

4 - Desktop Companion - Settings Menu

Configure the Desktop Companion for integration with AWS and the Real Load Portal.

Various application settings are configurable in the File -> Settings menu.

General settings

  • Default HAR input folder: Location where to look for .har (HTTP Archives) files by default. This should be the location where your browser writes files to.

  • Default export folder: This is the location where Real Load HTTP test scripts will be exported to in JSON format.

  • Agent Secret: The Measuring Agent secret to authenticate connections from the Real Load Portal to the Cloud Agent instance (AWS EC2 and Azure instances in future).

User API settings

  • Portal URL: The endpoint of the Real Load portal User API. Unless you have an on-premise installation, use the default value https://portal.realload.com/RemoteUserAPI

  • Authentication Token: Enter here the authentication token that was generated by the Portal as part of the pre-requisites steps. Click on the “Test” button to test the API token.

  • Refresh Interval: How frequently should the list of Measuring Agents registered with the Real Cloud portal be refreshed. Any value 60 seconds or lower indicates no background refresh, you’ll need to manually trigger a refresh via context menu. By default set to 61 seconds (background refresh enabled).

AWS settings

  • AWS Access Key: Paste the AWS Access Key that was obained as part of the preparation steps.

  • Secret Access Key: Paster the AWS Secret Access key that was obained as part of the preparation steps. Use the “Test” button to validate the credentials.

  • Preferred Instance Type: The EC2 instance type to use when launching a new Mesauring Agent instance.

  • AWS EC2 Refresh Interval: How frequently should the list of AWS EC2 instances be refreshed. Any value 60 seconds or lower indicates no background refresh, you’ll need to manually trigger a refresh via context menu. By default set to 61 seconds (background refresh enabled).

  • My AWS Regions: Select the AWS regions you commonly use. To select multiple regions hold the CTRL key while selecting.

Proxy Recorder settings

  • Proxy Port: The TCP port on the local machine that will listen for incoming proxy connections. You’ll need to configure this port as the HTTP proxy in your browser.

  • Export CA Certificate: This exports the CA certificate used by reverse proxy to sign SSL certificates. The exported CA should be added as a trusted CA to the browser you’re planning to use to record HTTP requests.

The next settings should be left to default values, unless there are specific reasons for changing them.

  • Proxy Backend Server Start Port Range: Starting TCP source port range for connections generated by the Proxy.
  • Proxy Backend Server End Port Range: Ending (high) TCP source port range for connections generated by the Proxy.
  • Debug HTTP Headers: Enables capturing HTTP headers values in Proxy debug log.

5 - Desktop Companion - File Menu

Import HTTP archives and export test scripts locally or to the Portal.

Import HAR file

To import an HTTP Archive generate by a browser use the corresponding option in the file menu and select the relevant .har file. All requests present in the file will appear in the editor tab.

Export test script to JSON file

You can export your test script to a Real Load JSON session file by selecting the corresponding option in the file menu. The file will be saved in the folder you select.

You’ll then need to manually upload the file to a Resource Set in the Real Load Portal using the upload function.

Export test script to Portal

Test scripts can be directly uploaded to the Real Load Portal via the “Export session to portal…” menu. You’ll need to select the resource set to save the load test to:

You have 2 options:

  • Overwrite existing test script: If you select and existing HTTP test script without modifying the filename this will effectively overwrite it.
  • Select a resource set: On the other hand if you select a resource set (… “Web Test” in the above screenshot for example) you’ll then have to enter a filename for your new test script.

6 - Desktop Companion - Editor

Simple request editor.

In the request editor tab you’ll be able to perform some basic editing of the requests imported from an HAR file or recorded by the proxy recorder.

For more complex editing please use the HTTP wizard in the Real Cloud portal after uploading your test script there.

Overview

The Editor tab is split in 3 main parts:

  • HTTP Requests lists: This section shows all HTTP requests imported from an HAR or recorded by the Recording Proxy. The context menu accessible via a right click allows you to perform some basic editing functions.
  • Request details: When selecting a request some additional details about the request will appear, like values extracted from HTTP headers, etc…
  • Unique domains: In this section all unique domain names will be listed. Clicking on a domain will select all relevant rows in the requests table.

Delete Requests

You can mark requestes in the main editor window by clicking on them. Hold the ctrl keyty to mark multiple request or use the shift key to mark a range of requests.

Once marked you can delete the requests by right-clicking on a marked request and selecting “Delete selected” from the context menu:

Adding time delays

To add a time delay (currently hardcoded to 1 second) before or after a request, select the relevant context menu item while hovering over a request.

Time delays rows appear as requests of type “T” in the main editor window:

Domain based selection

In order to bulk select all requests belonging to specific domains select one or more domains (by holding the CTRL key). This will select corresponding requests in the requests list which can then be easilly deleted.

It is also possible to directly delete requests belonging to one or multiple domains using the context menu.

7 - Desktop Companion - Measuring Agents

Launch and terminate AWS based measuring agents and manage their registration with the Portal.

The Measuring Agents tab allows you to manage Cloud Based (… currently AWS) Measuring Agents. This section of the application will be of most use if you configured AWS credentials in the preferences section of the application.

If no AWS credentials are configured, you won’t be able to start and terminate AWS instances.

Listing Measuring Agents AMIs

In the left pane you’ll see a list of available AWS AMIs. You can further filter the list of AMIs by selecting a specific version and/or by selecteing an AWS region.

Launching an instance

To launch an new EC2 instance right-click on the relevant AMI and select “Launch”. A screen to confirm the launch will be displayed. Confirm by clicking on the “Launch” button.

When launching an instance in an AWS EC2 region that is not yet part of your “My Regions” list, the region will be automatically added to the list.

Launching a new instaance will automatically trigger a refresh of the AWS Measuring Agents list. It might take a few second for the list to update and the new instance to be reflected in it.

Then confirm the launch action:

Listing running EC2 instances

After launching an instance go to the top right part of the window listing the running instances and right click on “Refresh”. This will retrieve all running EC2 instances from the preferred AWS regions and display them in the table.

Registering an instance

To register an AWS instance with the Real Load Portal right-click on the instance and then select the “Register with portal” menu item. The instance ID will be used as the description in the Real Load Portal.

List registered instances

In the left bottom part of the window you’ll see the Measuring Agents currently registered on the Portal. To update the list right click and select the “Refresh” option.

De-register an instance

In order to de-register an instance from the Portal right click on the instance name and select De-register.

Terminate an instance

To terminate an AWS EC2 instance right click on the instance name.

8 - Desktop Companion - Proxy Recorder

Run the proxy recorder locally on your desktop.

The Desktop Companion allows you to run the Proxy Recorder locally on your desktop. Recorded requests will then appear in the Editor tab. Refer to the Proxy Recorder documentation for further information on how it works.

There are two main sections in this chapter:

  • How to configure your browser.
  • Hot to start/stop the recording process.

Configure your browser

You’ll have to configure the port the Real Load Proxy listens on (default: 18080) in your browser. We recommend to use a browser that allows you to configure proxy settings independently from the Operating System proxy settings. FireFox is a good candidate for this and we’ve documented its configuration in this section.

Import Reverse Proxy CA certificate

For the browser to trust SSL certificates issued by the Recording Proxy, you’ll need to import the Proxy’s CA certificate as follows:

  • Export the certificate to a file: In the Desktop Companion’s Proxy Setting tab, click the “Export CA Certificate. Then select a folder where the certificate is to be exported. It will be saved in file “RecProxyCert.cer”.

  • Import certificate: Navigate to the certificate settings in FireFox:

Then click on the “Auhtorities” tab, “Import” button and select the “RecProxyCert.cer” that you’ve just exported from the Desktop Companion.

Make sure you trust the certificate to identify websites:

Configure proxy settings

In the FireFox “Settings” and scroll to the bottom of the page where “Network Settings” are located . The below window should be displayed and configure the Port to be 18080 for both HTTP and HTTPS. Configure the host and port as shown in the below screenshot. Also tick the “Also use this proxy for HTTPS”.

Test browser configuration

Navigate to any SSL enabled page. You shouldn’t see any warnings about untrusted SSL certificates beings used.

If you check the certificate of the site you’re visiting, the issuer should be “Real Load Pty Ltd”, as shown in this screenshot.

Start the recording process

To start the recording process go to the Proxy Recorder tab and click on the “Start Recorder” button. Note that when the recording process is started, previous Proxy Recorder logs are purged.

Stop the recording process

To stop the recording process clik on the “Stop Recorder” button. Then navigate to the “Editor” window and you should see all recorded requests as in this example: