JMeter HTTP(S) Test Script Recorder Guide

JMeter HTTP(S) Test Script Recorder Guide

The HTTP(S) Test Script Recorder is the fastest way for many teams to draft a JMeter web or browser-mediated API plan: run JMeter’s proxy, point the browser at it, click through a journey, and obtain HTTP Request samplers automatically. This guide covers how recording works, the recommended template workflow, HTTPS certificates, include/exclude filters, post-recording cleanup, correlation, and troubleshooting - based on the official proxy step-by-step, component reference, and best practices.

Filter before you record

The most important recording skill is excluding noise (images, CSS, analytics). Unfiltered sessions create unmaintainable plans. Official best practices stress include/exclude patterns up front.

Recording improved since JMeter 2.10

Since JMeter 2.10, recording better handles embedded resources and on-the-fly certificates. You need a working keytool (from the JRE/JDK). See the Apache wiki link in the step-by-step tutorial if certificate generation fails.

How the recorder works

1. JMeter starts an embedded HTTP proxy (default port 8888 in the browser tutorial).
2. The browser sends traffic through that proxy.
3. JMeter creates HTTP Request samplers (and related elements depending on settings) under a Target Controller.
4. Responses still return to the browser so you can navigate normally.

The recorder is not a full browser driver: it captures HTTP(S) conversations. Client-side JavaScript timing and in-page rendering are outside JMeter’s model (same as other HTTP sampler testing).

Where samples are stored

From the component reference and best practices:

• The recorder expects a Thread Group with a Recording Controller (or you set Target Controller explicitly).
• Default behaviour often stores samples under the first Recording Controller when “Use Recording Controller” is selected.
• Always add a Recording Controller before you start recording if you rely on that default.

Recommended quick start (Recording template)

Official basic instructions:

1. Start JMeter from JMETER_HOME/bin (jmeter / jmeter.bat / jmeterw.bat as appropriate).
2. Open Templates… on the menu bar.
3. Select the Recording template and create the plan.
4. In HTTP Request Defaults, set Server name or IP (and clear or set path as appropriate).
5. Open HTTP(S) Test Script Recorder and click Start.
6. Install the generated CA certificate for HTTPS (next section).
7. Configure the browser proxy to the recorder host/port.
8. Navigate the application.
9. Stop the recorder; save the plan; validate with a low thread count.

The template approach is preferable to hand-assembling proxy + controllers when you are learning.

Configure the browser proxy

From the Firefox-oriented tutorial (same ideas apply to other browsers):

1. Keep JMeter running with the recorder Started.
2. Browser network settings → Manual proxy configuration.
3. HTTP proxy host: localhost (or the machine running JMeter).
4. Port: 8888 (or whatever you set on the recorder).
5. Use this proxy for all protocols when recording HTTPS through the same proxy.
6. Browse the site; samplers appear under the target controller.

Localhost proxy pitfalls

Best practices note:

• If the browser works even when JMeter is not running, it is not using the proxy.
• Some browsers ignore proxy settings for localhost / 127.0.0.1. Try the LAN hostname or machine IP in the browser URL bar and ensure the proxy still points at JMeter.
• Corporate PAC files and system VPNs often bypass or block local proxies - use a clean browser profile when possible.

HTTPS and the JMeter CA certificate

When you Start the recorder, JMeter generates/export certificates for MITM HTTPS recording.

Certificate files

Documented names:

• ApacheJMeterTemporaryRootCA.crt (and related .usr variants on some platforms) in the JMeter launch directory (typically JMETER_HOME/bin when started from there).
• Underlying keystore file proxyserver.jks - delete it to force regeneration if certificates are stale (component reference).

Install the CA in the browser / OS

The component reference includes install steps for major browsers: trust ApacheJMeterTemporaryRootCA as a certificate authority for websites. Until it is trusted, HTTPS sites show errors or the recorder sees unknown_ca-class failures.

Best practices:

The error unknown_ca probably means you are trying to record HTTPS and the browser has not accepted the JMeter Proxy server certificate.

After installing:

1. Restart the browser if required by your OS.
2. Start the recorder again if needed.
3. Visit an HTTPS page and confirm samplers appear without TLS errors in the browser.

Corporate SSL inspection

If the enterprise already intercepts TLS, you may stack trust issues (enterprise CA + JMeter CA). You may need both CAs trusted, or record in an environment without double inspection. This is environmental - not a JMeter checkbox.

Include and exclude patterns (keep plans maintainable)

Best practices § Using the HTTP(S) Test Script Recorder:

