Mocking External APIs in Karate Tests with WireMock: A Practical Guide

The Problem: Flaky Tests from Real Services

When API tests call real third‑party endpoints, they become fragile. Network latency, rate limits, or occasional downtime turn a deterministic suite into a source of intermittent failures. Teams often spend time debugging whether a failure is due to code or an external service, slowing down feedback loops.

Karate’s Built‑In WireMock Support

Karate includes a lightweight WireMock server that can be started directly from a test script. The wireMock keyword launches a local mock process, registers stubs, and intercepts outgoing HTTP calls so the test never reaches the network. Because the server runs in the same JVM as Karate, you avoid extra container orchestration while still gaining full WireMock features such as request matching, response templating, and fault simulation.

Worked Example: Mocking a User Service

Suppose your application consumes a /users/{id} endpoint that returns JSON user data. The following Karate scenario outline demonstrates how to stub that endpoint with WireMock, vary the user ID via a data table, and assert the response.

Feature: User service mocking with WireMock

  Background:
    * wireMock: { port: 8080 }

  Scenario Outline: Retrieve user details for different IDs
    Given url 'http://localhost:8080/users/'
    When method get
    Then status 200
    And match response == { id: , name: , active: true }

    Examples:
      | id | name   |
      | 101| Alice  |
      | 102| Bob    |
      | 103| Charlie|

The wireMock step in the Background starts the server on port 8080 before any scenario runs. Because no explicit stub is defined, WireMock returns a 200 with an empty body by default; to return the JSON shown in the assertion you would add a stub in a * def stub = { ... } step or load a JSON file via wireMock with a mapping. The key point is that the test drives the mock locally, eliminating external calls.

Trade‑offs and Practical Tips

• Version alignment: Karate bundles a specific WireMock version. Using a different WireMock dependency can cause API mismatches (e.g., missing wireMock keyword). Keep the Karate version in sync with its bundled WireMock or explicitly exclude the bundled version and provide a matching one.
• Port conflicts: Fixed ports (like 8080) may clash with other services in CI containers. Use dynamic port allocation by omitting the port attribute; Karate will assign an available port and expose it via the wireMockPort variable, which you can reference in URLs.
• Startup overhead: Each test suite launch spins up a WireMock process. For large suites with many stubs, consider sharing a single WireMock instance across features via a karate-config.js callOnce block, or keep stub definitions minimal and reuse them with wireMock reset steps.

Getting Started in Your Suite

1. Add the Karate dependency (if not already present). For Maven:

   <dependency>
       <groupId>com.intuit.karate</groupId>
       <artifactId>karate-junit5</artifactId>
       <version>1.4.0</version>
       <scope>test</scope>
   </dependency>

2. In a *.feature file, start WireMock in a Background step as shown above, optionally using dynamic ports.
3. Define stubs either inline with wireMock mappings or load JSON files from classpath:mappings/.
4. Run the suite with mvn test or gradle test. Check the console for a line like WireMock started on port 56789 and verify that no outbound traffic appears in your network monitor.
5. To confirm reliance on the mock, temporarily remove or comment the wireMock background step; the test should fail with a connection error or unexpected response, proving the stub was active.

By integrating Karate’s WireMock support, you replace flaky, network‑dependent tests with fast, deterministic executions that run entirely locally. The approach scales from a single feature file to a full CI pipeline, provided you watch version compatibility and port allocation.