public interface RequestFixture
Handler
implementations.
A request fixture emulates a request, and the effective state of the request handling in the handler pipeline.
A request fixture can be obtained by the requestFixture()
method.
However it is often more convenient to use the alternative handle(Handler, Action)
method.
handle(Handler)
Modifier and Type | Method and Description |
---|---|
RequestFixture |
body(byte[] bytes,
String contentType)
Sets the request body to be the given bytes, and adds a
Content-Type request header of the given value. |
RequestFixture |
body(String text,
String contentType)
Sets the request body to be the given string in utf8 bytes, and adds a
Content-Type request header of the given value. |
RegistrySpec |
getRegistry()
A specification of the context registry.
|
static HandlingResult |
handle(Action<? super Chain> chainAction,
Action<? super RequestFixture> requestFixtureAction)
Unit test a
Handler chain. |
HandlingResult |
handle(Handler handler)
Invokes the given handler with a newly created
Context based on the state of this fixture. |
static HandlingResult |
handle(Handler handler,
Action<? super RequestFixture> action)
Unit test a single
Handler . |
HandlingResult |
handleChain(Action<? super Chain> chainAction)
Similar to
handle(Handler) , but for testing a handler chain. |
RequestFixture |
header(CharSequence name,
String value)
Set a request header value.
|
RequestFixture |
localAddress(HostAndPort local)
Set the local address to which this request is made.
|
RequestFixture |
method(String method)
Set the request method (case insensitive).
|
RequestFixture |
pathBinding(Map<String,String> pathTokens)
Adds a path binding, with the given path tokens.
|
RequestFixture |
pathBinding(String boundTo,
String pastBinding,
Map<String,String> pathTokens)
Adds a path binding, with the given path tokens and parts.
|
RequestFixture |
protocol(String protocol)
Set the HTTP protocol for the request.
|
RequestFixture |
registry(Action<? super RegistrySpec> action)
Configures the context registry.
|
RequestFixture |
remoteAddress(HostAndPort remote)
Set the remote address from which the request is made.
|
static RequestFixture |
requestFixture()
Create a request fixture, for unit testing of
handlers . |
RequestFixture |
responseHeader(CharSequence name,
String value)
Set a response header value.
|
RequestFixture |
serverConfig(Action<? super ServerConfigBuilder> action)
Configures the server config to have no base dir and given configuration.
|
RequestFixture |
timeout(int timeoutSeconds)
Sets the maximum time to allow the handler under test to produce a result.
|
RequestFixture |
uri(String uri)
The URI of the request.
|
static HandlingResult handle(Handler handler, Action<? super RequestFixture> action) throws Exception
Handler
.
import ratpack.handling.Context;
import ratpack.handling.Handler;
import ratpack.test.handling.RequestFixture;
import ratpack.test.handling.HandlingResult;
import static org.junit.Assert.assertEquals;
public class Example {
public static class MyHandler implements Handler {
public void handle(Context ctx) throws Exception {
String outputHeaderValue = ctx.getRequest().getHeaders().get("input-value") + ":bar";
ctx.getResponse().getHeaders().set("output-value", outputHeaderValue);
ctx.render("received: " + ctx.getRequest().getPath());
}
}
public static void main(String[] args) throws Exception {
HandlingResult result = RequestFixture.handle(new MyHandler(), fixture ->
fixture.header("input-value", "foo").uri("some/path")
);
assertEquals("received: some/path", result.rendered(String.class));
assertEquals("foo:bar", result.getHeaders().get("output-value"));
}
}
handler
- The handler to invokeaction
- The configuration of the context for the handlerHandlerTimeoutException
- if the handler takes more than timeout(int)
seconds to send a response or call next()
on the contextException
- any thrown by action
handle(Action, Action)
static HandlingResult handle(Action<? super Chain> chainAction, Action<? super RequestFixture> requestFixtureAction) throws Exception
Handler
chain.
import ratpack.func.Action;
import ratpack.handling.Chain;
import ratpack.test.handling.RequestFixture;
import ratpack.test.handling.HandlingResult;
import static org.junit.Assert.assertEquals;
public class Example {
public static class MyHandlers implements Action<Chain> {
public void execute(Chain chain) throws Exception {
chain.all(ctx -> {
String outputHeaderValue = ctx.getRequest().getHeaders().get("input-value") + ":bar";
ctx.getResponse().getHeaders().set("output-value", outputHeaderValue);
ctx.next();
});
chain.all(ctx -> ctx.render("received: " + ctx.getRequest().getPath()) );
}
}
public static void main(String[] args) throws Exception {
HandlingResult result = RequestFixture.handle(new MyHandlers(), fixture ->
fixture.header("input-value", "foo").uri("some/path")
);
assertEquals("received: some/path", result.rendered(String.class));
assertEquals("foo:bar", result.getHeaders().get("output-value"));
}
}
chainAction
- the definition of a handler chain to testrequestFixtureAction
- the configuration of the request fixtureHandlerTimeoutException
- if the handler takes more than timeout(int)
seconds to send a response or call next()
on the contextException
- any thrown by chainAction
or requestFixtureAction
handle(Handler, Action)
static RequestFixture requestFixture()
handlers
.handle(Handler, Action)
,
handle(Action, Action)
RequestFixture body(byte[] bytes, String contentType)
Content-Type
request header of the given value.
By default the body is empty.
bytes
- the request body in bytescontentType
- the content type of the request bodyRequestFixture body(String text, String contentType)
Content-Type
request header of the given value.
By default the body is empty.
text
- the request body as a stringcontentType
- the content type of the request bodyRegistrySpec getRegistry()
Can be used to make objects (e.g. support services) available via context registry lookup.
By default, only a ServerErrorHandler
and ClientErrorHandler
are in the context registry.
HandlingResult handle(Handler handler) throws HandlerTimeoutException
Context
based on the state of this fixture.
The return value can be used to examine the effective result of the handler.
A result may be one of the following:
Response.send()
methodsContext.render(Object)
Context.clientError(int)
Context.error(Throwable)
Context.next()
methodsinserted
by the handler under test will be invoked.
If the last inserted handler delegates to the next handler, the handling will terminate with a result indicating that the effective result was delegating to the next handler.
This method blocks until a result is achieved, even if the handler performs an asynchronous operation (such as performing blocking IO
).
As such, a time limit on the execution is imposed which by default is 5 seconds.
The time limit can be changed via the timeout(int)
method.
If the time limit is reached, a HandlerTimeoutException
is thrown.
handler
- the handler to testHandlerTimeoutException
- if the handler does not produce a result in the time limit defined by this fixtureHandlingResult handleChain(Action<? super Chain> chainAction) throws Exception
handle(Handler)
, but for testing a handler chain.chainAction
- the handler chain to testHandlerTimeoutException
- if the handler does not produce a result in the time limit defined by this fixtureException
- any thrown by chainAction
RequestFixture header(CharSequence name, String value)
By default there are no request headers.
name
- the header namevalue
- the header valueRequestFixture serverConfig(Action<? super ServerConfigBuilder> action) throws Exception
By default the server config is equivalent to ServerConfig.builder()
.build()
.
action
- configuration of the server configException
- any thrown by action
RequestFixture method(String method)
The default method is "GET"
.
method
- the request methodRequestFixture pathBinding(Map<String,String> pathTokens)
By default, there are no path tokens and no path binding.
pathTokens
- the path tokens to make available to the handler(s) under testRequestFixture pathBinding(String boundTo, String pastBinding, Map<String,String> pathTokens)
By default, there are no path tokens and no path binding.
boundTo
- the part of the request path that the binding bound topastBinding
- the part of the request path past boundTo
pathTokens
- the path tokens and binding to make available to the handler(s) under testRequestFixture registry(Action<? super RegistrySpec> action) throws Exception
action
- a registry specification actionException
- any thrown by action
RequestFixture responseHeader(CharSequence name, String value)
Can be used to simulate the setting of a response header by an upstream handler.
By default there are no request headers.
name
- the header namevalue
- the header valueRequestFixture timeout(int timeoutSeconds)
As handlers may execute asynchronously, a maximum time limit must be used to guard against never ending handlers.
timeoutSeconds
- the maximum number of seconds to allow the handler(s) under test to produce a resultRequestFixture uri(String uri)
No encoding is performed on the given value. It is expected to be a well formed URI path string (potentially including query and fragment strings)
uri
- the URI of the requestRequestFixture remoteAddress(HostAndPort remote)
Effectively the return value of Request.getRemoteAddress()
.
remote
- the remote host and port addressRequestFixture localAddress(HostAndPort local)
Effectively the return value of Request.getLocalAddress()
.
local
- the local host and port addressRequestFixture protocol(String protocol)
protocol
- The string representation of the HTTP protocol.