• Filter out requests you do not care about (for example images). JMeter can download embedded resources later via HTTP Request options if you need them.
• Prefer an include pattern when your app shares an extension (.*\.jsp, .*\.html, …).
• Or exclude patterns like .*\.gif and similar static types.
• Also exclude stylesheets, JavaScript files, and other includes when they are not part of the performance question.
• Test patterns, then erase and re-record cleanly.

Default-ish exclude suggestions appear in properties such as proxy.excludes.suggested (see properties reference) covering common static extensions (css, js, png, woff, …).

Grouping

Recorder settings can group samples (for example by first URL path segment or separators) to keep the tree readable. Use grouping so a multi-page journey does not become a flat list of hundreds of samplers without structure.

Abstracting common values while recording

One of the most useful documented features: define User Defined Variables (or Test Plan variables) such as server=xxx.example.com before/during recording so JMeter can replace matching values in recorded samples with \${server}.

Notes:

• Replacement matching is case-sensitive.
• This reduces later cleanup when promoting plans across environments.

Combine with \${__P(host,)} after recording if CI must override hosts (functions guide).

After recording: mandatory cleanup checklist

A raw recording is a draft, not a finished load test.

1. Save the test plan under a meaningful name (best practices: save each test case draft, wipe, record the next).
2. Set HTTP Request Defaults so samplers are not full of repeated server/port fields (tutorial warning: forgetting defaults means manual cleanup).
3. Add HTTP Cookie Manager for session cookies (web test plan).
4. Add Header Manager only where needed; remove noisy browser headers you do not intend to simulate.
5. Correlate dynamic values: CSRF tokens, viewstate, session IDs, redirect IDs - use Regular Expression Extractor, JSON Extractor, etc.
6. Replace hard-coded logins with CSV Data Set users (best practices).
7. Add assertions (status, key text/JSON) so errors surface.
8. Insert timers for think time if modelling users.
9. Disable View Results Tree before load; run CLI for real volume.
10. Parameterize threads/host with \${__P(...)} for automation.

Correlation is the hard part

Recorded scripts often fail on replay because tokens changed. Workflow:

1. Replay with one thread.
2. Find the first red sampler in View Results Tree.
3. Inspect the previous response for the dynamic value.
4. Add an extractor; replace hard-coded recorded value with \${var}.
5. Repeat until the journey passes.

Use the Regex Extractor Builder to draft regex fields from a pasted response body (browser-local).

Validate before load

From the step-by-step tutorial: validate the script before a real test. Practical approach:

1. Thread Group: 1 thread, 1 loop (or a short ramp).
2. View Results Tree enabled.
3. Run; fix correlation and assertions.
4. Only then increase threads and switch to non-GUI:

jmeter -n -t recorded-journey.jmx -l results.jtl -e -o report/

Recorder settings worth knowing

Consult the HTTP(S) Test Script Recorder component reference for the full field list. Concepts you will configure often:

Setting	Why it matters
Port	Must match browser proxy
Target Controller	Where samplers land
Grouping	Tree readability
Patterns to include/exclude	Noise control
Follow redirects / session options	Depends on app (verify replay)
Create new transaction after request (ms)	Splits bursts into transactions

Exact labels vary slightly by JMeter version - use the reference for your release.

Alternatives to the proxy recorder

Approach	When to use
HTTP(S) Test Script Recorder	Browser HTML apps, cookie-heavy flows, quick drafts
cURL import	API calls already available as curl/Postman exports
Manual HTTP Request samplers	Simple APIs, maximum clarity
Access log sampler tutorial	Replaying production-like HTTP logs

Choose recording when user journeys are easier to click than to hand-author; choose cURL/manual when the surface is pure JSON APIs.

Security and privacy

• Recorded plans may contain session cookies, tokens, and personal data. Treat .jmx as sensitive.
• The JMeter CA allows JMeter to decrypt HTTPS for recording - use only on machines and networks you control.
• Remove secrets before committing plans to git; switch to CSV/__P for credentials.
• Stop the recorder and revert browser proxy settings after sessions so traffic is not accidentally sent to a closed proxy.

Troubleshooting

Symptom	Likely cause	Fix
No samples recorded	Browser not using proxy	Verify proxy; try non-localhost URL; disable PAC
HTTPS errors / unknown_ca	CA not trusted	Install ApacheJMeterTemporaryRootCA.crt
Only some pages record	Include pattern too strict	Broaden include or use excludes instead
Huge messy plan	No excludes	Add static excludes; re-record
Replay fails at login	Dynamic token	Correlate CSRF/session; Cookie Manager
Works in browser during record, fails in JMeter	Missing headers, body, or async API calls	Compare View Results Tree request to browser devtools
Certificate age issues	Old keystore	Delete proxyserver.jks and regenerate per docs
keytool errors	JDK tools missing/misconfigured	Fix JAVA_HOME / keytool per JMeter 2.10+ recording wiki

