ratpack.test.exec

Interface ExecHarness

All Superinterfaces:

java.lang.AutoCloseable

public interface ExecHarness
extends java.lang.AutoCloseable

A utility for testing asynchronous support/service code.

An execution harness is backed by a thread pool. It is important to call close() when the object is no longer needed to shutdown this thread pool. Alternatively, if you are performing a single operation you can use one of the *single static methods.

See Also:

yield(Function), yieldSingle(Function), run(Action), runSingle(Action)

Method Summary

Modifier and Type	Method and Description
void	close() Shuts down the thread pool backing this harness.
default void	execute(ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Operation> function)
default void	execute(ratpack.exec.Operation operation)
static void	executeSingle(ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Operation> function)
static void	executeSingle(ratpack.exec.Operation operation)
default ratpack.exec.ExecStarter	fork()
ratpack.exec.ExecController	getController()
static ExecHarness	harness() Creates a new execution harness.
static ExecHarness	harness(int numThreads)
default void	run(ratpack.func.Action<? super ratpack.exec.Execution> action) Initiates an execution and blocks until it completes.
void	run(ratpack.func.Action<? super ratpack.registry.RegistrySpec> registry, ratpack.func.Action<? super ratpack.exec.Execution> action) Initiates an execution and blocks until it completes.
static void	runSingle(ratpack.func.Action<? super ratpack.exec.Execution> action) Convenient form of run(Action) that creates and closes a harness for the run.
static void	runSingle(ratpack.func.Action<? super ratpack.registry.RegistrySpec> registry, ratpack.func.Action<? super ratpack.exec.Execution> action) Convenient form of run(Action, Action) that creates and closes a harness for the run.
<T> ratpack.exec.ExecResult<T>	yield(ratpack.func.Action<? super ratpack.registry.RegistrySpec> registry, ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Promise<T>> func) Synchronously returns a promised value.
default <T> ratpack.exec.ExecResult<T>	yield(ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Promise<T>> func) Synchronously returns a promised value.
static <T> ratpack.exec.ExecResult<T>	yieldSingle(ratpack.func.Action<? super ratpack.registry.RegistrySpec> registry, ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Promise<T>> func) Creates an exec harness, executes the given function with it before closing it, then returning execution result.
static <T> ratpack.exec.ExecResult<T>	yieldSingle(ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Promise<T>> func) Creates an exec harness, executes the given function with it before closing it, then returning execution result.

Method Detail

harness

static ExecHarness harness()

Creates a new execution harness.

