Document how to separate REST documenting tests from 'real' Junit tests

[marceloverdijk]

When following the http://docs.spring.io/spring-restdocs/docs/1.0.0.M1/reference/html5/#getting-started-build-configuration-gradle setup the documenting tests are in the same 'scope' as the normal junit tests.

I think this is a bad practice. When you have a fairly big project with a lot of 'real' junit tests it means when generating the docs all junit tests will be run as well. This is time consuming if you just want to work on documentation.

Further more the unit tests for the documentation are also included in the project's test report, which is also not desired.

I haven't looked into it but with Gradle I think I can setup different SourceSets to separate them. I think it would be good to add something like this to the docs or maybe even making it easier for users by providing a specific restdocs plugin which setups these SrouceSets automatically.

[wilkinsona]

I think this is a bad practice

I disagree that it's bad practice and think it's more a matter of personal style/preference.

In the early days, Spring REST Docs had a (very basic) Gradle plugin and expected tests that produced documentation to be in src/documentation/java. This was removed when the Maven examples were added as I wanted things to be as similar as possible, irrespective of build system.

It's fairly straightforward to set up a documentation-specific source set. We can use this issue to document how to do it for Gradle users.

[marceloverdijk]

Yes probably a plugin for only creating SourceSets is a little bit of overkill. I will look into separate SourceSets soon, and will provide some example for documentation. Don't know if Maven would support this as well.

[steviemo]

This is a good guide on how to separate out your documentation tests from your regular src/test/java tests: http://www.petrikainulainen.net/programming/gradle/getting-started-with-gradle-integration-testing/ Using this guide I created a new sourceSet with a task docs (src/docs/test, src/docs/resources) and run the documentation task in a separate CI build

[leonard84]

A separate sourceset is overkill IMHO, just use JUnit categories, or simple naming conventions with include-exclude rules. Just as maven surefire/failsafe use *Test/*IT. You could use *AT for ApiTest

[wilkinsona]

You make a good point, @leonard84. Thank you. Given that this is largely down to personal preference, and that exactly how you split things up depends on that preference, the build system you're using, and the test framework that you're using, I now think it is out of the scope of REST Docs' own documentation.