A Pre-Processor is a small helper that runs just before a request is sent.

Apache JMeter is a free, open-source tool from the Apache Software Foundation. It pretends to be many users at the same time and measures how a system behaves under that crowd. A JMeter test is described by a test plan, which is a tree of small building blocks called elements. Some elements send requests, and these are called samplers. A Pre-Processor is an element that does some work immediately before a sampler runs.

The simple definition

A Pre-Processor prepares the ground for a sampler. It can set or change variables, modify the request that is about to be sent, fetch data from somewhere, or apply a limit. Whatever it does, it does it after the plan has decided that a sampler will run, and before the sampler actually sends anything.

What it is not

A Pre-Processor is not a sampler, so it does not send requests of its own and it does not appear as a row in the results. It is also not a Post-Processor, which does its work after the response comes back. And it is not a Config Element, which supplies defaults and data sources. The next chapters show how these neighbours differ, because confusing them is the most common beginner problem.

Real users are all different, and a test full of identical users proves very little.

Imagine a thousand customers visiting an online shop. Each one signs in with their own account, receives their own session, adds different items, and sends different addresses. If a test sends the same account name a thousand times, strange things happen. The shop may lock the account, return cached answers, or follow a shortcut that real traffic never takes. The result looks like a test, not like life.

Four reasons to prepare a request

What goes wrong without preparation

Without preparation the test may report excellent speed for the wrong reasons. Cached answers come back in a blink. Repeated sign-ins hit a shortcut. A request with an expired token returns a fast error. In each case the numbers look good while the test has quietly stopped measuring what users really do.

JMeter runs element types in a fixed order, and Pre-Processors come early.

When a sampler is about to run, JMeter does not simply go from top to bottom through the tree. It follows a fixed order by element type. According to the JMeter documentation, the order for each sampler is: Configuration Elements first, then Pre-Processors, then Timers, then the Sampler itself, then Post-Processors, then Assertions, and finally Listeners.

flowchart LR
    A["Config Elements"] --> B["Pre-Processors"]
    B --> C["Timers"]
    C --> D["Sampler sends the request"]
    D --> E["Post-Processors"]
    E --> F["Assertions"]
    F --> G["Listeners"]

Two important consequences

• Position in the tree does not change the type order. A Pre-Processor written below a sampler in the tree still runs before that sampler, as long as it is in scope.
• Nothing runs without a sampler. Pre-Processors, Timers, Post-Processors and Assertions are only processed when there is a sampler they apply to. An element with no sampler in its scope does nothing.

Position in the tree decides how many requests a Pre-Processor serves.

A test plan is a tree. At the top is the Test Plan, under it are thread groups, which are the crowds of virtual users, and below those sit controllers and samplers. You add a Pre-Processor by right-clicking an element and choosing Add, then Pre Processors. The element you right-click becomes its parent, and the parent decides its scope, the set of samplers it prepares.

flowchart TD
    TP["Test Plan"] --> TG["Thread Group"]
    TG --> P0["Pre-Processor at group level: runs before every sampler in the group"]
    TG --> S1["Sampler: Home Page"]
    TG --> C1["Controller: Checkout Steps"]
    C1 --> P1["Pre-Processor under the controller: runs before each sampler inside it"]
    C1 --> S2["Sampler: Add Address"]
    C1 --> S3["Sampler: Pay"]
    S3 --> P2["Pre-Processor under one sampler: runs only before Pay"]

Wide scope is convenient and costly

A Pre-Processor with a wide scope runs again and again, once before every sampler in its reach. If it does heavy work, such as a database query, that work repeats for every single request. Place each Pre-Processor as close as possible to the samplers that truly need it.

The Pre Processors menu holds several tools, each with a different job.

When you open the menu, you will see a short list of Pre-Processors. The exact list depends on your JMeter version, but the main members have been stable for many years. Here is a first overview before we study each one.

The simplest way to give each virtual user a personal set of values.

The User Parameters element holds a small table. Each row is a variable name, and each column after the name holds the values for one virtual user. When a thread runs, JMeter picks the column that matches that thread and sets the variables to those values. One user might get the name “alice” and another “bob”, from the same element.

How the table works

When it is a good choice

• You have a handful of users or values, so a small table is easy to read.
• The values do not need to change while the test runs.
• You want something simple that other team members can understand at a glance.

It reads names and values from an earlier extraction and creates matching variables.

Sometimes a reply contains a whole list of fields that the next request must send back, such as the hidden fields of a web form. Writing one extractor per field is tedious. The RegEx User Parameters element handles this pattern. It looks at the results of an earlier Regular Expression Extractor and turns pairs of captured text into variables.

