It is a JMeter element that marks a request as failed when the response took longer than a time limit you choose.

Starting with the basics

Apache JMeter is a free, open-source tool written in Java that measures how well a system behaves when many users use it at the same time. This is called load testing or performance testing. A JMeter test is arranged as a tree called a Test Plan, and the pieces inside are called test elements. Each virtual user is a thread, a small worker that walks through the tree independently of the others.

A Sampler sends one request, such as an HTTP call, and records the answer. Each request and answer pair is one sample. The recorded facts about a sample, such as how long it took and whether it passed, are the sample result.

What is an assertion?

An assertion is a check that JMeter performs on a sample result after the answer arrives. It asks a yes or no question and, if the answer is no, marks the sample as failed and records a message that says why. Different assertions ask different questions. One asks “does the response contain this text?” Another asks “is the response the right size?” The Duration Assertion asks one simple question: “did this request finish within the time I allowed?”

Why it matters

Without a time check, JMeter happily marks a slow answer as a success, as long as the answer arrives and has a good status code. A login that takes twenty seconds and then works counts as a pass. Your report shows zero errors, and your users are leaving. The Duration Assertion turns slowness into a visible failure, so that “too slow” becomes something the report can count, graph and alert on.

A test can only judge speed if someone has first decided what “too slow” means. This chapter explains where those rules come from.

Where time limits come from

In real organisations, speed expectations are written down in a few standard forms. Knowing the words helps you talk to the people who own the rules.

Turning rules into checks

A written rule is only useful if the test enforces it. The Duration Assertion is the simplest way to turn a rule like “login must finish within two seconds” into a check that runs on every single login request in the test. It does not replace careful analysis of percentiles, but it gives immediate, per-request evidence that something broke the rule.

Why users care about time

People notice delay quickly. A page that responds in a fraction of a second feels instant. A delay of a second or two is noticed but tolerated. Beyond several seconds, many users give up, tap again, or leave. Each of those reactions creates extra load, because repeated taps send more requests. Slowness therefore does not only hurt users. It can also make the system’s problems worse.

JMeter has several assertions. Each guards a different kind of promise, and they work best together.

The common assertions

Three questions every request should answer

A complete check uses all three. A response that is quick but wrong, or correct but slow, or fast and correct but only because the server returned an empty page, is a failure in each case. Using the Duration Assertion alone tells you nothing about correctness, and using content assertions alone tells you nothing about speed.

The position of the assertion in the tree decides which requests it judges, and JMeter always runs it at a fixed moment in each sample’s life.

A typical tree

A normal test starts with the Test Plan and a Thread Group, which controls how many virtual users run. Samplers sit inside the Thread Group. An assertion can be placed under one sampler, or directly under the Thread Group so it applies to all samplers.

flowchart TD
    A[Test Plan] --> B[Thread Group]
    B --> C[Duration Assertion global 5000 ms]
    B --> D[HTTP Request Login]
    D --> E[Response Assertion]
    D --> F[Duration Assertion 2000 ms]
    B --> G[HTTP Request Search]
    B --> H[Listener]

Scope in one idea

Scope means which samplers an element affects. An element affects its own level and everything beneath it, like a notice pinned on one floor of a building. A Duration Assertion directly under a sampler judges only that sampler. A Duration Assertion under the Thread Group judges every sampler in the group. If both are present, both apply, and the sample fails if either limit is broken.

The order JMeter runs things

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

For each sample, JMeter applies config elements, runs pre-processors and timers, sends the request, runs post-processors, and only then runs assertions. Listeners come last, so they record the final verdict, including any failure caused by the Duration Assertion.

The screen is one of the simplest in JMeter. There is only one real decision to make.

The fields

Milliseconds explained

A millisecond is one thousandth of a second. So one thousand milliseconds make one second, and two thousand make two seconds. JMeter reports all times in milliseconds, and the Duration Assertion uses the same unit. A very common slip is typing the number of seconds, such as “3”, which means three milliseconds. Almost every response is slower than that, and the whole test then fails on every request.

Using a variable or property for the limit

The duration box accepts a variable or a property, not only a fixed number. A property is a setting passed to JMeter when it starts, so you can set the limit from outside the plan. This is handy when the same test runs on a slow test environment, where you accept a larger limit, and a fast production-like environment, where you demand a strict one. One plan then serves both, and the number lives in one place instead of being scattered across many assertions.

To set a sensible limit, you must know exactly which stopwatch the assertion reads. Several different times exist for each request, and they are easy to confuse.

