We begin with the problem it solves, because the tool only makes sense once the problem is clear.

The repetition problem

A JMeter virtual user, called a thread, normally walks through its steps from top to bottom and then, if the test says so, walks through them again. Each walk is called an iteration. This repetition is what generates sustained load. The trouble is that some steps in a real journey are not repeated by real people. Signing in, accepting terms and conditions, downloading a configuration file or opening a long-lived connection usually happen once per visit, not once per action.

The solution in one sentence

The Once Only Controller is a container. Whatever steps you place inside it are executed during each thread’s first iteration only, and are skipped on every later iteration. The thread then continues with the rest of its journey as normal.

What happens without it

Without a way to run steps once, test authors tend to fall into one of two poor habits. Some put the sign-in at the top of the repeated section, so every iteration signs in again and the authentication system receives many times its real traffic. Others try to avoid sign-in altogether by pasting a fixed token into every request, which means the test never exercises real sessions and every virtual user pretends to be the same person. Both habits produce numbers that look precise and mean very little. The Once Only Controller gives a third, far more honest option.

Why it matters for accuracy

If sign-in were repeated in every iteration, the authentication system would receive far more traffic than in real life, and the rest of the journey would receive less, because time is wasted signing in again. The numbers would blame the login service for slowness that real users never see, while hiding how the actual pages behave. A single small controller removes this distortion.

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

The Once Only Controller is one member of a family, and seeing its relatives clarifies its purpose.

flowchart TD
  T[Thread Group] --> O[Once Only Controller]
  T --> L[Loop of repeated actions]
  O --> A[Login request]
  O --> B[Fetch settings request]
  L --> C[Browse products]
  L --> D[Search]
  L --> E[Add to basket]
        

The behaviour looks like magic until you see the simple bookkeeping behind it.

Each thread carries its own tree

When a test starts, every thread receives its own private copy of the parts of the plan it will run, along with its own state. This is why one user’s variables are invisible to another. The Once Only Controller lives inside that private copy, so its memory of whether it has already run belongs to that one thread. Thread number seven having completed its sign-in says nothing about thread number eight.

The first-iteration rule

When the thread reaches the controller, it asks one question: is this the first iteration of my enclosing loop? If yes, the controller passes the thread into its children, which then run in the order they appear. If no, the controller steps aside and the thread moves directly to the next element. No request is sent, no time is recorded and nothing appears in the results for that skipped pass.

The controller itself produces no sample

A logic controller is not a sampler. The Once Only Controller adds no timing of its own. What you see in the results are only the samples of the children that actually ran. If you want one combined timing for the whole sign-in sequence, wrap the children in a Transaction Controller inside it.

sequenceDiagram
  participant U as Virtual User
  participant O as Once Only Controller
  participant S as Login Sampler
  participant J as Journey Samplers
  U->>O: Iteration 1 arrives
  O->>S: Run children
  S-->>U: Login result and token
  U->>J: Browse and search
  U->>O: Iteration 2 arrives
  O-->>U: Skip children
  U->>J: Browse and search again
  U->>O: Iteration 3 arrives
  O-->>U: Skip children
  U->>J: Browse and search again
        

The controller is often misunderstood when it sits inside another looping controller, so this chapter takes it slowly.

The rule as documented

The official description says that the Once Only Controller runs during the first iteration of whatever looping parent surrounds it. When it sits directly under a thread group, that means the first iteration of the thread’s own loop, which is the familiar once-per-user behaviour. When it sits inside a Loop Controller, the first iteration of that loop is meant, and this happens again every time the outer thread loop brings the thread back into that Loop Controller.

A worked example in words

Suppose a thread group makes each user repeat three times. Inside it sits a Loop Controller set to loop five times, and inside that Loop Controller sits a Once Only Controller followed by a search sampler. On the thread’s first outer pass, the Loop Controller begins, and on its first inner iteration the Once Only children run once. Inner iterations two to five skip them. On the thread’s second outer pass, the Loop Controller starts afresh, so its first inner iteration again runs the Once Only children. By the end, the children have run three times, once per outer pass, not once in total.

