HTTP Requests

A minimal HTTP test needs a Thread Group, one HTTP Request Defaults, the managers the requests need and the samplers. Defaults and managers placed directly under the Thread Group (or the Test Plan) apply to every sampler below them; placed under one sampler, they apply to that sampler only. The scoping and merging rules are explained on Test Plan Elements, Execution Order & Scoping.

When a thread reaches a sampler, JMeter merges the configuration in scope into a copy of the sampler, runs the pre-processors and timers, sends the request and hands the result to post-processors, assertions and listeners. The sequence for one HTTP sample:

Source: Elements of a Test Plan (User Manual) and HTTP Request (Component Reference)

The timings in the result are defined in the glossary: elapsed time runs from just before the request is sent to just after the last byte of the response is received; latency from just before sending to just after the first part of the response arrives; connect time is the time to open the connection, including the TLS handshake. Connect time is not subtracted from latency, and it is only non-zero when a new connection is opened, so with keep-alive most samples of a thread show a connect time of 0.

Source: Glossary (User Manual)

The steps below create the first version of bookshelf-load.jmx: one Thread Group, the HTTP Request Defaults pointing at the local Bookshelf API, and one GET /api/books request. The Bookshelf API runs on localhost:8080, started with Docker Compose as described in Compose for Local Development; its endpoints are the ones built on REST APIs.

Because host and port are properties with defaults, the same plan runs against localhost:8080 by default and against any other environment with -Jhost=... -Jport=..., without editing the file. Property names threads, rampup, duration, host and port are used for the same purposes on every page of this section.

Source: Building a Web Test Plan (User Manual)

The HTTP Request panel has two tabs, Basic and Advanced. The tables list every field in JMeter 5.6.3 with the English GUI label, the property stored in the .jmx file and what the component reference says about it. The defaults column gives the value of a newly added sampler.

The method decides where parameters go. The table summarises the rules of the component reference’s "Parameter Handling" and "Method Handling" notes.

GET, DELETE, PUT and PATCH requests that carry a body need a Content-Type: add a Header Manager under the sampler and set it there. For POST, the property http.post_add_content_type_if_missing decides whether JMeter adds application/x-www-form-urlencoded when the header is missing; it defaults to false since 5.0 (Bug 60190).

URL encoding. Selecting URL Encode? on a parameter is almost always right: values with spaces, non-ASCII characters or reserved characters such as &, =, +, ? or / must be encoded. A value that is already encoded (copied from a browser address bar) must not be encoded twice.

Content encoding. Since 5.6.1 an empty Content encoding means UTF-8: parameter names, values and file names with Unicode characters are sent correctly without setting anything. The property sampleresult.default.encoding, which decides how a response without a charset is decoded, also defaults to UTF-8 since 5.6.1. Plans written for older versions sometimes set UTF-8 explicitly; that is harmless.

A search with a non-ASCII term on the Bookshelf API, written with parameters:

With term set to García Márquez (from search-terms.csv, see Parameterization & Test Data), the request line is GET /api/books?query=Garc%C3%ADa+M%C3%A1rquez.

The same API’s POST /api/loans takes a JSON body. With Body Data the sampler stores the body as one unnamed argument and sets HTTPSampler.postBodyRaw; the Content-Type comes from a Header Manager placed under the sampler:

The Authorization header the loan endpoint also needs, and the extraction of bookId and the token from earlier responses, are covered on the sessions page and on Correlation & Extractors.

Source: HTTP Request (Component Reference, Parameter Handling and Method Handling), Properties Reference (Apache HttpClient common properties) and Changes History (5.6.1)

Two check boxes control redirects, and they behave very differently:

Related properties: httpsampler.max_redirects (default 20) limits the redirects followed in one sequence, and JMeter collapses /../segment in redirect URLs unless httpsampler.redirect.removeslashdotdot=false. The message "Redirect requested but followRedirects is disabled" in the log can be ignored. For REST APIs a redirect is usually a bug or a missing trailing slash; keep Follow Redirects on and assert on the final status, or switch it off and assert that the 3xx itself is returned when the redirect is the behaviour under test.

The 5.6.3 sampler handles 307 and 308 like the other redirects. Preserving the original method on 307 and 308 (as the HTTP specification requires) is a change planned for 6.0 in changes.xml on the master branch.

