Package io.axoniq.framework.workflow.runtime.test.fixture

Interface WorkflowTestDriver

All Known Implementing Classes:
DefaultWorkflowTestDriver
public interface WorkflowTestDriver
Imperative test driver for workflow runtime tests.

This type exposes the low-level primitives that power WorkflowTestFixture. Use it directly when a test needs more control than the staged fixture API provides, for example when selecting a specific workflow execution, advancing time explicitly, or driving individual workflow steps in a precise order.

The term driver is used here in the modern testing sense: this class is a small facade that drives the system under test and keeps test code thin by wrapping workflow-specific interactions behind a focused API. It is not a classical integration-testing driver in the driver/stub sense where a temporary caller is built because the real upstream component does not exist yet.

Create an instance in one of two modes:

The driver is stateful. Selection methods such as executionExists(), executionMatches(Predicate), historyExists(), and historyMatches(Predicate) update the shared WorkflowEngineTestingState with the current execution and workflow history. Later operations that inspect the workflow state, especially step execution assertions, operate against that selected state.

Most observation methods are eventually consistent and use Awaitility under the hood. They wait until the expected execution or history entry appears and then surface the last assertion failure when the wait times out. This makes the driver suitable for workflows that advance asynchronously in response to published events or scheduled timeouts.

A typical stepping-mode test flow is:

  1. Create the driver with one of the stepper(...) factory methods
  2. Trigger the workflow with publishEvent(Object)
  3. Select the active execution with executionExists() or executionMatches(Predicate)
  4. Drive waiting steps with executeStep(String), executeStep(String, PayloadProcessor), or executeStepFailing(String, StepFailedException)
  5. Advance scheduled work with timePasses(Duration) when the workflow waits on time
  6. Assert the resulting execution or recorded history with executionSatisfies(Consumer), historySatisfies(Consumer), noExecution(), or noHistory()

Tests that create the driver directly should call shutdown() when finished so all workflow infrastructure is stopped cleanly.

Since:
5.4.0
Author:
Simon Zambrovski

  • Method Details

    • stepper

      static <C extends WorkflowContext> WorkflowTestDriver stepper(WorkflowModule<C> workflowModule, boolean throwFixtureException, UnaryOperator<WorkflowConfigurer> customize)
      Constructs a new test driver in stepping mode.
      Type Parameters:
      C - type of the workflow context
      Parameters:
      workflowModule - workflow module
      throwFixtureException - whether to fail assertions. If set to true, the failures are delivered as WorkflowTestFixtureExceptions, else as AssertionError
      customize - customizer of the workflow configuration
      Returns:
      workflow test driver

    • live

      static <C extends WorkflowContext> WorkflowTestDriver live(WorkflowModule<C> workflowModule, UnaryOperator<WorkflowConfigurer> customize)
      Creates a new test driver in live mode.
      Type Parameters:
      C - type of the workflow context
      Parameters:
      workflowModule - workflow module
      customize - customizer of the workflow configuration
      Returns:
      workflow test driver

    • live

      static <C extends WorkflowContext> WorkflowTestDriver live(WorkflowModule<C> workflowModule, boolean throwFixtureException, UnaryOperator<WorkflowConfigurer> customize)
      Creates a new test driver in live mode.
      Type Parameters:
      C - type of the workflow context
      Parameters:
      workflowModule - workflow module
      throwFixtureException - whether to fail assertions with WorkflowTestFixtureExceptions
      customize - customizer of the workflow configuration
      Returns:
      workflow test driver

    • stepNames

      static List<String> stepNames(String stepName, String... stepNames)
      Constructs a list of step names.
      Parameters:
      stepName - mandatory first step name
      stepNames - optional additional step names
      Returns:
      list of steps

    • workflowTestServices

      WorkflowTestServices workflowTestServices()
      Returns services for testing workflow runtime.
      Returns:
      services for testing workflow runtime

    • testingState

      WorkflowEngineTestingState testingState()
      Returns the shared testing state.
      Returns:
      shared testing state

    • assertionFailureHandler

      AssertionFailureHandler assertionFailureHandler()
      Returns the assertion failure handler.
      Returns:
      assertion failure handler

    • steppingMode

      boolean steppingMode()
      Indicates whether this driver runs in stepping mode.
      Returns:
      true if this driver runs in stepping mode, otherwise false

    • executionExists

      WorkflowExecution executionExists()
      Waits until an active workflow execution exists.
      Returns:
      the selected execution

    • executionMatches

      WorkflowExecution executionMatches(Predicate<WorkflowExecution> predicate)
      Waits until an active workflow execution matching the predicate exists.
      Parameters:
      predicate - predicate used to select matching executions
      Returns:
      the selected execution

    • executionSatisfies

      void executionSatisfies(Consumer<WorkflowExecution> executionConsumer)
      Waits until an active workflow execution exists and applies the given consumer.
      Parameters:
      executionConsumer - consumer applied to the selected execution

    • noExecution

      void noExecution()
      Waits until no active workflow executions exist.

    • historyMatches

      WorkflowHistory historyMatches(Predicate<WorkflowHistory> predicate)
      Waits until a workflow history matching the predicate exists.
      Parameters:
      predicate - predicate used to select matching histories
      Returns:
      the selected history

    • historyExists

      WorkflowHistory historyExists()
      Waits until a workflow history exists.
      Returns:
      the selected history

    • historySatisfies

      void historySatisfies(Consumer<WorkflowHistory> historyConsumer)
      Waits until a workflow history exists and applies the given consumer.
      Parameters:
      historyConsumer - consumer applied to the selected history

    • noHistory

      void noHistory()
      Asserts that no workflow histories exist.

    • publishEvent

      void publishEvent(Object event)
      Publishes an event.
      Parameters:
      event - event message or event payload

    • timePasses

      void timePasses(Duration duration)
      Advances time by the given duration.
      Parameters:
      duration - duration to advance time by

    • executeStep

      void executeStep(String stepName)
      Waits until the given step is executed calling original action defined in the workflow definition.

      This works only in stepping mode.

      Parameters:
      stepName - step name

    • executeStep

      void executeStep(String stepName, PayloadProcessor payloadProcessor)
      Waits until the given step is executed calling the given payload processor.

      This works only in stepping mode.

      Parameters:
      stepName - step name
      payloadProcessor - payload processor to use instead of the workflow-defined action

    • executeStepFailing

      void executeStepFailing(String stepName, StepFailedException exception)
      Waits until the given step is executed throwing the given exception.

      This works only in stepping mode.

      Parameters:
      stepName - name of the step to execute
      exception - exception to throw

    • shutdown

      void shutdown()
      Shuts down the tester.

    • awaitEventually

      void awaitEventually(String description, org.awaitility.core.ThrowingRunnable assertion)
      Waits until the given condition is met, using the defined assertion failure handler.
      Parameters:
      description - description of the assertion
      assertion - assertion to execute