TestWorkflowEnvironment (temporal-sdk 1.0.2 API)

All Known Implementing Classes:: TestWorkflowEnvironmentInternal

public interface TestWorkflowEnvironment

TestWorkflowEnvironment provides workflow unit testing capabilities.

Testing the workflow code is hard as it might be potentially very long running. The included in-memory implementation of the Temporal service supports an automatic time skipping. Anytime a workflow under the test as well as the unit test code are waiting on a timer (or sleep) the internal service time is automatically advanced to the nearest time that unblocks one of the waiting threads. This way a workflow that runs in production for months is unit tested in milliseconds. Here is an example of a test that executes in a few milliseconds instead of over two hours that are needed for the workflow to complete:


   public class SignaledWorkflowImpl implements SignaledWorkflow {
     private String signalInput;

     @Override
     public String workflow1(String input) {
       Workflow.sleep(Duration.ofHours(1));
       Workflow.await(() -> signalInput != null);
       Workflow.sleep(Duration.ofHours(1));
       return signalInput + "-" + input;
     }

     @Override
     public void processSignal(String input) {
       signalInput = input;
    }
  }

  @Test
  public void testSignal() throws ExecutionException, InterruptedException {
    TestWorkflowEnvironment testEnvironment = TestWorkflowEnvironment.newInstance();

    // Creates a worker that polls tasks from the service owned by the testEnvironment.
    Worker worker = testEnvironment.newWorker(TASK_QUEUE);
    worker.registerWorkflowImplementationTypes(SignaledWorkflowImpl.class);
    worker.start();

    // Creates a WorkflowClient that interacts with the server owned by the testEnvironment.
    WorkflowClient client = testEnvironment.getWorkflowClient();
    SignaledWorkflow workflow = client.newWorkflowStub(SignaledWorkflow.class);

    // Starts a workflow execution
    CompletableFuture result = WorkflowClient.execute(workflow::workflow1, "input1");

    // The sleep forwards the service clock for 65 minutes without blocking.
    // This ensures that the signal is sent after the one hour sleep in the workflow code.
    testEnvironment.sleep(Duration.ofMinutes(65));
    workflow.processSignal("signalInput");

    // Blocks until workflow is complete. Workflow sleep forwards clock for one hour and
    // this call returns almost immediately.
    assertEquals("signalInput-input1", result.get());

    // Closes workers and releases in-memory service.
    testEnvironment.close();
  }

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`void`	`awaitTermination(long timeout, java.util.concurrent.TimeUnit unit)` Blocks until all tasks have completed execution after a shutdown request, or the timeout occurs, or the current thread is interrupted, whichever happens first.
`void`	`close()` Calls `shutdownNow()` and `awaitTermination(long, TimeUnit)`.
`long`	`currentTimeMillis()` Returns the current in-memory test Temporal service time in milliseconds.
`java.lang.String`	`getDiagnostics()` Returns the diagnostic data about the internal service state.
`java.lang.String`	`getNamespace()`
`WorkerFactory`	`getWorkerFactory()`
`WorkflowClient`	`getWorkflowClient()` Creates a WorkflowClient that is connected to the in-memory test Temporal service.
`io.temporal.serviceclient.WorkflowServiceStubs`	`getWorkflowService()` Returns the in-memory test Temporal service that is owned by this.
`boolean`	`isShutdown()` Was `shutdownNow()` or `shutdown()` called?
`boolean`	`isStarted()` Was `start()` called?
`boolean`	`isTerminated()` Are all tasks done after `shutdownNow()` or `shutdown()`?
`static TestWorkflowEnvironment`	`newInstance()`
`static TestWorkflowEnvironment`	`newInstance(TestEnvironmentOptions options)`
`Worker`	`newWorker(java.lang.String taskQueue)` Creates a new Worker instance that is connected to the in-memory test Temporal service.
`Worker`	`newWorker(java.lang.String taskQueue, WorkerOptions options)` Creates a new Worker instance that is connected to the in-memory test Temporal service.
`void`	`registerDelayedCallback(java.time.Duration delay, java.lang.Runnable r)` Registers a callback to run after the specified delay according to the test Temporal service internal clock.
`void`	`shutdown()` Initiates an orderly shutdown in which polls are stopped and already received workflow and activity tasks are executed.
`void`	`shutdownNow()` Initiates an orderly shutdown in which polls are stopped and already received workflow and activity tasks are attempted to be stopped.
`void`	`sleep(java.time.Duration duration)` Wait until internal test Temporal service time passes the specified duration.
`void`	`start()` Start all workers created by this factory.

