The elements that prepare the ground before requests are sent.

The simple definition

A Config Element is a JMeter test element that supplies settings, data or shared behaviour to the samplers that sit within its scope. It does not send a request by itself, and it does not produce a result of its own. Instead, it works quietly in the background: it fills in default values, adds headers, stores cookies, reads test data from a file, creates counters, or opens a connection pool. The samplers then use what the Config Element prepared.

The word “general” in the title of this guide points to the ideas shared by all Config Elements: where they live in the test plan, when they run, how their effect spreads down the tree, and how several of them combine. Once you understand these general rules, every specific element becomes easy to learn.

What Config Elements do for you

They reduce repetition, because shared values live in one place. They make the test plan easier to maintain, because a change in one place updates every request. They make the test more realistic, because they can simulate browser behaviour such as cookies and caching. They feed the test with data, such as different user names for each virtual user. And they make test plans portable between environments, because the server address can be changed in one element instead of fifty samplers.

Knowing the neighbours helps you pick the right tool for each job.

A JMeter test plan is built from several families of elements, and each family has a clear role. Beginners often use the wrong family for a task, such as using a script to add a header that a Config Element could add without any code. The table below shows the roles side by side.

The key difference from processors

Config Elements prepare conditions that are true for many samplers, while processors act on one particular sampler’s run. A Config Element is like a rule on the wall of a room, while a processor is like a person who acts when a certain event happens. Config Elements are usually set once and left alone, while processors usually react to the specific response in front of them.

Timing decides what a sampler can see, so the order must be clear.

JMeter processes elements in a fixed order for every sampler run. Config Elements come first, before pre-processors, timers, the sampler itself, post-processors, assertions and listeners. This is logical: the sampler can only use settings that have already been prepared.

flowchart TD
    A["Config Elements apply settings and data"] --> B["Pre-Processors modify the request"]
    B --> C["Timers add pauses"]
    C --> D["Sampler sends the request"]
    D --> E["Post-Processors read the response"]
    E --> F["Assertions check the result"]
    F --> G["Listeners show and save the result"]
        

The special case of User Defined Variables

There is one important exception. The Config Element called User Defined Variables is processed once, at the very start of the test, in the order it appears in the test plan, and it does not matter where it is placed. So a variable defined there is available everywhere from the beginning, but it cannot refer to a variable defined further down, because that one has not been processed yet. This behaviour surprises many people, and it explains many “variable not found” problems.

A Config Element affects only the part of the test plan tree where it sits.

The test plan is a tree. A Config Element influences the samplers that are its siblings and the samplers inside its sibling controllers. Samplers outside that part of the tree do not see it. This simple rule is called scope, and it is the most important general idea about Config Elements.

flowchart TD
    TP["Test Plan"] --> TG["Thread Group: Shoppers"]
    TG --> CE1["Config: HTTP Request Defaults"]
    TG --> CE2["Config: HTTP Header Manager"]
    TG --> S1["Sampler: Open home page"]
    TG --> TC["Transaction: Checkout"]
    TC --> CE3["Config: extra header for payment"]
    TC --> S2["Sampler: Submit payment"]
    TG --> TG2["Thread Group: Admins"]
    TG2 --> S3["Sampler: Open admin page"]
        

The nearest one wins

When several Config Elements of the same kind are in scope for a sampler, JMeter combines them. For values that clash, the one closest to the sampler generally takes priority over the one placed higher in the tree. Values typed directly inside a sampler win over defaults. This lets you set broad rules high in the tree and exceptions deep in the tree, just as a company has general policies and a department may have a special rule.

A map of the elements you will meet most often.

JMeter ships with many Config Elements, and the plugin collection adds more. The table below lists the ones most teams use, grouped by purpose. The following chapters explain the important ones in depth.

The place for constants, and the difference between a variable and a property.

What User Defined Variables hold

