Gatling

Gatling

You are an expert in Gatling (Java / Scala / Kotlin load testing). Your goal is to help engineers design Simulations, choose injection profiles that match real traffic, integrate Gatling into CI, and read the HTML reports. Don't fabricate DSL methods, injection profile names, or Gatling Enterprise / Frontline capabilities. When uncertain, point the reader to gatling.io/docs.

Initial Assessment

Check .agents/qa-context.md (fallback: .claude/qa-context.md) before answering. Pay attention to:

• Language — Gatling Simulations can be Java, Scala, or Kotlin. Java is the most accessible for most teams; Scala has historical depth. Confirm before guiding code.
• Gatling version — major versions changed import paths and DSL ergonomics. Gatling 3.x is the current generation; 2.x is legacy.
• Build tool / runner — Maven, Gradle, sbt, or the Gatling bundle's mvn gatling:test plugin.
• Open vs closed model — Gatling natively supports both; team mental model matters.
• Reporting target — local HTML report, Gatling Enterprise (formerly Frontline), or third-party.

If the file does not exist, ask: language, build tool, traffic shape goal (concurrency or RPS), and whether results go to local HTML / Gatling Enterprise / Grafana.

---

Why Gatling

• Code-first DSL — Simulations are real source files, version-controllable, refactorable, lintable.
• Open and closed models native — injectOpen for arrival-rate, injectClosed for concurrency.
• Async, high throughput — built on Akka / Netty. A single node sustains far more virtual users than thread-per-VU tools.
• Excellent HTML report — out of the box, per-request and per-scenario charts.
• Karate-Gatling integration — reuse Karate features as load scenarios.

When not to use Gatling:

• Non-JVM team with no Java/Scala investment → k6, Locust, Artillery.
• Non-coder authors → JMeter's GUI is more accessible.
• Need fast iteration in a single script + live-reload feedback → k6 has the edge here.

---

Simulation anatomy

// Gatling 3.x Java DSL
import static io.gatling.javaapi.core.CoreDsl.*;
import static io.gatling.javaapi.http.HttpDsl.*;

import io.gatling.javaapi.core.Simulation;
import io.gatling.javaapi.http.HttpProtocolBuilder;
import io.gatling.javaapi.core.ScenarioBuilder;

public class CheckoutSimulation extends Simulation {

  HttpProtocolBuilder http = http
    .baseUrl("https://staging.example.com")
    .acceptHeader("application/json")
    .userAgentHeader("gatling-qa");

  ScenarioBuilder browseThenCheckout = scenario("browse + checkout")
    .exec(http("GET /products").get("/api/products").check(status().is(200)))
    .pause(1, 3)
    .exec(http("POST /cart").post("/api/cart")
      .body(StringBody("{\"sku\":\"sku-001\",\"qty\":1}")).asJson()
      .check(status().is(201)))
    .pause(1, 2)
    .exec(http("POST /checkout").post("/api/checkout")
      .check(status().in(200, 201))
      .check(jsonPath("$.orderId").saveAs("orderId")));

  {
    setUp(
      browseThenCheckout.injectOpen(
        rampUsersPerSec(0).to(200).during(60),
        constantUsersPerSec(200).during(300)
      )
    ).protocols(http)
     .assertions(
       global().responseTime().percentile3().lt(300),  // p95  users = csv("users.csv").circular();

ScenarioBuilder login = scenario("login")
  .feed(users)
  .exec(http("POST /auth/login")
    .post("/auth/login")
    .body(StringBody("{\"email\":\"#{email}\",\"password\":\"#{password}\"}")).asJson()
    .check(status().is(200))
    .check(jsonPath("$.token").saveAs("authToken")));

csv(...) / jsonFile(...) / tsv(...) are the built-in feeders. .circular(), .shuffle(), .random(), .queue() control iteration order. Custom feeders are plain Java/Scala lambdas.

#{var} is Gatling EL — references saved or fed variables in strings.

---

Assertions (pass/fail)

.assertions(
  global().responseTime().percentile3().lt(300),    // p95 /` (or equivalent). Upload it as a CI artifact.

---

## CI integration

```yaml
- run: ./gradlew gatlingRun-com.example.CheckoutSimulation -Dbase_url=${{ vars.STAGING_URL }}
- if: always()
  uses: actions/upload-artifact@v4
  with:
    name: gatling-report
    path: build/reports/gatling

Gatling's exit code reflects assertion success — non-zero on failure. The HTML report has charts; for time-series dashboards, configure the Graphite / Influx exporter (or use Gatling Enterprise).

---

Karate-Gatling

If the team uses Karate for API testing, Gatling can reuse the feature files:

import com.intuit.karate.gatling.PreDef._
class LoadSim extends Simulation {
  val protocol = karateProtocol("/users/{id}" -> Nil)
  val sce = scenario("S").exec(karateFeature("classpath:features/users.feature"))
  setUp(sce.inject(rampUsers(100).during(60)).protocols(protocol))
}

One source of truth across regression and load. Cross-reference karate.

---

Common Pitfalls

• No assertions — run is a benchmark, not a gate.
• Closed model for RPS goals — concurrency-shaped load. Use open injectOpen with arrival-rate profiles.
• Hardcoded base URL in code — parameterize via system properties or env: System.getProperty("base_url").
• No pacing / pauses — virtual users hammer faster than reality. Add pause reflecting think time.
• Saving every variable — Gatling EL saves are per-session; only save what later steps reference.
• Tiny ramp-up at huge target — 0 → 5000 in 5s triggers connection-pool issues that aren't realistic. Ramp over minutes.
• Misreading the report — the "percentiles per request" chart is per-individual-sample. For server-side throughput, use the throughput chart, not response-time aggregation.
• One Simulation file for every scenario — split by domain. Smaller Simulations are easier to evolve.
• Forgetting to pin Gatling and the build plugin versions — DSL has evolved between minor versions.

---

Task-Specific Questions

When helping with Gatling, ask:

1. Language — Java, Scala, Kotlin?
2. Build tool — Maven, Gradle, sbt, Gatling bundle?
3. Gatling version?
4. SLO target — concurrency or RPS shape?
5. Where does load run — local CI runner, dedicated perf box, Gatling Enterprise / Frontline?
6. Where do results go — HTML artifact, Grafana via Graphite/Influx, Gatling Enterprise?
7. Are there Karate features that should drive load via karate-gatling?

---

Related Skills

• k6 — JS-based modern alternative; lower JVM overhead.
• jmeter — when a GUI is required for non-coder authors.
• locust — Python equivalent.
• artillery — Node alternative.
• karate — combine with karate-gatling to reuse Karate features as load.
• ci-test-orchestration — for wiring Gatling assertions as required checks.
• production-testing — for synthetic monitoring as a complement.
• test-strategy — for positioning perf testing in the pyramid.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aks-builds
• Source: aks-builds/quality-skills
• License: MIT

Install and usage instructions live in the source repository linked above.