Recording API-only vs full browser journeys

Browser HTML applications

Recording shines when:

• Flows span many pages and redirects.
• Cookies and form fields are tedious to hand-build.
• Business users can click a script while performance engineers clean it.

Expect heavy correlation for modern single-page apps that call JSON APIs underneath. Often the maintainable end state is: record once to discover API calls, then rebuild a slim API-level plan (API load testing).

API-only services

If developers already give you OpenAPI examples or curl commands, cURL import may produce a cleaner tree than a browser recording full of static assets and third-party tags. Use the recorder when the only documentation is “click through the UI.”

Transaction naming after recording

Raw sampler names are often full paths or query strings. Before load:

• Rename samplers to stable business labels (Login, Search, AddToCart).
• Wrap multi-step sequences in Transaction Controllers so the dashboard reports user-meaningful transactions.
• Apply jmeter.reportgenerator.exporter.html.series_filter when you only want certain labels in the HTML report.

Stable names make CI gates and trend charts possible; recorded URL labels churn every time the front-end router changes.

Team workflow: from recording to repository

1. Engineer records in a sandbox with synthetic users.
2. Correlation and CSV parameterization land in a feature branch.
3. Peer review checks: no secrets, listeners off, \${__P} for host/threads.
4. CI smoke runs the plan non-GUI against staging (CI/CD).
5. Nightly job increases threads only after smoke is green.

Treat the first recording as throwaway discovery if the cleaned plan diverges heavily - do not romanticize the raw tree.

End-to-end checklist

1. Recording template created; defaults server set.
2. Recording Controller present; target set.
3. Include/exclude patterns configured and smoke-tested.
4. Recorder started; CA installed for HTTPS.
5. Browser proxy → JMeter port.
6. Journey executed once cleanly.
7. Recorder stopped; plan saved.
8. Cookie manager, correlation, assertions added.
9. One-thread validation green.
10. CLI load run with listeners off.
11. Sampler labels stabilized; secrets removed.
12. Plan documented with required -J properties and CSV layout.

Related reading

• Proxy step-by-step (official tutorial)
• Best Practices - recorder & variables
• Building a Web Test Plan
• Regular Expressions
• cURL import
• API load testing

Frequently asked questions

What port does the JMeter recorder use?

The step-by-step tutorial configures the browser for port 8888, which is the usual default. Always match the port shown in the HTTP(S) Test Script Recorder panel.

Why do I need ApacheJMeterTemporaryRootCA.crt?

HTTPS recording requires JMeter to present certificates to the browser. Trusting JMeter’s temporary root CA allows the browser to accept that TLS interception for test traffic.

Should I record images and CSS?

Usually no. Best practices say to filter them out; JMeter can fetch embedded resources from HTML if you enable that on HTTP Request for a deliberate reason.

Workbench or Test Plan?

Modern JMeter workflows use the Recording template and elements in the Test Plan tree (Thread Group + Recording Controller + recorder). Rely on current templates rather than obsolete Workbench-centric instructions from very old tutorials.

Why does replay fail immediately after a perfect recording?

Dynamic values (tokens, timestamps, nonces) embedded in the recording expired or changed. Correlate them with extractors and ensure a Cookie Manager is present.

Can I record mobile app traffic?

If the mobile client can use an HTTP proxy and trusts the JMeter CA (or you use a device proxy setup), you can capture HTTP(S) API calls. Platform-specific TLS pinning may block interception.

Is recording enough for a production load test?

No. Recording is a draft generator. You still need parameterization, correlation, assertions, timers, CLI execution, and sensible thread sizing (Thread Calculator).

Continue Learning

→

Next Practical Step

Use the Recording template once end-to-end, then clean the plan with Cookie Manager and one correlated token.

📖

Related Reference

• cURL Import - alternative for API-only traffic
• Access Log Sampler - production log replay
• Regex Extractor Builder - correlation helper
• Building a Web Test Plan - structure after recording

⚠

Common Mistakes

Recording without excludes; committing secrets inside recorded headers; load-testing a raw recording with View Results Tree enabled; forgetting the Cookie Manager.

🔧

Troubleshooting

If nothing records, the browser is not proxying. If HTTPS fails with unknown_ca, reinstall the JMeter root CA. If replay fails mid-flow, correlate the first dynamic value that differs from the recording.