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.
Managing simulation configuration through the Gatling Enterprise Edition UI is fine for getting started, but it does not scale well when you have multiple simulations, multiple teams, or a requirement that infrastructure changes pass through code review. Configuration as code solves this by describing your package name, simulation class, load generator locations, and distribution weights in a .gatling/package.conf file that lives alongside your simulation source code. A single mvn gatling:enterpriseDeploy command then creates or updates everything on Gatling Enterprise Edition — no manual UI clicks required.
Prerequisites
Step 1: Create the Package Descriptor File
Create the .gatling directory
At the root of your project, create a .gatling directory: Create package.conf
Inside .gatling, create a file named package.conf:touch .gatling/package.conf
Add the root block
Add the minimum valid HOCON content:gatling.enterprise.package {
}
All configuration properties in package.conf are optional. You can deploy with an empty block and Gatling Enterprise Edition will use default names derived from your build tool settings.
Step 2: Define the Package
The package represents the compiled artifact (JAR or npm package) uploaded to Gatling Enterprise Edition. Give it a meaningful name and assign it to a team.
gatling.enterprise.package {
# Uncomment and fill in after the first deploy to prevent duplicates:
# id = "package_00000000000000000000000000"
name = "My Load Test Package"
team = "Platform Team"
}
The team value must match a team name that already exists in the Gatling Enterprise Edition UI. If the team does not exist, the deploy command will fail with a validation error.
Step 3: Define Simulations
Add a simulations array with one object per simulation class you want to register.
gatling.enterprise.package {
# id = "package_00000000000000000000000000"
name = "My Load Test Package"
team = "Platform Team"
simulations = [
{
# id = "test_00000000000000000000000000"
simulation = "example.BasicSimulation"
},
{
# id = "test_11111111111111111111111111"
simulation = "example.CapacitySimulation"
}
]
}
simulation property is the fully-qualified class name (Java/Scala/Kotlin) or the simulation file path (JavaScript). The id fields are commented out initially — you fill them in after the first deploy.
Step 4: First Deployment
Deploy the package and simulations to Gatling Enterprise Edition for the first time. The CLI returns the generated IDs in the terminal output.
Maven
Gradle
sbt
JavaScript CLI
export GATLING_ENTERPRISE_API_TOKEN=<your-token>
mvn gatling:enterpriseDeploy
export GATLING_ENTERPRISE_API_TOKEN=<your-token>
gradle gatlingEnterpriseDeploy
export GATLING_ENTERPRISE_API_TOKEN=<your-token>
sbt Gatling/enterpriseDeploy
export GATLING_ENTERPRISE_API_TOKEN=<your-token>
npx gatling enterprise-deploy
package.conf:
gatling.enterprise.package {
id = "package_abc123def456abc123def456ab"
name = "My Load Test Package"
team = "Platform Team"
simulations = [
{
id = "test_abc123def456abc123def456ab"
simulation = "example.BasicSimulation"
}
]
}
Once IDs are set, Gatling Enterprise Edition tracks deployments by ID. If you remove an ID and change the name, the next deploy will create a new package or simulation instead of updating the existing one.
default block sets simulation properties that apply to every simulation in the package unless overridden at the simulation level. A typical use case is pinning load generators to specific geographic locations with a traffic distribution.
gatling.enterprise.package {
id = "package_abc123def456abc123def456ab"
name = "My Load Test Package"
team = "Platform Team" # or team = "team_00000000000000000000000000"
default {
simulation {
locations = [
{
name = "Europe - Paris"
size = 1
weight = 60
},
{
name = "US East - N. Virginia"
size = 1
weight = 40
}
]
}
}
}
Full package.conf Reference
gatling.enterprise.package {
id = "package_00000000000000000000000000" # Optional: fill after first deploy
name = "My Package"
team = "My Team" # or team ID
default {
simulation {
locations = [
{
name = "Europe - Paris"
size = 1 # Number of load generators at this location
weight = 100 # Percentage of virtual users (must sum to 100)
}
]
}
}
simulations = [
{
id = "test_00000000000000000000000000" # Optional: fill after first deploy
simulation = "example.BasicSimulation" # Fully-qualified class name
# Simulation-level properties override default block values
}
]
}
CI/CD Integration
Once package.conf is in your repository, the deploy command integrates cleanly into any CI/CD pipeline:
# GitHub Actions example
- name: Deploy to Gatling Enterprise
env:
GATLING_ENTERPRISE_API_TOKEN: ${{ secrets.GATLING_ENTERPRISE_API_TOKEN }}
run: mvn gatling:enterpriseDeploy
# GitLab CI example
deploy-gatling:
script:
- mvn gatling:enterpriseDeploy
variables:
GATLING_ENTERPRISE_API_TOKEN: $GATLING_ENTERPRISE_API_TOKEN
Storing simulation configuration in version control means every change is reviewed, audited, and reproducible — the same guarantees you expect from infrastructure-as-code for your application’s deployment configuration.