- Method Detail
  - newInstance
```
static TestWorkflowEnvironment newInstance()
```
  - newInstance
```
static TestWorkflowEnvironment newInstance(TestEnvironmentOptions options)
```
  - newWorker
```
Worker newWorker(java.lang.String taskQueue)
```
    Creates a new Worker instance that is connected to the in-memory test Temporal service.
    
    Parameters:
    
    taskQueue - task queue to poll.
  - newWorker
```
Worker newWorker(java.lang.String taskQueue,
                 WorkerOptions options)
```
    Creates a new Worker instance that is connected to the in-memory test Temporal service.
    
    Parameters:
    
    taskQueue - task queue to poll.
  - getWorkflowClient
```
WorkflowClient getWorkflowClient()
```
    Creates a WorkflowClient that is connected to the in-memory test Temporal service.
  - currentTimeMillis
```
long currentTimeMillis()
```
    Returns the current in-memory test Temporal service time in milliseconds. This time might not be equal to System.currentTimeMillis() due to time skipping.
  - sleep
```
void sleep(java.time.Duration duration)
```
    Wait until internal test Temporal service time passes the specified duration. This call also indicates that workflow time might jump forward (if none of the activities are running) up to the specified duration.
  - registerDelayedCallback
```
void registerDelayedCallback(java.time.Duration delay,
                             java.lang.Runnable r)
```
    Registers a callback to run after the specified delay according to the test Temporal service internal clock.
  - getWorkflowService
```
io.temporal.serviceclient.WorkflowServiceStubs getWorkflowService()
```
    Returns the in-memory test Temporal service that is owned by this.
  - getNamespace
```
java.lang.String getNamespace()
```
  - getDiagnostics
```
java.lang.String getDiagnostics()
```
    Returns the diagnostic data about the internal service state. Currently prints histories of all workflow instances stored in the service. This is useful information to print in the case of a unit test failure. A convenient way to achieve this is to add the following Rule to a unit test:
```
   @Rule
   public TestWatcher watchman =
       new TestWatcher() {
         @Override
         protected void failed(Throwable e, Description description) {
           System.err.println(testEnvironment.getDiagnostics());
           testEnvironment.close();
         }
       };
 
```
  - close
```
void close()
```
    Calls shutdownNow() and awaitTermination(long, TimeUnit).
  - getWorkerFactory
```
WorkerFactory getWorkerFactory()
```
  - start
```
void start()
```
    Start all workers created by this factory.
  - isStarted
```
boolean isStarted()
```
    Was start() called?
  - isShutdown
```
boolean isShutdown()
```
    Was shutdownNow() or shutdown() called?
  - isTerminated
```
boolean isTerminated()
```
    Are all tasks done after shutdownNow() or shutdown()?
  - shutdown
```
void shutdown()
```
    Initiates an orderly shutdown in which polls are stopped and already received workflow and activity tasks are executed. After the shutdown calls to ActivityExecutionContext.heartbeat(Object) start throwing ActivityWorkerShutdownException. Invocation has no additional effect if already shut down. This method does not wait for previously received tasks to complete execution. Use awaitTermination(long, TimeUnit) to do that.
  - shutdownNow
```
void shutdownNow()
```
    Initiates an orderly shutdown in which polls are stopped and already received workflow and activity tasks are attempted to be stopped. This implementation cancels tasks via Thread.interrupt(), so any task that fails to respond to interrupts may never terminate. Also after the shutdownNow calls to ActivityExecutionContext.heartbeat(Object) start throwing ActivityWorkerShutdownException. Invocation has no additional effect if already shut down. This method does not wait for previously received tasks to complete execution. Use awaitTermination(long, TimeUnit) to do that.
  - awaitTermination
```
void awaitTermination(long timeout,
                      java.util.concurrent.TimeUnit unit)
```
    Blocks until all tasks have completed execution after a shutdown request, or the timeout occurs, or the current thread is interrupted, whichever happens first.

Interface TestWorkflowEnvironment

Method Summary

Method Detail

newInstance

newInstance

newWorker

newWorker

getWorkflowClient

currentTimeMillis

sleep

registerDelayedCallback

getWorkflowService

getNamespace

getDiagnostics

close

getWorkerFactory

start

isStarted

isShutdown

isTerminated

shutdown

shutdownNow

awaitTermination