Source: HTTP Request (Component Reference) and Properties Reference (Miscellaneous configuration)

With Use KeepAlive and HttpClient4, a thread reuses its connection from one request to the next, as a browser or an HTTP client library in a microservice would. The server then sees a fixed number of long-lived connections (one or a few per virtual user) and most samples show a connect time of 0. Without keep-alive every request opens a new TCP connection and, with HTTPS, performs a new TLS handshake: that measures connection setup as much as the API, costs CPU on both sides and can exhaust ephemeral ports on the load generator.

Connection lifetime is tuned with properties of the HttpClient4 implementation:

Retries hide errors: a request that fails once and succeeds on retry is recorded as one successful sample. Keep the retry count at 0 for load tests unless a load balancer that drops idle connections makes it unavoidable.

Source: Properties Reference (HTTPClient4) and Properties Reference (SSL configuration)

Files go in the Files Upload tab: one row per file with File Path (relative to the .jmx directory, or absolute), Parameter Name (the form field name) and MIME Type (guessed from the file when empty). With at least one file the request becomes multipart/form-data; any other parameters become parts of the same form. Multipart and file upload work with POST only. For PUT or PATCH, or for a POST whose body is just the file, leave Parameter Name empty: the file is then sent as the whole body, with MIME Type as Content-Type.

The Bookshelf API has no upload endpoint; the fragment below shows the shape for a cover-image upload of the kind many APIs expose (POST /api/covers, a field named cover and a bookId form field), to adapt to a real endpoint of the system under test:

Source: HTTP Request (Component Reference, File Path, Parameter name, MIME Type)

Load-generator cost of uploads. JMeter reads the file for every request, so 50 threads uploading a 2 MB file at one upload per second each send about 100 MB/s, which saturates a 1 Gbit/s network link (about 125 MB/s) before the server does anything. Keep files small, or make sure the network and disk of the generator are part of the capacity check. In a distributed run, the files must exist on every load generator, like CSV data files.

Retrieve All Embedded Resources makes JMeter behave a little like a browser for HTML pages: it parses each HTML (and CSS) response and fetches the referenced resources. The parsers are configured with HTTPResponse.parsers (default htmlParser wmlParser cssParser); the HTML parser is LagartoBasedHtmlParser by default (htmlParser.className), and httpsampler.max_frame_depth (default 5) limits frame nesting. Resources are recorded as sub-samples of the page; httpsampler.ignore_failed_embedded_resources=true stops a failed resource from failing the parent, and httpsampler.embedded_resources_use_md5=true keeps only their size and MD5.

Filters keep the download to what a real browser of the application would fetch from the system under test. To fetch only resources from the Bookshelf host and skip images in any case:

For a JSON API, as Bookshelf is, leave the option off: there is nothing to parse, and parsing costs CPU. JMeter has no browser cache unless an HTTP Cache Manager is added, and it never executes JavaScript, so resources loaded by scripts are not fetched.

Source: HTTP Request (Component Reference) and Properties Reference (HTML Parser configuration)

Load-generator cost. Each page with embedded resources becomes many requests: a page with 30 resources and 50 users is 1 550 requests per page view. With Parallel downloads each thread uses up to the pool size (default 6) extra download threads, so 50 users can mean 300 extra threads on the generator; their keep-alive time is httpsampler.parallel_download_thread_keepalive_inseconds (default 60).

HttpClient4 is the default and the right choice for load testing; there is little reason to use Java today. The implementation can be set per sampler, once in the HTTP Request Defaults, or globally:

The component reference contradicts itself on the fallback: the HTTP Request entry says HttpClient4 is used when nothing is set, the HTTP Request Defaults entry says Java. The 5.6.3 source (HTTPSamplerFactory) reads jmeter.httpsampler with HttpClient4 as its default, and the properties reference gives the same default, so HttpClient4 is what runs.

Source: HTTP Request (Component Reference) and Properties Reference (jmeter.httpsampler)

HTTPS needs nothing more than https in Protocol (and usually port 443 or 8443). JMeter uses the TLS implementation of the JVM (JSSE), so the protocol versions and cipher suites available are those of the Java runtime that runs JMeter.