The sample time

The Duration Assertion compares the limit with the elapsed time recorded for the sample. Elapsed time starts just before JMeter sends the request and stops when the last byte of the response has been received. It therefore includes everything the user would wait for: opening the network connection, the secure handshake for HTTPS, the server’s thinking time and the time to download the whole answer.

What is not counted

Waiting caused by timers is not part of the measured time. If a timer pauses a virtual user for three seconds before a request, those three seconds do not count towards the request’s duration. That is correct, because a person’s thinking time is not the system’s slowness. Time spent inside JMeter processing results, such as running extractors, is also separate from the sample time.

Requests with several parts

Some requests contain sub-parts. A request that follows a redirect has a first answer and a final answer, and a request that downloads page extras has many smaller downloads. The main sample’s time covers the whole chain. Because the assertion reads the time recorded on the sample it is attached to, a limit on such a request must allow for the entire chain. When you are unsure which time the assertion judged, run one request and look at the time shown in a results viewer and at the assertion’s failure message, which states the actual time.

Behind the scenes, the check is a simple comparison. Seeing the steps explains how failures reach your reports.

Step by step

sequenceDiagram
    participant T as Virtual User Thread
    participant S as Sampler
    participant W as Web Server
    participant A as Duration Assertion
    participant L as Listener
    T->>S: Run next sample
    S->>W: Send request
    W-->>S: Send full response
    S->>S: Record elapsed time
    S->>A: Pass finished sample result
    A->>A: Compare elapsed time with the limit
    A-->>L: Result with pass or fail and message

The failure message

When the limit is broken, the assertion writes a message that says, in plain words, that the operation lasted too long, along with the actual time and the allowed time. This message appears in the results viewers, in the assertion results listener, and in the failure message column of saved result files. It is the main clue when you investigate a slow sample.

Each assertion is independent

If a sampler has a content assertion and a duration assertion, each one runs separately and records its own result. The sample is marked failed if any of them fails. This means one request can carry two failure messages, one about slowness and one about wrong content, and both are kept.

Beginners often think the Duration Assertion cuts off slow requests. It does not. Understanding the difference prevents serious misreadings.

What a timeout does

A timeout is a limit set on the sampler itself, such as the connect timeout and the response timeout on an HTTP request. When the limit is reached, JMeter stops waiting, abandons the request and records an error. The request is cut short, and the virtual user moves on.

What the Duration Assertion does

The Duration Assertion waits for the request to finish completely, however long that takes, and only then compares the time with the limit. It cannot save a virtual user from waiting. If a server takes one minute, the user waits one minute, and the assertion then marks the sample as failed.

flowchart TD
    A[Request sent] --> B{Timeout reached}
    B -->|Yes| C[Request abandoned and error recorded]
    B -->|No| D[Response fully received]
    D --> E{Elapsed time above duration limit}
    E -->|Yes| F[Sample marked failed with time message]
    E -->|No| G[Sample passes the time check]

Using them together

The best practice is to use both, with the assertion’s limit lower than the timeout. For example, a response timeout of ten seconds protects the test from hangs, while a Duration Assertion of two seconds marks anything slower than the service target. Requests between two and ten seconds complete and are flagged as too slow. Requests beyond ten seconds are cut and recorded as errors. The result is a clear picture of both the slow and the stuck.

A limit that is too strict makes every test fail. A limit that is too loose proves nothing. The right limit comes from evidence and from agreement.

Where the number should come from

A simple decision path

flowchart TD
    A[Need a time limit] --> B{Is there a written target}
    B -->|Yes| C[Use the target as the limit]
    B -->|No| D[Run a light trial and record times]
    D --> E[Take the slow end of normal times]
    E --> F[Add a margin and agree it with the owners]
    C --> G[Write the source in the Comments field]
    F --> G

Why one slow request is not always a breach

Service targets are usually stated with a share of requests, such as “ninety-five out of a hundred searches finish within two seconds”. The Duration Assertion, however, judges each request on its own. A single request that takes two and a half seconds is marked failed, even though the target allows five in a hundred slow ones. If you set the assertion limit equal to the target, you will see failures even in a healthy system, and you may chase problems that are not problems.

Two layers of limits

Many teams use two layers. The Duration Assertion has a generous limit that catches only clearly bad cases, for example three times the target. The strict service target is then checked after the test, by calculating percentiles from the saved results. This keeps the live failure count meaningful and the final judgement statistical.

There are three common ways to arrange Duration Assertions in a plan. Each suits a different kind of test.