The classic use case, built step by step, makes the idea concrete.

The scenario

An online store wants to know how its catalogue pages behave when two hundred shoppers browse at the same time. Each shopper signs in, then repeatedly opens a category page, a product page and a search result. The goal is to measure the browsing pages, not the sign-in.

When sign-in has several steps

Real sign-in is rarely one request. A user may load the sign-in page, receive a security token embedded in it, submit credentials, and then be redirected to a landing page that sets further cookies. All of these steps belong together inside the controller, in their true order, so that the session is complete before the browsing begins. If only the final credential submission is inside the controller and the earlier page load is outside it, the page load will repeat on every iteration, wasting traffic and confusing your counts.

flowchart LR
  A[Thread starts] --> B{First iteration?}
  B -- Yes --> C[Run sign-in once]
  B -- No --> D[Skip sign-in]
  C --> E[Browse category]
  D --> E
  E --> F[Open product]
  F --> G[Search]
  G --> H{More iterations?}
  H -- Yes --> B
  H -- No --> I[Thread ends]
        

Many people reach for this controller when what they really need is something that runs once for the entire test.

Two very different needs

Some work must happen once per virtual user, such as that user’s own sign-in. Other work must happen once for the whole test, such as creating a shared set of products, preparing a database, or fetching one administrator token that every thread reuses. The Once Only Controller serves the first need only. If you place a data creation step in it, and you run five hundred threads, the step runs five hundred times, which may be exactly the problem you were trying to avoid.

Running sign-in once only helps if the result of that sign-in survives to later iterations, and that is not automatic.

Variables persist per thread

A value extracted during the first iteration, such as a token or a user identifier, is stored in a variable that belongs to that thread. In normal circumstances it remains available in every later iteration, because variables are not cleared between iterations. This is what allows the browsing steps to use a token obtained once at the start.

It helps to remember the difference between a variable and a property here. A variable belongs to one thread and is the correct home for personal values such as a token. A property is shared by the whole test, so storing a personal token there would make every user overwrite everyone else’s. If you ever need to hand a value from a setup group to the main users, a property is the right bridge, but a token that identifies one user must stay in that user’s own variable.

Cookies and the same-user setting

Web sessions often live in cookies. Two settings can silently erase them. The thread group has an option, usually described as using the same user on each iteration, which is normally switched on. When it is switched off, JMeter treats each iteration as a brand new browser: cookies, caches and connections are reset. The cookie manager also has its own option to clear cookies at the start of every iteration. If either is active, the session created in the first iteration vanishes, and from the second iteration the user is effectively signed out, but the sign-in never runs again.

The Once Only Controller is one tool among several, and each alternative solves a slightly different problem.

A decision table turns the options into a confident choice.

Three questions to ask

First, who owns the repeated action in real life, the user or the system? Second, how long will the test run compared with how long a session or token stays valid? Third, what is the purpose of the test: to measure the repeated journey, or to measure the one-time step? Answering these three questions usually reveals the right element within a minute.

Because the controller skips work, the numbers in your report look different, and that difference needs interpreting.

Sample counts reflect execution

Every sampler inside the controller produces one sample per execution. With two hundred threads, you will see about two hundred sign-in samples, while the browsing requests may number in the tens of thousands. This is correct and expected, but it affects how much you can trust each row of the statistics table.

Percentiles need enough samples

A ninety-fifth percentile computed from two hundred samples is far less stable than one computed from fifty thousand. A single slow sign-in changes the figure noticeably. When the sign-in row of your report looks alarming, check the number of samples before panicking, and rerun if necessary.

Throughput is not constant

Sign-in requests happen only when users arrive, so their rate depends on the ramp-up and then drops to zero. The rate of sign-ins over time therefore looks like a bump at the start of the test, not a steady line. This is the realistic shape for a one-time action, but it surprises people who expected a flat chart.

The rate at which users start decides how hard the one-time steps hit the system.

Arrival rate equals users divided by ramp-up

If two hundred users start over one hundred seconds, about two new users begin every second, and each new user triggers one sign-in. The authentication service therefore sees roughly two sign-ins per second during the ramp, and nothing afterwards. If you shorten the ramp to ten seconds, the same two hundred sign-ins arrive at about twenty per second, a tenfold increase in pressure on that one service.

