---
title: "JMeter HTTP(S) Test Script Recorder Guide"
description: "Record browser traffic with the JMeter HTTP(S) Test Script Recorder: proxy port 8888, SSL root CA, include/exclude filters, and post-record cleanup."
url: https://docs.jmeter.ai/topics/http-recorder/
lastUpdated: 2026-10-01
source: docs.jmeter.ai
---

# 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](/user-manual/jmeter-proxy-step-by-step/), [component reference](/user-manual/component-reference/), and [best practices](/user-manual/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](/user-manual/jmeter-proxy-step-by-step/):

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](/user-manual/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](/topics/functions-and-variables/)).

## 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](/user-manual/build-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](/user-manual/regular-expressions/), JSON Extractor, etc.
6. Replace hard-coded logins with **CSV Data Set** users ([best practices](/user-manual/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](/tools/regex-tester/) 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:

```bash
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](/user-manual/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](/user-manual/curl/)** | API calls already available as curl/Postman exports |
| **Manual HTTP Request samplers** | Simple APIs, maximum clarity |
| **[Access log sampler tutorial](/user-manual/jmeter-accesslog-sampler-step-by-step/)** | 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](/topics/api-load-testing/)).

### API-only services

If developers already give you OpenAPI examples or curl commands, [cURL import](/user-manual/curl/) 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](/user-manual/generating-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](/topics/ci-cd-load-testing/)).
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)](/user-manual/jmeter-proxy-step-by-step/)
- [Best Practices - recorder & variables](/user-manual/best-practices/)
- [Building a Web Test Plan](/user-manual/build-web-test-plan/)
- [Regular Expressions](/user-manual/regular-expressions/)
- [cURL import](/user-manual/curl/)
- [API load testing](/topics/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](/tools/thread-calculator/)).

## Continue Learning

→

### Next Practical Step

Use the [Recording template](/user-manual/jmeter-proxy-step-by-step/) once end-to-end, then clean the plan with Cookie Manager and one correlated token.

📖

### Related Reference

- [cURL Import](/user-manual/curl/) - alternative for API-only traffic
- [Access Log Sampler](/user-manual/jmeter-accesslog-sampler-step-by-step/) - production log replay
- [Regex Extractor Builder](/tools/regex-tester/) - correlation helper
- [Building a Web Test Plan](/user-manual/build-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.