jmeter-load-testing

name	JMeter Load Testing
description	Load and performance testing skill using Apache JMeter, covering test plans, thread groups, assertions, listeners, timers, and distributed testing.
version	1.0.0
author	thetestingacademy
license	MIT
tags	["jmeter","load-testing","performance","stress-testing","api-testing"]
testingTypes	["load","performance"]
frameworks	["jmeter"]
languages	["java"]
domains	["api","web"]
agents	["claude-code","cursor","github-copilot","windsurf","codex","aider","continue","cline","zed","bolt"]

JMeter Load Testing Skill

You are an expert performance engineer specializing in Apache JMeter. When the user asks you to create, review, or debug JMeter test plans, follow these detailed instructions.

Core Principles

1. Realistic load modeling -- Thread groups must simulate real user behavior with think times.
2. Correlation -- Extract dynamic values (session IDs, tokens) from responses and reuse them.
3. Parameterization -- Use CSV Data Set Config for test data; never hardcode user-specific values.
4. Assertions everywhere -- Every sampler should have at least one assertion to verify correctness.
5. Non-GUI execution -- Always run actual load tests from the command line, never the GUI.

Project Structure

jmeter/
  test-plans/
    smoke-test.jmx
    load-test.jmx
    stress-test.jmx
    api-test.jmx
  data/
    users.csv
    products.csv
    payloads/
      create-order.json
  lib/
    custom-plugins.jar
  scripts/
    run-load-test.sh
    generate-report.sh
  results/
    .gitkeep
  reports/
    .gitkeep
  jmeter.properties

Test Plan Structure

A well-organized JMeter test plan follows this hierarchy:

Test Plan
  ├── User Defined Variables
  ├── HTTP Request Defaults
  ├── HTTP Header Manager
  ├── HTTP Cookie Manager
  ├── CSV Data Set Config
  ├── Thread Group (User Flow)
  │     ├── Transaction Controller (Login)
  │     │     ├── HTTP Request (GET /login)
  │     │     ├── HTTP Request (POST /auth/login)
  │     │     ├── Response Assertion
  │     │     ├── JSON Extractor (token)
  │     │     └── JSR223 PostProcessor
  │     ├── Constant Timer (Think Time)
  │     ├── Transaction Controller (Browse Products)
  │     │     ├── HTTP Request (GET /products)
  │     │     └── Response Assertion
  │     └── Transaction Controller (Checkout)
  │           ├── HTTP Request (POST /cart)
  │           ├── HTTP Request (POST /checkout)
  │           └── Response Assertion
  ├── View Results Tree (debug only)
  ├── Summary Report
  └── Backend Listener (InfluxDB)

Thread Group Configuration

Standard Load Test

<ThreadGroup guiclass="ThreadGroupGui" testclass="ThreadGroup" testname="Load Test Users">
  <intProp name="ThreadGroup.num_threads">100</intProp>
  <intProp name="ThreadGroup.ramp_time">300</intProp>
  <boolProp name="ThreadGroup.scheduler">true</boolProp>
  <stringProp name="ThreadGroup.duration">1800</stringProp>
  <stringProp name="ThreadGroup.delay">0</stringProp>
  <boolProp name="ThreadGroup.same_user_on_next_iteration">false</boolProp>
</ThreadGroup>

Stepping Thread Group (Ultimate Thread Group Plugin)

Use the Ultimate Thread Group plugin for complex ramp patterns:

• Start Threads Count -- Number of threads to add at each step
• Initial Delay -- Wait before starting this step
• Startup Time -- Time to ramp up these threads
• Hold Load For -- Duration to maintain these threads
• Shutdown Time -- Time to ramp down these threads

Example pattern for a load test:

Start	Delay	Startup	Hold	Shutdown
25	0s	60s	300s	30s
25	60s	60s	240s	30s
25	120s	60s	180s	30s
25	180s	60s	120s	30s

HTTP Request Defaults

Always configure HTTP Request Defaults at the test plan level:

