We begin with the problem it solves, because the tools only make sense once the problem is clear.

The replay problem

The quickest way to build a test is to record a real journey in a browser and replay it with many virtual users. The recording captures every value exactly as it was that day: the session identifier, the security token on the form, the order number the server produced. When the test replays, it sends those frozen values. Most of them are now wrong, because the server generates fresh ones for every session.

The solution in one sentence

Correlation means capturing a dynamic value from a server response, storing it in a variable, and using that variable in the later requests that need it, so every virtual user presents the value that the server gave to that user.

Why it matters for honest results

If correlation is missing, the server rejects or redirects the requests. The test then measures how quickly the server says no, which is usually very fast, so the report shows excellent response times for a system that never did any real work. Correct correlation is therefore not a convenience; it is what makes a load test measure the real application.

A handful of terms appear throughout this guide, and learning them now makes everything easier.

Two ideas are constantly confused, and mixing them up leads to the wrong fix.

A simple test to tell them apart

Ask whether you could have written the value into a spreadsheet before the test started. A username could be listed in advance, so it is a parameter. A token that the server creates at sign-in could never be listed in advance, so it needs correlation.

They work together

Most real journeys use both. The username and password come from a data file, and the session token that results from signing in is captured by an extractor. Parameterisation supplies what you decide; correlation carries what the server decides.

Knowing the usual suspects makes finding them much faster.

The mechanism is simple, and seeing the order of events explains most correlation bugs.

The order of events

A sampler sends its request and receives the response. Then, before the thread moves on, every post-processor in the sampler’s scope runs in order and looks at that response. An extractor finds its value and stores it under a variable name in the thread’s private variables. The next sampler is then built: JMeter replaces every reference with the current value of the variable, and sends the request carrying the fresh value.

The key consequence

An extractor can only supply values to samplers that run after it. A token captured in step four is useless to step two. Correlation is therefore always a matter of finding the first response in which a value appears and extracting it there.

sequenceDiagram
  participant V as Virtual User
  participant S1 as Sign-in Sampler
  participant X as Extractor
  participant Srv as Server
  participant S2 as Next Sampler
  V->>S1: Send sign-in request
  S1->>Srv: Request
  Srv-->>S1: Response with fresh token
  S1->>X: Hand over response
  X->>V: Store token in user's variable
  V->>S2: Build next request using the variable
  S2->>Srv: Request carries the fresh token
  Srv-->>S2: Accepted
        

JMeter offers several extractors, and each suits a different kind of response.

flowchart TD
  A[What is the response?] --> B{JSON?}
  B -- Yes --> C[JSON Extractor]
  A --> D{HTML page?}
  D -- Yes --> E[CSS Selector Extractor or Boundary Extractor]
  A --> F{XML?}
  F -- Yes --> G[XPath Extractor]
  A --> H{Header, address or plain text?}
  H -- Yes --> I[Boundary or Regular Expression Extractor]
  A --> J{Logic too complex?}
  J -- Yes --> K[Script post-processor]
        

It is the most flexible extractor and the most commonly misused, so each field deserves explanation.

The shape of a good pattern

A dependable pattern has three parts: a short, stable piece of text that always appears immediately before the value, a capture group that matches the value itself using the shortest possible match, and a short, stable piece of text that always follows the value. Everything else in the page is ignored. The goal is to anchor on text that identifies the value’s location without including anything that changes.

A pattern that works today and breaks next week wastes more time than no pattern at all.

Principles

Many correlation jobs need only two pieces of fixed text, and there is an extractor built for exactly that.

The idea

The Boundary Extractor asks for two things: the text that sits immediately to the left of the value and the text that sits immediately to the right. Whatever lies between them is captured. There is no pattern language to learn, no special characters to escape and no risk of an over-greedy match.

When it shines

It is ideal for simple, predictable markers: a value between two quotes after a known field name, a number after a label and before a comma, or a code between two known characters in a header. Because it avoids pattern syntax, it is also easier for colleagues to read and maintain.

Most modern interfaces answer in JSON, and a JSON-aware extractor is far safer than treating the response as plain text.

How JSON extraction works

