Introducing the JMeter Correlation Recorder Plugin — Now Featuring Auto Correlation

BlazeMeter has just released the JMeter Correlation Plugin. This new Apache JMeter™ recorder plugin enables you to easily load test applications with dynamic variables. The plugin records the dynamic variables and automatically correlates them during the recording time, instead of having to manually apply correlations to each request and response. This makes the correlation process much quicker and easier for QA engineers and developers and enables replaying and test iterations.

The latest update to the JMeter Correlation Recorder Plugin now features Auto Correlation. This offering allows testers to save significant time spent on correcting broken or mismatched HTTP requests. The Auto Correlation Plugin identifies dynamic elements of your performance test and correlates them for testers. This had primarily been done manually in the past and was extremely time-consuming.

What is the JMeter Correlation Plugin?

The JMeter Correlation plugin provides multiple improvements and features over its predecessor, the Siebel CRM Correlation Plugin. While the Siebel plugin was focused on correlations for Siebel, the Correlation Recorder generalizes the entire process so you can now correlate any application using rules that you either create manually or saved/loaded into a template.

This is also why we have prepared a Centralized Repository, so that everyone can upload and share their templates for various applications with the rest of the community. You can find it here.

Why Correlations are Important When Load Testing

Before we dive into how the plugin works, here's a quick reminder about correlations and why they are needed.

Let's say a user logs into an application. They type their credentials in a form. The information is sent to the server. If the login is successful, the user gets a session identifier and accesses the app.

However, certain values are dynamic. This means they are unique per user or per session and change each time.

Values that might change:

• The session identifier
• The time of the login
• The CSRF security token

If a dynamic value is recorded and then run in the test iterations, the test will fail. This happens because it is not consistent with the one the server was expecting to perform the flow.

To overcome this challenge, load testers user correlations. Correlation is the process of capturing and storing the dynamic response from the server and passing it on correctly to subsequent requests. The server gets the correct response and the test keeps running.

You can learn more from this blog post: “How to Handle Correlation in JMeter”.

Creating Your Script with the JMeter Correlation Plugin

Step 1: Installing the Plugin

1. If you don’t have the JMeter Plugins Manager installed yet, you can find easy instructions in the article, ”How to Install the JMeter Plugins Manager”. Then, open it up. (Options → Plugins Manager)

2. Select the Available Plugins. In the search field, write Correlation Recorder, and select the bzm - Correlation Recorder plugin checkbox.

3. Click the button Apply Changes and Restart JMeter.

Step 2: Setting up the Test

It is considered a good practice to use the “Correlation Recorder Template” as a starting point, since it contains multiple elements that will aid you during the recording.

To do so, follow the steps below:

• Go to Templates (in File menu) → Select bzm-Correlation Recorder Template → Create

This is the test plan you’ll get:

If you prefer working without the default template, you can manually add the correlation recorder:

• Right-click on the Test Plan’s Thread Group element to get to the Add menu: (Add → Non-Test Elements → bzm - Correlation Recorder).

Step 3: Configuring the Correlation Recorder Component

The Correlation Recorder Component looks pretty similar to the JMeter HTTP(S) Recorder. The main difference is that it contains a Correlation Rules tab. What is the purpose of this new tab?

As mentioned before, manually correlating flows using JMeter is a difficult task, from detecting all the dynamic variables from responses to identifying where they are used in subsequent requests. Now, this process is simplified and can be easily done in the Correlation Rules tab. 

The structure of the Correlation Rules tab consists of:

• A Reference Variable - to store the dynamic variables
• A Correlation Extractor - to locate and extract dynamic variables
• A Correlation Replacement - to replace the dynamic variables in the following requests

In this tab, you can set up correlation rules.

Correlation Rules

The key point of a correlation with the JMeter Correlation Recorder starts with the Correlation Rules. These are the rules that will determine which information should be extracted and replaced from each response and request.

Setting a Correlation Rule

To add a new Correlation Rule, click the Add button under the empty cage.

One horizontal row with 3 components will be displayed, as shown in the next image. You can configure each of these components according to your correlation needs. Some values will be selected by default in order to help configuring.

For easy recognition, every element has a tooltip that displays its name when you hover over it, starting from the Reference Variable, then the Correlation Extractor and finally the Correlation Replacement.

Every rule must have a Reference Variable. Then, you can select either a Correlation Extractor, a Correlation Replacement or even both of them.

The JMeter Correlation plugin comes with a set of predefined Correlation Extractors and Replacements. When you select one of them from each combo box, the fields required to configure that particular Extractor/Replacement will be displayed.

For more information about each Correlation Extractors and Replacements, you can click on the helper icon right after the combo box. It will open up information to help you out doing the configuration stage. You can find a detailed list of all the Correlation Extractors and Replacements, their parameters and explanations in the documentation of the plugin: Extractors and Replacements. 

Now let's set up a Regex Correlation Extractor for our rule.

The Regex Correlation Extractor and the Regex Correlation Replacement are set as defaults, to ease the configuration of the Rule. Each field will display a tooltip when hovering over and a descriptive text when they are empty.

Step 4: Recording and Running the JMeter Correlation Recorder Plugin