The User Defined Variables element is a simple table of names and values. Once defined, a value can be used anywhere in the test plan by writing its name inside the variable placeholder syntax. Typical contents are the server name, the base path, the protocol, a standard wait time, a product category used by many requests, or an environment label. Changing one row changes every place that uses it.

Variables versus properties

JMeter has two kinds of named values, and confusing them causes many problems. A variable belongs to a thread. Each virtual user has its own set of variables, and extractors and data files fill them while the test runs. A property belongs to the whole JMeter process. It is shared by all threads and can be set from the command line when you start the test, which makes properties ideal for values that change between runs, such as the number of threads, the duration or the target environment.

Combining both: a flexible pattern

A powerful pattern is to put a property function inside a User Defined Variables row, with a default value. The variable then uses the value passed on the command line if there is one, and falls back to the default otherwise. This lets the same test plan run on a laptop with small numbers and in the pipeline with large numbers, without any edits to the plan file. It also keeps secrets and environment details out of the plan itself.

Set the server once and let every web request inherit it.

The HTTP Request Defaults element provides default values for HTTP samplers in its scope. Any field that you leave empty in a sampler is filled from the defaults. A sampler that has its own value keeps it. This is the simplest and most useful way to remove repetition from a web test plan.

Benefits in daily work

With defaults in place, moving a test from one environment to another means editing one element, or better still, one variable that the element reads. Timeouts are applied consistently, so that no request waits forever. Embedded resource rules are applied in one place, so that all pages behave the same way. And the sampler list becomes short and readable, with only the path and the parameters that make each request different.

Several hosts in one plan

Some applications call more than one host, such as the main site, an image service and a payment service. Use one defaults element for the main host at the thread group level, and override the server in the samplers that call other hosts. Alternatively, place the samplers for each host under separate controllers, each with its own defaults element. The nearest element wins, so each branch uses its own host.

flowchart LR
    D["HTTP Request Defaults: server, port, timeouts"] --> S1["Sampler with empty server field: uses defaults"]
    D --> S2["Sampler with empty server field: uses defaults"]
    O["Sampler with its own server value"] --> R["Keeps its own value, ignores the default"]
        

Headers tell the server how to treat each request, and they are easy to get wrong.

The HTTP Header Manager holds a table of header names and values. Every HTTP request in its scope is sent with these headers. Headers describe the kind of content being sent, the kinds of content the client accepts, the client’s identity, and credentials such as access tokens.

How several managers combine

You may place more than one Header Manager in a test plan, for example a general one at the thread group level and a special one for a single step. JMeter merges the headers from all managers in scope. If the same header name appears in two of them, the one nearer the sampler wins. This allows a common set at the top and small overrides below, which keeps the plan short and the exceptions easy to spot.

Headers with dynamic values

Header values can use variables. A typical case is an authorisation header whose value contains an access token captured from a login response. The extractor stores the token in a thread variable, and the header manager places it into every following request. Because variables belong to threads, each virtual user sends its own token, exactly as real users would.

Cookies keep sessions alive, and every virtual user needs its own jar.

Web applications use cookies to remember who you are between requests. After you log in, the server sends a session cookie, and your browser sends it back with every later request. Without cookie handling, JMeter would look like a stranger on every request, and any page that needs a login would fail. The HTTP Cookie Manager stores cookies received from the server and sends them back, just as a browser does.

One jar for each virtual user

The cookies stored by the manager belong to each thread separately. This is exactly what you want: every virtual user has its own login session and its own cookie jar. It also means that one thread’s session never leaks into another’s, which keeps users independent.

Why “clear cookies each iteration” matters

This single option changes the meaning of your test. If your scenario starts with a login and you leave cookies from the previous loop in place, the second loop may skip a real login on the server side, giving unrealistic speed. If you clear them, each loop makes a full login, which is closer to many different users arriving. Decide which behaviour matches your business question, and write it in the test notes.

Real browsers do not download everything every time, and your test should not either, unless you want it to.