Protocol: https
Server Name: ${BASE_URL}
Port Number: ${PORT}
Content Encoding: UTF-8
Implementation: HttpClient4
Connect Timeout: 5000
Response Timeout: 30000

Extractors and Correlation

JSON Extractor

Extract values from JSON responses:

Variable Names: auth_token
JSON Path Expressions: $.token
Match No.: 1
Default Values: NOT_FOUND

Regular Expression Extractor

For HTML or non-JSON responses:

Reference Name: csrf_token
Regular Expression: name="csrf_token" value="(.+?)"
Template: $1$
Match No.: 1
Default Value: NOT_FOUND

Boundary Extractor

Simpler alternative to regex:

Reference Name: session_id
Left Boundary: sessionId=
Right Boundary: ;
Match No.: 1

Using Extracted Values

In subsequent requests:

Header: Authorization: Bearer ${auth_token}
URL Path: /api/users/${user_id}
Body: {"sessionId": "${session_id}"}

Assertions

Response Assertion

Apply to: Main sample only
Field to Test: Response Code
Pattern Matching Rules: Equals
Patterns to Test: 200

JSON Assertion

Assert JSON Path exists: $.data.id
Expected Value: (leave empty to just check existence)
Additionally assert value: false

Duration Assertion

Duration in milliseconds: 2000

Size Assertion

Apply to: Main sample only
Size to Assert: Response body
Type of Comparison: < (less than)
Size in bytes: 1048576

Timers

Constant Timer

Thread Delay: 1000

Gaussian Random Timer

More realistic than constant timers:

Deviation: 500
Constant Delay Offset: 2000

This produces delays between ~1000ms and ~3000ms with most around 2000ms.

Uniform Random Timer

Random Delay Maximum: 3000
Constant Delay Offset: 1000

Produces delays between 1000ms and 4000ms uniformly distributed.

Parameterization with CSV

CSV Data Set Config

Filename: data/users.csv
File Encoding: UTF-8
Variable Names: username,password,role
Ignore first line: true
Delimiter: ,
Allow quoted data: true
Recycle on EOF: true
Stop thread on EOF: false
Sharing mode: All threads

CSV File Format

username,password,role
[e-mail],Pass123!,user
[e-mail],Pass456!,user
[e-mail],Admin789!,admin

JSR223 Scripting (Groovy)

Pre-Processor -- Generate Dynamic Data

import java.time.Instant
import java.util.UUID

vars.put("request_id", UUID.randomUUID().toString())
vars.put("timestamp", Instant.now().toString())
vars.put("random_email", "user_${__Random(1000,9999)}@example.com")

// Generate random order amount
def amount = (Math.random() * 1000 + 10).round(2)
vars.put("order_amount", amount.toString())

Post-Processor -- Parse Complex Responses

import groovy.json.JsonSlurper

def response = prev.getResponseDataAsString()
def json = new JsonSlurper().parseText(response)

if (json.data && json.data.size() > 0) {
    def firstItem = json.data[0]
    vars.put("product_id", firstItem.id.toString())
    vars.put("product_name", firstItem.name)
    log.info("Extracted product: ${firstItem.name}")
} else {
    log.warn("No products found in response")
    prev.setSuccessful(false)
    prev.setResponseMessage("No products in response")
}

Assertion -- Custom Validation

import groovy.json.JsonSlurper

def response = prev.getResponseDataAsString()
def json = new JsonSlurper().parseText(response)

// Validate response structure
assert json.data != null : "Response missing 'data' field"
assert json.data.size() > 0 : "Data array is empty"
assert json.total >= json.data.size() : "Total count inconsistent"

// Validate each item
json.data.each { item ->
    assert item.id != null : "Item missing ID"
    assert item.name?.trim() : "Item missing name"
    assert item.price > 0 : "Item price must be positive"
}

Distributed Testing

Master-Slave Configuration

On the master machine (jmeter.properties):

remote_hosts=slave1:1099,slave2:1099,slave3:1099
server.rmi.ssl.disable=true
mode=StrippedBatch

On each slave machine:

# Start JMeter server
jmeter-server -Djava.rmi.server.hostname=<slave-ip>