It's important to consider setting some request filters, to avoid recording information that is not relevant for the flow you want to test. You can do this by clicking on the "Requests Filtering" tab.

By default, JMeter suggests some patterns that help with a clean recording. To add them, click on the “Add suggested excludes” in the URL Patterns to Exclude section. 

Once you’ve set up your JMeter testing script and are sure it behaves the way you expect it to, these filters can be removed, in case you want to perform a more realistic recording by including all the downloaded resources.

Before starting the recording, remember to set up the JMeter Proxy in the browser you are using to navigate the app. Additionally, always ensure you are using an updated JMeter’s CA Certificate for your HTTP recordings (take into consideration that, by default, the certificate expires after 7 days).

It's considered a good practice to perform these recordings using an incognito/private tab to ensure a cleaner recording without the interference of previous cookies and sessions.

Click the Start Button and start recording your flow (by navigating the app in the browser).

Example Scenario: Login to WordPress

Let’s look at a scenario based on the rule from before. In this recorded scenario, the user:

• Logs in to WordPress
• Accesses the WordPress dashboard
• Clicks on the Logout link
• Arrives at the Login Form 

After the login/logout recording is run, four samples are generated containing the flow for the application.

The responses obtained from sending credentials to the server (Login), are contained in the “Landing WP Dashboard” sample. The dynamic session ID generated by WordPress for each login is “wpnonce”. It is embedded on different tags all over the dashboard HTML. 

In the highlighted example above, there is a link for the logout action with “wpnonce”. You can also see it below:

The string “d5183252f6” is used by the server to ensure the logout session ID is the same one used after login.

When the log out request is made, its value is contained in the request body in the next step, as follows:

The selected URL, used in this replay, is the following:

We need to ensure that wpnonce is retrieved from the responses of every replayed flow. The “Regular Expression Extractor” is automatically created in the “Landing WP Dashboard” step to do just that.

Now, in the “Send action ‘Log out’ to WP Server" step, the parameter that contains the wpnonce is automatically replaced by a variable. This variable has the same name of the one used in the Regular Expression Extractor. So, both values are linked each time the flow is replayed.

This entire cycle, from extracting the information of a response, in this case the wpnonce variable, to replacing it in the following requests, was previously configured in the Correlation Rule.

Once everything goes as expected, after the recording each sampler that matched the configured Correlation Extractor will contain a Regular Expression Extractor. The extractor gets the dynamic values from the response using the Reference Variable name. 

If the condition of the Correlation Replacement is matched, there is a value stored in the reference variable for the configured rule, and that value matches the one obtained from the first group of the Replacement - it will be replaced by the Reference Variable surrounded by ${}. This is shown in the following image for the ${sessionNonce} created for the _wpnonce argument.

It's important to mention that when setting the Regular Expression for the Replacement it should only contain one capturing group. This is the group the information will be extracted from and where replacement will occur, by using the rest of the regex as contextual information to match the proper value.

Executing the recorded test plan with this setup will allow you to do performance testing in your flows without having to worry about variables changing between each iteration or user.

Advanced Custom Extensions

Please note that if during your configuration, you need more complex logic than just extracting or replacing variables, the Correlation Recorder plugin can also be extended. This allows you to develop your very own Custom Extensions using Java as your main language. You can read more about it here. 

Correlation Templates

One of the main functionalities the Correlation Recorder offers over its predecessor, Siebel CRM Recorder, is the possibility of loading, saving and sharing sets of configured Correlation Rules using Correlation Templates. Here's how:

Saving a Set of Rules

When you finish configuring your Correlations, you can click the Save Template button over the Correlation Rules tab to save all the Rules you have set. 

As displayed in the previous image, all templates contain - aside from their Correlation Rules - their version, description and changed fields. This allows documenting the information about the template and the particular changes included in this particular version. Description and changed fields support HTML tags for richer documentation. The dependencies section should only be used by advanced users when implementing Custom Extensions, more details here.

Loading Templates

The Correlation Recorder comes with a set of predefined templates, including one for the Siebel CRM environment, to support the most commonly used correlations. Also, because we know the community likes to share, we have prepared a Centralized Repository where everyone can upload their configurations over different platforms and applications.

You can select between local, central or even custom remote repositories to get your templates and use them in your computer at any time.

As shown in the previous image, the templates can be either Available or Installed. You will always need to install any template before loading it and, if it has multiple versions, you will be able to select the one you need.

Backwards Compatibility

If you were working with the Siebel CRM Recorder and want to migrate any Test Plans to the Correlation Recorder: we've got you covered! Backward compatibility between Test Plans exists, so it is safe to upload your .jmx file into the new Recorder and keep testing like a champ!

And that’s it! This is a general overview of some of the changes that BlazeMeter Labs has prepared for you. Don’t just read about them though, try them! Let us know what other improvements or new features you’d like to see.

To help improve your experience, we also just launched a Correlation Recorder Plugin course on the BlazeMeter University platform! The course will teach you how to easily leverage the plugin's capabilities to create dynamic scripts and significantly simplify the script building process.

This blog was updated on 4/27/23 with new information.

Related Resources: 

• How to Handle Correlation in JMeter