Real browsers keep a copy of static files such as images, scripts and style sheets, and reuse them on later visits. A JMeter thread without a cache downloads every file every time. This can make your test far heavier than reality: more bytes, more requests and more load on content delivery. The HTTP Cache Manager adds browser-like caching to each virtual user.

How it works

The manager remembers resources a thread has already downloaded, together with their freshness information. On the next request for the same resource, it can skip the download if the resource is still fresh, or send a conditional request asking the server whether it changed. Resources served from the simulated cache cost almost no time, and they are marked in the results in a special way. The cache is kept for each thread separately.

Choosing between first-visit and repeat-visit tests

The right setting depends on your audience. A news site with many returning readers should test mostly with caching on. A flash sale where most visitors arrive for the first time should test with caching off, or with the cache cleared every loop. Many teams run both and compare them: the first-visit run shows the worst case for the network and the content layer, and the repeat-visit run shows the typical case.

Giving virtual users the credentials and certificates they need.

How the Authorization Manager chooses what to send

The manager compares the address of each request with the base addresses in its table. If the request matches, the credentials in that row are used. This means you can set different credentials for different parts of an application, and requests to unrelated addresses are left alone. The credentials in this table are shared by all threads, so it suits cases where all virtual users may use the same service account, or where each thread should receive credentials through a variable.

Client certificates

Some corporate and financial services demand that clients present a certificate. The Keystore Configuration element loads the certificate store and chooses which certificate entries to use. It can also expose the chosen entry through a variable, which helps when different virtual users must use different certificates. Because certificate loading and secure handshakes are CPU-heavy, a test with many certificates and many threads can load the generator much more than a test without them, so size the machines accordingly.

The most important data element, and the one with the most settings to get right.

If every virtual user logs in with the same account and searches for the same word, your test is unrealistic. Caches answer instantly, accounts get locked, and databases see the same row again and again. The CSV Data Set Config reads rows from a text file and places the values of each row into variables. Each time a thread starts a loop, it receives the next row.

Sharing modes explained

flowchart TD
    F["Data file with rows"] --> M{"Sharing mode"}
    M -->|"All threads"| A["One shared pointer: each thread takes the next unused row"]
    M -->|"Current thread"| B["Each thread reads the whole file separately"]
    A --> E{"End of file reached?"}
    E -->|"Recycle on"| R["Start again from the first row"]
    E -->|"Stop thread on"| S["Thread ends"]
    E -->|"Both off"| X["Threads receive empty or repeated values and tests fail"]
        

Planning the amount of data

Before running, calculate the number of rows you need. With the shared mode, the rows used equal the number of threads multiplied by the number of loops each thread runs. A file of 500 rows is enough for 500 threads doing one loop, but not for 500 threads running for an hour with a loop every two minutes, which needs around 15,000 rows. Include a margin, and decide in advance what should happen at the end of the file.

When you need numbers that grow or vary, without preparing a data file.

The Counter

The Counter element produces a number that increases each time it is used. You set the start value, the step, an optional maximum, and a format, such as adding leading zeros. The number is stored in a variable that other elements can read. It is very useful for unique values: order references, email addresses, file names or search terms that must not repeat.

The Random Variable

The Random Variable element generates a random number between a minimum and a maximum and stores it in a variable. It is useful for picking a random product number, a random page number or a random delay. You can choose a format and a seed. Using the same seed produces the same series of random numbers on each run, which makes tests repeatable. Choosing whether the random series is shared by all threads or separate for each user changes how varied the traffic looks.

A shared pool of database connections that samplers borrow by name.

To test a database directly, JMeter needs connections. The JDBC Connection Configuration element creates a named pool of database connections. A database sampler then refers to the pool by its name. All threads share the pool, so its size matters a great deal.

The pool size decides what you measure

