304 lines
8.3 KiB
Plaintext
304 lines
8.3 KiB
Plaintext
[[webtestclient]]
|
|
= WebTestClient
|
|
|
|
`WebTestClient` is a thin shell around <<web-reactive.adoc#webflux-client, WebClient>>,
|
|
using it to perform requests and exposing a dedicated, fluent API for verifying responses.
|
|
`WebTestClient` binds to a WebFlux application by using a
|
|
<<testing.adoc#mock-objects-web-reactive,mock request and response>>, or it can test any
|
|
web server over an HTTP connection.
|
|
|
|
TIP: Kotlin users: See <<languages.adoc#kotlin-webtestclient-issue,this section>>
|
|
related to use of the `WebTestClient`.
|
|
|
|
|
|
|
|
|
|
[[webtestclient-setup]]
|
|
== Setup
|
|
|
|
To create a `WebTestClient` you must choose one of several server setup options.
|
|
Effectively you're either configuring the WebFlux application to bind to, or using
|
|
a URL to connect to a running server.
|
|
|
|
|
|
|
|
[[webtestclient-controller-config]]
|
|
=== Bind to Controller
|
|
|
|
The following example shows how to create a server setup to test one `@Controller` at a time:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
client = WebTestClient.bindToController(new TestController()).build();
|
|
----
|
|
|
|
The preceding example loads the <<web-reactive.adoc#webflux-config,WebFlux Java configuration>> and
|
|
registers the given controller. The resulting WebFlux application is tested
|
|
without an HTTP server by using mock request and response objects. There are more methods
|
|
on the builder to customize the default WebFlux Java configuration.
|
|
|
|
|
|
|
|
[[webtestclient-fn-config]]
|
|
=== Bind to Router Function
|
|
|
|
The following example shows how to set up a server from a
|
|
<<web-reactive.adoc#webflux-fn,RouterFunction>>:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
RouterFunction<?> route = ...
|
|
client = WebTestClient.bindToRouterFunction(route).build();
|
|
----
|
|
|
|
Internally, the configuration is passed to `RouterFunctions.toWebHandler`.
|
|
The resulting WebFlux application is tested without an HTTP server by using mock
|
|
request and response objects.
|
|
|
|
|
|
|
|
[[webtestclient-context-config]]
|
|
=== Bind to `ApplicationContext`
|
|
|
|
The following example shows how to setup a server from the Spring configuration of your application or
|
|
some subset of it:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
@RunWith(SpringRunner.class)
|
|
@ContextConfiguration(classes = WebConfig.class) // <1>
|
|
public class MyTests {
|
|
|
|
@Autowired
|
|
private ApplicationContext context; // <2>
|
|
|
|
private WebTestClient client;
|
|
|
|
@Before
|
|
public void setUp() {
|
|
client = WebTestClient.bindToApplicationContext(context).build(); // <3>
|
|
}
|
|
}
|
|
----
|
|
|
|
<1> Specify the configuration to load
|
|
<2> Inject the configuration
|
|
<3> Create the `WebTestClient`
|
|
|
|
Internally, the configuration is passed to `WebHttpHandlerBuilder` to set up
|
|
the request processing chain. See
|
|
<<web-reactive.adoc#webflux-web-handler-api,WebHandler API>> for more details. The
|
|
resulting WebFlux application is tested without an HTTP server by using mock request
|
|
and response objects.
|
|
|
|
|
|
|
|
[[webtestclient-server-config]]
|
|
=== Bind to Server
|
|
|
|
The following server setup option lets you connect to a running server:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
client = WebTestClient.bindToServer().baseUrl("http://localhost:8080").build();
|
|
----
|
|
|
|
|
|
|
|
[[webtestclient-client-config]]
|
|
=== Client Builder
|
|
|
|
In addition to the server setup options described earlier, you can also configure client
|
|
options, including base URL, default headers, client filters, and others. These options
|
|
are readily available following `bindToServer`. For all others, you need to use
|
|
`configureClient()` to transition from server to client configuration, as follows:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
client = WebTestClient.bindToController(new TestController())
|
|
.configureClient()
|
|
.baseUrl("/test")
|
|
.build();
|
|
----
|
|
|
|
|
|
|
|
|
|
[[webtestclient-tests]]
|
|
== Writing Tests
|
|
|
|
`WebTestClient` provides an API identical to <<web-reactive.adoc#webflux-client,WebClient>>
|
|
up to the point of performing a request by using `exchange()`. What follows after
|
|
`exchange()` is a chained API workflow to verify responses.
|
|
|
|
Typically, you start by asserting the response status and headers, as follows:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
client.get().uri("/persons/1")
|
|
.accept(MediaType.APPLICATION_JSON_UTF8)
|
|
.exchange()
|
|
.expectStatus().isOk()
|
|
.expectHeader().contentType(MediaType.APPLICATION_JSON_UTF8)
|
|
// ...
|
|
----
|
|
|
|
Then you specify how to decode and consume the response body:
|
|
|
|
* `expectBody(Class<T>)`: Decode to single object.
|
|
* `expectBodyList(Class<T>)`: Decode and collect objects to `List<T>`.
|
|
* `expectBody()`: Decode to `byte[]` for <<webtestclient-json>> or an empty body.
|
|
|
|
Then you can use built-in assertions for the body. The following example shows one way to do so:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
client.get().uri("/persons")
|
|
.exchange()
|
|
.expectStatus().isOk()
|
|
.expectBodyList(Person.class).hasSize(3).contains(person);
|
|
----
|
|
|
|
You can also go beyond the built-in assertions and create your own, as the following example shows:
|
|
|
|
----
|
|
client.get().uri("/persons/1")
|
|
.exchange()
|
|
.expectStatus().isOk()
|
|
.expectBody(Person.class)
|
|
.consumeWith(result -> {
|
|
// custom assertions (e.g. AssertJ)...
|
|
});
|
|
----
|
|
|
|
You can also exit the workflow and get a result, as follows:
|
|
|
|
----
|
|
EntityExchangeResult<Person> result = client.get().uri("/persons/1")
|
|
.exchange()
|
|
.expectStatus().isOk()
|
|
.expectBody(Person.class)
|
|
.returnResult();
|
|
----
|
|
|
|
TIP: When you need to decode to a target type with generics, look for the overloaded methods
|
|
that accept
|
|
{api-spring-framework}/core/ParameterizedTypeReference.html[`ParameterizedTypeReference`]
|
|
instead of `Class<T>`.
|
|
|
|
|
|
|
|
[[webtestclient-no-content]]
|
|
=== No Content
|
|
|
|
If the response has no content (or you do not care if it does) use `Void.class`, which ensures
|
|
that resources are released. The following example shows how to do so:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
client.get().uri("/persons/123")
|
|
.exchange()
|
|
.expectStatus().isNotFound()
|
|
.expectBody(Void.class);
|
|
----
|
|
|
|
Alternatively, if you want to assert there is no response content, you can use code similar to the following:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
client.post().uri("/persons")
|
|
.body(personMono, Person.class)
|
|
.exchange()
|
|
.expectStatus().isCreated()
|
|
.expectBody().isEmpty();
|
|
----
|
|
|
|
|
|
|
|
[[webtestclient-json]]
|
|
=== JSON Content
|
|
|
|
When you use `expectBody()`, the response is consumed as a `byte[]`. This is useful for
|
|
raw content assertions. For example, you can use
|
|
http://jsonassert.skyscreamer.org[JSONAssert] to verify JSON content, as follows:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
client.get().uri("/persons/1")
|
|
.exchange()
|
|
.expectStatus().isOk()
|
|
.expectBody()
|
|
.json("{\"name\":\"Jane\"}")
|
|
----
|
|
|
|
You can also use https://github.com/jayway/JsonPath[JSONPath] expressions, as follows:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
client.get().uri("/persons")
|
|
.exchange()
|
|
.expectStatus().isOk()
|
|
.expectBody()
|
|
.jsonPath("$[0].name").isEqualTo("Jane")
|
|
.jsonPath("$[1].name").isEqualTo("Jason");
|
|
----
|
|
|
|
|
|
|
|
[[webtestclient-stream]]
|
|
=== Streaming Responses
|
|
|
|
To test infinite streams (for example, `"text/event-stream"` or `"application/stream+json"`),
|
|
you need to exit the chained API (by using `returnResult`), immediately after the response status
|
|
and header assertions, as the following example shows:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
FluxExchangeResult<MyEvent> result = client.get().uri("/events")
|
|
.accept(TEXT_EVENT_STREAM)
|
|
.exchange()
|
|
.expectStatus().isOk()
|
|
.returnResult(MyEvent.class);
|
|
|
|
----
|
|
|
|
Now you can consume the `Flux<T>`, assert decoded objects as they come, and then
|
|
cancel at some point when test objectives are met. We recommend using the `StepVerifier`
|
|
from the `reactor-test` module to do that, as the following example shows:
|
|
|
|
[source,java,intent=0]
|
|
[subs="verbatim,quotes"]
|
|
----
|
|
Flux<Event> eventFux = result.getResponseBody();
|
|
|
|
StepVerifier.create(eventFlux)
|
|
.expectNext(person)
|
|
.expectNextCount(4)
|
|
.consumeNextWith(p -> ...)
|
|
.thenCancel()
|
|
.verify();
|
|
----
|
|
|
|
|
|
|
|
[[webtestclient-request-body]]
|
|
=== Request Body
|
|
|
|
When it comes to building requests, the `WebTestClient` offers an API identical to the
|
|
`WebClient`, and the implementation is mostly a simple pass-through. See
|
|
the <<web-reactive.adoc#webflux-client-body,WebClient documentation>> for examples on
|
|
how to prepare a request with a body, including submitting form data, multipart requests,
|
|
and more.
|