ratpack.test

Class UnitTest

java.lang.Object

ratpack.test.UnitTest

public abstract class UnitTest
extends java.lang.Object

Static methods for the unit testing of handlers.

Method Summary

Modifier and Type	Method and Description
static ExecHarness	execHarness() Creates a new execution harness, for unit testing code that produces a promise.
static HandlingResult	handle(ratpack.func.Action<? super ratpack.handling.Chain> chainAction, ratpack.func.Action<? super RequestFixture> requestFixtureAction) Unit test a Handler chain.
static HandlingResult	handle(ratpack.handling.Handler handler, ratpack.func.Action<? super RequestFixture> action) Unit test a single Handler.
static RequestFixture	requestFixture() Create a request fixture, for unit testing of handlers.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

handle

public static HandlingResult handle(ratpack.handling.Handler handler,
                                    ratpack.func.Action<? super RequestFixture> action)
                             throws java.lang.Exception

Unit test a single Handler.

import ratpack.handling.Context;
 import ratpack.handling.Handler;
 import ratpack.test.UnitTest;
 import ratpack.test.handling.HandlingResult;

 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 = UnitTest.handle(new MyHandler(), fixture ->
         fixture.header("input-value", "foo").uri("some/path")
     );

     assert result.rendered(String.class).equals("received: some/path");
     assert result.getHeaders().get("output-value").equals("foo:bar");
   }
 }
 

Parameters:

handler - The handler to invoke

action - The configuration of the context for the handler

Returns:

A result object indicating what happened

Throws:

HandlerTimeoutException - if the handler takes more than RequestFixture.timeout(int) seconds to send a response or call next() on the context

java.lang.Exception - any thrown by action

See Also:

handle(Action, Action)

handle

public static HandlingResult handle(ratpack.func.Action<? super ratpack.handling.Chain> chainAction,
                                    ratpack.func.Action<? super RequestFixture> requestFixtureAction)
                             throws java.lang.Exception

Unit test a Handler chain.

import ratpack.func.Action;
 import ratpack.handling.Chain;
 import ratpack.test.UnitTest;
 import ratpack.test.handling.HandlingResult;

 public class Example {

   public static class MyHandlers implements Action<Chain> {
     public void execute(Chain chain) throws Exception {
       chain.handler(ctx -> {
         String outputHeaderValue = ctx.getRequest().getHeaders().get("input-value") + ":bar";
         ctx.getResponse().getHeaders().set("output-value", outputHeaderValue);
         ctx.next();
       });
       chain.handler(ctx -> {
         ctx.render("received: " + ctx.getRequest().getPath());
       });
     }
   }

   public static void main(String[] args) throws Exception {
     HandlingResult result = UnitTest.handle(new MyHandlers(), fixture ->
         fixture.header("input-value", "foo").uri("some/path")
     );

     assert result.rendered(String.class).equals("received: some/path");
     assert result.getHeaders().get("output-value").equals("foo:bar");
   }
 }
 

Parameters:

chainAction - the definition of a handler chain to test

requestFixtureAction - the configuration of the request fixture

Returns:

a result object indicating what happened

Throws:

HandlerTimeoutException - if the handler takes more than RequestFixture.timeout(int) seconds to send a response or call next() on the context

java.lang.Exception - any thrown by chainAction or requestFixtureAction

See Also:

handle(Handler, Action)

requestFixture

public static RequestFixture requestFixture()

Create a request fixture, for unit testing of handlers.

Returns:

a request fixture

See Also:

handle(ratpack.handling.Handler, ratpack.func.Action), handle(ratpack.func.Action, ratpack.func.Action)

execHarness

public static ExecHarness execHarness()

Creates a new execution harness, for unit testing code that produces a promise.

 import ratpack.func.Action;
 import ratpack.func.Function;
 import ratpack.exec.ExecControl;
 import ratpack.exec.Execution;
 import ratpack.exec.Promise;
 import ratpack.exec.Fulfiller;
 import ratpack.test.UnitTest;
 import ratpack.test.exec.ExecHarness;
 import ratpack.test.exec.ExecResult;
 import javax.inject.Inject;

 public class Example {

   // An async callback based API
   static class AsyncApi {

     static interface Callback<T> {
       void receive(T value);
     }

     public <T> void returnAsync(final T value, final Callback<? super T> callback) {
       new Thread() {
         public void run() {
           callback.receive(value);
         }
       }.run();
     }
   }

   // Our service class that wraps the raw async API
   // In the real app this is created by the DI container (e.g. Guice)
   static class AsyncService {
     private final ExecControl execControl;
     private final AsyncApi asyncApi = new AsyncApi();

     @Inject
     public AsyncService(ExecControl execControl) {
       this.execControl = execControl;
     }

     // Our method under test
     public <T> Promise<T> promise(final T value) {
       return execControl.promise(new Action<Fulfiller<T>>() {
         public void execute(final Fulfiller<T> fulfiller) {
           asyncApi.returnAsync(value, new AsyncApi.Callback<T>() {
             public void receive(T returnedValue) {
               fulfiller.success(returnedValue);
             }
           });
         }
       });
     }
   }


   // Our test
   public static void main(String[] args) throws Throwable {

     // the harness must be close()'d when finished with to free resources
     try(ExecHarness harness = UnitTest.execHarness()) {

       // set up the code under test using the exec control from the harness
       final AsyncService service = new AsyncService(harness.getControl());

       // exercise the async code using the harness, blocking until the promised value is available
       ExecResult<String> result = harness.execute(new Function<Execution, Promise<String>>() {
         public Promise<String> apply(Execution execution) {
           // execute the code under test
           return service.promise("foo");
         }
       });

       assert result.getValue() == "foo";
     }
   }
 }
 

Returns:

An exec harness