Question: How to share documentation snippets for multiple tests

[Koizumi85]

Hello,

in 1.0.0.RELEASE it was possible to build a RestDocumentationResultHandler with some standard snippets in the a @Before method of an abstract test class and then extend this in the test methods like in the following gist:

https://gist.github.com/Koizumi85/99c71e3b07a4dfbfb27def47351132e5

With 1.1.0.RELEASE you deprecated the RestDocumentationResultHandler.snippets() method and provided RestDocumentationResultHandler.document() instead.

The new one creates a new RestDocumentationResultHandler instance and therefore if I simply replace .snippets(...) with .document(...) it doesn't work, because my .alwaysDo(this.document) in the abstract class' setup method, got the old instance of the RestDocumentationResultHandler.

As a workaround I can remove the .alwaysDo() in the abstract class and put an andDo() in each test method. But it feels kind of dirty compared to the old way. So is there another way to do this in 1.1.0.RELEASE now?

Greetings

[wilkinsona]

It became apparent that the old snippets approach was flawed as it made the result handler stateful. This caused problems as the state could become stale. It also wasn't clear exactly when the extra snippets would be documented; only when a subsequent call to perform was made.

It sounds like you're on the right track with andDo. Your test that was:

@Test
public void test() {
    this.document.snippets(
        responseFields(
            fieldWithPath("page").description("The requested Page")
        ));
    this.mockMvc.perform(MockMvcRequestBuilders.get("/search"))
          .andExpect(status().isOk());
}

Should become:

public void test() {
    this.mockMvc.perform(MockMvcRequestBuilders.get("/search"))
        .andExpect(status().isOk())
        .andDo(this.document.document(responseFields(
                fieldWithPath("page").description("The requested Page")
        ));
}

To make the code read a bit better (avoiding the double document in this.document.document), I typically called the document field documentationHandler instead.

I'll use this issue to do a better job of explaining how the new method should be used.

[Koizumi85]

Hello @wilkinsona

thank you for your answer. I understand the intention behind this change. But in fact it prevents to "share" documentation configuration in abstract classes or something.

So in my example above the following 3 lines are becoming unused if I do it the way you suggest and I would have to repeat them in every test, right?

this.document = document(documentationPath,
                preprocessRequest(prettyPrint()),
                preprocessResponse(prettyPrint()));

At least in my project if I did it the way you suggest above the standard snippets (http-request.adoc, http-response.adoc, curl-request.adoc) were lost after this change. So I could not prove if the prettyPrint() processors were still applied to them.

But maybe I did something wrong here... tried a lot of stuff last time. I will try again and give feedback again what exactly happens when I do it this way.

[wilkinsona]

At least in my project if I did it the way you suggest above the standard snippets (http-request.adoc, http-response.adoc, curl-request.adoc) were lost after this change

There's an integration test that verifies that all of the expected snippets are generated.

But maybe I did something wrong here... tried a lot of stuff last time. I will try again and give feedback again what exactly happens when I do it this way.

Thanks