Introduction & Architecture

The official documentation is explicit: JMeter works at protocol level. For a web application it can mimic what a browser sends (headers, cookies, form posts, embedded resources), but it does not perform all browser actions. In particular it does not run the JavaScript found in HTML pages and it does not render pages, so the time a browser would spend executing scripts and painting the page is not part of any sample. A JMeter response time is the time to send a request and receive the response, for an application whose front end does heavy client-side work that is only a part of what a user feels.

This has two practical consequences. First, single-page applications must be tested at the API level: the plan calls the JSON endpoints the front end calls (for Bookshelf, GET /api/books?query= and POST /api/loans), not the page that displays them. Second, front-end performance (rendering, script execution, Core Web Vitals) needs a browser-driven tool; the Playwright, Cypress and Selenium material of this documentation (tracked as issue #258) covers browser automation, and the two approaches complement each other.

The table lists what the official site and the user manual name as supported by a standard installation, and what needs an external jar or a community plugin. Anything not in the first rows should be treated as unsupported in core.

Source: Apache JMeter home page

The figure reads from top to bottom. A test plan (the .jmx file) is opened either in GUI mode, to design and debug it, or by CLI mode, to run it. The engine inside one JVM reads the tree and starts the thread groups. Each thread of a thread group is one virtual user and repeatedly walks the plan: every sampler sends a request to the system under test and the response is turned into a result. Results flow to the listeners in scope, which display them or store them in a JTL file. The HTML dashboard is generated from that file after (or, with -g, long after) the run, and the Backend Listener can stream the same numbers to a time-series database while the test is running.

JMeter uses a thread-per-user model. A thread group is configured with a number of threads, and each one is a real Java thread that executes the elements below the thread group in tree order, one after another, completely independently of the other threads. Within a thread the work is synchronous: a thread sends a request and blocks until the response arrives (or a timeout fires), then runs the next element. The official test plan page states it this way: each thread executes the test plan in its entirety and completely independently of other test threads.

Several consequences follow from this model, and later pages build on each of them.

A test plan is a hierarchy of test elements. The position of an element in the tree defines what it applies to: a config element, timer, assertion or listener affects the samplers in its branch (its scope), and a timer or assertion placed at the top level applies to every sampler below it. For each sampler JMeter processes the elements in scope in a fixed order.

Logic controllers and samplers run in tree order, and timers, assertions and processors run only when a sampler they apply to is present. Because the order is fixed by element type and not by position among siblings, putting an assertion above its sampler in the tree makes no difference. The dedicated page on execution order and scoping works through the rules and their exceptions.

A minimal saved plan looks like this. The root element carries the JMeter version that wrote it, and every element is followed by a hashTree holding its children.

The fragment is shortened to the properties that matter here; JMeter itself writes more properties (for example HTTPSampler.follow_redirects) and the exact set depends on the version. Always create plans through the GUI or a generator and treat the XML as something to read and review, not to hand-write.

Source: Elements of a Test Plan

When a sampler finishes it returns a SampleResult: an object recording the sampler label, the start time, the elapsed time, the latency (time to the first byte), the connect time, the response code and message, whether the sample was successful, the number of bytes and the response data. The post-processors and assertions of that sampler run against the result (an assertion failure marks the sample as failed), and then every listener in scope receives it. A listener is just a consumer of results, so the same stream can be shown in a tree, aggregated into a table, written to a file and sent to a database at once. Listeners are therefore also the main source of load-generator overhead: see the next section.

The sample file written by a listener or by the -l option of the command line is called a JTL file. By default it is a CSV file with a header line, one row per sample, and the columns are controlled by jmeter.save.saveservice.* properties. An XML format exists, but it is far larger and is not used for load tests. The HTML dashboard is generated from a CSV JTL file, which is why the later page on results files treats the column configuration carefully.

The root element has a small set of settings that affect the whole run.

Source: Test Plan (Component Reference)

The setUp and tearDown thread groups behave exactly like normal thread groups, except that setUp threads run before the regular thread groups and tearDown threads after they finish. A typical Bookshelf use is a setUp group that creates a test user and a tearDown group that deletes the loans created during the run.

Source: setUp Thread Group (Component Reference)

Unit and integration tests answer whether an answer is correct for one caller. Load tests answer how the system behaves when many callers arrive together: latency percentiles, throughput, error rate and saturation. JMeter is built for the second job, but because it has assertions, extractors, logic controllers and JUnit and JDBC samplers it can also run functional or integration checks: the Test Plan element even has a Functional Test Mode that records full request and response data for that purpose. The two uses should not share a plan. A functional plan has one user, many assertions and saves everything; a load plan has many users, few assertions and saves the minimum.

For Bookshelf, one .jmx file can hold both a journey with strict assertions run by a single user in CI as a smoke test, and the same journey with relaxed assertions run by 50 users. The section builds exactly that, as the smoke profile in the first case and the load profile in the second.

JMeter is not the only choice and the section does not teach the others. Gatling (plans written as code in a Scala, Java or Kotlin DSL), k6 (scripts written in JavaScript) and Locust (users written as Python classes) are widely used alternatives with a code-first workflow; JMeter’s strengths are the GUI for building plans, the broad protocol coverage through its samplers and plugins and the large body of existing plans and knowledge. The choice is mostly about team skills and the protocols needed. JMeter also has programmatic routes (the 5.6 Java and Kotlin DSL and the third-party JMeter Java DSL) described near the end of the section.