JSON describes data as nested named fields and ordered lists. The JSON Extractor takes a path that starts at the root of the response and walks down through field names and list positions to the wanted value. Because it understands the structure, it is unaffected by spacing, line breaks or the order of unrelated fields, all of which break text patterns.

Useful options

The JMESPath alternative

A companion extractor uses a different query language that can filter, project and reshape JSON in a single expression. It is helpful for complicated structures, such as picking the identifier of the first item whose status equals a given word. For ordinary one-value extraction the plain JSON extractor is easier to read.

Web pages and XML documents have structure, and extractors that read structure are more dependable than text patterns.

The CSS Selector Extractor

A page is a tree of elements. The CSS Selector Extractor takes a selector that names an element, for example a hidden input with a particular name, and an attribute name whose value you want, usually the value attribute. It finds the element wherever it sits and returns the attribute. Reordered attributes, extra classes and changed spacing do not matter, because the extractor reads the page as a document.

The XPath Extractor

For XML responses, such as older web service replies, the XPath Extractor takes a path through the document tree and returns the text or attribute found there. It has options to treat imperfect page markup as a document and to handle namespaces, which are labels that qualify element names in XML.

Not every dynamic value lives in the body, and some live in a response that JMeter hides by default.

Values in response headers

Some systems return tokens, identifiers or the address of a newly created item in a response header. An extractor can be told to search the response headers instead of the body, so a header value can be captured just like a body value.

Redirects hide the middle step

When a server answers a request with a redirect, a browser silently follows it. By default, JMeter’s web request element can do the same. If the dynamic value is carried in the redirect itself, such as a one-time code in the address of the next page, the automatic following hides it, and the extractor only sees the final page.

The two redirect settings

A large share of session handling is automatic, and knowing this saves you from needless extractors.

The cookie manager does it for you

When a server sets a cookie, the HTTP Cookie Manager stores it and sends it back on later requests to the same site, exactly as a browser would. Many session identifiers travel this way, so a plan containing a cookie manager often needs no explicit correlation for the session itself. Without a cookie manager, the session is lost after the first request.

When explicit capture is still needed

Cookies cover only values the server sets as cookies. A token returned in a response body, a code placed in a hidden form field or a value in a header still needs an extractor. Some applications send the same session information in both a cookie and a field or header, and the extra copy must be correlated.

A repeatable routine turns correlation from guesswork into a calm, mechanical task.

flowchart TD
  A[Record or build the journey] --> B[Replay with one user]
  B --> C{Does it succeed?}
  C -- Yes --> H[Add assertions and run with several users]
  C -- No --> D[Find the first failing request]
  D --> E[Identify the dynamic value in it]
  E --> F[Find the earlier response that supplied it]
  F --> G[Add extractor and replace value with variable]
  G --> B
        

The fastest way to find every dynamic value is to let the differences between two recordings reveal them.

The idea

Record the same journey twice, using different test accounts and different input where possible. Static values, such as page paths and fixed parameter names, are identical in both recordings. Dynamic values, such as tokens and identifiers, differ. Comparing the two recordings with any file comparison tool therefore highlights exactly the values that need correlation.

What to compare

Separating genuine dynamics from your own input

Some differences come from the data you typed, such as different names or search words, and belong to parameterisation. Others come from the server and belong to correlation. If a value appears in a response before you typed anything, the server produced it. If it matches something you entered, it is your input.

A correlated value that is never checked is a hope, not a fix.

Extraction will sometimes fail, and the test must notice when it does.

Why failure is silent by nature

An extractor that finds nothing is not an error from JMeter’s point of view. The request that created the response may have succeeded perfectly. The failure surfaces later, when a request carries a missing or stale value and the server complains. By then, the cause is several steps behind.

Defaults as tripwires

Setting a distinctive default text, such as a phrase that says the token was not found, turns silent failure into a visible sign. The default shows up in the resolved request and in the server’s complaint, pointing straight at the extractor that failed.

Assertions that check the extraction

A response assertion can examine the stored variable and fail the sample if it still holds the default text. This makes the problem appear at the right place, in the right row of the report, and with a clear failure message. Pair it with a rule that stops a thread whose critical extraction failed, so it does not flood the results with consequent errors.

Many pages contain lists, and realistic users pick from them.

Capturing every match