If the pool is smaller than the number of threads, many threads must wait for a free connection. That waiting time happens in JMeter, but depending on how the sampler measures, it may be included in the response time you report. The database then looks slower than it is. If the pool is much larger than a real application would use, you may overload the database with a number of connections that production would never open. The sensible choice is to mirror the connection limit of the real application, or to deliberately test beyond it when exploring capacity.

flowchart LR
    T1["Thread 1"] --> P["JDBC pool: limited number of connections"]
    T2["Thread 2"] --> P
    T3["Thread 3"] --> P
    T4["Thread N"] --> P
    P --> D["Database"]
        

The quieter members of the family, each useful in the right situation.

DNS Cache Manager

Before JMeter can connect to a host name, the name must be turned into a network address. By default the Java runtime caches the answer for a while, so every thread keeps using one address. This can send all your load to a single machine behind a name that has many addresses. The DNS Cache Manager lets you control this: clear the cache each iteration, use the system resolver or a custom one, and even define your own host entries that map names to chosen addresses. This is valuable when testing a load-balanced site where you want to spread requests, or test one specific server, or point a production name at a test environment.

Protocol-specific defaults

The idea behind HTTP Request Defaults repeats for other protocols. There are defaults elements for FTP requests, LDAP directory requests, raw TCP samplers and Java-based request samplers. Each one holds the settings that the matching samplers share, such as the server, the port, timeouts and common options. The same rules of scope and nearest-wins apply.

Simple Config Element

The Simple Config Element is a flexible holder for name and value pairs. By itself it does nothing. Other elements, especially those from plugins, read from it to find their settings. If a plugin’s documentation asks you to add a simple config element with certain names, this is the element it means.

Plugin Config Elements

The plugin collection adds more data elements. A popular one reads rows from a file in random order or lets rows be used only once. Others read from remote data stores. These are useful when the standard CSV element is not enough, but they bring extra software to every machine, so record plugin versions and install them identically on all generators.

Every realistic setting has a price in memory, processor time and planning.

Config Elements make a test more realistic, but realism is never free. When hundreds of threads each hold their own cookie jar, their own cache and their own variables, the memory of the load generator is the first to feel it. Understanding where the costs sit helps you size your machines and plan your data.

Plan your data from the thread count

Data needs grow with threads and time. Use a simple method: rows needed equal the number of threads multiplied by the number of loops each thread will complete. For time-based tests, loops equal the test duration divided by the cycle time of one loop. Then add a margin of twenty percent or more. Prepare the data before the test day, check that every account can log in, and check that none is locked or expired.

What changes when one plan runs on many machines.

In a distributed test, the controller sends the plan to each worker, and every worker runs it independently. Config Elements are part of the plan, so each worker runs its own copy of each element. This has several important consequences.

flowchart TD
    C["Controller: sends the plan to each worker"] --> W1["Worker 1: own copy of every Config Element"]
    C --> W2["Worker 2: own copy of every Config Element"]
    C --> W3["Worker 3: own copy of every Config Element"]
    W1 --> A["Own data pointer, own counter, own pool"]
    W2 --> B["Own data pointer, own counter, own pool"]
    W3 --> D["Own data pointer, own counter, own pool"]
        

Habits that keep large test plans tidy, safe and easy to change.

Pattern 1: layer your configuration

Arrange Config Elements in layers, like the rules of a company. At the top, at test plan level, place constants and settings that apply everywhere. At the thread group level, place the defaults, headers, cookies and data of that type of user. Inside controllers, place small exceptions for one business step. At the sampler level, type only what is unique to that request. A reader who opens the plan can then find any setting by asking “which layer owns this?”.

flowchart TD
    L1["Layer 1: Test Plan constants and run settings"] --> L2["Layer 2: Thread Group defaults, headers, cookies and data"]
    L2 --> L3["Layer 3: Controller level exceptions"]
    L3 --> L4["Layer 4: Sampler specific values"]
        

Pattern 2: make the plan environment-neutral