The three settings that matter

An idea in plain words

Suppose a page contains many hidden fields, each with a name and a value. An extractor captures every pair. This Pre-Processor then creates one variable per pair, named after the field, holding the field’s value. The next request can send all of them without you writing a line for each.

When a site keeps your session inside the web address, this element adds it for you.

Most websites remember a visitor using a cookie, which is a small piece of data the browser sends back automatically. JMeter handles cookies through the HTTP Cookie Manager. A few older or special systems instead place a session identifier inside the web address itself. Each page link then ends with a long code that identifies the visitor. If the test does not copy that code into each new address, the server treats every request as a stranger.

What the modifier does

The HTTP URL Re-writing Modifier looks for the session identifier in the previous response, using a name you provide. It then appends that identifier to the addresses of the following requests. You tell it the name of the argument, and optionally whether the identifier is added as a path extension or as an ordinary parameter, and whether to remember it for later use.

Run a database statement just before a request and keep the answer in variables.

JDBC stands for Java Database Connectivity, the standard way for Java programs to talk to databases. The JDBC PreProcessor lets a test run a statement against a database right before a sampler, for example to read a fresh order number or to prepare test data. It works together with a JDBC Connection Configuration element, which holds the connection details and gives the connection pool a name.

Main settings in plain words

Use it with respect

• Point it at a test database, never at real customer data.
• Remember that it runs before every sampler in its scope, so keep the scope small.
• Prefer fetching a block of data once at the start, when the data does not change per request.
• Be aware that database work competes with the system under test if both share a server.

When nothing else fits, a short script can prepare anything.

JSR223 is a standard that lets Java programs run scripts in other languages. The JSR223 PreProcessor runs a short script before the sampler. The script can read and write variables, build values, compute signatures, pick random entries, or adjust the sampler. The JMeter documentation generally recommends JSR223 with the Groovy language for scripting, because it is fast when its compiled form is cached.

Main settings in plain words

• Language: which scripting language to use. Groovy is the usual choice.
• Parameters: optional text passed to the script, so one script can serve several elements.
• Script file: an optional file to run instead of text typed in the screen.
• Script: the script text itself.
• Cache compiled script: a check box that lets JMeter compile the script once and reuse it, which matters greatly for speed.

When a script is worth it

Three more members of the family, each with a narrow job.

BeanShell PreProcessor

BeanShell is an older scripting engine that came with JMeter for many years. The BeanShell PreProcessor runs a script before a sampler, much like the JSR223 version. The documentation advises that JSR223 elements are the better choice, mainly because they perform better and are better supported. You will meet BeanShell in older test plans, and it is fine to leave a working one alone, but new work should use JSR223.

Sample Timeout

The Sample Timeout element sets a time limit, in milliseconds, for the sampler it prepares. If the sampler runs longer than the limit, JMeter interrupts it. This is useful when a request might hang forever and you prefer to record a failure and move on. Not every kind of sampler can be interrupted cleanly, so check the behaviour with your own samplers.

HTML Link Parser

The HTML Link Parser reads the links, forms, and images found in the previous response and chooses one of them to fill in the next HTTP request. It is mostly used for simple “click around the site” spidering tests, where you do not know in advance which links exist. It is a blunt instrument, because a random click is not a realistic user journey, so many production tests prefer carefully scripted paths.

Almost every Pre-Processor works by putting a value somewhere that the sampler can read.

JMeter has two main places to keep named values. Variables belong to a single virtual user, which JMeter calls a thread. Properties belong to the whole JMeter program and are shared by every thread. A Pre-Processor usually writes variables, because the preparation is personal to one user’s next request.

How the sampler reads what was prepared

When a sampler runs, JMeter looks through its settings for variable references and replaces each one with the current value. This happens at the moment the sampler runs, which is why a Pre-Processor that sets a variable just before can influence what is sent. The earlier the value is set, the more samplers can use it, but variables set by one thread are never seen by another.

Config Elements set the stage once. Pre-Processors prepare each scene.

Config Elements supply defaults and data sources. Examples include HTTP Request Defaults, which gives every request the same server name, the CSV Data Set Config, which reads rows from a file, and the Counter, which counts upwards. They run before Pre-Processors in the order of execution, and they are often a simpler answer than a Pre-Processor.

A good rule of thumb