Why this matters

Real systems often face sign-in storms at particular moments, such as the start of a working day or a sale. A test that ramps users slowly will never reveal weakness in sign-in. A test that ramps users abruptly may overstate the problem if real arrivals are gentler. Choose the ramp-up to match the arrival pattern you want to study, and state it in your test notes.

Estimating the sign-in load before you run

You can predict the pressure on the authentication service with simple arithmetic. Divide the number of threads by the ramp-up time in seconds to get the arrival rate, then compare it with the rate the service handles in production at its busiest moment. If your plan produces ten times the real peak, you are running a stress test of sign-in, not a realistic test of browsing, and you should say so in your notes. If it produces a tenth of the real peak, you will learn nothing about sign-in capacity. Doing this sum takes a minute and prevents many arguments after the results arrive.

flowchart LR
  A[Short ramp-up] --> B[High sign-in rate at the start]
  B --> C[Stress on authentication service]
  D[Long ramp-up] --> E[Gentle sign-in rate]
  E --> F[Browsing load dominates]
  C --> G[Different bottlenecks found]
  F --> G
        

A sign-in that happens only once can outlive the session it created, and the test then quietly turns into a test of error pages.

The hidden clock

Most applications give sessions and tokens a lifetime, often measured in minutes. A test that runs for an hour with a token valid for twenty minutes will see healthy results for the first twenty minutes and then a flood of authorisation failures. Because the sign-in was a once-only step, nothing in the plan ever refreshes the token.

Ways to handle it

Data files and one-time steps can interfere with each other in surprising ways.

The credentials file

Tests commonly read usernames and passwords from a file, giving each thread its own row. The data-file element reads a new row as threads iterate. If it advances every iteration while the sign-in runs only in the first, the user-name variable on later iterations will belong to a different person than the one who actually signed in. Later requests that quote the username, such as a profile page or an order history, may then ask for someone else’s data.

Ways to stay consistent

Supporting elements follow scope rules, and the Once Only Controller changes what falls inside that scope.

Scope decides who is affected

Timers, assertions and extractors apply to the samplers in their scope, which means the samplers at or below their position in the tree. A timer placed inside the Once Only Controller delays only the one-time steps. A timer placed at thread-group level delays every sampler, including those inside the controller. Decide on purpose where each helper belongs.

Think time for the first iteration

Real people pause after signing in, often to look at the landing page. A short think time after the one-time steps makes the first iteration resemble real behaviour. Without it, many users hit their first browsing request in the same instant they finish signing in.

Extractors must be reliable

If the extractor that captures the token fails during the one-time sign-in, nothing will retry it. Every later iteration will then use an empty or stale value. Always add an assertion directly on the sign-in request and consider stopping the thread if sign-in fails, since continuing would only create a stream of meaningless errors.

Where you put the controller matters as much as what you put inside it.

When several machines generate load together, the word “once” still means once per thread, and the numbers multiply.

Each worker runs the whole plan

In a distributed test, the controller machine sends the full plan to every worker, and each worker runs its own set of threads. Thread counts therefore apply per worker. The Once Only Controller operates inside each thread, exactly as before, so the total number of one-time executions equals the total number of threads across all workers.

What this means for shared steps

If you place a “create shared data” step in a Once Only Controller and run three workers with a hundred threads each, that step runs three hundred times. For one-time work that belongs to the whole test, use the setUp thread group, remembering that in distributed mode it also runs on each worker, so shared preparation should be idempotent or done outside JMeter.

flowchart LR
  C[Controller] --> W1[Worker 1: 100 threads]
  C --> W2[Worker 2: 100 threads]
  C --> W3[Worker 3: 100 threads]
  W1 --> S1[100 sign-ins]
  W2 --> S2[100 sign-ins]
  W3 --> S3[100 sign-ins]
  S1 --> A[Authentication service sees 300 sign-ins]
  S2 --> A
  S3 --> A
        

Because the controller hides work, bugs show up as things that did not happen, which are harder to notice.

