Ersatz Server

Mock HTTP server for testing client code.

View project on GitHub
Build Status Coverage Status


Ersatz (noun) An artificial substance or article used to replace something natural or genuine; a substitute.

Ersatz Server is a "mock" HTTP server library for testing HTTP clients. It allows for server-side request/response expectations to be configured so that your client library can make real HTTP calls and get back real pre-configured responses rather than fake stubs.

A simple example of the expectation configuration would be (using Groovy):

ErsatzServer ersatz = new ErsatzServer()

server.expectations {
        called equalTo(1)
        query 'name','Ersatz'
        responder {
            body 'Hello Ersatz','text/plain'


URL url = "${ersatz.serverUrl}/say/hello?name=Ersatz".toURL()
assert url.text == 'Hello Ersatz'

assert ersatz.verify()


which will assert that a GET request to "/say/hello?name=Ersatz" will only happen once and that it will respond with "Hello Ersatz" so that the client code being tested may proceed and do what it needs to do with the response. The expectation may also be written in a builder form, such as:

server.expectations {
        .responds().body('Hello Ersatz','text/plain')

Standard Java 8 may also be used; the example above would look very similar in Java:

ErsatzServer ersatz = new ErsatzServer();

server.expectations(expectations -> {
    expectations.get("/say/hello", req -> {
        req.responder().body("Hello Ersatz","text/plain")

Both forms are equivalent and may be used together.


  • Uses an embedded Undertow server to setup the HTTP server
  • Provides a Java 8 compatible builder interface
  • Provides a Groovy configuration DSL
  • Works well with Kotlin
  • Compatible with the JUnit and Spock testing frameworks (and probably others)
  • Allows configuration of expectations for requests and expected responses
  • Support for Hamcrest matchers
  • Call verification to ensure that expected requests are actually called (including specific call counts).
  • Support for both multipart request and response body content.
  • Support for mocking HTTPS requests.
  • Support for BASIC and DIGEST authentication.
  • Request/Response compression (gzip and/or deflate) supported.
  • Support for GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS, and TRACE request methods.
  • Ability to delay the response from the server to simulate slow connections.
  • Provides a simple standalone proxy server for testing proxied connections.
  • Alternate distribution as a shadowed jar with the Undertow library repackaged to avoid collisions.


Note: There is a breaking interface change between 1.4.0 and 1.5.0 - The Request.header(String, Matcher<String>) method was modified to be Request.header(String, Matcher<Iterable<String<<) in order to support headers with multiple values.

The Ersatz Server library is available on Bintray (JCenter) and Maven Central; it may be added to a project via Gradle dependency:
testCompile 'com.stehno.ersatz:ersatz:1.5.0'
or for Maven:


The best place to learn how to use the Ersatz Server is in the User Guide (especially the Getting Started section) or the Groovy Docs; however, there are a few other interesting documents available:

If you find any issues with the library or the documentation, please feel free to create an issue with a description of the problem or suggestion.

Ersatz is developed and maintained by Christopher J. Stehno under the Apache 2 open source license. This page was originally generated by GitHub Pages using the Architect theme by Jason Long.