Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document JUnit 5 before JUnit 4

Browse Source 
Closes gh-864
This commit is contained in:
Andy Wilkinson
2022-11-18 18:25:54 +00:00
parent 16a096faa0
commit decb53b686
1 changed files with 68 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
docs/src/docs/asciidoc/getting-started.adoc
View File

@@ -201,77 +201,12 @@ It then produces documentation snippets for the request and the resulting respon
==== Setting up Your Tests
Exactly how you set up your tests depends on the test framework that you use.
Spring REST Docs provides first-class support for JUnit 4 and JUnit 5.
Spring REST Docs provides first-class support for JUnit 5 and JUnit 4.
JUnit 5 is recommended.
Other frameworks, such as TestNG, are also supported, although slightly more setup is required.
[[getting-started-documentation-snippets-setup-junit]]
===== Setting up Your JUnit 4 Tests
When using JUnit 4, the first step in generating documentation snippets is to declare a `public` `JUnitRestDocumentation` field that is annotated as a JUnit `@Rule`.
The following example shows how to do so:
[source,java,indent=0]
----
@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
----
By default, the `JUnitRestDocumentation` rule is automatically configured with an output directory based on your project's build tool:
[cols="2,5"]
|===
| Build tool | Output directory
| Maven
| `target/generated-snippets`
| Gradle
| `build/generated-snippets`
|===
You can override the default by providing an output directory when you create the `JUnitRestDocumentation` instance.
The following example shows how to do so:
[source,java,indent=0]
----
@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("custom");
----
Next, you must provide an `@Before` method to configure MockMvc or WebTestClient, or REST Assured.
The following examples show how to do so:
[source,java,indent=0,role="primary"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/ExampleApplicationTests.java[tags=setup]
----
<1> The `MockMvc` instance is configured by using a `MockMvcRestDocumentationConfigurer`.
You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.
[source,java,indent=0,role="secondary"]
.WebTestClient
----
include::{examples-dir}/com/example/webtestclient/ExampleApplicationTests.java[tags=setup]
----
<1> The `WebTestClient` instance is configured by adding a `WebTestclientRestDocumentationConfigurer` as an `ExchangeFilterFunction`.
You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`.
[source,java,indent=0,role="secondary"]
.REST Assured
----
include::{examples-dir}/com/example/restassured/ExampleApplicationTests.java[tags=setup]
----
<1> REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a `Filter`.
You can obtain an instance of this class from the static `documentationConfiguration()` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured` package.
The configurer applies sensible defaults and also provides an API for customizing the configuration.
See the <<configuration, configuration section>> for more information.
[[getting-started-documentation-snippets-setup-junit-5]]
===== Setting up Your JUnit 5 Tests
@@ -350,6 +285,72 @@ See the <<configuration, configuration section>> for more information.
[[getting-started-documentation-snippets-setup-junit]]
===== Setting up Your JUnit 4 Tests
When using JUnit 4, the first step in generating documentation snippets is to declare a `public` `JUnitRestDocumentation` field that is annotated as a JUnit `@Rule`.
The following example shows how to do so:
[source,java,indent=0]
----
@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation();
----
By default, the `JUnitRestDocumentation` rule is automatically configured with an output directory based on your project's build tool:
[cols="2,5"]
|===
| Build tool | Output directory
| Maven
| `target/generated-snippets`
| Gradle
| `build/generated-snippets`
|===
You can override the default by providing an output directory when you create the `JUnitRestDocumentation` instance.
The following example shows how to do so:
[source,java,indent=0]
----
@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation("custom");
----
Next, you must provide an `@Before` method to configure MockMvc or WebTestClient, or REST Assured.
The following examples show how to do so:
[source,java,indent=0,role="primary"]
.MockMvc
----
include::{examples-dir}/com/example/mockmvc/ExampleApplicationTests.java[tags=setup]
----
<1> The `MockMvc` instance is configured by using a `MockMvcRestDocumentationConfigurer`.
You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.mockmvc.MockMvcRestDocumentation`.
[source,java,indent=0,role="secondary"]
.WebTestClient
----
include::{examples-dir}/com/example/webtestclient/ExampleApplicationTests.java[tags=setup]
----
<1> The `WebTestClient` instance is configured by adding a `WebTestclientRestDocumentationConfigurer` as an `ExchangeFilterFunction`.
You can obtain an instance of this class from the static `documentationConfiguration()` method on `org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation`.
[source,java,indent=0,role="secondary"]
.REST Assured
----
include::{examples-dir}/com/example/restassured/ExampleApplicationTests.java[tags=setup]
----
<1> REST Assured is configured by adding a `RestAssuredRestDocumentationConfigurer` as a `Filter`.
You can obtain an instance of this class from the static `documentationConfiguration()` method on `RestAssuredRestDocumentation` in the `org.springframework.restdocs.restassured` package.
The configurer applies sensible defaults and also provides an API for customizing the configuration.
See the <<configuration, configuration section>> for more information.
[[getting-started-documentation-snippets-setup-manual]]
===== Setting up your tests without JUnit