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.

Gatling’s low-code tools bridge the gap between existing API specifications and load test scripts. Instead of writing every HTTP request by hand, you can import a Postman collection you already maintain or record a real browser session and let Gatling generate the simulation structure for you. The result is a fully editable Gatling simulation that you can enrich with checks, feeders, and custom injection profiles. This page covers two workflows: importing a Postman collection using the @gatling.io/postman package, and recording a browser session using the Gatling Recorder or Gatling Studio.
The Postman integration is only available in the JavaScript/TypeScript SDK. The browser Recorder and Gatling Studio support both the Java/Maven and JavaScript/npm project types.

Postman Collection Import

The Gatling Postman component lets you load a Postman collection JSON file directly into a simulation. This reduces test authoring time, keeps your functional and load test definitions consistent, and improves collaboration between developers, QA, and operations teams who already maintain Postman collections.
The Gatling Postman component is licensed under the Gatling Enterprise Component License. When used with Gatling Community Edition, tests are limited to 5 concurrent users and 5-minute duration. Usage is unlimited on Gatling Enterprise.

Supported Features

Most core Postman request features are supported. The following items are currently limited or not yet available:
  • Postman Cloud integration — collections must be exported as JSON files; direct cloud sync is not supported
  • Pre-request and post-response scripts — script execution is not supported
  • Dynamic variable handling — modifying variable values at runtime is not supported
  • Randomly generated data — Postman’s {{$randomXxx}} dynamic variables are not supported
  • File uploads — supported by placing files in your project’s resources folder

Step-by-Step: Import a Postman Collection

1

Get a Gatling JavaScript Project

You need an existing Gatling JavaScript or TypeScript project, or you can use the dedicated demo project.Option A — Use the Postman demo project:
git clone https://github.com/gatling/se-ecommerce-demo-gatling-tests.git
# JavaScript:
cd se-ecommerce-demo-gatling-tests/postman/javascript
# TypeScript:
cd se-ecommerce-demo-gatling-tests/postman/typescript
npm install
Option B — Add to an existing Gatling JavaScript project:
npm install --save "@gatling.io/postman"
2

Export Your Postman Collection

In the Postman application:
  1. Open the collection you want to use for load testing.
  2. Click the (three-dot) menu next to the collection name.
  3. Select Export.
  4. Choose Collection v2.1 format and click Export.
  5. Save the resulting .json file.
Optionally export your Postman Environment and Global Variables as separate JSON files if your collection depends on them.
3

Add Collection Files to Your Project

Copy the exported JSON files into your Gatling project’s resources folder:
your-gatling-project/
├── src/
│   └── mySimulation.gatling.js
└── resources/
    ├── myCollection.postman_collection.json
    └── myEnvironment.postman_environment.json   # optional
4

Write the Simulation

Create a simulation file in src/ with the .gatling.js extension. The simulation has three parts: imports, a scenario built from the Postman collection, and an injection profile.
import { simulation, constantUsersPerSec } from "@gatling.io/core";
import { http } from "@gatling.io/http";
import { postman } from "@gatling.io/postman";

export default simulation((setUp) => {
  const httpProtocol = http;

  // 1. Load the Postman collection from the resources folder
  const collection = postman
    .fromResource("myCollection.postman_collection.json");

  // 2. Convert the collection into a Gatling scenario
  //    The `pauses: 1` option adds 1-second pauses between requests
  const scn = collection.scenario("My Scenario", { pauses: 1 });

  // 3. Injection profile: 1 new user every 10 seconds for 50 seconds
  setUp(
    scn.injectOpen(
      constantUsersPerSec(0.1).during(50)
    ).protocols(httpProtocol)
  );
});
You can blend Postman-sourced requests with hand-written Gatling requests in the same scenario. Refer to the Postman reference documentation for advanced composition patterns.
5

Run the Simulation Locally

Test your simulation locally before deploying to Gatling Enterprise:
npx gatling run
When prompted, select your Postman simulation. The HTML report opens in target/gatling/.
6

Deploy to Gatling Enterprise (Optional)

Package and upload your simulation for distributed, cloud-scale execution.Manual packaging:
npx gatling enterprise-package
This produces a .zip file in target/. Upload it via Packages in the Gatling Enterprise console, then create a simulation pointing to it.Automated deployment (Configuration as Code):
# Set your API token (generate one in Gatling Enterprise with Configure permission)
export GATLING_ENTERPRISE_API_TOKEN=<your-api-token>

# Deploy and start immediately
npx gatling enterprise-start --enterprise-simulation="My Postman Simulation"

# Or deploy only (without starting a run)
npx gatling enterprise-deploy

Browser Recorder