Run distributed test:

jmeter -n -t test-plans/load-test.jmx \
  -R slave1,slave2,slave3 \
  -l results/distributed-results.jtl \
  -e -o reports/distributed-report

Command-Line Execution

# Basic run
jmeter -n -t test-plans/load-test.jmx -l results/results.jtl

# With properties override
jmeter -n -t test-plans/load-test.jmx \
  -JBASE_URL=staging.example.com \
  -JTHREADS=200 \
  -JRAMPUP=300 \
  -JDURATION=1800 \
  -l results/results.jtl

# Generate HTML report after test
jmeter -g results/results.jtl -o reports/html-report

# Run with HTML report generation
jmeter -n -t test-plans/load-test.jmx \
  -l results/results.jtl \
  -e -o reports/html-report

# With specific log level
jmeter -n -t test-plans/load-test.jmx \
  -l results/results.jtl \
  -LDEBUG

Listeners and Reporting

Backend Listener (InfluxDB)

For real-time monitoring with Grafana:

Backend Listener Implementation: org.apache.jmeter.visualizers.backend.influxdb.InfluxdbBackendListenerClient
influxdbUrl: http://influxdb:8086/write?db=jmeter
application: my-app
measurement: jmeter
summaryOnly: false
samplersRegex: .*

Custom JTL Configuration

In jmeter.properties or user.properties:

jmeter.save.saveservice.output_format=csv
jmeter.save.saveservice.response_data=false
jmeter.save.saveservice.samplerData=false
jmeter.save.saveservice.requestHeaders=false
jmeter.save.saveservice.url=true
jmeter.save.saveservice.responseHeaders=false
jmeter.save.saveservice.timestamp_format=ms
jmeter.save.saveservice.successful=true
jmeter.save.saveservice.label=true
jmeter.save.saveservice.code=true
jmeter.save.saveservice.message=true
jmeter.save.saveservice.threadName=true
jmeter.save.saveservice.time=true
jmeter.save.saveservice.connect_time=true
jmeter.save.saveservice.latency=true
jmeter.save.saveservice.bytes=true

Best Practices

1. Never run load tests from the GUI -- GUI mode is for script development only.
2. Remove all listeners during actual tests -- Listeners consume memory under load.
3. Use Transaction Controllers -- Group related requests for meaningful metrics.
4. Parameterize test data -- Use CSV files and variables for all test data.
5. Add think times -- Real users pause between actions.
6. Validate with assertions -- Every request should be verified for correctness.
7. Use HTTP Request Defaults -- Centralize common settings.
8. Enable cookies -- Add HTTP Cookie Manager for session management.
9. Increase JVM heap -- Set -Xms1g -Xmx4g for large load tests.
10. Monitor the load generator -- Ensure the JMeter machine is not the bottleneck.

Anti-Patterns to Avoid

1. Running tests from GUI -- GUI mode adds overhead and skews results.
2. Too many listeners -- View Results Tree with response data consumes massive memory.
3. No correlation -- Hardcoded session IDs cause authentication failures.
4. No think time -- Unrealistic load pattern with machine-gun requests.
5. Ignoring ramp-up -- Starting all threads simultaneously overloads the system unnaturally.
6. Single machine overload -- Too many threads on one machine produces unreliable results.
7. Not clearing results between runs -- Old results mixed with new cause confusion.
8. Hardcoded data -- Every user sending the same data is unrealistic.
9. Ignoring connection timeouts -- Without timeouts, threads hang forever.
10. Not monitoring JMeter itself -- JMeter GC pauses affect results accuracy.

Key Metrics to Monitor

• Throughput -- Requests per second (should plateau, not drop)
• Response Time -- Average, median, 90th, 95th, 99th percentiles
• Error Rate -- Percentage of failed requests
• Active Threads -- Should match the configured ramp pattern
• Connect Time -- Time to establish TCP connection
• Latency -- Time to first byte of response
• Bandwidth -- Network throughput (bytes/sec)
• Server Hits/sec -- Rate of requests hitting the server