Karate DSL for API Mocking and Performance Testing: Beyond Functional Tests

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 path
  • pathParams — named path parameters (if configured)
  • requestHeaders — request headers map
  • requestParams — query parameters map
  • request — 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 == true

karate.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 = 204

State 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 200

Or 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.productId

Assertions 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=ProductLoadTest

Results 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:

  1. Write Karate feature files for functional API tests
  2. Run them in CI with mvn test — validates correctness
  3. Promote to load test with a Gatling simulation file — no test rewriting
  4. Run load tests before major releases or after significant architecture changes
  5. 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.

Read more

Start now free