The controller behaves identically in both modes, but your way of working should differ.

Same logic, different purpose

The skipping logic lives inside the engine, so the plan behaves the same whether it is run from the graphical interface or from the command line. Use the graphical interface to build the structure and to prove with one or a few users that the sign-in runs once. Use the command line for real load with a lightweight results writer.

Parameterise what changes

Expose the number of threads, the ramp-up time, the number of iterations and the credentials file location as properties with default values. That lets the same plan run as a one-user proof in the graphical interface and as a large run from the command line without edits.

Remember the heavy listeners

The detailed results viewer you used to verify the once-only behaviour should be disabled before a heavy run, because it stores every request and response in memory and distorts timings at scale.

A controller that changes your traffic pattern also changes what the application experiences, so watch the right metrics.

A step that handles credentials and tokens deserves the same care as any other sensitive part of a test.

These patterns appear again and again in tidy, trustworthy plans that use one-time steps.

Naming and documentation habits

Give the controller a descriptive name, such as one that says it holds each user’s start-up work, and add a short comment explaining the assumptions: how long the token lives, which setting keeps the session, and where the credentials come from. A plan that is read months later by a colleague, or by you, is far easier to trust when the reasons behind its structure are written next to the elements they explain.

These mistakes look harmless, and each one quietly spoils results.

An honest look at benefits and costs helps you decide when the controller is the right answer.

A short order of operations avoids the stumbles described in this guide.

Keep a written test note

For every run, record the thread count, ramp-up time, iteration count or duration, the token lifetime, the credentials source and the number of sign-ins observed. These few lines let anyone reproduce the run and quickly explain odd results later. When two runs disagree, the difference very often hides in one of these settings rather than in the application itself.

The controller works with any sampler, so its usefulness extends well past web pages.

Stories show how the controller helps, and how it can mislead, in everyday projects.

Once per user, meaning once per thread in its first iteration. With two hundred threads, the children run two hundred times in total.

The controller is most likely inside a Loop Controller or similar element, so it runs on the first iteration of each cycle of that loop. Move it directly under the thread group.

Usually the session was cleared. Check the same-user option in the thread group and any cookie-clearing option, and confirm the token variable is still filled in later iterations.

Not reliably. Use the setUp thread group for preparation, or a Throughput Controller in total-executions mode for work that must be counted across all threads.

No. It only acts on the first iteration. For cleanup, use the tearDown thread group or build explicit conditions for the final iteration.

No. Controllers do not produce samples. You will see rows only for the samplers inside it, unless you wrap them in a Transaction Controller.

The controller will not retry it, because it only runs in the first iteration. Add assertions and make the thread stop on error, otherwise every later iteration will fail in confusing ways.

Not with this controller alone. Combine a conditional controller with a record of the sign-in time, or use a refresh call, so the plan renews the token when it nears expiry.

Each worker runs its own threads, and each thread runs the one-time steps once. The total number of executions equals the total thread count across all workers.

No. Few samples and a burst shaped by the ramp-up make it a poor basis for capacity conclusions. Build a dedicated scenario that repeats sign-in at the desired rate.

It is often a good choice then, because the token stays valid for the whole test. Just confirm the lifetime against the planned duration.

The credentials file has too few rows, wraps around, or is identical on several workers. Provide at least one distinct account per thread across the whole test.

You can, but the behaviour becomes harder to reason about. Prefer placing it directly under the thread group and using separate conditional logic elsewhere.

Run a short test and compare the number of sign-in samples with the number of threads. If they match, placement is correct. If not, inspect the parent elements.

The Once Only Controller is a small element with a clear job: run its children in each virtual user’s first iteration and skip them afterwards. Used in the right place, it turns an unrealistic test that signs in again and again into a faithful model of a real session. Used carelessly, it hides failed sign-ins, outlives expiring tokens, multiplies shared work across threads and leaves misleading statistics behind. The remedy is to be clear about whose “once” you mean, to keep the design simple, to protect session state, to prove the behaviour with a few iterations, and to reach for setUp groups, conditional controllers or dedicated scenarios when the problem is bigger than a single start-up step.