User Guide

• 1: AWS Measuring Agents
• 2: HTTP Test Wizard
• 3: HTTP/S Remote Proxy Recorder

1 - AWS Measuring Agents

This document describes how to launch Measuring Agents in AWS as EC2 instances. Readers are assumed to be familiar with AWS EC2 terms used in here, in particular if launching Measuring Agents manually.

Listing available AWS AMIs

We make pre-installed Measuring Agents available for everybody to use in AWS redy-to-run AMIs. No additional costs (beyong the costs charged by AWS) apply when using these images.

To obtain a list of these ready to run AMIs proceed you can use one of these options:

Via our Desktop Companion

Our Desktop Companion allows you to manage AWS Measuring Agents. You can launch and terminate agents as well as register them directly with the Real Load Portal with a few mouseclicks.

Refer to the Desktop Companion Documentation for further information.

Via the Real Load portal

Login to the Real Load portal and then head to the Measuring Agents configuration section. Then click on the AWS logo:

… and a list of available AWS AMIs will be displayed.

Via the AWS Console

Using the AWS console locate AMIs belonging to our AWS account 775953462348 in your preferred AWS region. This can be done by looking for public images owned by our account, as illustrated in this screenshot:

For example in the Sydney region (ap-southeast-2) you’ll find the above listed AMI. If you can’t find an AMI in your desired region please contact us so that we can make it available.

Launching an AMI

Via our Desktop Companion

Our Desktop Companion allows you to launch AMIs with a mouseclick.

Refer to the Desktop Companion Documentation for further information.

Via the AWS Console

Once you’ve located a suitable AMI you can launch it as you would with any other Linux image as illustrated in this section.

Configure a Security Group

In order for the AMI to be reachable from the Real Load Portal you’ll need to configure a Security Group allowing inbound connections to port 8080 as a minimum.

Set the Measuring Agent secret

In order to protect access to your Measuring Agent we strongly recommend setting a non-default secret when launching the AMI.

The secret can be set at launch time by providing User Data to the AMI as follows (replace “secret” with the secret of your choice):

#!/bin/sh
echo "AGENT_SECRET=secret" > /home/ec2-user/agent_secret.sh

(Optional) Set instance tag

If you want this instance to appear in the Desktop Companion application then you’ll have to set the “REAL_LOAD_AGENT” tag to “true” when launching.

Select the Security Group

(Optional) Select SSH key

If for some reasons you think you might need to login via SSH to the Measuring Agent instance, then select an SSH key. This is not required for normal agent operations.

Configure EC2 instance in Real Load Portal

Via our Desktop Companion

Our Desktop Companion allows you to configue EC2 instances with a mouseclick.

Refer to the Desktop Companion Documentation for further information.

Manual Configuration

Once the EC2 instance is up and running, you’ll need to configure it in the Real Load portal so that you can execute load tests from it.

Once added you can validate connectivity to the agent as shown in this screenshot:

Terminating EC2 instances

Once you’ve completed your load testing it’s important to terminate the Measuring Agent instance to avoid unwatend AWS charges.

Via our Desktop Companion

Our Desktop Companion allows you to terminate EC2 instances and remove it from the Real Load Portal configuration with a mouseclick.

Refer to the Desktop Companion Documentation for further information.

Via the AWS Console

Terminate the instace as you would terminate any other Linux instance.

Remove EC2 instance from Real Load Portal

Via our Desktop Companion

Our Desktop Companion allows you to remove Measuring Agent instances with a mouseclick.

Refer to the Desktop Companion Documentation for further information.

Manual Configuration

From the Meausring Agents menu select to delete the agent.

Alternatively you could decide to keep the agent configured and simply deactivate it. Disabling is recommended to avoid warning messages in the Portal console about failing connectivity tests.

2 - HTTP Test Wizard

Overview and Functionality

The HTTP Tests Wizard supports you to create sophisticated tests in an easy way. You can compile (define) the entire test via the user interface and then generate a ready-to-run test program from this definition. A powerful debugger helps you to perfect your test.

