Keep Your Promises: Contract-Based Testing for JAX-RS APIs

great! pact is there, the stage is set, and we are ready to take off with some real code snippets. let's assume we are developing a restful web api for managing people, using terrific apache cxf and jax-rs 2.0 specification. to keep things simple, we are going to introduce only two endpoints:

• post /people/v1 to create a new person.
• get /people/v1?email=<email> to find the person by email address.

essentially, we may not bother and just communicate these minimal pieces of our service contract to everyone so let the consumers deal with that themselves (and indeed, pact supports such a scenario). surely, we are not like that; we do care and would like to document our apis comprehensively. likely, we are already familiar with swagger . with that, here is our peoplerestservice :

@api(value = "manage people")
@path("/people/v1")
@consumes(mediatype.application_json)
@produces(mediatype.application_json)
public class peoplerestservice {
    @get
    @apioperation(value = "find person by e-mail", 
        notes = "find person by e-mail", response = person.class)
    @apiresponses({
        @apiresponse(code = 404, 
            message = "person with such e-mail doesn't exists", 
            response = genericerror.class)
    })
    public response findperson(
        @apiparam(value = "e-mail address to lookup for", required = true) 
        @queryparam("email") final string email) {
        // implementation here
    }

    @post
    @apioperation(value = "create new person", 
        notes = "create new person", response = person.class)
    @apiresponses({
        @apiresponse(code = 201, 
            message = "person created successfully", 
            response = person.class),
        @apiresponse(code = 409, 
            message = "person with such e-mail already exists", 
            response = genericerror.class)
    })
    public response addperson(@context uriinfo uriinfo, 
        @apiparam(required = true) personupdate person) {
        // implementation here
    }
}

the implementation details are not important at the moment. however, let's take a look at the genericerror , personupdate , and person classes, as they are an integral part of our service contract.

@apimodel(description = "generic error representation")
public class genericerror {
    @apimodelproperty(value = "error message", required = true)
    private string message;
}

@apimodel(description = "person resource representation")
public class personupdate {
    @apimodelproperty(value = "person's first name", required = true) 
    private string email;
    @apimodelproperty(value = "person's e-mail address", required = true) 
    private string firstname;
    @apimodelproperty(value = "person's last name", required = true) 
    private string lastname;
    @apimodelproperty(value = "person's age", required = true) 
    private int age;
}

@apimodel(description = "person resource representation")
public class person extends personupdate {
    @apimodelproperty(value = "person's identifier", required = true) 
    private string id;
}

excellent! once we have swagger annotations in place and apache cxf swagger integration turned on, we could generate swagger.json specification file, bring it to live in swagger ui and distribute to every partner or interested consumer.

it would be great if we could use this swagger specification along with pact framework implementation to serve as a service contract. thanks to atlassian , we are certainly able to do that using swagger-request-validator , a library for validating http requests and responses against a swagger and openapi specification that nicely integrates with pact jvm, as well.

cool! now, let's switch sides from provider to consumer and try to figure out what we can do having such swagger specification in our hands. it turns out, we can do a lot of things. for example, let's take a look at the post action, which creates a new person. as a client (or consumer), we could express our expectations in such a form that having a valid payload submitted along with the request, we would expect http status code 201 to be returned by the provider and the response payload should contain a new person with an identifier assigned. in fact, translating this statement into pact jvm assertions is pretty straightforward.

@pact(provider = provider_id, consumer = consumer_id)
public pactfragment addperson(pactdslwithprovider builder) {
    return builder
        .uponreceiving("post new person")
        .method("post")
        .path("/services/people/v1")
        .body(
            new pactdsljsonbody()
                .stringtype("email")
                .stringtype("firstname")
                .stringtype("lastname")
                .numbertype("age")
        )
        .willrespondwith()
        .status(201)
        .matchheader(httpheaders.content_type, mediatype.application_json)
        .body(
            new pactdsljsonbody()
                .uuid("id")
                .stringtype("email")
                .stringtype("firstname")
                .stringtype("lastname")
                .numbertype("age")
        )
       .tofragment();
}

to trigger the contract verification process, we are going to use awesome junit and very popular rest assured framework. before that, let's clarify what provider_id and consumer_id are from the code snippet above. as you may expect, provider_id is the reference to the contract specification. for simplicity, we would fetch swagger specification from running peoplerestservice endpoint. luckily, spring boot testing improvements make this task a no-brainer.

