org.springframework.test.web.reactive.server

Interface WebTestClient

public interface WebTestClient

Non-blocking, reactive client for testing web servers. It uses the reactive WebClient internally to perform requests and provides a fluent API to verify responses.

WebTestClient can connect to any server over an HTTP connection. It can also bind directly to WebFlux applications using mock request and response objects, without the need for an HTTP server.

See the static bindToXxx entry points for creating an instance.

Warning: WebTestClient is not usable yet in Kotlin due to a type inference issue which is expected to be fixed as of Kotlin 1.3. You can watch SPR-16057 for up-to-date information. Meanwhile, the proposed alternative is to use directly WebClient with its Reactor and Spring Kotlin extensions to perform integration tests on an embedded WebFlux server.

Since:

5.0

Author:

Rossen Stoyanchev, Brian Clozel

See Also:

StatusAssertions, HeaderAssertions, JsonPathAssertions

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	WebTestClient.BodyContentSpec Spec for expectations on the response body content.
static interface	WebTestClient.BodySpec<B,S extends WebTestClient.BodySpec<B,S>> Spec for expectations on the response body decoded to a single Object.
static interface	WebTestClient.Builder Steps for customizing the WebClient used to test with, internally delegating to a WebClient.Builder.
static interface	WebTestClient.ControllerSpec Specification for customizing controller configuration equivalent to, and internally delegating to, a WebFluxConfigurer.
static interface	WebTestClient.ListBodySpec<E> Spec for expectations on the response body decoded to a List.
static interface	WebTestClient.MockServerSpec<B extends WebTestClient.MockServerSpec<B>> Base specification for setting up tests without a server.
static interface	WebTestClient.RequestBodySpec Specification for providing body of a request.
static interface	WebTestClient.RequestBodyUriSpec Specification for providing the body and the URI of a request.
static interface	WebTestClient.RequestHeadersSpec<S extends WebTestClient.RequestHeadersSpec<S>> Specification for adding request headers and performing an exchange.
static interface	WebTestClient.RequestHeadersUriSpec<S extends WebTestClient.RequestHeadersSpec<S>> Specification for providing request headers and the URI of a request.
static interface	WebTestClient.ResponseSpec Chained API for applying assertions to a response.
static interface	WebTestClient.RouterFunctionSpec Specification for customizing router function configuration.
static interface	WebTestClient.UriSpec<S extends WebTestClient.RequestHeadersSpec<?>> Specification for providing the URI of a request.

Field Summary

Fields

Modifier and Type	Field and Description
static String	WEBTESTCLIENT_REQUEST_ID The name of a request header used to assign a unique id to every request performed through the WebTestClient.

Method Summary

Modifier and Type	Method and Description
static WebTestClient.MockServerSpec<?>	bindToApplicationContext(org.springframework.context.ApplicationContext applicationContext) Use this option to setup a server from the Spring configuration of your application, or some subset of it.
static WebTestClient.ControllerSpec	bindToController(Object... controllers) Use this server setup to test one `@Controller` at a time.
static WebTestClient.RouterFunctionSpec	bindToRouterFunction(org.springframework.web.reactive.function.server.RouterFunction<?> routerFunction) Use this option to set up a server from a RouterFunction.
static WebTestClient.Builder	bindToServer() This server setup option allows you to connect to a running server via Reactor Netty.
static WebTestClient.Builder	bindToServer(org.springframework.http.client.reactive.ClientHttpConnector connector) A variant of bindToServer() with a pre-configured connector.
static WebTestClient.MockServerSpec<?>	bindToWebHandler(org.springframework.web.server.WebHandler webHandler) Integration testing with a "mock" server targeting the given WebHandler.
WebTestClient.RequestHeadersUriSpec<?>	delete() Prepare an HTTP DELETE request.
WebTestClient.RequestHeadersUriSpec<?>	get() Prepare an HTTP GET request.
WebTestClient.RequestHeadersUriSpec<?>	head() Prepare an HTTP HEAD request.
WebTestClient.RequestBodyUriSpec	method(org.springframework.http.HttpMethod method) Prepare a request for the specified HttpMethod.
WebTestClient.Builder	mutate() Return a builder to mutate properties of this web test client.
WebTestClient	mutateWith(WebTestClientConfigurer configurer) Mutate the WebTestClient, apply the given configurer, and build a new instance.
WebTestClient.RequestHeadersUriSpec<?>	options() Prepare an HTTP OPTIONS request.
WebTestClient.RequestBodyUriSpec	patch() Prepare an HTTP PATCH request.
WebTestClient.RequestBodyUriSpec	post() Prepare an HTTP POST request.
WebTestClient.RequestBodyUriSpec	put() Prepare an HTTP PUT request.