When an extractor is told to keep all matches, it creates one variable per match, numbered from one, plus a variable that holds the count. A page listing twenty products yields twenty identifiers ready to use, along with the number twenty.

Looping over the list

A ForEach Controller walks through such numbered variables one by one. You give it the common name prefix, the start and end positions and an output variable name, and on each pass the output variable holds the next identifier. Requests inside the loop then refer to the output variable, for example to open each product in turn.

Picking one at random

Real users choose different items. You can ask the extractor for a random match, or capture all and choose a position with a random-number function. The second approach lets you control the range and reuse the same chosen item across several requests.

flowchart LR
  A[Page lists products] --> B[Extractor keeps all matches]
  B --> C[Numbered variables and a count]
  C --> D{Need all or one?}
  D -- All --> E[ForEach Controller loops over them]
  D -- One --> F[Random position picks one variable]
  E --> G[Requests use the current item]
  F --> G
        

Some values are not captured once; they change throughout the journey.

One value, many generations

Many applications issue a new anti-forgery token after every form submission, and some rotate the session identifier after login to prevent a certain class of attack. In these systems the value you captured on page two is already stale by page four. The test must capture again, from the response that replaced it, and overwrite the variable. Because an extractor writes to the same variable name each time it runs, this usually means placing an extractor after every request that issues a new generation.

Time-limited values

Access tokens in modern sign-in flows live for a limited time, often minutes. A long test with think time can easily outlive a token. Real browsers and apps handle this by using a refresh token to obtain a new access token shortly before expiry. A faithful test must do the same: record when the token was issued, check the age before each use, and call the refresh step when it is close to expiry.

Deciding whether the refresh belongs in the test

If your scenario is short, say two minutes, and the token lives for an hour, refreshing is pointless complexity. If your endurance test runs for hours, ignoring expiry will produce a wave of authorisation failures that has nothing to do with capacity. Match the test to what a real session of that length would do.

A value can be captured perfectly and still be rejected because of how it is written.

Why text gets disguised

Web pages and web addresses reserve certain characters for their own use. An angle bracket, an ampersand, a quotation mark or a plus sign can confuse the page or the address, so they are replaced with safe stand-ins. In a page, an ampersand may appear as a short entity code. In an address, a space or slash may appear as a percent sign followed by two digits. This is called escaping or encoding, and it is the most common reason a correct-looking token is refused.

Two directions, two problems

The remedies

For the first problem, the regular expression extractor can be asked to read the unescaped body of the response, which decodes entity codes before matching. For the second, JMeter offers a function that applies address encoding to a value at the moment it is used, and the parameter table in a sampler has an encode option per row. Choose one place to encode and stay consistent; encoding twice is as harmful as not encoding at all.

Where you put an extractor in the tree decides which responses it reads.

The attachment rule

A post-processor placed inside a sampler runs only for that sampler. Placed at the level of a controller, it runs after every sampler in that controller. Placed at the level of the thread group, it runs after every sampler in the whole group. This is the scoping rule of the test tree, and it is the source of two opposite surprises: an extractor that never fires because it is attached to the wrong request, and an extractor that fires too often and overwrites a good value with a failed one.

Choosing the tightest scope

The safest habit is to attach each extractor directly to the one sampler whose response holds the value. It documents itself, it cannot fire elsewhere, and a reader of the tree sees the cause and the capture together. Broad scope is useful only when many samplers return the same kind of value, such as a rotating token present in every page.

Which response does it read?

Besides scope, an extractor chooses which part of a response to search: the main body, the response headers, the request address, or the whole response text. Applying it to the wrong part is a quiet way to fail. A redirect address lives in headers, not in the body; a token in the address of a followed link is in the address, not in the body.

flowchart TD
  T[Thread Group] --> C[Controller]
  C --> S1[Sampler One]
  C --> S2[Sampler Two]
  S1 --> E1[Extractor on Sampler One only]
  C --> E2[Extractor on Controller: runs after each sampler inside]
  T --> E3[Extractor on Thread Group: runs after every sampler]
        

Controllers change how often and in what order requests run, which affects the values they leave behind.

Inside loops

