Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gatling/gatling.io-doc/llms.txt

Use this file to discover all available pages before exploring further.

The Gatling Recorder accelerates simulation development by capturing real HTTP traffic and converting it into a ready-to-run Gatling scenario. Instead of writing every request by hand, you navigate through your application while the Recorder observes the traffic, then generates a simulation file that replays your steps under load. The Recorder supports two distinct capture modes: acting as an HTTP proxy that intercepts browser traffic in real time, and converting a pre-recorded HAR (HTTP Archive) file exported from browser developer tools.
Gatling Studio is a low-code scripting application with an integrated recorder for an even faster workflow. See gatling.io/product/studio for details.

​
Launching the Recorder

# Linux/macOS
./mvnw gatling:recorder

# Windows
mvnw.cmd gatling:recorder
Once launched, the Recorder opens a GUI window where you configure the capture mode, ports, HTTPS handling, filters, and naming options before pressing Start.

​
Configuration

​
Listening Proxy Port

In proxy mode, the Recorder listens on a single local port for both HTTP and HTTPS traffic. Configure your browser to use this port as its proxy. In Firefox, this is found under Settings → General → Network Settings → Manual proxy configuration.
Both HTTP and HTTPS traffic use the same local proxy port. Configure your browser to route all traffic — not just HTTP — through it.

​
HTTPS Mode

Because the Recorder acts as a man-in-the-middle to decrypt HTTPS traffic, browsers will flag it as a security threat unless you configure them to trust the Recorder’s certificate. Three modes are available:
1

Certificate Authority (recommended)

The Recorder uses a private Certificate Authority to sign certificates on the fly for every visited domain. You can have the Recorder generate the CA certificate and key, or provide your own.After obtaining the CA certificate, import it into your browser’s certificate store:
  • Chrome: Settings → Privacy and Security → Manage Certificates
  • Firefox: Settings → Privacy & Security → View Certificates → Authorities
  • iOS: Email the certificate file to your device and open the attachment
  • Android: Settings → Security → Install from storage
2

Provided KeyStore

Supply a full Java keystore in JKS or PKCS12 format. This is useful if you already have a keystore for your application and want to reuse it. The CA certificate from the keystore must still be imported into your browser.
3

Self-signed Certificate (legacy)

The Recorder uses the same self-signed certificate for every domain. Browsers will present a security warning for each domain visited. This mode is increasingly difficult to use due to modern browser security hardening and is only recommended for older setups.
You can also pass custom keystore details via system properties:
  • gatling.recorder.keystore.path
  • gatling.recorder.keystore.passphrase

​
Outgoing Proxy

If your network requires an outgoing proxy to reach the application under test, configure the proxy host and ports in the Outgoing proxy section. HTTP and HTTPS can use different ports, even if they resolve to the same host.
Even if HTTP and HTTPS share the same port on your outgoing proxy, you must specify both ports explicitly in the Recorder configuration.

​
Filters

Filters prevent unwanted requests from appearing in the generated simulation. For example, to exclude CSS files from the recording, add .*\.css (a Java regex) to the deny list. The strategy setting controls evaluation order:
  • Whitelist first: Requests that match the whitelist are included; the deny list then further excludes from that set.
  • Blacklist first: Requests that match the deny list are excluded; the whitelist can re-include from the remaining set.

​
Embedded Resources Fetching

Enable Infer HTML resources? to have the Recorder:
  1. Add inferHtmlResources with matching allow/deny list patterns to the generated HttpProtocol.
  2. Parse HTML response bodies to identify embedded resources.
  3. Remove those embedded resource requests from the main scenario flow (they’ll be fetched concurrently via inferHtmlResources).
The Recorder cannot detect all embedded resources. For example, images embedded in stylesheets that are themselves embedded in HTML are not captured and will be loaded sequentially as regular requests in the generated simulation.

​
HTTP Request Naming

By default, generated request names use the prefix request_ followed by a counter (e.g., request_1, request_2). Enable Use class name as request prefix? to use the simulation class name as the prefix instead (e.g., MySimulation_1).

​
Response Bodies

Enable Save & check response bodies? to dump response bodies alongside the simulation file and generate RawFileBody checks that verify actual responses match the recorded ones. You may want to replace these with ElFileBody checks to parametrize the expected body content.

​
Running a Recording

1

Configure the Recorder

Set the proxy port, HTTPS mode, filters, and naming options as described above.
2

Configure your browser

Point your browser’s proxy settings to localhost and the port you configured in the Recorder.
3

Press Start

Click Start in the Recorder UI. The Recorder begins listening for requests.
4

Navigate your application

Browse through your application as a real user would. The Recorder logs three types of events:
  • Requests — HTTP requests sent by the browser.
  • Pauses — Time gaps between requests (used to generate pause steps).
  • Tags — Optional markers you add manually by typing text and pressing Add (appear as comments in the scenario).
5

Stop and save

Click Stop to finish recording. Gatling writes the simulation file to the configured output folder in the format (Scala, Java, Kotlin, or JavaScript) you selected.

​
HAR File Import

If you prefer to capture traffic through browser developer tools instead of configuring a proxy, export a HAR file and convert it with the Recorder.
1

Capture traffic in Chrome DevTools

Open DevTools → Network tab. Check Preserve log so the log is not cleared on navigation. Browse the pages you want to record, then right-click the request list and select Copy all as HAR. Save the clipboard contents to a .har file.
2

Select HAR Converter mode

In the Recorder’s top-right dropdown, switch to HAR converter.
3

Import and convert

Browse to your .har file and click Start. The Recorder converts the archive to a Gatling simulation immediately.
Do not use Charles Proxy to export HAR files for Gatling. Charles adds proxy-specific requests (such as CONNECT tunnel requests) that corrupt the HAR and cause the conversion to produce incorrect simulations.

​
Headless (CLI) Mode

The Recorder can run without a GUI for CI/CD and automation workflows. Enable headless mode via the -cli / --headless flag or by setting it in recorder.conf. Stopping a headless proxy recording: 
# send CTRL-C, or kill by PID file
cat .gatling-recorder-pid | xargs kill
Converting a HAR file headlessly: 
# the recorder converts the file and exits immediately
./mvnw gatling:recorder -Dgatling.recorder.mode=Har \
  -Dgatling.recorder.harFilePath=/path/to/recording.har \
  -Dgatling.recorder.headless=true

​
Command-Line Options Reference

All command-line options override the saved preferences in recorder.conf.
ShortLongDescription
-lp <port>--local-port <port>Local proxy HTTP/HTTPS port
-ph <host>--proxy-host <host>Outgoing proxy host
-pp <port>--proxy-port <port>Outgoing proxy port
-pps <port>--proxy-port-ssl <port>Outgoing proxy SSL port
-sf <path>--simulations-folder <path>Output folder for generated simulations
-rf <path>--resources-folder <path>Output folder for generated resources
-cn <name>--class-name <name>Name of the generated simulation class
-pkg <pkg>--package <pkg>Package of the generated simulation
-enc <enc>--encoding <enc>Encoding used in the Recorder
-fr <bool>--follow-redirect <bool>Enable follow redirects
-ar <bool>--automatic-referer <bool>Enable automatic Referer header
-fhr <bool>--fetch-html-resources <bool>Enable fetch HTML resources inference
-m <mode>--mode <Proxy|Har>Recorder mode
-cli <bool>--headless <bool>Run in headless (no GUI) mode
-hf <path>--har-file <path>HAR file to convert (when mode is Har)

Build docs developers (and LLMs) love

Get started for freeTalk to us