A Test Plan is the container that holds everything JMeter needs to run one complete performance test.

Apache JMeter is a free, open-source program written in Java. It began in the late 1990s as a tool to test the performance of Apache web software, and over the years it grew to test many other things: websites, web services, databases, message queues, mail servers, and more. It is maintained by the Apache Software Foundation, which is why the word Apache is in the name. Because it is written in Java, it runs on Windows, macOS, and Linux as long as a Java runtime is installed.

A Test Plan is the top-level element in JMeter. When you open JMeter, you see an empty Test Plan in a tree on the left side of the screen. Everything you build is hung from that tree like branches. When you save your work, JMeter writes the whole tree into a single file with the extension .jmx. That file is plain text in a format called XML, which means it can be stored in Git, reviewed by teammates, and compared between versions like any other project file.

What a Test Plan answers

A well-built Test Plan answers five plain questions. Who are the users, and how many of them are there? What do they do, step by step? How fast and how often do they do it? How do we decide whether a response was correct? And what do we record so we can study the outcome later? Each question maps to one family of JMeter elements, and the rest of this guide walks through those families one by one.

Before building anything, it helps to know what kind of test you are trying to run and why.

Performance testing means checking how a system behaves under work. The system might be fast with one user and painfully slow with one thousand. It might work all day and then run out of memory at night. These problems do not show up when a developer clicks around on their own laptop. They only appear under crowd conditions, and a Test Plan is how you create those conditions on purpose and safely.

There are several kinds of performance test, and each one asks a different question. The kind you choose changes how you configure the Test Plan, especially the number of users and the length of the run.

What goes wrong without a plan

Teams that skip careful planning tend to make the same mistakes. They test with too few users and declare victory. They test only one easy page and miss the slow checkout. They forget that real people pause to read, so their test hammers the server far harder than reality. Or they run the test from a weak laptop and blame the server for slowness that was really the laptop. A Test Plan forces you to decide these things deliberately instead of by accident.

A famous real-world lesson is the launch of the United States federal health insurance website in 2013. It was widely reported to have struggled badly when real users arrived, and later reviews pointed to inadequate end-to-end testing under realistic load. The lesson applies to every project: the crowd always arrives, so it is cheaper to rehearse it first.

A Test Plan is a tree. Where an element sits in the tree decides what it affects.

Every JMeter element is placed somewhere in the tree. Some elements sit at the very top and apply to everything. Others sit inside a Thread Group and apply only to that group. Others sit directly under a single request and apply only to it. This idea is called scope, and it is the single most important rule for understanding why a JMeter test behaves the way it does.

graph TD
  TP["Test Plan"]
  TP --> UDV["User Defined Variables"]
  TP --> TG["Thread Group - the virtual users"]
  TG --> CM["HTTP Cookie Manager"]
  TG --> HD["HTTP Request Defaults"]
  TG --> CSV["CSV Data Set Config - test data"]
  TG --> TC["Transaction Controller - Login"]
  TC --> S1["HTTP Request - Open Login Page"]
  TC --> S2["HTTP Request - Submit Credentials"]
  S2 --> EX["JSON Extractor - save token"]
  S2 --> AS["Response Assertion - check success"]
  TG --> TM["Constant Timer - think time"]
  TG --> LS["Summary Report Listener"]

The main families of elements

JMeter organises its elements into families. Learning the families is like learning the sections of a toolbox: once you know that screwdrivers live in one drawer and pliers in another, you can find what you need quickly.

The order in which elements run

People often assume JMeter runs elements from top to bottom in the tree. That is only partly true. Samplers and controllers run in tree order, but the supporting elements around a sampler follow a fixed order that does not depend on where you drew them. For every single request, JMeter does the following in sequence.

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

Scope also controls Configuration Elements. A cookie manager placed at group level serves every request in the group. A header manager placed under one request affects only that request. When two elements of the same kind overlap, the one closer to the sampler usually wins. Keep this in mind whenever a result looks strange: ask first, “which elements are in scope for this request?”

The Thread Group decides how many pretend users exist and how they arrive.

In JMeter, one virtual user is called a thread. A thread is simply a single line of activity inside the program that runs your steps from start to finish, independently of the others. A Thread Group is a collection of threads that all run the same steps. If your Test Plan describes a shopper journey, the Thread Group says how many shoppers walk that journey and when each one starts.

The key settings

Special groups: setUp and tearDown