When a request sits in a loop, its extractor runs on every pass and overwrites the variable each time. That is exactly what you want for a token that changes per page, and exactly what you do not want if you meant to keep the first value for later. If you need to preserve a value across passes, copy it into a second variable before the loop continues, using a small script or a variable-setting element.

Polling until something is ready

Some applications start a job and make you ask repeatedly whether it is finished. The reply carries a status, and the test needs to keep asking until the status says done. A While Controller, with its condition reading the extracted status variable, models this. Two cautions apply: put a short pause inside the loop so you do not hammer the server, and bound the loop with a counter so a stuck job cannot trap a user forever.

Conditional paths

An If Controller can use an extracted value to choose a path. If the response says an account needs verification, the test follows the verification steps; otherwise it skips them. This keeps one script realistic for users in different states.

Once Only and sign-in

The Once Only Controller runs its children on the first pass of each virtual user and not again. Placed around the sign-in sequence, it makes each user log in once and reuse the captured session for all later passes. Because variables are per user, the captured token remains available on later passes. Be careful when the token expires during a long loop; the earlier chapter on refresh applies.

Modern single sign-in journeys chain several correlated values across several redirects.

The shape of the journey

In an authorisation-code style flow, your application sends the user to an identity provider carrying a random state value and sometimes a one-time challenge value. The provider shows a login form with its own hidden fields, accepts the credentials, and redirects back to your application with a short-lived code and the same state value. Your application then exchanges the code for tokens behind the scenes. Every step passes a value that must be read from the previous reply and handed to the next request.

sequenceDiagram
  participant U as Virtual User
  participant A as Application
  participant I as Identity Provider
  U->>A: Open protected page
  A-->>U: Redirect with state value
  U->>I: Follow redirect
  I-->>U: Login form with hidden fields
  U->>I: Submit credentials and hidden fields
  I-->>U: Redirect with code and state
  U->>A: Return with code and state
  A-->>U: Session established
        

Handling it in a test

Turn off automatic redirect following on the samplers in the chain so you can read the address in each redirect reply, or leave it on and rely on recordings of every hop. Extract the state and code from the redirect address, extract hidden fields from the login form, and use each in the next request. Cookies from both the application and the provider live in the cookie manager, so make sure cookies are cleared per iteration when you intend each iteration to start unauthenticated.

Token-style replies

When the exchange step returns structured data containing an access token, the JSON extractor reads it directly. The token is then attached as an authorisation header on every later call, through a header manager that reads the variable. Because the header manager can sit at the thread-group level, one element covers all calls, while the extractor sits only on the exchange request.

The idea of reading one reply and using it in the next request is not limited to web protocols.

Database results

A database sampler can store the values from a query into variables named after result columns, or into a single object variable that holds the whole result set. A later request can use the identifier it returned, for example the number of an order that was just created. This is correlation without an extractor, because the sampler itself performs the capture when you name the result variables.

Message systems

Message-based samplers can read a message identifier or correlation identifier from a reply and use it to match a request with its response, or to pick up a specific message from a queue. The extractor family works here too, since the reply is just text with a structure.

Raw connection protocols

For plain socket traffic, a server may open a session by returning a handshake token that must be echoed on every later message. The regular expression extractor can read it from the response data, and later messages can contain the variable.

Reading responses is work, and at high load that work belongs to the machine running the test.

Where the time goes

Every extractor reads the response text after the sampler completes. A pattern with careless wildcards over a very large page can take noticeable processor time. Multiply that by thousands of virtual users and the load generator itself may become the bottleneck, which distorts timings and hides the real behaviour of the system under test.

How to keep extraction cheap

Watching the generator

Keep an eye on the processor and memory of the load generator during the run. If it is near its limits, the numbers you report are partly the generator’s, not the server’s. Spread the load over more generators instead of trusting a stressed one.

When a correlated script breaks, the symptoms point to the cause if you read them in order.

Start at the first wrong step

Failures cascade. A missed token on page two makes pages three through nine fail, and the later errors are noise. Walk forward from the beginning, find the first request whose response differs from what a human browser saw, and fix that one before looking further.

A calm routine

A script that works while you watch it must also work when nobody is watching.

Build in the window, run on the command line