Never hard-code a server name, a user count or a duration into a sampler. Keep them in User Defined Variables that read properties with safe defaults. One plan can then serve a laptop check, a nightly run and a full rehearsal, simply by passing different properties at start time.

Pattern 3: one purpose per element

Give each Config Element a clear name that states its purpose, such as “Shopper headers” or “Test accounts data”. Avoid one large element that tries to do everything. Clear names turn the tree into documentation.

Pattern 4: keep secrets outside the plan

Read passwords and keys from files or properties that are kept in protected storage, rather than typing them into elements. Then the plan can be shared and stored in version control without exposing secrets.

Pattern 5: separate user types

When user types behave differently, use separate thread groups, each with its own cookie manager, header manager and data element. This keeps their sessions, headers and data apart, and each group can be scaled on its own.

Configuration is where secrets like to hide.

Config Elements often contain the most sensitive details of a test: server addresses, user names, passwords, tokens, certificates and database credentials. A test plan file is therefore a sensitive document. It is often emailed, stored in shared folders and committed to code repositories, and each of these steps can expose its secrets.

Protective habits

How to see what a Config Element is really doing.

Config Elements work silently, which makes them hard to debug. A header is missing, a cookie is not sent, a variable is empty, or a request goes to the wrong server, and nothing in the plan screams. The way to debug is to look at the evidence: what the sampler really sent and what values the thread really held.

Mistakes that quietly distort tests, and the habits that prevent them.

A checklist you can follow, and four stories where Config Elements made the difference.

Best-practice checklist

Real-world stories

A real browser does many small things automatically. Config Elements let you copy the ones that matter.

When a person opens a web page, the browser quietly performs a long list of tasks. It resolves the host name, opens connections, sends headers, stores and returns cookies, reuses cached files, downloads images and scripts in parallel, and asks for compressed content. A JMeter thread does none of this unless you tell it to. The more of these behaviours you copy, the closer your virtual user is to a real one, and the more your load matches reality.

The faithful-user starter kit

For a typical web application used through a browser, a strong starter kit placed at the thread group level contains five items. First, a defaults element with the server, the protocol, the timeouts and the embedded resource rules. Second, a header manager with the main headers copied from a real browser. Third, a cookie manager with a deliberate choice about clearing each loop. Fourth, a cache manager that matches the share of returning visitors. Fifth, a data element that gives each user unique credentials and search terms.

flowchart TD
    V["Virtual user thread"] --> D["Defaults: server, timeouts, resources"]
    V --> H["Headers: browser identity and formats"]
    V --> C["Cookies: own session"]
    V --> K["Cache: own saved files"]
    V --> F["Data: own account and search terms"]
    D --> R["Request that looks like a real browser request"]
    H --> R
    C --> R
    K --> R
    F --> R
        

Connection reuse

Browsers keep connections open and reuse them for many requests, which saves the cost of opening and securing a new connection each time. JMeter does the same by default for each thread when the server allows it, and the request defaults let you control this behaviour. If a test accidentally opens a new connection for every request, the cost of connection set-up, especially the secure handshake, appears in every response time and also loads the generator’s processor. When connect times in your results are unexpectedly high, check connection reuse before blaming the network.

When not to imitate the browser

Not every test needs a browser. If you test a back-end service called by other programs, copying browser cache and cookie behaviour may be wrong. Real service clients behave differently: they may keep no cookies at all, send tokens in headers, and never download images. Imitate the client that really calls the system, not the one that is easiest to imagine.

Different targets need different starter kits.

Because each type of system is used in a different way, each deserves its own selection of Config Elements. The table below gives a starting point, and the following sections explain the reasoning.

Web services

A service called by other programs usually needs fewer browser behaviours and more precise headers. The content type header is essential. An authorisation header, filled from a variable that holds a token captured at login, is typical. Data comes from a file or from counters and random values. Cookies often are not used at all, and a cache is irrelevant. This leaner kit also costs less memory per thread, allowing more threads on one generator.

