🎯

gatling

🎯Skill
g1joshi/agent-skills1 Installs9Last Updated Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill gatling

Run it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).

Uses skills.sh Β· Node.js 22.20+

After installing

Ask for related work and the agent uses it on its own, or call it yourself.

Run it (Claude Code)/gatling
Install by hand

Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.

Open the skill folder β†’
  • This project .claude/skills/gatling/
  • All projects ~/.claude/skills/gatling/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

Expert Gatling load testing assistance covering virtual users, scenarios, assertions, and throughput benchmarking. Use when designing performance tests, stress-testing HTTP APIs, or analyzing latency distributions.

Gatling

Gatling is a powerful load testing tool. It is designed for ease of use, maintainability, and high performance. It uses an asynchronous (Akka/Netty) architecture that allows generating huge load from a single machine.

When to Use

  • High-Concurrency Load Testing: Simulating tens of thousands of concurrent virtual users with minimal CPU and memory footprints.
  • Performance Regression Gates in CI/CD: Running automated performance assertions against staging environments on every release.
  • Scala / Java / Kotlin / TypeScript Load DSLs: Writing programmatic, version-controlled load testing scenarios as code.
  • Protocol Benchmarking: Stress testing HTTP, WebSockets, Server-Sent Events, and JMS message queues.

Quick Start

import static io.gatling.javaapi.core.CoreDsl.*;
import static io.gatling.javaapi.http.HttpDsl.*;

public class BasicSimulation extends Simulation {

  HttpProtocolBuilder httpProtocol = http
    .baseUrl("http://computer-database.gatling.io")
    .acceptHeader("application/json");

  ScenarioBuilder scn = scenario("BasicSimulation")
    .exec(http("request_1").get("/computers"));

  {
    setUp(
      scn.injectOpen(atOnceUsers(10))
    ).protocols(httpProtocol);
  }
}

Core Concepts

Non-Blocking Asynchronous Engine (Netty & Akka)

Unlike thread-per-user load tools, Gatling uses non-blocking actors to simulate thousands of users on a single OS thread:

[ Gatling Scenario Engine ] ──(Netty Event Loop)──→ [ Thousands of Async Virtual Users ]

Scenario DSL & Injection Profiles (Java / TypeScript)

Defines user journeys, think times, and virtual user ramp-up profiles:

// Java / Scala Gatling Simulation
import io.gatling.javaapi.core.*;
import io.gatling.javaapi.http.*;
import static io.gatling.javaapi.core.CoreDsl.*;
import static io.gatling.javaapi.http.HttpDsl.*;

public class ApiLoadSimulation extends Simulation {
    HttpProtocolBuilder httpProtocol = http
        .baseUrl("https://api.staging.example.com")
        .acceptHeader("application/json");

    ScenarioBuilder scn = scenario("Browse and Checkout")
        .exec(http("Get Products").get("/products").check(status().is(200)))
        .pause(2)
        .exec(http("Add to Cart").post("/cart").body(StringBody("{"id": 101}")).asJson());

    {
        setUp(
            scn.injectOpen(
                rampUsers(500).during(60) // Ramp up to 500 users over 60 seconds
            )
        ).protocols(httpProtocol)
         .assertions(
             global().responseTime().percentile(95).lt(300), // 95th percentile under 300ms
             global().successfulRequests().percent().gt(99.0) // 99% success rate
         );
    }
}

Feeders for Dynamic Parameterized Test Data

Injects dynamic user credentials and search queries from CSV or JSON files:

FeederBuilder<String> csvFeeder = csv("users.csv").circular();

ScenarioBuilder scn = scenario("User Login")
    .feed(csvFeeder)
    .exec(http("Login")
        .post("/login")
        .formParam("user", "#{username}")
        .formParam("pass", "#{password}"));

Common Patterns

Ramp-up Virtual Users with Latency Assertions

Problem: Sudden spike tests cause immediate connection saturation that masks normal production bottlenecks.

Solution: Use incremental user ramping with percentile assertions:

import io.gatling.core.Predef._
import io.gatling.http.Predef._
import scala.concurrent.duration._

class ApiLoadTest extends Simulation {
  val httpProtocol = http.baseUrl("https://api.example.com")
    .acceptHeader("application/json")

  val scn = scenario("Checkout Workflow")
    .exec(http("Get Products").get("/products"))
    .pause(1)
    .exec(http("Place Order").post("/orders").body(StringBody("{\"item\":\"widget\"}")) .asJson)

  setUp(
    scn.inject(rampUsers(500).during(60.seconds))
  ).protocols(httpProtocol)
   .assertions(
     global.responseTime.percentile3.lt(500),
     global.successfulRequests.percent.gt(99.0)
   )
}

Best Practices

Do:

  • Enforce Service Level Agreements (SLAs) with Assertions: Define explicit assertions on p95/p99 response times and error rates.
  • Ramp Virtual Users Smoothly: Use rampUsers or rampUsersPerSec to allow connection pools and autoscalers to adapt realistically.
  • Model Realistic Think Times: Use pause(min, max) to replicate human user behavior rather than firing continuous request loops.
  • Generate Real-Time Reports with Graphite / InfluxDB: Stream Gatling metrics live into Grafana dashboards during tests.

Don't:

  • Run load tests from the same machine hosting the application: CPU contention corrupts latency measurements.
  • Ignore network bandwidth limits on test runners: Saturated runner network cards artificially degrade response percentiles.
  • Hardcode fixed authentication tokens: Rotate users via feeders to test realistic database index and cache hit rates.

Troubleshooting

ErrorCauseSolution
java.net.ConnectException: Cannot assign requested addressOS ephemeral socket exhaustion on Gatling runner.Increase ephemeral port range and enable TCP TIME_WAIT socket recycling.
i.g.h.c.i.Response: 504 Gateway TimeoutTarget server overwhelmed under simulated load.Inspect server metrics, connection pool limits, and database query latency.
Gatling simulation compile errorGatling version API mismatch between Gatling 3.x and 3.10+.Check imported packages against official Gatling SDK migration guide.

References

More from this repository10