If the value comes from a file, a counter, or a random range, look for a Config Element first. If the value needs a decision, a calculation, a lookup, or a change to the request that is about to go, use a Pre-Processor. Using the simplest element that works keeps the plan lighter and easier to teach to new team members.

Three ways to do something before a request, each with a different meaning of “before”.

Beginners often reach for a Pre-Processor when another element would do better. Two close neighbours are the Timers and the Setup Thread Group.

Timers

A Timer adds a pause before its sampler runs. It does not change the request. Timers run after Pre-Processors, so the preparation is already finished by the time the pause begins. Use a Timer when the only thing you need before the request is to wait.

The Setup Thread Group

A Setup Thread Group is a special group that runs once, before the normal thread groups start. It is meant for one-time preparation, such as creating test accounts or clearing old data. A Pre-Processor, by contrast, runs again and again, before every sampler in its scope.

One prepares the request. The other studies the answer.

A Post-Processor runs after the sampler has received its response. It usually reads the response and captures values, such as a token or an identifier. The most famous Post-Processors are the extractors: the Regular Expression Extractor, the JSON Extractor, the CSS Selector Extractor, and the XPath Extractor. They capture values into variables.

A Pre-Processor and a Post-Processor often work as a pair. The Post-Processor of one step captures a value. The Pre-Processor of a later step may prepare it for use. Understanding this partnership clears up most of the confusion about the two types.

Many users run at once, so shared values need special care.

JMeter runs each virtual user in its own thread, a separate line of work inside the program. Many threads run at the same moment. A property of thread safety means a piece of code behaves correctly even when many threads run it at the same time. Variables set by a Pre-Processor are private to one thread, so they are naturally safe. Problems appear when threads share something.

Where sharing creates trouble

Simple habits that keep things safe

• Prefer variables over properties for per-user data.
• Use built-in elements, such as the Counter, which are designed with threads in mind.
• Give each user separate data where possible, so threads never fight for the same row.
• If a script must share something, keep that part tiny and protect it with the language’s standard tools for safe sharing.

Follow one request from the moment it is chosen to the moment it leaves.

When a virtual user reaches a sampler in its journey, JMeter assembles all the elements in scope, sorts them by type, and runs them in the fixed order we met earlier. The steps below show what happens around the Pre-Processors.

sequenceDiagram
    participant T as Virtual User Thread
    participant C as Config Elements
    participant P as Pre-Processors
    participant M as Timers
    participant S as Sampler
    participant V as Server
    T->>C: Apply defaults and data sources
    C-->>T: Variables and defaults ready
    T->>P: Run each Pre-Processor in scope
    P-->>T: Variables set, request adjusted
    T->>M: Apply timers
    M-->>T: Pause completed
    T->>S: Run the sampler
    S->>V: Send the prepared request
    V-->>S: Response

A thread repeats its journey many times, and preparation repeats with it.

A thread group tells each virtual user how many times to repeat its journey. Each repetition is called an iteration. In each iteration, each sampler runs again, and so do the Pre-Processors in its scope. The values they set therefore change with every loop, unless the element is told to update only once.

The life of a variable across a test

A stale value is a silent problem

Because a variable stays set until it is changed, a value from a previous iteration can accidentally be reused when the new preparation fails. The request then goes out with yesterday’s data, and nothing complains. Protect against this by clearing or resetting variables at the start of each iteration, where it matters, and by checking for the expected value in an assertion.

Correlation is the art of carrying a value from one response into the next request.

Modern web applications are full of values that change on every visit: session tokens, form tokens, order identifiers, and security codes. A test that replays a recorded request with an old value fails, because the server expects the fresh one. The technique of capturing the fresh value and sending it back is called correlation.

The usual partnership

A few questions lead you to the simplest tool that works.

flowchart TD
    A["I need something prepared before a request"] --> B{"Is it a data file or counter?"}
    B -- "Yes" --> C["Use a Config Element such as CSV Data Set Config"]
    B -- "No" --> D{"Do users need different fixed values from a small table?"}
    D -- "Yes" --> E["Use User Parameters"]
    D -- "No" --> F{"Does the site put the session in the address?"}
    F -- "Yes" --> G["Use HTTP URL Re-writing Modifier"]
    F -- "No" --> H{"Is the value stored in a database?"}
    H -- "Yes" --> I["Use JDBC PreProcessor, or fetch once in Setup Thread Group"]
    H -- "No" --> J{"Must I limit how long a request may run?"}
    J -- "Yes" --> K["Use Sample Timeout"]
    J -- "No" --> L["Use JSR223 PreProcessor with a short script"]

Why this order of questions