import ratpack.exec.Promise;
 import ratpack.test.exec.ExecHarness;
 import ratpack.exec.ExecResult;

 import static org.junit.Assert.assertEquals;

 public class Example {

   // An async callback based API
   static class AsyncApi {

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

     public <T> void returnAsync(T value, Callback<? super T> callback) {
       new Thread(() -> 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 AsyncApi asyncApi = new AsyncApi();

     // Our method under test
     public <T> Promise<T> promise(final T value) {
       return Promise.async(downstream -> asyncApi.returnAsync(value, downstream::success));
     }
   }

   public static void main(String[] args) throws Throwable {
     // the harness must be close()'d when finished with to free resources
     try (ExecHarness harness = ExecHarness.harness()) {

       // set up the code under test
       final AsyncService service = new AsyncService();

       // exercise the async code using the harness, blocking until the promised value is available
       ExecResult<String> result = harness.yield(execution -> service.promise("foo"));

       assertEquals("foo", result.getValue());
     }
   }
 }
 

When using Ratpack's RxJava integration, ExecHarness can be used to test rx.Observable instances by first converting them to a promise. See the ratpack.rx2.RxRatpack.single(Observable) documentation for an example of testing observables.

Returns:

a new execution harness

harness

static ExecHarness harness(int numThreads)

fork

default ratpack.exec.ExecStarter fork()

getController

ratpack.exec.ExecController getController()

yield

default <T> ratpack.exec.ExecResult<T> yield(ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Promise<T>> func)
                                      throws java.lang.Exception

Synchronously returns a promised value.

The given function will execute in a separate thread. The calling thread will block, waiting for the promised value to be provided.

Type Parameters:

T - the type of promised value

Parameters:

func - a function that exercises some code that returns a promise

Returns:

the result of the execution

Throws:

java.lang.Exception - any thrown by the function

yield

<T> ratpack.exec.ExecResult<T> yield(ratpack.func.Action<? super ratpack.registry.RegistrySpec> registry,
                                     ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Promise<T>> func)
                              throws java.lang.Exception

Synchronously returns a promised value.

The given function will execute in a separate thread. The calling thread will block, waiting for the promised value to be provided.

Type Parameters:

T - the type of promised value

Parameters:

registry - the intial contents of the execution registry

func - a function that exercises some code that returns a promise

Returns:

the result of the execution

Throws:

java.lang.Exception - any thrown by the function

yieldSingle

static <T> ratpack.exec.ExecResult<T> yieldSingle(ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Promise<T>> func)
                                           throws java.lang.Exception

Creates an exec harness, executes the given function with it before closing it, then returning execution result.

Type Parameters:

T - the type of promised value

Parameters:

func - a function that exercises some code that returns a promise

Returns:

the result of the execution

Throws:

java.lang.Exception - any thrown by the function, or the promise failure exception

yieldSingle

static <T> ratpack.exec.ExecResult<T> yieldSingle(ratpack.func.Action<? super ratpack.registry.RegistrySpec> registry,
                                                  ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Promise<T>> func)
                                           throws java.lang.Exception

Creates an exec harness, executes the given function with it before closing it, then returning execution result.

Type Parameters:

T - the type of promised value

Parameters:

registry - the intial contents of the execution registry

func - a function that exercises some code that returns a promise

Returns:

the result of the execution

Throws:

java.lang.Exception - any thrown by the function, or the promise failure exception

run

default void run(ratpack.func.Action<? super ratpack.exec.Execution> action)
          throws java.lang.Exception

Initiates an execution and blocks until it completes. If an uncaught exception is thrown during the execution, it will be thrown by this method.

This method is useful for testing an execution that has some detectable side effect, as this method does not return the “result” of the execution.

Parameters:

action - the start of the execution

Throws:

java.lang.Exception - any thrown during the execution that is not explicitly caught

See Also:

runSingle(Action), yield(Function)

run

void run(ratpack.func.Action<? super ratpack.registry.RegistrySpec> registry,
         ratpack.func.Action<? super ratpack.exec.Execution> action)
  throws java.lang.Exception

Initiates an execution and blocks until it completes. If an uncaught exception is thrown during the execution, it will be thrown by this method.

This method is useful for testing an execution that has some detectable side effect, as this method does not return the “result” of the execution.

Parameters:

registry - the intial contents of the execution registry

action - the start of the execution

Throws:

java.lang.Exception - any thrown during the execution that is not explicitly caught

See Also:

runSingle(Action), yield(Function)

runSingle

static void runSingle(ratpack.func.Action<? super ratpack.exec.Execution> action)
               throws java.lang.Exception

Convenient form of run(Action) that creates and closes a harness for the run.

Parameters:

action - the start of the execution

Throws:

java.lang.Exception - any thrown during the execution that is not explicitly caught

See Also:

run(Action), yield(Function)

runSingle

static void runSingle(ratpack.func.Action<? super ratpack.registry.RegistrySpec> registry,
                      ratpack.func.Action<? super ratpack.exec.Execution> action)
               throws java.lang.Exception

Convenient form of run(Action, Action) that creates and closes a harness for the run.

Parameters:

registry - the intial contents of the execution registry

action - the start of the execution

Throws:

java.lang.Exception - any thrown during the execution that is not explicitly caught

See Also:

run(Action), yield(Function)

execute

default void execute(ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Operation> function)
              throws java.lang.Exception

Throws:

java.lang.Exception

execute

default void execute(ratpack.exec.Operation operation)
              throws java.lang.Exception

Throws:

java.lang.Exception

executeSingle

static void executeSingle(ratpack.func.Function<? super ratpack.exec.Execution,? extends ratpack.exec.Operation> function)
                   throws java.lang.Exception

Throws:

java.lang.Exception

executeSingle

static void executeSingle(ratpack.exec.Operation operation)
                   throws java.lang.Exception

Throws:

java.lang.Exception

close

void close()

Shuts down the thread pool backing this harness.

Specified by:

close in interface java.lang.AutoCloseable