The Gatling Recorder is a proxy-based tool that intercepts HTTP traffic from your web browser and converts it into a Gatling simulation. It is included with every Gatling installation and supports both Java/Maven and JavaScript/npm projects.

Step-by-Step: Record a Browser Session

1

Clone the Demo Project and Configure Prerequisites

The recorder tutorial uses the Gatling e-commerce demo site at https://ecomm.gatling.io. Clone the demo project and navigate to your preferred SDK directory:
Requirements: Java 17 or 21, Firefox browser configured to use a proxy.
git clone https://github.com/gatling/se-ecommerce-demo-gatling-tests.git
cd se-ecommerce-demo-gatling-tests/java/maven
2

Launch the Recorder

Start the Recorder GUI from the command line:
# Linux / macOS
./mvnw gatling:recorder

# Windows
mvnw.cmd gatling:recorder
The Recorder GUI will open. Configure it with the following settings before clicking Start!:
SettingValue
Recorder ModeHTTP Proxy
Packageexample
Class NameRecordedSimulation
Follow Redirects?✅ Checked
Infer HTML Resources?✅ Checked
Automatic Referers?✅ Checked
Remove Cache Headers?✅ Checked
No Static Resources✅ Clicked
FormatJava 17 (or JavaScript)
3

Record the User Session

With the Recorder running, browse the e-commerce site as a real user would. The Recorder captures all HTTP requests in real time.Use the Recorder’s control buttons to organize your session:
ButtonAction
AddInsert a tag to label a group of actions (e.g. “Homepage”, “Login”)
ClearClear all captured events
CancelAbort the recording
Stop & SaveFinish and write the simulation file
Example user journey to record:
  1. In the Recorder, add the tag Homepage, then navigate to https://ecomm.gatling.io.
  2. Add the tag Authentication, then click the Login button and submit the form.
  3. Add the tag Cart, then click Add to cart for a product.
  4. Click Stop & Save in the Recorder.
Behave as a real user would — pause briefly between actions to read content. These think-time pauses are captured and automatically inserted as pause() calls in the generated simulation.
4

Inspect the Generated Simulation

The Recorder writes the simulation to:
src/test/java/example/RecordedSimulation.java
Open the file and review the generated code. You can customize it by:
  • Adding .check(status().is(200)) to requests
  • Extracting dynamic values with .check(jsonPath("$.token").saveAs("authToken"))
  • Replacing hardcoded credentials with feeder-supplied values
5

Run the Recorded Simulation

./mvnw gatling:test
Select your RecordedSimulation from the prompt.

Gatling Studio (Desktop Recorder)

Gatling Studio is a native desktop application that records browser sessions and exports a ready-to-run Gatling project. It is available for macOS, Windows, and Linux.
Gatling Studio requires a Gatling Enterprise Edition account to log in. Sign up for a free 14-day trial if you don’t have one.
1

Download and Install Gatling Studio

Download the latest version from the Gatling Studio GitHub releases page. Open the downloaded file and follow the installation instructions for your operating system.Requirements: A Chromium-based browser (Chrome or Edge) must be installed for recording.
2

Log In and Set Up a Workspace

  1. Open Gatling Studio.
  2. Click Log in with Gatling Enterprise Edition account.
  3. Complete authentication in the browser window that opens, then return to the Studio.
  4. Set your workspace — a local folder where recordings, scenarios, and exported projects are stored.
3

Record a Journey

  1. Click Record a journey on the Recordings page.
  2. Select your Chromium-based browser from the detected list (or provide a path).
  3. Enter the URL you want to test and click Start the recording.
  4. Browse through the user journey you want to simulate.
  5. Close the browser when done. Studio saves the recording as a HAR file in your workspace.
4

Create a Scenario from the Recording

  1. Open the recording in Studio to view its captured requests.
  2. Click Create a scenario from recording.
  3. In the scenario filter, select which domains to include and whether to include static resources (static resources are generally not recommended for load testing).
  4. Click Save.
Studio automatically groups requests with less than 100 ms between them and inserts pause() calls between groups based on recording timing.
5

Export as a Gatling Project

  1. From the scenario view, click Export project.
  2. Studio generates a complete Java/Maven project pre-loaded with your scenario.
  3. Open the exported project in your IDE, customize it as needed, and run it with ./mvnw gatling:test.
Exported projects are currently Java/Maven only. Sec-* headers are filtered out automatically during export since they are not relevant in load testing contexts.

Next Steps

No-Code GUI Builder

Build and run load tests entirely through Gatling Enterprise’s point-and-click interface — no code or local tooling required.

First Simulation (Code)

Learn how the generated simulation code works so you can customize checks, feeders, and injection profiles.

Build docs developers (and LLMs) love