As the name suggests, the HTTP Tests Wizard is optimized for the execution of HTTP/S tests. However, by using plug-ins, any other protocols can also be tested and measured (such as SMTP, DNS queries, DB-SQL queries, etc.).

HTTP Tests Wizard Features:

• No programming required (except for self written plug-ins). You can create your test through the powerful user interface by assembling all required functionalities via simple dialogs.
• The executed HTTP/S calls can be either entered manually our can be inported from a Proxy Recorder session.
• Variable values (variables) can be extracted and assigned directly via the user interface.
• Integrated Remote-Debugger: The defined test can be debugged in advance on any Measuring Agent - before generating the test program. The degugger supports also to define variables as well as to define variable-extractors and variable-assigners at the fly, which are adopted into the test.
• After the test has been passed by the debugger, the defined test can be automatically converted into a performance-optimized test program.

Session and Session Elements

The test sequence is referred to as a so-called “Session”, whereby each simulated user repeatedly executes the session in a loop (so called “User Session” or “Session Loop”).

In order to define a test sequence, you can add various “Session Elements” to a session:

• User Input Field: Displays an additional input field when starting the test and stores the entered value in a global variable.
• Measurement Group: Measures the execution time over several session elements.
• URL: Executes a HTTP request and receives the HTTP response. Measures the execution time, and verifies the HTTP response. The HTTP response can either received synchronously or asynchronously (see also URL Synchronisation Point). Supports “Bound to URL Plug-Ins” which, among other things, can modify HTTP request and postprocess HTTP responses.
• URL Synchronisation Point: Synchronizes asynchronously received HTTP responses.
• Delay Time: Delays the execution of the user session for an amount of time.
• Basic Authentication: Adds a Basic Authentication username and password to all or selected URLs.
• SSL/TLS Client Certificate: Adds a SSL/TLS Client Certificate to all or selected URLs.
• General Request Header Field: Adds a HTTP request header field (for example “User-Agent”) to all or selected URLs.
• Cookie Modifier: Sets/Extracts/Deletes cookies.
• Plug-In: Initializes and executes a “Normal Session Element Plug-In”.
• Input File: Reads an input file line by line, tokenizes the line and extracts the values of the tokens into variables.
• Output File: Stores the values of variables into an output file.

Adding session elements is in most cases quite simple and self-explanatory, but it can be a bit challenging for URLs and Input Files. For this reason, adding of these two session elements is described in more detail in the next two sub-chapters.

Adding URLs