JMeter also offers two special thread groups. A setUp Thread Group runs before all the normal groups and is used for preparation, such as creating test accounts or warming a cache. A tearDown Thread Group runs after everything else and is used for cleanup, such as deleting test data. They are like setting the table before dinner and washing up afterwards.

Closed model versus open model

A standard Thread Group follows what testers call a closed model. A fixed pool of users exists, and each user waits for a response before sending the next request. If the server slows down, the users slow down with it, so the test automatically sends less traffic exactly when the system is struggling. That is kind to the server but unlike many real websites, where new visitors keep arriving at their own pace regardless of how slow things are. That second pattern is the open model, where you control the arrival rate rather than the number of users.

Community plugins offer thread groups designed for the open style, such as groups that hold a target number of concurrent users or shape arrival rates over time. If your real traffic comes from the public internet, consider an open style so your test does not quietly back off when the system slows.

A sampler is one action sent to the system under test, with one measured result.

The word sampler comes from the idea of taking a sample: each time a sampler runs, JMeter records one sample of how the system responded, including how long it took and whether it worked. The most common sampler by far is the HTTP Request, which sends a web request to a server. You fill in the protocol, the server name, the port, the method such as GET or POST, the path, and any parameters or body content.

Samplers beyond the web

Naming matters more than you think

Every sampler has a name, and that name becomes the label in your results. A plan full of requests named “HTTP Request” and “HTTP Request 2” produces a report nobody can read. Give each one a clear business name such as “Search Product” or “Place Order”. Teams that follow a naming rule, for example a step number followed by a short action, can scan a report of fifty requests in a minute.

Think about what a sampler really measures

JMeter records several time values for each sample. The elapsed time runs from just before the request is sent until the last byte of the response arrives. The latency runs until the first byte arrives. The connect time measures how long it took to open the network connection. Comparing them tells a story: a long connect time hints at network or load balancer trouble, while a long gap between latency and elapsed time hints at a large response being downloaded.

Configuration elements keep your plan tidy by holding settings once instead of copying them into every request.

Imagine writing the same server address into forty different requests. When the test moves from a staging server to a pre-production server, you would have to change forty places and might miss one. A Configuration Element solves this by holding a setting in one place that all requests in scope can use.

Why the cookie manager is non-negotiable for web tests

When you log in to a website, the server hands your browser a small piece of text called a cookie, which proves who you are on later requests. Without a cookie manager, every JMeter request arrives as a stranger, and the server may redirect each one to the login page. The test would then happily measure the login page over and over while you believed you were testing checkout. Placing a cookie manager in each Thread Group gives every virtual user its own private cookie jar, exactly like separate real browsers.

The cache manager and realism

A real browser does not download the company logo every time you click. It keeps a copy. If your plan downloads every image on every click, the load on the server and network is higher than reality. Adding a cache manager makes virtual users behave more like browsers. Whether you want that depends on your goal: to stress the servers you might skip it on purpose, but to predict real user experience you should include it.

Controllers decide which requests run, in what order, and how often.

Real people do not all behave identically. Some search first, some go straight to a product, some abandon the cart. A Logic Controller lets you express these choices. It is a container that holds samplers, and it applies a rule to them. The rule may repeat the contents, skip them unless a condition holds, pick one at random, or group them so they are reported as a single business step.

Why the Transaction Controller is a favourite

A single page action, such as pressing the Pay button, may trigger several requests behind the scenes: one to validate the card, one to create the order, one to send a confirmation. Business people do not care about each technical request. They care how long Pay took. A Transaction Controller wraps those requests and reports one combined time, so your report talks in business terms: Login took 1.2 seconds, Search took 0.8 seconds, Pay took 2.5 seconds.

Mixing user types with realistic ratios

A shop might see 60 percent browsers, 30 percent searchers, and 10 percent buyers. Real traffic mixes are rarely equal. Using a Throughput Controller in percentage mode, or separate thread groups sized to those ratios, lets you reproduce the true mix. A test where everyone buys at the same rate usually overloads the payment system far more than reality and gives a misleading answer.

Real people pause. Timers put those pauses into the test.

After a page loads, a human reads it, thinks, and then clicks. That pause is called think time. By default JMeter has no pause at all: a thread fires its next request the instant the previous one returns. Ten threads with no think time can generate as much traffic as hundreds of real people. A Timer adds a deliberate delay before each request in its scope, restoring realistic pacing.

Choosing the right timer

Think time changes how much load you create