Strategy one: one global limit

Place one Duration Assertion under the Thread Group. It applies to every sampler in the group. This is the quickest way to catch badly slow requests everywhere and needs almost no maintenance. The drawback is that one number must suit very different requests. A search and a large report download do not take the same time, so the number must be generous enough for the slowest legitimate request, which makes it blunt for fast ones.

Strategy two: a limit per request

Place a separate Duration Assertion under each important sampler, with a limit that fits that request. Login may have two seconds, search one and a half, and the report download ten. This matches how real service targets are written and gives precise failures. The drawback is maintenance: more assertions to keep correct.

Strategy three: limits from data

Store the limits in a data file, next to the request names, and read them with a CSV element or properties. The assertion then uses a variable for its limit. A change to a limit becomes an edit to a file and not to the plan, so people who own the targets can update them without touching JMeter.

Combining strategies

A common and sensible design is a generous global limit as a safety net plus stricter limits on a few business-critical requests, such as login, search and payment. When both apply to the same request, both are checked, and either one can fail the sample.

A Duration Assertion changes the numbers in your report. Knowing how, and how to untangle them, keeps your conclusions honest.

What changes when the assertion fails

The mixing problem

A single error percentage now blends two very different kinds of failure: requests that really broke, and requests that merely took too long. A report that says “five percent errors” could mean five percent of requests returned error pages, or five percent were slower than the limit, or any mixture. These have very different causes and fixes. The first suggests broken code or a crashed service. The second suggests overload or a slow component.

Why the response time numbers do not change

The assertion does not alter the recorded time of the sample. The average, the median and the percentiles still describe the true response times. The assertion only adds a failed flag. So the percentile report remains the most direct view of speed, and the assertion’s count of failures is the quick alarm that something went beyond a limit.

A Duration Assertion does not live alone. Because it can fail a sample, it can trigger behaviour in other parts of the plan.

The Thread Group error action

The Thread Group has a setting that decides what to do after a sampler error: continue, start the next pass, stop the thread, stop the test gracefully, or stop the test immediately. A failure raised by an assertion counts as a failed sample, so it can trigger that action. If the Thread Group is set to stop on error, a single slow response can end a virtual user, or the whole test. That is rarely what you want from a speed check, particularly during warm-up when the first few requests are naturally slow.

flowchart TD
    A[Sample finishes] --> B[Duration Assertion fails]
    B --> C[Sample marked failed]
    C --> D{Thread Group error action}
    D -->|Continue| E[User carries on]
    D -->|Stop thread| F[This user ends]
    D -->|Stop test| G[Whole test ends]

Transaction Controllers

A Transaction Controller bundles several samplers into one measured business step, such as “Add To Cart”. Teams often want a limit on the whole step rather than each request. Place the assertion where it applies to the transaction’s own result, and confirm in a trial run, using a results viewer, that the failure appears on the transaction and shows the time you expect. Do not assume. Check.

Timers and loops

Timers add pauses before samplers, and those pauses are not counted in the sampler’s time, so they do not affect the assertion. Inside a Loop Controller, which repeats its children several times, the assertion runs on every pass and judges each pass separately. A slow first pass, caused by cold caches and new connections, may fail a limit that later passes meet. Consider whether the first pass needs a looser limit or a warm-up request before the measured loop.

Extractors and variables

Extractors read values out of a response and store them in variables. A failed Duration Assertion does not stop an extractor from working, because the response did arrive. But if a later request depends on a value from a slow response, the dependent step still gets its data. The slow request is judged and recorded, and the journey continues, unless the Thread Group is set to stop.

The assertion itself costs almost nothing. The danger is that it may blame the server for slowness that the load generator caused.

The assertion is cheap

The check is a comparison of two numbers, done once per sample. Even with millions of samples, the work is trivial compared with sending the requests. You do not need to hold back on using it for performance reasons.

The false alarm problem

A Duration Assertion cannot tell why a request was slow. A request can be slow because the server was slow, because the network was slow, or because the load generator itself was struggling. If the generator is overloaded, its own pauses make requests look slow, and the assertion happily fails them. The test then reports a slow system when the real culprit was the testing machine.

Spotting a generator problem

Signs include slow requests that appear in bursts across all samplers at the same moment, throughput lower than the plan should produce, and slowness that disappears when you reduce users on the same server. Watch the generator’s own processor and memory during the run. A trustworthy speed check needs a healthy measuring tool.

Distributed runs