Develop and debug correlation in the graphical tool, where result trees and debug elements are available. For measured runs, execute from the command line, which uses fewer resources and has no screen to update. Before trusting a command-line run, do a small smoke run with the same plan and check the result file for errors, since the debugging aids that caught problems earlier are now switched off.

Distributed generators

When several machines generate load, each runs its own copy of the plan and holds its own variables. Correlated values are per user and per machine, so nothing is shared by accident. However, files used for parameterisation must exist on every machine, and if each machine reads the same file from the top, different machines may use identical accounts. Split the data or configure the file reading so each machine reads a different portion.

Reading the results afterwards

Configure the result file to record failure messages and response codes. A correlation failure shows up as a cluster of unexpected response codes or assertion failures beginning at one point in each user’s journey. Without this information, you see only that errors occurred, not why.

Correlation handles credentials and session keys, so the test artefacts deserve the same care as the system.

What your files may contain

Captured tokens appear in debug output, in saved response bodies, in result files and in screenshots shared during troubleshooting. A session key from a test against a shared environment can be as powerful as a real user’s. Treat result files and logs from authenticated runs as sensitive, store them in access-controlled places, and delete them when no longer needed.

Test accounts

Use dedicated test accounts with limited rights, never staff or customer accounts. Rotate their passwords after large campaigns and keep the credentials out of the plan file by supplying them through data files or properties that are not committed to shared repositories.

Sharing scripts

Recorded scripts often embed real addresses, cookie values and tokens from the recording session. Scrub them before the plan is shared, and remove any hard-coded tokens that were replaced by correlation but remain in disabled elements or comments.

A few repeatable shapes keep correlated scripts understandable months later.

These habits look harmless and cause the most painful failures.

Correlation is necessary for realism, but it is not free.

When the trade-off tilts

For a stateless public page that serves identical content to everyone, correlation may be unnecessary. For anything with sign-in, forms, carts or tokens, it is mandatory. The skill lies in correlating what must be correlated and leaving the rest alone, because every extra extractor is another piece to maintain.

Run through these points before declaring any correlated script ready.

Four familiar situations show how the pieces combine.

Short answers to the points that most often trip up newcomers.

Do I always need correlation?

Only when the application issues values that must be echoed back and that differ between users or visits. Static sites often need none.

How do I know which values are dynamic?

Record the same journey twice, with different accounts if possible, and compare. Anything that differs, other than the data you typed, is a suspect.

What is the difference between correlation and parameterisation?

Parameterisation feeds your own varied data into requests. Correlation reads values the server generated and returns them to the server.

Which extractor should I start with?

Use the one that matches the shape of the reply: JSON for structured data, selector for page elements, boundary for simple text, pattern when the others cannot express the rule.

Why does my variable show the default value?

The extractor did not match. Compare the raw response in the viewer with your boundaries or pattern, check which part of the response is being searched and confirm that the extractor is attached to the correct request.

Why does a correct-looking token get rejected?

Common causes are encoding problems, an older generation of the token, an expired token, or a missing cookie that ties the token to the session.

Should I keep the first match or the last?

Choose according to the page. If the value you need is the first of its kind, use match one; if values repeat and the last is current, use the last or capture all and choose.

Can one extractor capture several things?

Yes. A pattern with several groups and a template can capture or combine multiple pieces, though separate extractors are usually easier to read.

Do cookies need correlation?

Generally no. The cookie manager stores and replays cookies automatically, provided it is present and its clearing behaviour matches the scenario.

How do I handle values that appear in headers?

Point the extractor at the response headers instead of the body, and read the address or token from the relevant header line.

What if the value is created by browser code rather than the server?

The test tool does not run page scripts, so you must reproduce the calculation with a function or script, or capture the inputs and compute the value yourself.

Why does it work for one user but fail for many?

Usually a value is hard-coded or shared among users, or the server rejects repeated use of one account. Search for typed-in identifiers and use distinct accounts.

How many extractors is too many?

There is no fixed number. Add one for each value that truly changes, and no more. If a script is full of extractors, check that each is justified by the two-recording comparison.

Is there a tool that does this automatically?

Some recording tools and plugins suggest candidates by comparing recordings. Treat suggestions as hints, and always confirm them by inspecting the responses yourself.

Correlation turns a brittle recording into a script that behaves like many real, distinct users.