Think time is not decoration. It directly controls how many requests per second your users produce. If a user sends a request every 2 seconds, then 100 users create about 50 requests per second. If the same user thinks for 10 seconds between requests, 100 users create only about 10 requests per second. Choosing a number out of thin air can make your test five times heavier or lighter than production. The honest way to choose is to look at real analytics data or logs and measure how long real visitors spend between actions.

A good plan does not hard-code values. It reads them from variables and data files.

If all 500 virtual users log in with the same username, the system under test may cache that one account’s data and look much faster than it would with 500 different accounts. This is one of the most common reasons for misleadingly good results. The fix is parameterisation, which means replacing fixed values with placeholders that are filled in differently for each user.

Variables

A variable is a named box holding a value. In JMeter you refer to a variable by wrapping its name in a dollar sign and curly brackets. Each virtual user has its own copy of its variables, so two users can hold different values under the same name without interfering. Variables are the way a value found in one response, such as an order number, gets reused in the next request.

Properties

A property is a setting that belongs to the whole JMeter run rather than to one user. Properties are usually given when you start the test, which makes them perfect for things you want to change from outside the file: the number of users, the duration, or the target server. Using a property for the user count means the same .jmx file can run a small smoke test on a laptop and a large load test in a pipeline, with no edits.

Functions

JMeter includes built-in functions that produce values on demand. Examples include a random number, a unique identifier, the current time, the thread number, and a counter. A unique identifier function is handy for creating order references that never collide. A property function reads a value given at start-up and offers a default if none was given.

CSV Data Set Config

The CSV Data Set Config element reads a text file of comma separated values, one row per line, and hands the next row to each thread. A login file might hold a username and a password on every line. You name the columns, and each row feeds the variables with those names. You can choose whether to recycle the file when it runs out, stop the test, or share the file across all groups.

Keep data files out of the test file itself and load them from a relative path, so the whole test folder can be zipped, shared, and run on another machine. Treat the data like source code: version it, and note how it was generated.

Many real systems hand out values that must be replayed. Extractors catch them.

Modern systems generate fresh, one-time values during a session: a login token, a session identifier, a form security code, an order number. If you recorded a session yesterday and replay it today, the old value is no longer valid, and the server rejects it. The technique of capturing a value from one response and feeding it into later requests is called correlation. It is the skill that most separates a toy script from a working script.

sequenceDiagram
  participant U as Virtual User
  participant S as Server
  U->>S: 1. Login with username and password
  S-->>U: 2. Response contains a fresh token
  Note over U: Post-Processor extracts the token into a variable
  U->>S: 3. Next request sends the saved token
  S-->>U: 4. Server accepts the request

The extractor family

Extractors are a kind of post-processor, meaning they run after a response arrives and pull information out of it. Choose the one that matches the shape of the response.

How to find what needs correlating

A reliable method is to run the recorded script once and look for failures such as unauthorised responses or redirects to the login page. For each failure, compare the recorded request against the live response of the previous step and spot which value changed. Another method is to record the same journey twice and compare the two recordings: anything that differs between them is a dynamic value that needs correlation.

A fast wrong answer is worse than a slow right one. Assertions catch wrong answers.

By default JMeter marks a web request as successful when the server returns a normal status code in the 200 range. But a server under stress can return a friendly-looking error page with a successful status code, or return an empty list where products should be. Your test would count those as passes, and the dashboard would show healthy numbers while customers see blank pages. An Assertion adds a rule that the response must satisfy, and if it breaks the rule, JMeter marks the sample as failed.

Keep assertions light

Every assertion costs processing time on the load generator. A heavy pattern applied to every response of a large page can slow your own test machine and distort results. Assert on something small and meaningful, such as a success message or an order identifier, rather than on the entire page body. Put cheap, important assertions on every critical step and avoid checking things that have little business value.

Assertion versus a service level target

A Duration Assertion fails individual requests that are too slow, which is useful for strict rules but can make the error rate mix up correctness problems and speed problems. Many teams prefer to assert on correctness only and judge speed afterwards using percentile numbers from the report. Decide which approach your team wants before the first run, and apply it consistently.

Listeners watch the test and record what happened. Choosing them wisely protects your results.

A Listener receives the result of each sample and displays or stores it. JMeter ships with many listeners, and they fall into two groups: ones for looking at results while you build the test, and ones for saving results during a real run.

Choose what you store

You can tell JMeter exactly which columns to save: timestamp, elapsed time, label, response code, success flag, bytes, thread name, and more. Saving fewer fields keeps files smaller and the generator faster. Do not save response bodies for a large test unless you have a specific need, because they make files huge and may contain private data.

