Karate DSL for API Mocking and Performance Testing: Beyond Functional Tests
Most teams use Karate DSL for functional API testing and reach for separate tools when they need mocking or performance testing. That's a missed opportunity — Karate includes both capabilities, and using them means your functional scenarios can drive your mock servers and load tests without duplication.
This guide covers Karate's extended capabilities: karate-netty for mock servers and karate-gatling for performance testing.
Karate Mock Servers with karate-netty
The Problem Mocks Solve
Integration tests against real downstream services are slow, flaky, and expensive. If you're testing a service that calls payment processors, inventory systems, or third-party APIs, real calls are impractical in CI.
Karate's mock server speaks HTTP, returns JSON, and uses the same Gherkin syntax as your tests. You configure mock behavior once and start a local server.
Setup
Add to your pom.xml:
<dependency>
<groupId>com.intuit.karate</groupId>
<artifactId>karate-netty</artifactId>
<version>1.4.1</version>
<scope>test</scope>
</dependency>Writing a Mock Feature
Mock features use special variables that Karate sets on each incoming request:
requestMethod— GET, POST, PUT, etc.requestUri— full pathpathParams— named path parameters (if configured)requestHeaders— request headers maprequestParams— query parameters maprequest— parsed request body
Configure the response by setting:
response— response body (JSON, XML, or string)responseStatus— HTTP status code (default 200)responseHeaders— response headers map
Simple product API mock:
Feature: Product Service Mock
# Match GET /products/{id}
Scenario: pathMatches('/products/{id}') && methodIs('get')
* def productId = pathParams.id
* def response =
"""
{
id: '#(productId)',
name: 'Test Product',
price: 29.99,
available: true
}
"""
# Match GET /products (list)
Scenario: pathMatches('/products') && methodIs('get')
* def response =
"""
[
{ id: '1', name: 'Product A', price: 9.99 },
{ id: '2', name: 'Product B', price: 19.99 }
]
"""
# Match POST /products
Scenario: pathMatches('/products') && methodIs('post')
* def response = { id: '999', name: request.name, created: true }
* def responseStatus = 201
# Default: 404 for unmatched routes
Scenario:
* def responseStatus = 404
* def response = { error: 'Not Found' }Scenarios are matched in order. The first matching scenario handles the request. The final scenario (no condition) is the default.
Starting the Mock in Tests
Inline in a feature file:
Feature: Product integration tests
Background:
# Start mock server on a random available port
* def mock = karate.start('classpath:mocks/products-mock.feature')
* def port = mock.port
* url 'http://localhost:' + port
Scenario: Get product returns correct data
Given path '/products/42'
When method get
Then status 200
And match response.id == '42'
And match response.available == true
Scenario: Create product
Given path '/products'
And request { name: 'New Widget' }
When method post
Then status 201
And match response.created == truekarate.start() starts the server. karate.stop() is called automatically when the scenario ends (or you can call it explicitly).
In a JUnit test:
@Test
public void testWithMock() {
MockServer server = MockServer
.feature("classpath:mocks/products-mock.feature")
.http(8080)
.build();
System.setProperty("mock.url", "http://localhost:" + server.getPort());
Results results = Runner.path("classpath:features/products.feature")
.parallel(5);
server.stop();
assertThat(results.getFailCount()).isEqualTo(0);
}Stateful Mocks
Mocks can maintain state across requests using Karate's karate.set() and karate.get():
Feature: Cart Mock (Stateful)
Scenario: pathMatches('/cart') && methodIs('get')
* def cart = karate.get('cart') || { items: [], total: 0 }
* def response = cart
Scenario: pathMatches('/cart/items') && methodIs('post')
* def cart = karate.get('cart') || { items: [], total: 0 }
* def newItem = request
* cart.items.add(newItem)
* cart.total = cart.total + newItem.price
* karate.set('cart', cart)
* def response = cart
* def responseStatus = 200
Scenario: pathMatches('/cart') && methodIs('delete')
* karate.set('cart', null)
* def responseStatus = 204State persists across requests within the same mock server instance. Use this for testing workflows that depend on previous operations.
Dynamic Responses Based on Input
Feature: Auth Mock
Scenario: pathMatches('/auth/login') && methodIs('post')
* def valid = request.username == 'admin' && request.password == 'secret'
* def response = valid ? { token: 'valid-token-123', role: 'admin' } : { error: 'Invalid credentials' }
* def responseStatus = valid ? 200 : 401
Scenario: pathMatches('/auth/validate') && methodIs('get')
* def authHeader = requestHeaders['authorization']
* def valid = authHeader && authHeader[0] == 'Bearer valid-token-123'
* def responseStatus = valid ? 200 : 401
* def response = valid ? { valid: true } : { error: 'Unauthorized' }Performance Testing with karate-gatling
The Reuse Advantage
The promise of karate-gatling is compelling: the same Karate feature files you use for functional testing can drive Gatling load tests. No rewriting tests in Scala. No duplicating HTTP setup.
Setup
Add the dependency:
<dependency>
<groupId>com.intuit.karate</groupId>
<artifactId>karate-gatling</artifactId>
<version>1.4.1</version>
<scope>test</scope>
</dependency>Gatling also requires its Maven plugin:
<plugin>
<groupId>io.gatling</groupId>
<artifactId>gatling-maven-plugin</artifactId>
<version>4.3.0</version>
</plugin>Writing a Karate-Gatling Simulation
import com.intuit.karate.gatling.PreDef._
import io.gatling.core.Predef._
class ProductLoadTest extends Simulation {
val protocol = karateProtocol(
"/products/{id}" -> Nil,
"/products" -> List(
"get" -> Nil,
"post" -> Nil
)
)
// Use existing Karate feature as a scenario
val getProduct = scenario("Get Product")
.exec(karateFeature("classpath:features/get-product.feature"))
val createProduct = scenario("Create Product")
.exec(karateFeature("classpath:features/create-product.feature"))
setUp(
getProduct.inject(
rampUsers(100) during (30 seconds)
),
createProduct.inject(
constantUsersPerSec(10) during (60 seconds)
)
).protocols(protocol)
}The karateProtocol call maps URL patterns to Gatling's request recording structure. This is required for Gatling to group requests by pattern (not by exact URL) in reports.
Configuring the Feature for Load
Load tests need data variability — you don't want 100 users all requesting the same product ID.
Use Karate's karate.setup() hook to inject randomized data:
Feature: Load test - Get product
Background:
* url 'https://api.example.com'
* def productId = Math.floor(Math.random() * 1000) + 1
Scenario: Get random product
Given path '/products/' + productId
When method get
Then status 200Or use Gatling feeders passed through to Karate:
val feeder = csv("products.csv").random
val scenario = scenario("Product lookup")
.feed(feeder)
.exec(karateFeature("classpath:features/get-product.feature"))Access feeder data in Karate via session variables:
* def productId = __gatling.productIdAssertions in Load Tests
Functional assertions in Karate features still run during load tests. If Then status 200 fails, Gatling records the request as failed and includes it in error rate metrics.
For load-specific thresholds:
setUp(...)
.assertions(
global.responseTime.max.lt(2000), // Max response < 2s
global.successfulRequests.percent.gt(99), // 99%+ success rate
forAll.responseTime.percentile3.lt(500) // 95th percentile < 500ms
)Running the Load Test
mvn gatling:test -Dgatling.simulationClass=ProductLoadTestResults appear in target/gatling/ as an HTML report with response time percentiles, throughput charts, and error breakdown.
Combining Mock Server with Load Tests
You can performance test against your mock server to benchmark your service in isolation:
class LoadTestWithMock extends Simulation {
MockServer mock = MockServer
.feature("classpath:mocks/products-mock.feature")
.http(8080)
.build();
// Gatling simulation setup using localhost:8080
...
after { mock.stop() }
}This measures your service's throughput without downstream latency contaminating results.
Practical Workflow: From Functional to Performance
The workflow that makes karate-gatling valuable:
- Write Karate feature files for functional API tests
- Run them in CI with
mvn test— validates correctness - Promote to load test with a Gatling simulation file — no test rewriting
- Run load tests before major releases or after significant architecture changes
- Monitor in production with scheduled API health checks
Step 5 is where continuous monitoring tools complement the test frameworks. Karate and Gatling validate behavior at a point in time. HelpMeTest keeps running those same scenarios against production, every 5 minutes, catching regressions that appear after deployment.
Error Handling and Retry in Mocks
Production services are imperfect. Test your client's resilience by simulating errors in mocks:
Feature: Flaky service mock
Scenario: pathMatches('/payments') && methodIs('post')
# Simulate 20% failure rate
* def random = Math.random()
* def responseStatus = random < 0.2 ? 503 : 200
* def response = random < 0.2 ?
{ error: 'Service temporarily unavailable' } :
{ transactionId: java.util.UUID.randomUUID() }Or simulate latency:
Scenario: pathMatches('/slow-service') && methodIs('get')
* karate.pause(500) # 500ms delay
* def response = { data: 'slow response' }Use this to test timeout handling and retry logic in your service.
Summary
Karate DSL's mocking and performance testing capabilities are underused by most teams. The mock server eliminates external dependencies in integration tests. The Gatling integration converts functional tests into load tests without duplication.
The key insight: write your API scenarios once in Karate's readable syntax, then use them for functional testing, integration testing (with mocks), and performance testing. One set of test files covers three testing needs.
The complexity ceiling is real — stateful mocks, complex load patterns, and advanced Gatling simulations require careful design. But for most teams, the built-in capabilities are more than enough, and the lack of duplication between test types is worth the Karate-specific learning curve.