Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

MicroShed Testing

Maven Central Javadocs Website Build Status License

Why use MicroShed Testing?

MicroShed Testing offers a fast and simple way of writing and running true-to-production integration tests for Java microservice applications. MicroShed Testing exercises your containerized application from outside the container so you are testing the exact same image that runs in production.

MicroShed Testing aims to:

  1. be easy to get started with
  2. work with any Java EE, Jakarta EE or MicroProfile runtime
  3. provide true-to-production tests

How to use in an existing project:

Add microshed-testing-testcontainers and junit-jupiter as test-scoped dependencies:


    <!-- other dependencies... -->

How to try out a sample locally:

Run with Maven:

./gradlew publishToMavenLocal
cd sample-apps/maven-app
mvn clean install

Run with Gradle:

./gradlew :microshed-testing-jaxrs-json:test

NOTE: The first run will take longer due to downloading required container layers. Subsequent runs will be faster.

Tested with:

  • OpenLiberty
  • Wildfly
  • Payara Micro
  • Apache TomEE
  • Quarkus

To change which app server is used, [un]comment sections of the test app's Dockerfile at sample-apps/jaxrs-json/Dockerfile

What it looks like

Assume we have a basic JAX-RS application that can perform create, update, and delete operations on 'Person' data objects. It may look something like this:

public class PersonService {

    private final PersonRepo personRepo = // ...

    public Collection<Person> getAllPeople() {
        return personRepo.values();

    public Person getPerson(@PathParam("personId") long id) {
        Person foundPerson = personRepo.get(id);
        if (foundPerson == null)
            throw new NotFoundException("Person with id " + id + " not found.");
        return foundPerson;
    // ...

Using MicroShed Testing, we can write an integration test that looks something like this:

import static org.junit.jupiter.api.Assertions.*;
import org.junit.jupiter.api.Test;
import org.microshed.testing.jaxrs.RESTClient;
import org.microshed.testing.jupiter.MicroShedTest;
import org.microshed.testing.testcontainers.ApplicationContainer;
import org.testcontainers.junit.jupiter.Container;

public class BasicJAXRSServiceTest {

    // This will search for a Dockerfile in the repository and start up the application
    // in a Docker container, and wait for it to be ready before starting the tests.
    public static ApplicationContainer app = new ApplicationContainer()

    // This injects a REST _Client_ proxy of the PersonService shown above
    // This allows us to easily invoke HTTP requests on the running application container
    public static PersonService personSvc;

    public void testGetPerson() {
        // This invokes an HTTP POST request to the running container, which triggers
        // the PersonService#createPerson endpoint and returns the generated ID
        Long bobId = personSvc.createPerson("Bob", 24);
        // Using the generated ID, invoke an HTTP GET request to read the record we just created
        // The JSON response will be automatically converted to a 'Person' object using JSON-B 
        Person bob = personSvc.getPerson(bobId);
        assertEquals(24, bob.age);
    public void testGetUnknownPerson() {
        // This invokes an HTTP GET request to get a person with ID -1, which does not exist
        // asserts that the application container returns an HTTP 404 (not found) exception
        assertThrows(NotFoundException.class, () -> personSvc.getPerson(-1L));

    // ...