Using the result file later

The saved result file can be reopened in a listener for study, or turned into a complete web-based report with charts for response time over time, throughput, error distribution, and percentile curves. We return to this in the section on reading results.

The most important number in your plan is the amount of load. Here is how to choose it with arithmetic instead of guessing.

A workload model is a clear description of the traffic you expect: how many users, doing what, at what pace, at the busiest time. If your model is wrong, even a perfectly built Test Plan answers the wrong question. Teams usually build a workload model from three sources: production logs or analytics, business forecasts such as the expected size of a coming campaign, and agreed targets with the product owner.

Little’s Law, the one formula to remember

A neat rule from queueing theory connects users, speed, and waiting. It says that the average number of users in the system equals the arrival rate of users multiplied by the average time each user spends in the system. In performance language, the number of concurrent users equals throughput multiplied by the sum of response time and think time. You do not need to fear the maths. It is just a safe way to turn business statements into thread counts.

A worked example

Suppose a ticketing site expects 20 complete booking journeys to start every second at its busiest moment. A typical journey has five page requests that each respond in about one second, plus four pauses of about ten seconds each where the visitor reads and decides. So one journey lasts about five seconds of response time plus forty seconds of think time, which is forty-five seconds in total.

So the Thread Group needs about 900 threads, not 20 and not 20,000. Notice what happens if the real system slows down: journeys get longer, so more users pile up at the same arrival rate. That is exactly why a closed model, which keeps the user count fixed, can understate the pain when a system slows. It is wise to run the test at the expected peak and also at one and a half to two times that level, to learn how much safety margin exists.

A reliable order of work saves hours of confusion.

flowchart TD
  A["Define goals and targets"] --> B["Build the workload model"]
  B --> C["Prepare test environment and data"]
  C --> D["Create script for one user"]
  D --> E["Parameterize and correlate"]
  E --> F["Add assertions and timers"]
  F --> G["Debug with 1 user then 5 users"]
  G --> H["Run a baseline test"]
  H --> I["Run load test at expected peak"]
  I --> J["Run stress and soak tests"]
  J --> K["Analyze results and report"]
  K --> L["Fix, retest, and compare"]

Make the plan modular

As plans grow, repeating the same login steps in ten places becomes a maintenance headache. Use a Module Controller or Include Controller to keep one copy of shared steps. If login changes, you fix it once. Treat your Test Plan with the same care you would give production code: tidy names, small reusable pieces, and notes in the comment field of elements that explain unusual choices.

JMeter can watch you browse and write the first draft of the plan for you.

Building every request by hand for a ten-page journey is slow. JMeter includes the HTTP(S) Test Script Recorder, which works as a middleman. You point your browser to pass its traffic through JMeter, then perform the journey as a normal user. JMeter notes every request the browser makes and places it in the Test Plan for you. For secure sites, JMeter generates its own certificate that you must trust in the browser, so it can read the encrypted traffic during recording.

What you must clean up after recording

Use include and exclude patterns before recording so that images from third-party advertising and tracking services are skipped. You do not want to load-test someone else’s server, and you may not be allowed to. After recording, rename each request, group related ones into Transaction Controllers, move common settings into defaults, and then do the parameterisation and correlation described earlier.

The graphical screen is for building. Real load runs from the command line, and big loads run on many machines.

Why not run from the graphical screen

JMeter’s graphical interface draws windows, updates tables, and keeps results visible. That costs memory and processor time, which are exactly the resources you need for generating load. Running a heavy test through the graphical interface is like trying to race a car while also repainting it. Build and debug in the interface, then run the saved Test Plan in non-GUI mode, where JMeter has no windows and spends everything on generating traffic. You give the command line the test file, the result file, and optionally a folder where the web report should be generated at the end.

When one machine is not enough

A single load generator can only produce so much before its own processor, memory, or network becomes the bottleneck. When you need tens of thousands of users, JMeter supports distributed testing. One machine acts as the controller and several others act as workers. The controller sends the Test Plan to every worker, each worker runs it, and results flow back to the controller. Each worker runs the full Thread Group, so if a plan has 500 threads and there are four workers, the total load is 2,000 users.

