Recorder

Learn how to configure your Recorder and run it, either as an HTTP proxy or a HAR converter

The Gatling Recorder helps you to quickly generate scenarios, by either acting as a HTTP proxy between the browser and the HTTP server or converting HAR (Http ARchive) files. Either way, the Recorder generates a simple simulation that mimics your recorded navigation.

If you’re using the bundle or the Maven plugin, you can launch the Recorder with the following command:

./mvnw gatling:recorder

mvnw.cmd gatling:recorder

For the JavaScript SDK:

npx gatling recorder

You will get a window that looks like this one:

Configuration#

Listening proxy port#

In the Recorder, you have to define one port (for both HTTP and HTTPS): the local proxy port. This is the port your browser must connect to so that the Recorder is able to capture your navigation.

Then, you have to configure your browser to use the defined port.

Here is how to do with Firefox, open the browser Advanced settings, then go to the Network panel and update the connection settings:

HTTPS mode#

On the contrary to regular proxies that act as a pass-though, the recorder acts as a man-in-the-middle and decrypt your HTTPS traffic. The consequence is that it’s identified by browsers as a security threat, so, one way or the other, you have to tell your browser that everything is fine.

The Recorder has 3 modes:

Certificate authority#

In this mode, the Recorder will use a private Certificate Authority (CA) to generate on-the-fly properly signed certificates for every visited domain.

You can either ask the Recorder to generate the CA certificate and private key files for you, or provide your own ones.

Provided keyStore#

You can pass a full Java keyStore (JKS or PKCS#12 format) that contains the certificate to be used. This mode is useful if you have already generated a Java keystore for your application and want to reuse it for recording.

Self-signed certificate (legacy)#

The recorder will use the same self-signed certificate for every domain. This mode is the legacy one and is becoming more and more complicated to use due to the security hardening trend in web browsers.

Browsers will prompt a security alert, and ask you if you want to add a security exception for this domain. If it doesn’t do so, it means that you’ve already registered a validated (by a standard Certificate Authority) certificate and it refuses to replace it by a less secured one. You then have to remove it from your certificate registry.

Outgoing proxy#

If you must access your web application through a proxy, you can set it up in this section. Two different ports can be defined for the outgoing proxy (HTTP & HTTPS).

Filters#

Allow you to filter out some requests you don’t want to record. For example, if you don’t want to record any CSS files, you can add in the blacklist section the following Java regex .*\\.css.

The order of evaluation between the whitelist and the blacklist entries can be determined with the strategy setting. You can either evaluate the whitelist or the blacklist first.

Embedded resources fetching#

If you check the ‘Infer html resources?’ option, the Recorder will fetch the embedded HTML resources as follows:

• Add inferHtmlResources with the proper white/black lists on the HTTP protocol definition.
• Parse HTML response body to retrieve embedded HTML resources.
• Filter requests corresponding to embedded HTML resources from resulting Scenario.

HTTP request naming#

By default, Gatling will use the prefix request_ for recorded and converted http requests. When the ‘Use class name as request prefix?’ option is enabled, http requests will use the simulation class as prefix for the request name instead.

Response bodies#

When the ‘Save & check response bodies?’ option is enabled, response bodies will be dumped in the same folder as the request bodies, and the simulation will contain extra checks using RawFileBody to ensure the actual bodies are matching the dumped ones. You might want to edit these checks, for example to parametrize the expected bodies, using ElFileBody instead.

Running#

Once everything has been configured, press the Start button to launch the recorder.

Recorded events#

As you navigate through your application, the recorder will log three kinds of events:

• Requests: The requests sent by the browser.
• Pauses: The time between each request.
• Tags: Manually set markers.

Tag events#

To make your scenario more understandable, you can add tags, they will appear as comments in the scenario: /* my tag */

To add a tag, fill in the text field provided and press the Add button. After that, the tag will be displayed in the list below.

For example: TAG | my tag

Stop#

When you have finished recording your scenario, press the Stop button to save it in the format defined in the configuration.

HAR files#

You can import a HAR file (Http Archive) into the Recorder and convert it to a Gatling simulation.

HAR files can be obtained using the Chrome Developer Tools or with Firebug and the NetExport Firebug extension.

With Chrome Developer Tools, go to Network tab, and make sure you’ve selected the Preserve log checkbox, otherwise the log is reset when you change page. Select the requests you want to export, then right click and select Copy All as HAR and save what’s in your clipboard into a file.

Please don’t use Charles Proxy for this. Charles is an amazing tool and has an HAR export feature, but it’s a proxy, so when you use it, you change the HTTP behavior, and the HAR would contain requests that should be here, such as CONNECT requests.

To import a HAR file, select the HAR converter mode in the top right dropdown in the Recorder.

Headless mode#

Along the GUI mode, Gatling also offers a simple CLI interface, facilitating the automation of recording or converting simulations from HAR files. The Headless mode can be enabled either from the recorder.conf file or with the -cli/--headless command line option. Both ‘Proxy’ and ‘HAR’ modes are supported (you can set which mode to use using the -m/--mode command line option).

Proxy#

In ‘Proxy mode’, the Recorder will start listening for requests from your browser right away. To stop the Recorder and create the Simulation, you have to ‘kill’ the Recorder by either:

• Sending a ‘kill’ signal with CTRL-C
• Killing the Recorder’s process, using the Recorder process ID written to the .gatling-recorder-pid file: cat .gatling-recorder-pid | xargs kill

HAR converter#

In ‘Har’ mode, the Recorder will convert the provided HAR file to a Simulation and exits.

Command-line options#

For those who prefer the command line, command line options can be passed to the Recorder:

System properties#

There are 2 system properties to control the use of a custom certificate keystore for the proxy:

• gatling.recorder.keystore.path
• gatling.recorder.keystore.passphrase

Edit this page on GitHub