Wiremock returns mock responses. The general idea: if the request matches a set of criteria, the pre-defined response will be returned.

You can define criteria on everything that is available in a request: the HTTP method, query parameters, headers, cookies and you can even put constraints on the request body!

Search API

Suppose you have a simple search API, where you provide a query parameter q and its value is the word you search for.

A sample mapping for this endpoint is:

{
    "request": {
        "url": "/search?q=mock",
        "method": "GET"
    },
    "response": {
        "status": 200,
        "body": "Here are the search results for 'mock'!",
        "headers": {
          "Content-Type": "text/plain"
        }
    }
}

This mapping has 2 criteria:

  1. the url should equal /search?q=mock
  2. the HTTP method should be GET

In case all criteria are met, a response is sent back with

  • statuscode 200
  • a body containing the text Here are the search results for 'mock'!
  • a Content-Type header with text/plain value

Let’s put it to the test! Feel free to run this basic Java program.

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;

public class WiremockSearch {
    public static void main(String[] args) {
        HttpClient client = HttpClient.newHttpClient();

        HttpRequest test1 = HttpRequest.newBuilder()
                .GET()
                .uri(URI.create("http://localhost:9999/search?q=mock"))
                .build();

        HttpRequest test2 = HttpRequest.newBuilder()
                .POST(HttpRequest.BodyPublishers.noBody())
                .uri(URI.create("http://localhost:9999/search?q=mock"))
                .build();

        HttpRequest test3 = HttpRequest.newBuilder()
                .GET()
                .uri(URI.create("http://localhost:9999/search?q=hello"))
                .build();
        List<HttpRequest> tests = List.of(test1, test2, test3);
        tests.forEach(request -> {
            try {
                HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
                System.out.println(String.format("%s to %s - response code is %d", request.method(), request.uri().toString(), response.statusCode()));
            } catch (IOException | InterruptedException e) {
                e.printStackTrace();
            }
        });

    }
}

Output of this program looks like - a response code of 404 (not found) means there is not mapping defined for this particular request:

GET to http://localhost:9999/search?q=mock - response code is 200
POST to http://localhost:9999/search?q=mock - response code is 404
GET to http://localhost:9999/search?q=hello - response code is 404

Prime check

{
  "request": {
    "urlPath": "/isprime",
    "method": "GET",
    "queryParameters": {
      "number": {
        "matches": "[\\d]+"
      }
    }
  },
  "response": {
    "status": 200,
    "jsonBody": {
      "isPrime": true
    },
    "headers": {
      "Content-Type": "application/json"
    }
  }
}

This mapping has 3 criteria:

  1. the urlPath should equal /isprime
  2. the HTTP method should be GET
  3. the number query parameter is required and should match the [\\d]+ regular expression, so it should be a number with at least 1 digit

If all criteria are met, the wiremock will return a response with:

  • a 200 statuscode
  • a JSON response body. The JSON object has a isPrime property that has the value true
  • the Content-Type header is set to application/json

Let’s put it to the test with this Java program.

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;

public class WiremockPrime {
    public static void main(String[] args) {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest test1 = HttpRequest.newBuilder()
                .GET()
                .uri(URI.create("http://localhost:9999/isprime?number=123"))
                .build();

        HttpRequest test2 = HttpRequest.newBuilder()
                .method("OPTIONS", HttpRequest.BodyPublishers.noBody())
                .uri(URI.create("http://localhost:9999/isprime?number=123"))
                .build();

        HttpRequest test3 = HttpRequest.newBuilder()
                .GET()
                .uri(URI.create("http://localhost:9999/isprime?number=-7"))
                .build();

        HttpRequest test4 = HttpRequest.newBuilder()
                .GET()
                .uri(URI.create("http://localhost:9999/isprime"))
                .build();
        List<HttpRequest> tests = List.of(test1, test2, test3, test4);
        tests.forEach(request -> {
            try {
                HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
                System.out.println(String.format("%s to %s - response code is %d", request.method(), request.uri().toString(), response.statusCode()));
            } catch (IOException | InterruptedException e) {
                e.printStackTrace();
            }
        });


    }
}

And the ouput of this program is as follows - a response code of 404 (not found) means there is not mapping defined for this particular request::

GET to http://localhost:9999/isprime?number=123 - response code is 200
OPTIONS to http://localhost:9999/isprime?number=123 - response code is 404
GET to http://localhost:9999/isprime?number=-7 - response code is 404
GET to http://localhost:9999/isprime - response code is 404