The questions move from the simplest tool to the most flexible. Config Elements need no code. User Parameters need only a table. Special-purpose elements do one thing well. A script is last because it can do anything, and anything is also hard to read, test, and maintain.

Common needs and the usual element that serves them.

Three kinds of fresh values appear in almost every real test.

Time stamps

A time stamp is a number or text that records a moment. Many systems expect a current time in each request, either to reject old requests or to sign them. A prepared time stamp should be created just before sending, because a stamp prepared too early may expire by the time the request arrives. Time zones and formats matter, so check what the server expects.

Random values

A random value is chosen by chance within a range. Random choices make a test less repetitive: a random product, a random quantity, a random search word. Two cautions apply. Real traffic is rarely perfectly random, because popular items are chosen far more often than rare ones. And purely random choices can make results hard to reproduce, so many teams use a fixed starting value for repeatable runs.

Unique identifiers

A unique identifier is a value that should never repeat, such as an order number or a new account name. Many systems reject duplicates. Counters and standard unique-identifier functions are the safest sources. Hand-made values from random numbers can collide when thousands of threads run together.

A quiet failure in preparation can produce loud, confusing errors later.

Preparation steps can fail. A script may hit an unexpected value. A database may be unreachable. A table may be missing a column. What JMeter does next depends on the element and on the kind of failure, but a general pattern is common: the problem is written to the log file, and the sampler may still run with whatever values happen to be available. Check the behaviour of your own version and elements, instead of assuming.

The chain of confusion

How to guard against it

• Add assertions that check for correct responses, so bad requests are marked as failures.
• Set a clear default for important variables, so a failed step produces an obvious value instead of a misleading blank.
• Read the log file after every run, and look for errors from the elements you added.
• In scripts, check for missing data and write a short log line that names the step.

You cannot see preparation directly, so you need windows into it.

A Pre-Processor does not appear in the results, so debugging means looking at what it did: which variables it set, what the request looked like when it left, and what the log says. JMeter offers several friendly tools for this.

A calm routine

Every preparation step uses the same machine that is generating your load.

The load generator has a limited amount of processor power. Time spent preparing a request is time not spent sending or receiving. For a few users this is invisible. When thousands of threads run, small costs multiply, and a slow Pre-Processor can reduce the load you can generate or distort the measurements.

Where the costs hide

Measuring the cost

The simplest check is to run the same test with and without the Pre-Processor, for the same number of users, and compare throughput and processor use on the generator. If throughput drops or processor use climbs sharply, the preparation is expensive. Run such comparisons in a quiet environment and repeat them, because single runs can mislead.

When one machine is not enough, preparation must work on many machines at once.

A single JMeter machine has limits. To generate more load, teams use distributed testing, in which a controller directs several other machines, called remote engines or workers. Each worker runs its own copy of the test plan. This has important consequences for preparation.

Things that change when you distribute

Habits that scale

• Split data files so each worker receives different rows.
• Give each worker its own numeric range for counters and unique identifiers.
• Pass settings to each worker through properties set when it starts.
• Keep preparation cheap so each worker can spend its power sending requests.
• Check each worker with a tiny run before the real test.

Preparation data that is too big for memory causes slow tests and strange failures.

Some tests need thousands or millions of distinct values: accounts, products, search words. A few ways of holding that data are cheap, and others are very expensive. The choice affects how much memory the load generator needs.

Habits that save memory

• Keep large lists in files and read them with the data file element.
• Avoid storing large values, such as whole responses, in variables unless needed.
• Release or overwrite large variables when they are no longer useful.
• Give the JMeter program enough memory, and watch it during the run.

Preparation leaves no rows in the results, so you must watch it another way.

Because Pre-Processors do not produce results, a healthy-looking report can hide preparation problems. The solution is to observe preparation through logs, through the requests that came out, and through the health of the load generator.

flowchart LR
    PP["Pre-Processors"] --> RQ["Prepared request"]
    PP --> LG["JMeter log file: warnings and errors"]
    RQ --> SV["System under test"]
    SV --> RS["Results file"]
    RS --> RP["Report: errors, percentiles, throughput"]
    GH["Generator health: CPU, memory, network"] --> DB["Dashboard"]
    LG --> DB
    RP --> DB

What to watch

• The log file: errors from scripts, database calls, and missing variables.
• The error rate: sudden jumps often mean prepared values went bad.
• Request details for a sample: a few recorded requests, to confirm the values look right.
• Generator health: processor, memory, and network, to see whether preparation is costly.
• Database load: if a database Pre-Processor is used, check its effect on the database.