When adding an URL you have at least to select the HTTP Method (for example GET) and to enter the absolute URL (https://<host>/path).

Checking the HTTP response code and the HTTP response content is optional, but strongly recommended, as otherwise the test result may contain false positive results.

The following fields can be entered or selected:

• General Area
  • HTTP Method: Select the HTTP method (GET, POST, …).
  • URL: Enter an absolute URL, inclusive (optional) query string parameters. Example: https://www.dkfqa.com/?v=1&w=2
  • Execute - synchronous or asynchronous: Select how the HTTP response is received. If you choose “asynchronous” then you have also to add an “URL Synchronisation Point” to the test sequence after the asynchronous executed URLs.
  • Error Handling: Select what happens if the HTTP request fails or if the HTTP response is invalid. “Final End” means that the whole test is aborted.
  • Enable Implicit Assigners ${<variable-name>}: If checked, then placeholders for variables are considered in the URL as well as in the HTTP request header and content. Example: URL = https://${vHost}/?v=1&w=2, Variable vHost = “www.realload.com”, Result = https://www.realload.com/?v=1&w=2 . Note insted of using inplicit Assigners you can also define Variable Assigers (see next chapter: Variables).
• HTTP Request Content Area | Only fill in this area if the HTTP request contains a content, for example for POST requests.
  • Request Content Type: Select or enter the request content type. For example “application/x-www-form-urlencoded” or “application/json”.
  • Request Content Charset: Select or enter the request content charset - or let the field blank if not applicable.
  • Direct Value or Read From File: Select if the request content data are directly entered here or are read from a file.
  • Request Content Data: Enter the request content data (if they are not read from a file). Note: select first the Request Content Type before you enter the Request Content Data.
  • Also send Zero Content Length: If checked, but no content is available, the HTTP request header field “Content-Length: 0” is sent.
• Additional HTTP Header Fields Area
  • You can enter additional HTTP request header fields here which are only applied for this URL. Note: additional HTTP request header fields that apply to all URLs should instead be defined by using a “General Request Header Field” session element.
• Verify HTTP Response Area | Note: you should configure at least a HTTP response code in order to verify the test result.
  • Verify HTTP Status Code: Select the expected HTTP response code(s).
  • Verify Content Type: Select the expected HTTP response content type(s).
  • Verify Content Text: Enter text fragments that must be present in the HTTP response content, or let the fields blank if not applicable.
• Plug-Ins Area
  • Here you can add “Bound to URL Plug-Ins” (see chapter “Plug-Ins”).

Adding Input Files

Input files are text files (*.txt, *.csv) whose content is read line by line during the test. Each line is divided into tokens from which values of variables are extracted. Empty lines are skipped. Note that the variables must first be defined before you can add an input file.

The following fields can be entered or selected:

• Token Delimiter: The token delimiter. This is usually a single character, but can be also a string.
• Comment Tag: Lines which are starting with the comment tag are skipped. You can place also the comment tag within a line which means that the remaining part of the line is ignored. The comment tag is usually a single character, but can be also a string.
• Cyclic Read: If not checked, then the test will end when no further line can be read (at eof). On the other hand, if checked, the file is re-read after the end of file was reached.
• Randomize Lines: if checked then the order of the lines is randomized each time when the file is read.
• Trim Values: If checked then whitespace characters are removed from the start and end of the extracted values (tokens).
• Remove Double Quotes: If checked then double quotes are removed from the extracted values (tokens).
• Scope: Get Next Line per:
  • Global: Reads only a single one line of the file. The line is read at the start of the test.
  • User: Reads each time a line from the file when a simulated user is started.
  • User Session: Reads each time a line from the file when a simulated user starts a new session loop iteration.
• 6x Variable - Token[Index]: You can configure up to 6 token indexes whose values are extracted into variables.

Variables

The HTTP Tests Wizard (as well as the debugger) supports to define variables and to extract and assign variable values from/to session elements. Variable definitions which are (remotely) made in the debugger are automatically synchronized with the HTTP Test Wizard at portal server side.

The data type of a variable is always a string, which can also be empty, but is usually never null.

Defining Variables

When defining a variable, the following attributes can be set:

1. Variable Name
2. Scope: “Global”, “User” or “User Session”
3. Defailt Value (initial value)

For variables with the scope “Global” there is only one instance which is initialized when the test is started.

For variables that have the scope “User”, there is a separate instance for each simulated user, which is initialized when the user is started.

In the case of variables with the scope “User Session”, a new instance is created and initialized at the start of each iteration of the session loop. The visibility is resricted to the current session loop of the simulated user.

Variable Extractors and Assigers

Variable extractors are definitions which contain instructions about how to extract a value from a session element into a variable. Variable assigners, on the other hand, are definitions that contain instructions how to assign or replace a value of a session element.

The following two images show a variable extractor that extracts a dynamic value from URL[2], and a variable assigner which assigns the value to a JSON post request of URL[3].

While variables (almost) always have to be defined manually, the definition of variable extractors and assigners is usually done implicitly (semi-automatically), depending on the context of the session element.

For example, if you define an input file, you must first create the variables that contain the extracted values (for username and password in this example). If you then assign the line token numbers to the variables, the corresponding variable extractors are automatically created.

Note: In this example above, a separate username and password are read from the input file for each simulated user and assigned to the value of the corresponding variables. For this reason the variables have the scope “User”, and the input file has the scope “Get Next Line per User”.

Assigning and Extracting Variable Values to/from URLs

Apart from Implicit Assigners (see “Adding URLs”), variable values of URLs can only be extracted and assigned by using the debugger. However, this is not a problem as definitions made in the debugger are automatically synchronized with the portal server.

Extracting variable values from URLs during debugging is quite easy. After executing a URL in the debugger, click on the symbol of the HTTP response header or of the HTTP response content and then extract the value.

Assigning variable values to URLs is a little bit more tricky. You have to interrupt the HTTP request in the debugger in the middle - after the request is initialized, but before the request is send to the server.

For this you have temporary to enable the option “HTTP Request Breakpoint” in the debugger, before you execute the URL (Next Step):

After you have clicked on “Next Step” you can assign the variable value to the pending HTTP request:

Click on the symbol of the URL, or of the HTTP request header or of the HTTP request content, and then assign the variable value:

Plug-Ins

Plug-Ins are reusable HTTP Test Wizard extensions that are manually programmed. They can also be published by manufacturing users and imported by other users. Therefore, before you start programming your own plug-in, take first a look at the already published plug-ins.

Plug-In Types

There are 3 types of plug-ins:

• Normal Session Element Plug-Ins: As the name suggests, such plug-ins are executed as a normal session element. This type of plug-in is versatile and can, among other things, process variables, abort the current session, the user or the entire test, or even perform independent measurements with any protocol.
• Bound to URL Plug-Ins: Such plug-ins are linked to a URL session element and can change the HTTP request before sending it to the server and post-process the received HTTP response - such as extracting variable values or checking the content of the HTTP response. Such plug-ins can also abort the current session, the user, or the entire test.
• Java Source Code Modifier Plug-Ins: These are special plug-ins that can subsequently modify the source code generated by the HTTP Test Wizard. Usually such plug-ins are only used as a workaround if the HTTP Test Wizard generates faulty or incomplete source code.

Importing Published Plug-Ins

After you have imported the plug-in you have to load and compile it - then save the compiled plug-in.

After you have saved the compiled plug-in you can add it to your HTTP Test Wizard session. Plug-ins of the type “Java Source Code Modifier Plug-Ins” do not have to be added, but can be called directly after the source code of the test program has been generated.

Developing own Plug-ins

Own plug-ins can be developed in Java 8 or 11. The following example shows a plug-in which decode a base64 encoded string.

After clicking at “New Plug-In” the plugin type has to be selected (in this example “Normal Session Element Plug-In”):

At the “General Settings” tab you have at least to enter the Plug-In Title and the Java Class Name. You should als enter a Plug-In Description which can be formatted by simple HTML tags. The onInitialize Scope can be set to “Global”, as this plug-in does not require any initialization. The onExecute Scope is set to “User Session” in order that all kind of variabe scopes are supported.

At the next tab - “Input & Output Values” - a plug-in input and a plug-in output (Java-)variable is defined for the plug-in method onExecute. The values of this two Java variables will later correspond with two HTTP Test Wizard variables (which may have a different variable name):

When you click at the next tab - “Resources Files” - you will see that the Java library com.dkfqs.tools.jar is already added to the plugin. This is normal as all kind of plug-ins require this library. Here you may add also other Java libraries required by the plug-in - but in this case no other libraries are needed.

Now at the “Source Code & Compile” tab, you can first generate the plug-in template. Then you have to extend the generated code with your own code, ie in this example you have to complete the Java import definitions and program the inner logic of the Java method onExecute. Then compile the plug-in.

At the last tab “Test & Save” you can first test the plug-in (remotely) on any Measuring Agent. To perform the test enter for example “SGVsbG8gV29ybGQ=” as input and you will see as output “Hello World”.

Finally save the plug-in:

After you have saved the plug-in click at the “Close” button. Then you will see the new plug-in in the plug-in list:

Publishing Plug-Ins

If your plug-in can be used universally, it would be nice if you also publish it - to make it available to other users.

Note that you have to enable in your Profile Settings the option “Public In-App User” in order that you entitled to publish plug-ins.

Publishing plug-ins is especially useful for users who have additionally activated the option “Publish My Profile as Technical Expert” in their Profile Settings. This will significantly improve your visibility and competence.

3 - HTTP/S Remote Proxy Recorder

By using an HTTP/S Proxy Recorder, the HTTP/S traffic from Web browsers and technical Web clients can be recorded and easily converted into a HTTP Test Wizard session.

The HTTP Test Wizard session can then be debugged and post-processed. Finally, an executable test program can be generated from the recorded session.

Functional Overview: Remote Proxy Recorder

An HTTP/S Remote Proxy Recorder has two service ports:

• A Control Port that is addressed by the portal server.
• A Proxy Port that records the data traffic from a Web browser or from a technical Web client.

All data traffic that passes through the proxy port is first decrypted by the Proxy Recorder and then encrypted again before it is forwarded to the target Web server(s).

In order to record a Web surfing session by a Web browser you have to start two different Web browser products on your local machine. For example:

• A Chrome browser to operate the portal server (Web Browser 1), and
• A Firefox browser to record the Web surfing session (Web Browser 2)

We recommend to use always Firefox as Web Browser 2.

To be able to record a Web surfing session, you have to reconfigure Web Browser 2:

• Import the Proxy Server CA Root Certificate into the Web Browser 2.
• Configure the Network Settings of Web Browser 2 to use the Proxy Server.

Additional note: Before you start recording a Web surfing session in Web Browser 2, you must always clear the browser cache.

Once the recording is completed you should undo the configuration changes in Web Browser 2 (restore the original network settings and delete the Proxy Server CA Root Certificate).

Registering a Proxy Recorder at the Portal

After you have started a HTTP/S Proxy Recorder as a cloud instance or installed it on one of your systems, you have to register it at the Portal Server.

You can set any user name and password for Proxy Authentication. The Control API Authentication Token was defined/set by the person who started or installed the Proxy Recorder.

Once you have registered the Proxy Recorder you can try to ping it on the application level:

Then try to connect to the Control Port of the Proxy Recorder. If this works, the Proxy Recorder is now ready for use.

Configuring Web Browser 2 for Recording

Import the Proxy Server CA Root Certificate

Click at the certificate icon and store the certificate at any location.

Then open the Web browser settings and import the certificate.

Since there is a small bug in some versions of Firefox, you have to close and reopen the Certificate Manager to view the imported certificate.

Configure the Network Settings

Recording a Web Surfing Session

Navigate with Web Browser 1 to the Proxy Recorder control menu.

Then configure the “Hosts Recording Filter” and click on the “Start Recording” icon.

In Web Browser 2, first clear the browser cache and then enter the URL where you want the recording to start.

In Web Browser 1 you can now see the recording of the first page. Before navigating to the next page in Web Browser 2, first insert a “Page Break” in Web Browser 1 with a brief description of the next page.

Then navigate to the next page in Web Browser 2.

In Web Browser 1 you can now see the recording of the next page.

Then continue as before. Insert a Page Break in Web Browser 1, navigate to a next page in Web Browser 2. and so on …

After you have done the recording click on the “Stop Recording” icon. Then convert the recording into an HTTP Test Wizard session.

Converting the Recorded Session

Here you can select different options. The HTTP Status Code Filter also supports * as a wildcard. An exclamation mark in the font of a value means “do not / exclude”.

The option Enable Parallel Execution of HTTP Requests should be enabled if you have recorded a session with a Web browser (as described above), but should be disabled if the recording was performed by a technical Web client.

Once you have clicked on the Convert button, the recorded session is converted and directly loaded into the HTTP Test Wizard.

After that debug the converted session in the HTTP Test Wizard and then save the HTTP Test Wizard session. Finally generate and execute the test.