Simulation DSL source compatibility ends at the Gatling 2.x to 3.x boundary

Confirmed facts – DSL areas that must be rewritten

The Gatling 3.x simulation DSL introduces breaking API changes; the following categories require manual edits when moving from a 2.x simulation:

• Imports – io.gatling.core.Predef._ and io.gatling.http.Predef._ replace the 2.x wildcard imports.
• HTTP protocol configuration – http.baseURL becomes http.baseUrl; the builder method is now httpProtocol instead of httpConfig.
• Scenario definition – the scenario factory signature is unchanged but the chain must start with .exec; any direct exec calls on the scenario object need the new syntax.
• Injection profiles – rampUsers(n) over(t) changes to rampUsers(n).during(t); constantUsersPerSec becomes constantUsersPerSec(rate).during(t) (or the equivalent constantUsersPerSec overload).
• Feeders – methods like .circular are now invoked as functions: csv(\"data.csv\").circular().
• Checks – the check DSL moved to io.gatling.http.check.HttpCheckBuilder; e.g., status.is(200) stays the same but must be imported from the new package.
• Assertions – the assertions builder now expects a details clause: assertions(global.responseTime.percentile3.lt(500)) or assertions(...).details(...) depending on the assertion type.

Likely explanation – migration aid and verification

Gatling does not provide an automated migration tool or a compatibility shim; the official migration guide documents the API changes listed above. Consequently, the migration is a manual rewrite effort.

To verify behavioral parity between the original 2.x simulation and its 3.x counterpart:

1. Run the 2.x simulation with Gatling 2.3.1 (the last 2.x release) against the target system, using the exact feeder data, think‑time, and load profile you intend to test.
2. Capture the simulation.log (TSV) and the summary statistics from the generated report.
3. Rewrite the simulation for a pinned 3.x minor version (e.g., 3.10.5) following the migration guide.
4. Run the 3.x simulation with the same feeder, user counts, duration, base URL, and think‑time settings.
5. Collect its simulation.log and report.
6. Parse both logs (or the JSON/HTML reports) and compare key metrics: request‑level percentiles (p50, p95, p99), error rates, and requests‑per‑second. A small tolerance (e.g., ≤5% difference) indicates functional equivalence.
7. Optionally, configure the Gatling Maven or Gradle plugin to set a fixed resultsDirectory (e.g., target/gatling/results) so that the two runs write to comparable folder names, simplifying automated diff scripts.

Recommendation – version pinning

Pinning the migration to a specific 3.x minor release (e.g., 3.10.x) is the safest strategy. Gatling’s 3.x line introduces further DSL tweaks between minor versions (such as Netty updates, Scala version bumps, or check‑builder refinements). Locking both the Gatling core version and the plugin version in build.gradle or pom.xml prevents unexpected rewrites when a new minor release is pulled in by a version range.

If you encounter a situation where the migrated simulation still fails to compile or exhibits divergent metrics, please share the exact error message or the metric that diverges; that detail would determine whether a deeper API change or a configuration mismatch is the cause.