Field Detail

WEBTESTCLIENT_REQUEST_ID

static final String WEBTESTCLIENT_REQUEST_ID

The name of a request header used to assign a unique id to every request performed through the WebTestClient. This can be useful for storing contextual information at all phases of request processing (e.g. from a server-side component) under that id and later to look up that information once an ExchangeResult is available.

See Also:

Constant Field Values

Method Detail

get

WebTestClient.RequestHeadersUriSpec<?> get()

Prepare an HTTP GET request.

Returns:

a spec for specifying the target URL

head

WebTestClient.RequestHeadersUriSpec<?> head()

Prepare an HTTP HEAD request.

Returns:

a spec for specifying the target URL

post

WebTestClient.RequestBodyUriSpec post()

Prepare an HTTP POST request.

Returns:

a spec for specifying the target URL

put

WebTestClient.RequestBodyUriSpec put()

Prepare an HTTP PUT request.

Returns:

a spec for specifying the target URL

patch

WebTestClient.RequestBodyUriSpec patch()

Prepare an HTTP PATCH request.

Returns:

a spec for specifying the target URL

delete

WebTestClient.RequestHeadersUriSpec<?> delete()

Prepare an HTTP DELETE request.

Returns:

a spec for specifying the target URL

options

WebTestClient.RequestHeadersUriSpec<?> options()

Prepare an HTTP OPTIONS request.

Returns:

a spec for specifying the target URL

method

WebTestClient.RequestBodyUriSpec method(org.springframework.http.HttpMethod method)

Prepare a request for the specified HttpMethod.

Returns:

a spec for specifying the target URL

mutate

WebTestClient.Builder mutate()

Return a builder to mutate properties of this web test client.

mutateWith

WebTestClient mutateWith(WebTestClientConfigurer configurer)

Mutate the WebTestClient, apply the given configurer, and build a new instance. Essentially a shortcut for:

 mutate().apply(configurer).build();
 

Parameters:

configurer - the configurer to apply

Returns:

the mutated test client

bindToController

static WebTestClient.ControllerSpec bindToController(Object... controllers)

Use this server setup to test one `@Controller` at a time. This option loads the default configuration of @EnableWebFlux. There are builder methods to customize the Java config. The resulting WebFlux application will be tested without an HTTP server using a mock request and response.

Parameters:

controllers - one or more controller instances to tests (specified Class will be turned into instance)

Returns:

chained API to customize server and client config; use WebTestClient.MockServerSpec.configureClient() to transition to client config

bindToRouterFunction

static WebTestClient.RouterFunctionSpec bindToRouterFunction(org.springframework.web.reactive.function.server.RouterFunction<?> routerFunction)

Use this option to set up a server from a RouterFunction. Internally the provided configuration is passed to RouterFunctions#toWebHandler. The resulting WebFlux application will be tested without an HTTP server using a mock request and response.

Parameters:

routerFunction - the RouterFunction to test

Returns:

chained API to customize server and client config; use WebTestClient.MockServerSpec.configureClient() to transition to client config

bindToApplicationContext

static WebTestClient.MockServerSpec<?> bindToApplicationContext(org.springframework.context.ApplicationContext applicationContext)

Use this option to setup a server from the Spring configuration of your application, or some subset of it. Internally the provided configuration is passed to WebHttpHandlerBuilder to set up the request processing chain. The resulting WebFlux application will be tested without an HTTP server using a mock request and response.

Consider using the TestContext framework and @ContextConfiguration in order to efficiently load and inject the Spring configuration into the test class.

Parameters:

applicationContext - the Spring context

Returns:

chained API to customize server and client config; use WebTestClient.MockServerSpec.configureClient() to transition to client config

bindToWebHandler

static WebTestClient.MockServerSpec<?> bindToWebHandler(org.springframework.web.server.WebHandler webHandler)

Integration testing with a "mock" server targeting the given WebHandler.

Parameters:

webHandler - the handler to test

Returns:

chained API to customize server and client config; use WebTestClient.MockServerSpec.configureClient() to transition to client config

bindToServer

static WebTestClient.Builder bindToServer()

This server setup option allows you to connect to a running server via Reactor Netty.

 WebTestClient client = WebTestClient.bindToServer()
         .baseUrl("http://localhost:8080")
         .build();
 

Returns:

chained API to customize client config

bindToServer

static WebTestClient.Builder bindToServer(org.springframework.http.client.reactive.ClientHttpConnector connector)

A variant of bindToServer() with a pre-configured connector.

 WebTestClient client = WebTestClient.bindToServer()
         .baseUrl("http://localhost:8080")
         .build();
 

Returns:

chained API to customize client config

Since:

5.0.2