Karate Performance Testing with Gatling: Load Test Your APIs
Karate's integration with Gatling lets you run your existing .feature files as load tests. Instead of writing separate Gatling simulations in Scala, you point Gatling at your Karate scenarios and define the load profile around them. This means your functional tests and load tests stay in sync — same requests, same assertions.
How the Integration Works
The karate-gatling module wraps Karate execution inside Gatling's simulation engine. Gatling handles virtual user scheduling, ramp-up, and metrics collection. Karate handles the actual HTTP calls and response assertions. You write the scenario once and run it as both a functional test and a load test.
Setup
Maven Dependencies
<dependency>
<groupId>com.intuit.karate</groupId>
<artifactId>karate-gatling</artifactId>
<version>1.4.1</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>io.gatling.highcharts</groupId>
<artifactId>gatling-charts-highcharts</artifactId>
<version>3.9.5</version>
<scope>test</scope>
</dependency>You also need the Gatling Maven plugin to run simulations:
<plugin>
<groupId>io.gatling</groupId>
<artifactId>gatling-maven-plugin</artifactId>
<version>4.6.0</version>
<configuration>
<simulationClass>load.ApiLoadSimulation</simulationClass>
</configuration>
</plugin>Gradle
testImplementation 'com.intuit.karate:karate-gatling:1.4.1'
testImplementation 'io.gatling.highcharts:gatling-charts-highcharts:3.9.5'Writing the Feature File
Write a normal Karate feature. The key constraint: each scenario should be independent and stateless so it can run concurrently without side effects.
# src/test/resources/load/users-api.feature
Feature: Users API Load Test
Background:
* url 'https://api.example.com'
* configure ssl = true
Scenario: Get all users
Given path '/users'
When method GET
Then status 200
And match response == '#[]'
Scenario: Get single user
Given path '/users/1'
When method GET
Then status 200
And match response.id == 1
Scenario: Create user
Given path '/users'
And request { name: 'Test User', email: 'test@example.com' }
When method POST
Then status 201
And match response.id == '#notnull'Writing the Gatling Simulation
Create a Scala simulation class in src/test/scala/:
package load
import com.intuit.karate.gatling.PreDef._
import io.gatling.core.Predef._
import scala.concurrent.duration._
class ApiLoadSimulation extends Simulation {
val protocol = karateProtocol(
"/users" -> Nil,
"/users/{id}" -> Nil
)
val getAllUsers = scenario("Get All Users")
.exec(karateFeature("classpath:load/users-api.feature@name=Get all users"))
val createUser = scenario("Create User")
.exec(karateFeature("classpath:load/users-api.feature@name=Create user"))
setUp(
getAllUsers.inject(
rampUsers(50).during(30.seconds),
constantUsersPerSec(10).during(60.seconds)
),
createUser.inject(
rampUsers(20).during(30.seconds)
)
).protocols(protocol)
.assertions(
global.responseTime.max.lt(2000),
global.successfulRequests.percent.gt(99)
)
}The @name= tag selects a specific scenario by name. Without it, all scenarios in the feature file run.
karateProtocol declares which paths Gatling should track in its metrics. Paths with path parameters use {param} notation so Gatling groups them correctly instead of treating each /users/1, /users/2, etc. as a separate metric.
Injection Profiles
Gatling provides several injection strategies:
// Constant load
constantUsersPerSec(20).during(60.seconds)
// Ramp up
rampUsers(100).during(30.seconds)
// Step load
stressPeakUsers(500).during(20.seconds)
// Ramp up, hold, ramp down
rampUsersPerSec(1).to(50).during(60.seconds).randomizedA realistic load test usually combines a warm-up ramp with a sustained period:
setUp(
scenario("API Load")
.exec(karateFeature("classpath:load/users-api.feature"))
.inject(
nothingFor(5.seconds),
rampUsers(20).during(30.seconds),
constantUsersPerSec(10).during(120.seconds)
)
).protocols(protocol)Parameterized Load Tests
For testing with varied data, use a Gatling feeder:
val emailFeeder = Iterator.continually(Map(
"email" -> s"user${scala.util.Random.nextInt(10000)}@example.com"
))
val createScenario = scenario("Create Users")
.feed(emailFeeder)
.exec(karateFeature("classpath:load/create-user.feature"))In the feature file, access feeder values via Karate's __gatlingFeeder:
Scenario: Create user with dynamic email
Given path '/users'
And request { name: 'Load Test User', email: '#(__gatlingFeeder.email)' }
When method POST
Then status 201Running the Simulation
mvn gatling:testOr specify the simulation class directly:
mvn gatling:test -Dgatling.simulationClass=load.ApiLoadSimulationFor Gradle:
gradle gatlingRunAssertions
Gatling's assertion DSL lets you define pass/fail criteria:
.assertions(
global.responseTime.mean.lt(500), // avg response < 500ms
global.responseTime.percentile3.lt(1000), // 95th percentile < 1s
global.responseTime.max.lt(5000), // max < 5s
global.successfulRequests.percent.gt(99), // 99% success rate
forAll.failedRequests.count.is(0) // specific scenario has 0 failures
)If any assertion fails, Gatling exits with a non-zero status code, which fails the CI build.
Reading the Report
After a run, Gatling generates an HTML report at target/gatling/. The report includes:
- Response time percentiles over time — shows degradation under load
- Requests per second — actual throughput achieved
- Response time distribution — histogram of all response times
- Active users over time — confirms the injection profile executed correctly
- Errors — grouped by error type with counts
The most useful metric for API testing is usually the 95th percentile response time. Mean response time can hide a long tail where 5% of users experience 10x the typical latency.
Common Issues
Karate scenarios are stateful: If a scenario creates data and expects to find it later, concurrent execution will cause interference. Either make scenarios fully independent or use unique identifiers per virtual user.
SSL configuration: Set * configure ssl = true in Background, or configure it globally in karate-config.js. Missing SSL config causes connection errors that look like timeouts.
Connection pool exhaustion: Under high load, you may hit OS-level connection limits. Increase with * configure connectTimeout = 10000 and * configure readTimeout = 10000 in Background.
Gatling version compatibility: The Karate Gatling module version must match the Karate core version. Mismatched versions cause runtime errors at simulation start.
When to Use This
Use karate-gatling when you already have Karate functional tests and want load testing without writing a separate test suite. The main trade-off: Gatling's native Scala API gives you more control over virtual user behavior (pause times, conditional branching), while the Karate integration is simpler but less flexible. For most API load testing needs, the Karate integration is sufficient.