In a distributed test, assertions run on each load generator, and each one measures the time from its own location. Generators in different places will see different times for the same request. Set limits that match the location of the real users you are imitating, and do not compare numbers from far apart generators as if they measured the same thing.

Many teams run performance tests automatically with every release. A Duration Assertion becomes part of the safety net, with one important catch.

The pipeline idea

A pipeline is an automated series of steps that builds, tests and releases software. A performance step in the pipeline runs a short JMeter test in non-GUI mode, saves the results to a file, and then examines the file. If too many requests are over the limit, the pipeline stops the release.

flowchart LR
    A[New build deployed to test system] --> B[JMeter runs in non GUI mode]
    B --> C[Results saved to a file]
    C --> D[Analysis step counts failed samples]
    D --> E{Within the agreed threshold}
    E -->|Yes| F[Release continues]
    E -->|No| G[Release stopped and team notified]

The important catch

JMeter itself does not fail a build because assertions failed. A finished run exits normally even if thousands of samples were marked failed. The pipeline must read the results and make the decision. This is a common surprise: a team adds assertions, sees the pipeline stay green, and assumes everything passed, when in fact the failures were in the file and nobody looked.

Ways to turn failures into a decision

Choosing thresholds for the gate

A gate should tolerate normal noise. If a single slow request fails the build, the gate will fail constantly and people will learn to ignore or disable it. Common gate rules are “no more than a small percentage of samples over the limit” or “the ninety-fifth percentile must stay within a number”. The Duration Assertion supplies the per-sample flag, and the gate supplies the tolerance.

A speed check is a gentle tool, but the tests it lives in can still cause harm if handled carelessly.

The assertion adds no load

The Duration Assertion sends nothing and creates no traffic. The load comes from the plan around it. Safety rules for the test, such as permission, preparation and limits on thread counts, apply fully.

Test only what you are allowed to test

Running a load test against a system you do not own, or have no written permission to test, can disrupt it and may be illegal. Test in an environment you control or have been given. Warn the operators before a heavy run, because unannounced traffic looks like an attack to security tools and staff.

Failure messages may reveal details

The failure message states the actual time and the limit, which is harmless. But result files that save full requests and responses may contain tokens, passwords and personal details. Treat result files as sensitive. Save only the fields you need, store them in protected folders, and delete them when the work ends.

When a Duration Assertion fails and you do not understand why, a few simple tools give the answer.

The debugging toolkit

A reliable routine

Reading the knee

The most useful discovery from a Duration Assertion is often the point where failures start. If failures begin when the number of users passes a certain level, that level is a rough measure of how much the system can take within your speed rule. Note it down, and compare it across releases.

Experienced engineers use a few reliable ways to apply time limits, and avoid a handful of tempting shortcuts.

Patterns that work

Anti-patterns to avoid

These are the habits that experienced performance engineers repeat on every project, and the slips that beginners make again and again.

Best practices checklist

Common mistakes

• Believing the assertion stops slow requests, when it only judges after the response arrives.
• Typing seconds instead of milliseconds, and failing every request.
• Using one global limit for requests of very different weight, such as a search and a large file download.
• Leaving the first slow requests of a warm-up under a strict limit.
• Reading a high error percentage as “the system is broken” when many failures are only slow successes.
• Forgetting that a green pipeline does not prove the assertions passed unless the results were checked.
• Comparing numbers from generators in different places as if they measured the same thing.
• Blaming the server for failures that line up with a stressed load generator.

Here is how teams use the Duration Assertion in different kinds of systems. These are illustrative patterns that show the kind of scale and care involved, not descriptions of any company’s private tooling.

What these examples share

In every case, the assertion is a small part of a wider design. The limits come from real expectations, they are paired with content checks and timeouts, the load generator is watched, and the final judgement is made on saved results with proper statistics.

The Duration Assertion is simple and useful, and it has clear edges. Other tools fill the gaps.

Alternatives and complements

Closed model and tail latency

A normal thread group is a closed model. A fixed number of users each wait for a response before sending the next request. When the server stalls, those users send fewer requests, so a stall appears in the data as one long wait rather than as many users suffering together. This is sometimes called coordinated omission. It means the failures counted by a Duration Assertion in a closed test may understate how bad a stall was for real users, who would have kept arriving. For tail latency, complement the assertion with a fixed-rate test, which keeps sending requests at a steady rate whether or not the server keeps up.

Short, direct answers to the questions people ask most often about the Duration Assertion.

The Duration Assertion is a small element that turns “too slow” into something a report can count. Used with care, it keeps speed promises visible. Used carelessly, it creates noise.