Preparation often touches credentials, databases, and scripts, so it deserves extra care.

Pre-Processors handle some of the most sensitive material in a test: user names, passwords, tokens, connection details, and scripts that can do almost anything. A test plan can be shared, stored, and copied, so secrets inside it travel with it.

Specific risks

• Scripts run with the power of the JMeter program. A plan from an unknown source may contain scripts that read files or call other systems, so review before you run it.
• Database Pre-Processors can change real data if pointed at the wrong server, so double-check connection details.
• Tokens and passwords in plans can leak through shared files, screenshots, and version control history.
• Load can look like an attack. Always notify the owners of the system and test only what you are allowed to test.

Preparation makes tests realistic, and it costs effort and complexity.

Good habits repeat across good test plans.

A pattern called “Prepare, Send, Capture, Check”

Some habits look clever and cause trouble later.

A plan that is easy to read stays correct for longer.

Test plans live for years. People join and leave the team, the application changes, and the plan is edited many times. Preparation elements are scattered through the tree and invisible in the results, so they are easy to forget. A little organisation prevents big confusion later.

Habits that help

• Name every element for its purpose. Avoid default names such as “JSR223 PreProcessor”, which tell the reader nothing.
• Add comments. Every element has a comments field. Use it for the reason the element exists and the version of the system it was written for.
• Group related steps under controllers. Putting the preparation near its samplers makes the story of each step easy to follow.
• Keep scripts in files for reuse. A shared script file avoids copies that drift apart over time.
• Store plans in version control. A history of changes explains why a plan is the way it is.
• Review old plans regularly. Remove elements that no longer serve a purpose.

Preparation is invisible, so you must test it on purpose.

A Pre-Processor that silently does nothing looks exactly like one that works. The only way to know is to check the evidence: the request that was sent, the values that were set, and the responses that came back. A short routine gives you that confidence before you scale up.

Most problems come from a small set of causes. Match your symptom with the table.

A method for any puzzle

Follow an imaginary online shop test from sign-in to order.

A team wants to test a shop where many different customers sign in, add an item, and place an order. Each customer needs a distinct account, and each order needs a unique reference. The shop returns a token after sign-in that every later request must carry.

flowchart TD
    D["Data file: one account per user"] --> L["Sampler: Sign In"]
    L --> X["Post-Processor: capture token"]
    X --> P1["Pre-Processor: build unique order reference"]
    P1 --> O["Sampler: Place Order with token and reference"]
    O --> A["Assertion: order confirmation text present"]
    A --> R["Results and report"]
    P1 --> LG["Log shows any preparation errors"]

What makes this plan healthy

• The Pre-Processor has a narrow scope, attached only to the order step.
• It has one job, and a name that says what it does.
• Its result is verified by an assertion on the response.
• Values come from proven sources: a data file for accounts and a counter for uniqueness.

Six ideas that beginners often get wrong.

A habit that corrects all six

Before you rely on a preparation step, ask three questions. What exactly will it set, and for whom? When will it run, and how often? How will I see that it worked? Honest answers to those three questions expose most misunderstandings before they cost you a run.

A short checklist to carry into your next test.

Common mistakes in one list

• Using a heavy Pre-Processor with a wide scope, so it runs far too often
• Writing long scripts that only one person understands
• Holding per-user data in shared properties
• Forgetting that Config Elements run before Pre-Processors
• Never checking that preparation succeeded
• Leaving old BeanShell scripts in busy parts of the plan without review
• Splitting data badly across distributed workers, so users collide
• Hard-coding passwords and tokens in shared plans
• Leaving debug elements enabled during a real run

Five typical situations, described in general terms so you can adapt them.

A one-page summary you can keep next to your test plan.

Five questions before pressing start

• Does every virtual user get the values it needs, and are they different where they should be?
• Is each Pre-Processor attached to the smallest scope that works?
• Have I seen the sent request and confirmed the prepared values arrived?
• Will a failed preparation show up as a failure, through assertions or the log?
• Are secrets protected, and are debug elements switched off?

Quick answers to the questions beginners ask most often.

Pre-Processors are the dressing room of JMeter requests. They run just before a sampler, after Config Elements and before Timers, and they turn identical robot requests into realistic traffic by giving each virtual user its own values, tokens, and limits. Used well, they are small, narrow, named, and verified. Used badly, they hide failures, waste processor time, and confuse the next reader. If you remember one idea, let it be this: prepare only what realism requires, as close to the request as possible, and always check that the preparation really worked.