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 Postman support lets you take a collection you’ve already built and tested in Postman and run it as a full-scale load test. The @gatling.io/postman package reads your exported collection JSON, resolves Postman variables from environment and global files, and generates Gatling HTTP requests and scenarios that participate in Gatling’s standard injection profiles. This means you can go from a verified Postman collection to a load test with minimal additional code.
The Gatling Postman component is distributed under the Gatling Enterprise Edition Component License. It works with both Community and Enterprise editions — unlimited with Gatling Enterprise Edition, and limited to 5 users / 5 minutes with Community Edition. Postman support is available only for JavaScript and TypeScript simulations. Java, Kotlin, and Scala are not supported. If you need JVM support, submit a request on the public roadmap. Scope of Postman Support
The component supports the most common Postman collection features needed for load testing. The following features are not yet supported:
- Integration with Postman Cloud (collections and environments must be exported to local JSON files)
- Pre-request and post-response scripts
- Modifying variable values during execution or injecting them from feeder files
- Dynamic variables
- Request authorization schemes (Basic Auth, Bearer Token, etc.) and per-request settings
For file upload requests, place referenced files in your Gatling project’s resources folder, mirroring Postman’s working directory.
Installation
Demo Project
The quickest way to get started is to clone the official demo project:
Adding to an Existing Project
Add the @gatling.io/postman package to an existing Gatling JavaScript or TypeScript project:
npm install --save "@gatling.io/postman"
resources folder.
Exporting from Postman
In your Postman workspace, open the Collections sidebar, click the ⋯ menu on the collection you want to export, choose Export, and select Collection v2.1. Save the resulting JSON file to the resources folder of your Gatling project.
SDK Overview
The @gatling.io/postman package extends Gatling’s standard HTTP protocol. Import it alongside the core Gatling imports:
import { simulation, scenario, atOnceUsers } from "@gatling.io/core";
import { http } from "@gatling.io/http";
import { postman } from "@gatling.io/postman";
import { simulation, scenario, atOnceUsers } from "@gatling.io/core";
import { http } from "@gatling.io/http";
import { postman } from "@gatling.io/postman";
export default simulation((setUp) => {
const httpProtocol = http;
const collection = postman
.fromResource("My Collection.postman_collection.json");
const scn = scenario("My scenario").exec(
// Standard Gatling HTTP request:
http("My HTTP request").get("http://example.com"),
// Request generated from the Postman collection:
collection.request("My Postman request"),
);
setUp(scn.injectOpen(atOnceUsers(1))).protocols(httpProtocol);
});
SDK Reference
Loading a Collection
Load a collection from the resources folder:
const collection = postman.fromResource("My Collection.postman_collection.json");
Injecting Environment Variables
Inject a Postman environment from an exported JSON file or a plain JavaScript object:
// From exported JSON file:
collection.environment("My Environment.postman_environment.json");
// From a JavaScript object:
collection.environment({ "base_url": "https://api.example.com" });
Injecting Global Variables
// From exported JSON file:
collection.globals("My Globals.postman_globals.json");
// From a JavaScript object:
collection.globals({ "key 1": "value 1" });
Navigating Folders
If your collection uses folders, navigate into them with the folder function:
const folder = collection.folder("My Folder");
// Reference a request inside the folder:
folder.request("My Request");
Generating Individual Requests
Generate a Gatling HTTP request from a named Postman request:
// Use the Postman request name as the Gatling request name:
collection.request("My Request");
// Override the name shown in Gatling reports:
collection.request("My Request", "Overridden Request Name");
Generating Entire Scenarios
Generate a Gatling scenario that runs all requests in the collection (or folder) in order:
// Basic scenario:
collection.scenario("My Scenario");
// With fixed pauses between requests (seconds):
collection.scenario("My Scenario", { pauses: 1 });
// With explicit time unit:
collection.scenario("My Scenario", { pauses: { amount: 1, unit: "seconds" } });
// Include requests from all sub-folders recursively:
collection.scenario("My Scenario", { recursive: true });
scenario() includes only requests at the current level. Use recursive: true to include all requests from nested folders at any depth.
A Realistic Load Test Example
The following simulation runs a Postman collection scenario with a constant injection rate for 60 seconds:
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;
const collection = postman
.fromResource("My API Collection.postman_collection.json");
const scn = collection.scenario("My Scenario", { pauses: 1 });
setUp(
scn.injectOpen(
constantUsersPerSec(1).during(60)
).protocols(httpProtocol)
);
});
Running on Gatling Enterprise Edition
To remove Community Edition limits (5 users / 5 minutes), run your test on Gatling Enterprise Edition:
Package Your Simulation
npx gatling enterprise-package
target folder.Upload to Gatling Enterprise Edition
Log in to your Gatling Enterprise Edition account, navigate to Simulations, click Create a simulation, and follow the prompts to upload the package.
Run and Monitor
Start your simulation from the dashboard and watch real-time metrics as the load test runs.