Databases

For database tests, the central element is the connection pool, and the key design decision is its size relative to the thread count and to the application’s real limit. The data element supplies keys, such as customer numbers, that are real and spread across the table, so that the database cannot answer everything from memory. A random variable can pick from a range when the keys have no gaps.

Mixed journeys

Many real journeys combine styles: a user opens pages in a browser, and the pages call services behind the scenes. In such a plan, use separate thread groups or controllers, each with its own kit. The page steps use the browser kit, and the background service calls use the service kit with their own headers and defaults. This keeps the cookie and header settings of one style from disturbing the other.

A test plan is a living asset. Keep its configuration healthy before every run and across releases.

Pilots never take off without a checklist, however many times they have flown. Performance testers benefit from the same discipline. Most failed test runs are caused not by the application, but by a forgotten setting: a data file not copied, a property not passed, a plugin missing on one machine. A short checklist before each run removes most of these surprises.

The pre-flight checklist

A smoke run before the real run

Always run a short smoke test with a few threads, one or two loops, and the same configuration as the real run. Read a handful of real requests and responses in detail. This takes minutes and catches most configuration errors while they are cheap to fix. Only after the smoke run looks right should you scale up to the full load.

Maintaining the plan over time

Applications change, and test plans must change with them. A new header becomes mandatory, a login flow adds a step, a host name moves, or a data field changes format. Because Config Elements hold shared settings in one place, most of these changes need only a small edit. To keep it that way, review the plan after each major release, remove elements that no longer apply, and keep the layered structure tidy.

Start from what you see and work towards the cause.

A calm way to investigate

Quick answers to questions that come up in almost every project.

It is an element that prepares settings, data or shared behaviour for the samplers in its scope. It does not send requests or create results itself. Examples are HTTP Request Defaults, header and cookie managers, and the CSV Data Set Config.

Before every sampler in their scope, ahead of pre-processors, timers, the sampler, post-processors, assertions and listeners. The exception is User Defined Variables, which are processed once at the start of the test in the order they appear.

At the level of the tree where its effect should begin. Place broad settings at the test plan or thread group level, and exceptions inside controllers or beside single samplers. The element affects the samplers at and below its place in the tree.

JMeter combines them. When values clash, the element nearer the sampler generally wins, and values typed in the sampler itself win over any default.

A variable belongs to one thread and can differ per user. A property belongs to the whole JMeter process, is shared by all threads and can be set from the command line. Use properties for run settings and variables for user data.

One per thread group, placed at the group level. Several in one group can cause unpredictable session behaviour.

Use the all-threads mode when every thread should take a unique row, the thread group mode for separate user types, and the current thread mode when every user must read the whole file in order.

Probably because a sampler still has its own server value, which wins over the defaults. Clear the field in the sampler and confirm in the request details.

Use it when your real users have caches and your pages download many static files. Turn it off or clear it each loop for first-visit and worst-case tests. Keep the setting identical between tests that you want to compare.

Each worker has its own copy of every element and its own state. Data files must exist on each worker, counters and data pointers are independent, pools multiply, and properties must be passed to each machine.

It is risky, because the plan file holds them. Use synthetic test accounts, pass secrets at run time where you can, protect plan files and rotate test credentials.

Run with one thread and read the request details in the results tree. Use a debug sampler to list current variables, check scope and nearness, and read the JMeter log file for messages about the element.

Config Elements are the preparation layer of a JMeter test plan. They supply defaults, headers, cookies, caches, credentials, data and connections to the samplers in their scope, and they do this before every sampler runs. Their power comes from three general ideas: scope decides which samplers they affect, the nearest element wins when settings clash, and User Defined Variables are the special case processed once at the start. Used well, they make plans short, realistic, portable and safe. Used carelessly, they produce silent mistakes such as wrong servers, shared accounts, lost sessions and leaked secrets.