Goals and Task Names

Gatling does not ship one universal "run" command. Each build tool has its own Gatling plugin, and each plugin follows its **host tool's** naming convention rather than a Gatling-wide one. Knowing which name belongs to which tool is the difference between a pipeline that runs your load test and one that silently runs nothing. ## The common core underneath Every launcher ends in the same place: `io.gatling.app.Gatling`, an ordinary JVM main class. Its command-line surface is deliberately tiny, and the option that matters here is `--simulation` (short `-s`), which names the simulation class to run. It does **not** search for simulations: on the run path, when no class name was supplied the selection step throws `IllegalArgumentException("Missing simulation class")`, and if the class it was handed does not extend a Gatling `Simulation` it throws again. That refusal is scoped to running a simulation, not to starting the process. `--reports-only <runId>` (short `-ro`) is checked first and short-circuits the runner entirely, so it never reaches the selection step: pointed at a results directory with `--results-folder <dir>`, it re-reads an existing run's log file and regenerates that run's HTML report with no simulation class at all. Generating the reports for a run that already happened is the option's whole job. Everything friendlier than that — scanning the compiled output for simulation classes, prompting you to pick one, defaulting to the only one present — is added by the **build-tool plugin**, not by Gatling's core. That is why the ergonomics differ per tool even though the runtime is identical. ## The four names, side by side | Tool | Launch a simulation | Naming shape | |---|---|---| | Maven | `mvn gatling:test` | `gatling:` prefix plus a camel-case goal | | Gradle | `./gradlew gatlingRun` | a `gatling`-prefixed camel-case task | | sbt | `sbt 'Gatling/testOnly com.project.simu.MySimulation'` | a `Gatling/` configuration prefix on a standard sbt task | | JavaScript / TypeScript | `npx gatling run` | an npm CLI with kebab-case subcommands | ### Maven The `gatling-maven-plugin` publishes the goals `test`, `recorder`, `enterprisePackage`, `enterpriseDeploy`, `enterpriseStart` and `help`; `mvn gatling:help -Ddetail=true -Dgoal=test` prints every configuration option on the `test` goal. Two things trip people up: 1. Plain `mvn test` does **not** run simulations. `gatling:test` is a direct goal invocation. You only reach it from a phase if you add an `<execution>` block, in which case `test` is bound to `integration-test` and `enterprisePackage` to `package` by default. 2. From version 4 the plugin no longer compiles Scala, so a Scala project must also configure `scala-maven-plugin`. ### Gradle The `io.gatling.gradle` plugin registers `gatlingRun`, `gatlingRecorder`, `gatlingEnterprisePackage`, `gatlingEnterpriseDeploy` and `gatlingEnterpriseStart`. There is no colon — Gradle has tasks, not goals. `gatlingRun` accepts `--simulation <FullyQualifiedClassName>` to force one simulation and `--all` to run every discovered simulation sequentially in alphabetic order. ### sbt The `gatling-sbt` plugin registers a custom sbt configuration named `Gatling`, so every task is prefixed with it. `sbt Gatling/testFull` runs all simulations and `sbt 'Gatling/testOnly com.project.simu.MySimulation'` runs one by fully qualified class name. Be careful with the bare `test` task: in sbt 1.x `test` ran everything and `testQuick` ran only what had changed, while sbt 2.x renamed those to `testFull` and `test` respectively. `testOnly` means the same in both. The plugin also offers `Gatling/startRecorder`, `Gatling/generateReport`, `Gatling/lastReport`, `Gatling/copyConfigFiles` and `Gatling/copyLogbackXml`. Its hard limit is the one to remember: **it supports simulations written in Scala only.** Java or Kotlin means Maven or Gradle. ### JavaScript and TypeScript Here the launcher is not a build-tool plugin at all but an npm package, `@gatling.io/cli`, invoked through `npx gatling`. Its subcommands are kebab-case: `run`, `recorder`, `install`, `enterprise-package`, `enterprise-deploy`, `enterprise-start`. `npx gatling run` looks for simulations under `src` and writes its report into `target/gatling`. ## Where the names stop matching - `--simulation` exists on both `gatlingRun` and `npx gatling run`, but they take different things: Gradle wants a fully qualified **class name**, the JavaScript CLI wants the simulation's **name**, so `--simulation "my-simulation"` matches `src/my-simulation.gatling.ts`. - Maven has no `--simulation` flag at all. It uses the Java system property `-Dgatling.simulationClass=<FullyQualifiedClassName>` or a `<simulationClass>` element in the plugin's `<configuration>`. - Only Gradle documents a run-everything switch, `--all`. sbt achieves the same with `Gatling/testFull`, and `mvn gatling:test` runs exactly one simulation per invocation. - The Recorder is `gatling:recorder`, `gatlingRecorder`, `Gatling/startRecorder` and `npx gatling recorder` — four spellings of one tool. ## Why this matters in a pipeline A job that types the wrong name does not always fail loudly. Maven will report an unknown goal, but a Gradle build that runs `gradle test` instead of `gradle gatlingRun` happily runs the unit tests, reports success and never touches the load test. Treat the launch command as part of the contract between the repository and the pipeline: write it down once, in the build file or in a documented command, rather than retyping it in every job.