Ersatz Server

Mock HTTP server for testing client code.

View project on GitHub
Build Status Coverage Status

Introduction

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.

Features

  • 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.

Getting Started

The Ersatz User Guide and Groovy 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 {
            content 'Hello Ersatz', 'text/plain'
        }
    }
}

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

assert ersatz.verify()

ersatz.stop()

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 {
    get('/say/hello').called(1).query('name','Ersatz')
        .responds().content('Hello Ersatz','text/plain')
}

Standard Java 8 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.called(1)
        req.query("name","Ersatz")
        req.responder().content("Hello Ersatz","text/plain")
    }
}).start();

Both forms are equivalent and may be used together.

Artifacts

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:
<dependency>
    <groupId>com.stehno.ersatz</groupId>
    <artifactId>ersatz</artifactId>
    <version>1.5.0</version>
</dependency>
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.

Documentation

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.