flowchart LR
  C["JMeter Controller"] --> W1["Worker 1"]
  C --> W2["Worker 2"]
  C --> W3["Worker 3"]
  W1 --> LB["Load Balancer"]
  W2 --> LB
  W3 --> LB
  LB --> GW["API Gateway"]
  GW --> A1["App Server 1"]
  GW --> A2["App Server 2"]
  GW --> A3["App Server 3"]
  A1 --> DB["Database"]
  A2 --> DB
  A3 --> DB
  W1 -. results .-> C
  W2 -. results .-> C
  W3 -. results .-> C

Rules for healthy distributed runs

Many organisations now run workers as containers in a cluster, or hire cloud machines for the duration of a test and shut them down afterwards, which makes large tests affordable. The Test Plan itself does not change; only the number of machines does.

JMeter shows what the users felt. Monitoring shows why.

A test result might say that the checkout slowed to eight seconds at 700 users. That is the symptom. To find the cause, you need to look inside the servers during the same minutes. Was the processor at 100 percent? Did memory run out? Was the database waiting on locks? Did a connection pool reach its limit? Without server-side monitoring, you are guessing at the cause.

flowchart LR
  J["JMeter Backend Listener"] --> I["Time Series Database"]
  H["Host Metrics Agents"] --> I
  A["Application Metrics"] --> I
  I --> G["Dashboard Tool"]
  G --> E["Engineer watches live"]

What to watch

JMeter’s Backend Listener can stream results as they happen into a time series store, and a dashboard tool can draw them next to server health charts. Seeing response time and processor use on the same timeline is often enough to reveal the bottleneck in seconds. Also record the start and end time of every test run so you can line up logs afterwards.

Numbers can lie if you read them carelessly. Learn the few that matter most.

The core measurements

Imagine 100 requests, where 99 take one second and one takes 101 seconds. The average is two seconds, which sounds fine, yet one customer waited nearly two minutes. In a system serving millions of requests, that one unlucky share is thousands of unhappy people every hour. This is why experienced teams set targets on percentiles rather than averages.

How the curves should look

A healthy system shows response time staying flat as users increase, while throughput climbs in step. At some point, called the knee, response time starts climbing and throughput stops growing, because some resource is saturated. Beyond the knee, adding more users only adds waiting. Finding the knee, and knowing which resource causes it, is the main prize of a load test.

Questions to ask of every result

JMeter can also generate a web-based HTML dashboard report from the saved result file. It contains response time over time, throughput, percentile charts, error breakdowns, and an at-a-glance satisfaction score table based on response time thresholds. It is a convenient attachment for a test summary email.

A test that runs only when someone remembers it will be forgotten. Automate it.

Modern teams release software many times a week. If performance is only checked once before a big release, a slow change can sneak in unnoticed and be very hard to trace later. Continuous integration and delivery pipelines are automated routes that build, test, and deploy code. You can add a performance step to that route so that every change, or every night, runs a short JMeter test against a test environment.

A sensible layered approach

Pass or fail gates

An automated run needs a way to decide success. Teams define thresholds, such as the 95th percentile of every critical journey under two seconds and the error rate under one percent. A small script or a tool that reads the result file compares numbers to these limits and signals the pipeline to stop if a limit is broken. Because JMeter test plans are text files, they are easy to keep in the same repository as the application code, so the test always matches the version it targets.

Some teams use wrapper tools that let you describe tests in a simple readable format and then run them through JMeter, adding built-in pass or fail rules and reports. Whether you use a wrapper or not, the principles stay the same: keep tests repeatable, keep environments stable, and keep results stored so you can see trends over weeks.

A load test is powerful. Used carelessly, it can harm real systems and leak private data.

A load test sends large amounts of traffic. Pointed at the wrong target, it looks identical to an attack. It is both a technical and a legal matter to know exactly who owns the target and to have written permission before testing. Even inside your own company, running a heavy test on a shared system without warning can disrupt other teams.

Testing security-related behaviour

A load test is not a security test, but it can reveal security-relevant weaknesses. Does the system rate-limit repeated login attempts, or does it let thousands of attempts through? Do error pages under load leak internal details? Does a token expire as designed? Include a few such checks in your plan, but keep real attack simulation for a separate, authorised security test.

Seeing how the same building blocks answer different business questions makes the ideas stick.

Large technology companies run performance and resilience testing in their own ways, often with in-house tools, but the thinking is the same as in this guide: model real traffic, push beyond it, measure the experience, find the first bottleneck, fix it, and test again. JMeter is simply a free and approachable way to practise that thinking.

Every tool has strengths and weak points. Knowing both keeps you honest.

The mistakes that waste the most time

Keep these habits on one page and review them before every important run.

Short answers to the questions beginners ask most often.