@runwith(springjunit4classrunner.class)
@springboottest(webenvironment = webenvironment.random_port, 
    classes = peoplerestconfiguration.class)
public class peoplerestcontracttest {
    private static final string provider_id = "people rest service";
    private static final string consumer_id = "people rest service consumer";

    private validatedpactproviderrule provider;
    @value("${local.server.port}")
    private int port;

    @rule
    public validatedpactproviderrule getvalidatedpactproviderrule() {
        if (provider == null) {
            provider = new validatedpactproviderrule("http://localhost:" + port + 
                "/services/swagger.json", null, provider_id, this);
        }

        return provider;
    }
}

the consumer_id is just a way to identify the consumer, not much to say about it. with that, we are ready to finish up with our first test case:

@test
@pactverification(value = provider_id, fragment = "addperson")
public void testaddperson() {
    given()
        .contenttype(contenttype.json)
        .body(new personupdate("tom@smith.com", "tom", "smith", 60))
        .post(provider.getconfig().url() + "/services/people/v1");
}

awesome! as simple as that. please notice the presence of the @pactverification annotation where we are referencing the appropriate verification fragment by name. in this case, it points out the addperson method that we have introduced before.

great, but...what's the point? glad you are asking, because from now on, any change in the contract which may not be backward compatible will break our test case. for example, if the provider decides to remove the id property from the response payload, the test case will fail. renaming the request payload properties is big no-no; again, the test case will fail. adding new path parameters? no luck; the test case won't let it pass. you may go even further than that and fail on every contract change, even if it's backward-compatible (using swagger-validator.properties for fine-tuning).

validation.response=error
validation.response.body.missing=error

not a very good idea but still, if you need it, it is there. similarly, let us add a couple of more test cases for the get endpoint, starting from a successful scenario where the person we are looking for exists. for example:

@pact(provider = provider_id, consumer = consumer_id)
public pactfragment findperson(pactdslwithprovider builder) {
    return builder
        .uponreceiving("get find person")
        .method("get")
        .path("/services/people/v1")
        .query("email=tom@smith.com")
        .willrespondwith()
        .status(200)
        .matchheader(httpheaders.content_type, mediatype.application_json)
        .body(
            new pactdsljsonbody()
                .uuid("id")
                .stringtype("email")
                .stringtype("firstname")
                .stringtype("lastname")
                .numbertype("age")
        )
        .tofragment();
}

@test
@pactverification(value = provider_id, fragment = "findperson")
public void testfindperson() {
    given()
        .contenttype(contenttype.json)
        .queryparam("email", "tom@smith.com")
        .get(provider.getconfig().url() + "/services/people/v1");
}

please take a note that here we introduced query string verification using query("email=tom@smith.com") assertion. following the possible outcomes, let us also cover the unsuccessful scenario, where person does not exist and we expect some error to be returned, along with the 404 status code. for example:

@pact(provider = provider_id, consumer = consumer_id)
public pactfragment findnonexistingperson(pactdslwithprovider builder) {
    return builder
        .uponreceiving("get find non-existing person")
        .method("get")
        .path("/services/people/v1")
        .query("email=tom@smith.com")
        .willrespondwith()
        .status(404)
        .matchheader(httpheaders.content_type, mediatype.application_json)
        .body(new pactdsljsonbody().stringtype("message"))
        .tofragment();
}

@test
@pactverification(value = provider_id, fragment = "findnonexistingperson")
public void testfindpersonwhichdoesnotexist() {
    given()
        .contenttype(contenttype.json)
        .queryparam("email", "tom@smith.com")
        .get(provider.getconfig().url() + "/services/people/v1");
}

this is a really brilliant, maintainable, understandable, and non-intrusive approach to address such complex and important problems as contract-based testing and consumer-driven contracts . hopefully, this somewhat new testing technique would help you to catch more issues during the development phase way before they would have a chance to leak into production.

thanks to swagger, we were able to take a few shortcuts, but in case you don't have such a luxury, pact has a quite rich specification that you are very welcome to learn and use. in any case, pact jvm does a really great job in helping you out writing small and concise test cases.

the complete project sources are available on github .