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.


  • Uses an embedded Undertow server to setup the HTTP server
  • Works with Java 11+
  • Provides a Groovy configuration DSL
  • Works well with Kotlin
  • Compatible with the JUnit (4 or 5) 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.
  • Support for upload requests with up to 1.5 GB of content and response downloads of up to 500 MG.
  • Support for simulating web socket message sending and receiving.
  • Support for chunked response content (e.g. Transfer-encoding: "chunked"), with optional delay times.

Getting Started

The Ersatz User Guide and Java Docs provide detailed documentation of the features and configuration; however, a simple example of the expectation configuration would be (using Groovy):

ErsatzServer ersatz = new ErsatzServer()

ersatz.expectations {
    GET('/say/hello') {
        called 1
        query 'name', 'Ersatz'
        responder {
            body 'Hello Ersatz', 'text/plain'

URL url = "${ersatz.httpUrl}/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 11+ may also be used; the `expectations` block in 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.


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:2.0.0'
or for Maven:
There is also a "safe" (shadow jar) artifact available for situations where the Undertow server is already being used (e.g. Grails or Spring-Boot using Undertow as the embedded server) - see the Shadow Jar section of the User Guide for more information.


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

  • GitHub Project - the GitHub project has all the source code as well as links to all of the documentation.
  • Unit Test Report - the build-generated unit test results report.
  • Test Coverage Report - the build-generated unit test coverage report (via Jacoco).

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.