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.

Hard-coding the number of users, test duration, or target environment URL inside a simulation class means you need to edit and recompile every time those values change. Gatling provides first-class support for passing parameters at launch time — via Java system properties for JVM-based projects and a key=value CLI syntax for the JavaScript SDK. This lets you drive the same simulation file across smoke, capacity, and stress test configurations without touching the source code.

​
Java, Kotlin, and Scala — System Properties

The JVM-based Gatling SDKs read standard Java system properties passed with the -D flag on the command line.

​
Passing Properties at Launch

mvn gatling:test -Dusers=500 -Dramp=3600

​
Reading Properties in Your Simulation

Use System.getProperty(key, defaultValue) to read each property inside your simulation. Providing a default value ensures the simulation still runs sensibly when a property is omitted (e.g., during a quick local smoke test). 
import java.time.Duration;

public class MySimulation extends Simulation {

  private final int users = Integer.parseInt(
      System.getProperty("users", "1"));
  private final int ramp = Integer.parseInt(
      System.getProperty("ramp", "10"));

  {
    setUp(
      myScenario.injectOpen(
        rampUsers(users).during(Duration.ofSeconds(ramp))
      )
    ).protocols(httpProtocol);
  }
}
Always parse the string value returned by System.getProperty into the appropriate type (int, long, double). A NumberFormatException at startup is preferable to silently using a wrong value.

​
JavaScript and TypeScript — CLI Parameters

The Gatling JavaScript CLI uses a key=value format directly on the npx gatling run command. No -D prefix is required.

​
Passing Parameters at Launch

npx gatling run users=500 ramp=3600

​
Reading Parameters with getParameter

import {
  simulation,
  scenario,
  rampUsers,
  getParameter,
} from "@gatling.io/core";
import { http } from "@gatling.io/http";

export default simulation((setUp) => {
  const users = parseInt(getParameter("users", "1"));
  const ramp  = parseInt(getParameter("ramp", "10"));

  const httpProtocol = http.baseUrl("https://example.com");

  setUp(
    myScenario.injectOpen(rampUsers(users).during(ramp))
  ).protocols(httpProtocol);
});

​
Reading Environment Variables with getEnvironmentVariable

For secrets and infrastructure details that should not appear in command-line history, use environment variables instead. 
import { getEnvironmentVariable } from "@gatling.io/core";

const baseUrl    = getEnvironmentVariable("TARGET_URL",  "https://staging.example.com");
const apiKey     = getEnvironmentVariable("API_KEY",     "");
Then pass them through your shell or CI/CD pipeline’s secrets management before invoking the run command: 
export TARGET_URL="https://production.example.com"
export API_KEY="my-secret-token"
npx gatling run users=1000 ramp=600
Never pass secrets as CLI key=value parameters — they will appear in process listings and shell history. Use getEnvironmentVariable for any value that should remain confidential.

Centralise in a Config class

Create a single Config utility class that reads all properties and environment variables in one place. Reference Config.USERS throughout the simulation instead of scattering System.getProperty calls.

Use meaningful defaults

Set default values that produce a valid smoke test (1 user, short duration). This ensures mvn gatling:test with no flags always works locally.

Document properties in comments

Add a comment block at the top of your simulation listing every accepted property, its type, and its default. Teammates and CI pipelines will thank you.

Combine with test type switching

Use a testType property to switch between injection profiles (smoke, capacity, soak) so a single simulation file drives all test scenarios from the pipeline.

​
Full Config Utility Example

// utils/Config.java
public final class Config {

  // Number of virtual users to ramp up to
  public static final int USERS =
      Integer.parseInt(System.getProperty("users", "1"));

  // Ramp duration in seconds
  public static final int RAMP_SECONDS =
      Integer.parseInt(System.getProperty("ramp", "10"));

  // Smoke | capacity | soak | stress | breakpoint | ramp-hold
  public static final String TEST_TYPE =
      System.getProperty("testType", "smoke");

  // Target environment: dev | staging | production
  public static final String TARGET_ENV =
      System.getProperty("targetEnv", "dev");

  // Prevent instantiation
  private Config() {}
}

# Run a full capacity test against staging
mvn gatling:test \
  -DtestType=capacity \
  -DtargetEnv=staging \
  -Dusers=200 \
  -Dramp=300

Build docs developers (and LLMs) love

Get started for freeTalk to us