By default JMeter resolves host names through the JVM, which caches the result. Behind a DNS-based load balancer or CDN, every virtual user then talks to the same address and only one server of the cluster gets the load. The DNS Cache Manager (Add → Config Element → DNS Cache Manager) resolves names separately for each thread and keeps the result in its own cache, independent of the JVM and operating system caches. It can also map names to addresses like an /etc/hosts file, so a plan can use the real host name while the requests go to a test server.

It belongs at the root of the Thread Group or Test Plan, never under a single sampler, and it works only with the HttpClient4 implementation.

A DNS Cache Manager that sends requests for bookshelf.example.test to the local Compose stack, while the requests keep Host: bookshelf.example.test (useful when a reverse proxy routes on the host name):

Run it with -Jhost=bookshelf.example.test. Per-thread resolution costs one DNS lookup per thread (and per iteration with Clear cache each iteration): with 50 threads and iterations of a few seconds that is tens of lookups per second against the DNS server, which is part of the load.

Source: DNS Cache Manager (Component Reference)

A load generator on the same network as the server downloads responses far faster than users on mobile networks do, which keeps connections short and hides the effect of slow clients on server threads and connection pools. JMeter can emulate slow connections with two properties, in characters (bytes) per second; 0, the default, disables throttling:

Worked numbers: a Bookshelf search response of 24 KB takes about 24 000 / 125 000 = 0.19 s to read at that rate, on top of the server time. With 50 threads and a server time of 50 ms, each thread completes a request about every 0.24 s instead of every 0.05 s, so the closed-model throughput falls from about 1 000 to about 210 requests per second, while the server holds about four times as many open responses at any moment. The HttpClient4 implementation supports both properties; the Java implementation only the HTTPS one.

Source: Properties Reference (Apache HttpClient common properties) and HTTP Request (Component Reference, Emulating slow connections)

Bandwidth throttling with these properties is the technique described in the JMeter Cookbook (chapter 8) and Pro Apache JMeter (chapter 10); it is unchanged in 5.6.3.

Core JMeter speaks HTTP/1.1 (httpclient.version defaults to 1.1); it has no HTTP/2 support. HTTP/2 load comes from the community BlazeMeter - HTTP Plugin (Plugins Manager id bzm-http2, version 3.2.0 in the catalogue, covering HTTP/1.1, HTTP/2 and HTTP/3; the older Java 8 bzm-http2-legacy is deprecated), which adds its own sampler. It is installed through the Plugins Manager like any plugin, and is covered with the other plugins later in this section. jmeter-plugins.org is an independent community catalogue, not an Apache project.

Source: JMeter Plugins repository catalogue and BlazeMeter HTTP Plugin README

The plan built above, bookshelf-load.jmx, now runs as a smoke test: one user, ten iterations of GET /api/books?query=java. GUI mode is for building and debugging; tests run in CLI mode.

Reading the rows:

Source: Getting Started (CLI mode), Glossary (User Manual) and Response Assertion (Component Reference)

The same plan then runs the load profile used across the section (50 threads, a 60 s ramp-up, held for 10 minutes) once the Thread Group is switched to a lifetime of ${__P(duration,660)} seconds with infinite loops, as shown on the thread groups page:

Worked numbers for this profile: 50 threads over 60 s start 0.83 threads per second. With no think time and a 25 ms response, each thread could send about 40 requests per second, so 50 threads would aim at about 2 000 requests per second against one endpoint, which measures the API’s ceiling, not realistic use. With the 3 s average think time the Bookshelf journey uses (see Timers & Think Time), each thread sends 1 / (3 + 0.025) ≈ 0.33 requests per second, about 16.5 requests per second for 50 users. Adding think time before any real run is the next step after this smoke test. Running tests in CLI mode, the results file and the HTML dashboard are covered in detail later in this section.

Source: Getting Started (CLI mode)

The HTTP sampler is cheap per request compared with the server’s work, but a few options multiply its cost:

The JMeter best practices are to run load in CLI mode, with few listeners and assertions and results saved as CSV; they apply to every HTTP plan.

Source: Best Practices and Properties Reference (Miscellaneous configuration)

Source: Changes History and changes.xml on the master branch (planned 6.0)