Ersatz Server

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.

And it's fast!

Features

Uses an embedded Undertow server to setup the HTTP server
Works with Java 11+, Groovy, and Kotlin
Compatible with the JUnit 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 HTTP and HTTPS requests for GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS, and TRACE request methods.
Alternate distribution as a shadowed jar with many of the dependencies repackaged to avoid collisions.
Support for upload requests with up to 1.5 GB of content and response downloads of up to 500 MB.
Support for chunked response content (e.g. Transfer-encoding: "chunked"), and the configuration of delay times.
Provides a means of using an external endpoint as a configured response (i.e. request forwarding).
Limited support for web sockets messaging.

Getting Started

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

var ersatz = new ErsatzServer();

ersatz.expectations(expect -> {
    expect.GET("/say/hello", req -> {
        req.called(1);
        req.query("name", "Ersatz");
        req.responder(res -> {
            res.body("Hello Ersatz", "text/plain");
        });
    });
});

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(expect -> {
    expect.GET("/say/hello")
        .called(1)
        .query("name","Ersatz")
        .responds()
            .body("Hello Ersatz","text/plain");
});

Artifacts

The Ersatz Server library is available on Maven Central; it may be added to a project via Gradle dependency:

testImplementation 'io.github.cjstehno.ersatz:ersatz:4.0.1'

for Java, and

testImplementation 'io.github.cjstehno.ersatz:ersatz-groovy:4.0.1'

for Groovy (and Java). Or, if you are using Maven:

<dependency>
    <groupId>io.github.cjstehno.ersatz</groupId>
    <artifactId>ersatz</artifactId>
    <version>4.0.1</version>
</dependency>

and

<dependency>
    <groupId>io.github.cjstehno.ersatz</groupId>
    <artifactId>ersatz-groovy</artifactId>
    <version>4.0.1</version>
</dependency>

respectively. 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 Java Docs and Groovy Extension Docs. The GitHub Project also has useful information.

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.