Gatling - Configuration as Code

This skill provides guidance on how to generate or update the .gatling/package.conf package descriptor file for deploying tests to Gatling Enterprise.

Instructions

1. Discover simulations based on the project language and build tool used: Java with Maven, JavaScript/TypeScript with the JavaScript CLI, Kotlin with Gradle, and Scala with sbt.

Collect their fully qualified class names (FQCN).

1. Read existing config: check if .gatling/package.conf already exists.

For reference check assets/package.conf from this skill using the Read tool.

1. Before asking any questions, call all the proper MCP tools to get real data from the user's account:

• Which teams are available.
• Which managed and private locations are available.
• Check if a package already exists for this project.
• Check if a test (aka simulation) already exists for this project.

1. Ask the user what they need with the AskUserQuestion tool.

If a list has >4 items, output the full list as markdown in a text message and ask the user to specify their choice(s) by name.

• Which tests to include.
• Package name (default to the project name, use artifactId if this is a Maven project).
• Team name or ID, asks the users if they want to create a new team.
• Load generator locations and weights, ask if they want to use a managed or private location.
• Any system properties or environment variables.
• Ramp up and ramp down time windows.
• Stop criteria.

1. Generate or update the file following the structure and rules below.

Key Rules

• simulation (FQCN) is the only mandatory field per simulation entry.
• Location weight values must sum to 100 across all locations for a simulation.
• System property names must be quoted (HOCON interprets dots as nested keys).
• Prefix system properties with sensitive. to hide values from the dashboard.
• Prefix environment variables with SENSITIVE_ to hide values from the dashboard.
• The default block avoids repeating shared config; simulation-specific values override it.
• Maps (systemProperties, environmentVariables) are merged, with simulation values taking priority.
• ignoreDefaults refers to Gatling Enterprise's Default Load Generator Parameters, not the default {} block.
• After first deploy, IDs are logged — add them to id fields for consistent updates (allows renaming without creating duplicates).

Locations

For managed locations, use the full name. For private locations, use their ID.

Stop criteria

stopCriteria = [
  {
    type = "meanCpu"
    timeFrameInSeconds = 10
    threshold = { maxPercentage = 90 }
  },
  {
    type = "globalResponseTime"
    timeFrameInSeconds = 10
    threshold = { maxMilliseconds = 500, percentile = 95 }
  },
  {
    type = "globalErrorRatio"
    timeFrameInSeconds = 10
    threshold = { maxPercentage = 5 }
  }
]

Troubleshooting

MCP tool call fails

If any MCP tool call fails, check authentication first:

1. Verify GATLING_ENTERPRISE_API_TOKEN is set in the environment.
2. If missing, warn the user, suggest using direnv, and offer to create a .envrc file.
3. Never print the actual token value in the terminal or logs.
4. The token needs at least the Configure role on Gatling Enterprise.