You are reading GraphMaquina 2.0.2. The latest version is 2.0.6.

Testing samples: graphs, outcomes, probes and async

Contents

The graph, its watch and its edges

Names are the runtime's public names — the name the DSL or the generated companion declared — not the name of the Java method that implements them. From TestingApiTest:

assertThat(orders.definition())
        .hasInitial(OrderStatus.NEW)
        .hasTerminalsExactly(OrderStatus.SHIPPED, OrderStatus.CANCELLED)
        .hasAsync()
        .hasTransitionsExactly(
            OrderStatus.NEW,
            OrderTransition.PAYMENT_DECLINED,
            OrderTransition.PAY,
            OrderTransition.CANCEL)
        .hasTransitionsExactly(
            OrderStatus.PAYMENT_DECLINED,
            OrderTransition.RETRY,
            OrderTransition.CANCEL)
        .watch(OrderStatus.PAID)
        .hasPeer(ItemsRuntime.KEY)
        .hasRulesExactly(List.of(new WatchRuleExpectation<>("allIn PACKED", OrderTransition.SHIP)));

One edge carries everything its declaration gave it, including the parts no diagram shows:

assertThat(orders.definition())
        .transition(OrderStatus.NEW, OrderTransition.PAY)
        .hasTarget(OrderStatus.PAID)
        .isAction()
        .hasActionNamed("pay")
        .hasAsyncAction()
        .hasGuardsExactly(new GuardExpectation("retryBudgetLeft", false))
        .hasTimeout(Duration.ofSeconds(5))
        .hasFailureTransition(OrderTransition.PAYMENT_DECLINED)
        .failsOnExactly(IOException.class)
        .hasNoHook();

An absent edge has no view of its own, because there is nothing to describe. What a test asserts instead is that nothing is keyed there, and what the node will say when it is asked:

assertThat(items.definition())
        .hasNoTransition(ItemStatus.PENDING, ItemTransition.PACK)
        .policy(ItemStatus.PENDING)
        .hasDefaultReason("an item is packed by going through PACKING");

One identifier can leave several states. Each (from, id) pair is its own edge, asserted on its own:

assertThat(items.definition())
        .transition(ItemStatus.PENDING, ItemTransition.CANCEL)
        .hasTarget(ItemStatus.CANCELLED)
        .isAction().hasActionNamed("restock").hasHookNamed("applyRestock");
assertThat(items.definition())
        .transition(ItemStatus.PACKING, ItemTransition.CANCEL)
        .hasTarget(ItemStatus.CANCELLED)
        .isAction().hasActionNamed("restock").hasHookNamed("applyRestock");

A terminal is asserted by the absence of everything, not by a kind:

assertThat(orders.definition())
        .hasTransitionsExactly(OrderStatus.SHIPPED)
        .hasNoTransition(OrderStatus.SHIPPED, OrderTransition.CANCEL)
        .policy(OrderStatus.SHIPPED)
        .hasDefaultReason("a shipment cannot be undone");

hasGuardsExactly keeps order and multiplicity, because the engine evaluates guards in declaration order and stops at the first rejection. failsOnExactly() with no argument asserts that the edge's own failsOn maps no exception to its fallback onFailure route; the exceptions a recovery rule maps are not part of it. recoversExactly(rules) compares every rule of the edge, its exception classes included, in declaration order.

Outcomes, reactions and observed state

movedTo reads the state the outcome recorded; hasEntityState reads the entity through a getter at the moment the expectation runs. A reaction is reached from the outcome that carries it, selected by machine and by entity identity. From OrderFlowTest:

assertThat(orders.pay(order)).isApplied().movedTo(OrderStatus.PAID)
        .hasEntityState(Order::status, OrderStatus.PAID);
assertThat(items.pack(i2)).isApplied().reactions()
        .forEntity(OrdersRuntime.KEY, order).single().isDone().outcome()
        .isApplied().movedTo(OrderStatus.SHIPPED)
        .hasEntityState(Order::status, OrderStatus.SHIPPED);

A guard rejection names the guard, and asserting the name also asserts RejectionKind.GUARD. The DSL refuses two guards of one name on an edge with SG105, and so does the annotation processor, so in a graph the DSL built the name identifies the guard that rejected. A definition assembled without the DSL is not checked for it. A domain failure keeps the very exception instance the action reported, and names the identifier that recovered:

assertThat(orders.retry(order)).isRejected().isRejectedByGuardNamed("retryBudgetLeft");
assertThat(orders.pay(order)).isFailed().hasCauseSameAs(down)
        .hasEntityState(Order::status, OrderStatus.PAYMENT_DECLINED);
assertThat(orders.pay(order)).isFailed().movedTo(OrderStatus.PAYMENT_DECLINED)
        .hasFailureTransition(OrderTransition.PAYMENT_DECLINED)
        .hasEntityState(Order::status, OrderStatus.PAYMENT_DECLINED);

movedTo is where the recovering edge landed and hasFailureTransition is which edge that was. They are not the same question: a route may legitimately reach the state another edge also reaches.

Failures and the journal

An aborted transition throws rather than returning an outcome, so the subject is the throwable. captureFailure runs the operation and hands back what it threw; it catches no Error, so an AssertionError raised inside the body still fails the test the way it should. The order below has a PACKED item, which has no CANCEL edge, and a PENDING one. From OrderFlowTest:

Throwable failure = captureFailure(() -> orders.cancel(order, "B-7"));

assertThat(failure).isCascadeAbort()
        .hasErrorCount(1).hasPhase(CallPhase.ACTION).hasStatesWritten(StatesWritten.NONE)
        .journal().hasActionsExactly("cancel", "restock")
        .hasStatusesExactly(ActionStatus.THREW, ActionStatus.OK);
assertThat(failure).isCascadeAbort().flow()
        .hasValue(ShopFlow.CANCELLATION, "B-7")
        .hasNoValue(ShopFlow.restockOf(packed))
        .hasValue(ShopFlow.restockOf(pending), new Restock("B-7", order))
        .trail()
        .hasEntryTypesExactly(FlowEntry.Hop.class, FlowEntry.Hop.class, FlowEntry.Failed.class)
        .hasHopsExactly(OrderTransition.CANCEL, ItemTransition.CANCEL)
        .endsWithFailure(CallPhase.ACTION)
        .hops().forEntity(ItemsRuntime.KEY, pending).single()
        .from(ItemStatus.PENDING).hasTransition(ItemTransition.CANCEL).to(ItemStatus.CANCELLED);
assertThat(order, Order::status).isIn(OrderStatus.NEW);
assertThat(packed, Item::status).isIn(ItemStatus.PACKED);
assertThat(pending, Item::status).isIn(ItemStatus.PENDING);
assertEquals(Optional.empty(), packed.restockedIn());
assertEquals(Optional.empty(), pending.restockedIn());
assertEquals(List.of(), order.restocked());

The journal lists the actions that ran: cancel, which threw the aggregate of its COLLECT cascade, and the restock of the pending item, which completed. The flow keeps what the steps wrote, the batch and the pending item's restock, while its trail holds the order's hop and that item's, then the failure. No hook ran, so no entity holds the restock: the shop applies it in a hook, as set a field only when the call commits explains.

isCallFailure() reads any failure of a call through what every kind shares, and the four call-failure views offer the same expectations: hasPhase(...), hasStatesWritten(...), hasCallSameAs(...), which compares by reference with the MachineCall an observer received, journal(), and flow(), which the call's flow and its trail describes.

The call recorder

The recorder keeps the outcome of every call that completed, in the order the calls completed, and nothing else. It never walks reactions(), so a reaction is counted once — as its own call — even though the root outcome carries it too. From OrderFlowTest:

recorder.assertRecorded()
        .hasSize(9)
        .hasKeysExactly(
            OrdersRuntime.KEY,
            OrdersRuntime.KEY,
            ItemsRuntime.KEY,
            OrdersRuntime.KEY,
            ItemsRuntime.KEY,
            OrdersRuntime.KEY,
            ItemsRuntime.KEY,
            OrdersRuntime.KEY,
            ItemsRuntime.KEY)
        .hasStatusesExactly(
            APPLIED,
            IGNORED,
            APPLIED,
            IGNORED,
            APPLIED,
            IGNORED,
            APPLIED,
            APPLIED,
            APPLIED);

A registry accepts any number of observers, so a test adds its own beside the recorder. An entity keeps moving after its call completes, so if the assertion must see the entity as it was, build the recorder with TransitionRecorder.projecting((key, outcome) -> ...) and read what it projected when each call completed: recorder.snapshot() lists the RecordedTransitions so far, each with its sequence, key, outcome and projection. The projection runs on the thread of the call that completed; one that returns null makes the recorder throw, which the registry logs as it logs any observer that throws, and that call is not recorded.

Each outcome carries the call's flow, outcome.flow(), so the recorder also retains every flow it records: the root entity and the values the call's steps and hooks left there, and, for a call whose root machine records its trail, the entries of the trail, which hold the call's entities and the throwable a failure route took, all by reference, for as long as the recorder is kept. It stores the outcome beside a projection too, so projecting releases neither.

Tracked entity state

A StateSnapshot reports only the entities it was given, so an entity the test does not name may move without ever failing assertUnchanged(). From TestingApiTest:

private StateSnapshot track(Order order, Item first, Item second) {
    return StateSnapshot.builder()
            .track(OrdersRuntime.KEY, order, Order::status)
            .track(ItemsRuntime.KEY, first, Item::status)
            .track(ItemsRuntime.KEY, second, Item::status)
            .capture();
}
StateSnapshot before = track(order, packed, pending);

assertThat(captureFailure(() -> orders.cancel(order, "B-7"))).isCascadeAbort().hasErrorCount(1);

before.assertUnchanged();

assertUnchanged() fails with every entity that moved, not only the first, so one run names the whole difference. changes() reads every tracked getter again on each call and answers about the entities as they are now. Each StateChange holds the key, the entity and its states before() and after(), both Optional: a getter that answers null observes no state, which is empty, so a state that appears or disappears is a change like any other.

Probes

A probe stands where a guard, an action or a hook stands and answers from an explicit script. A shared CallTrace records the order the callbacks were entered in, and events() lists them as TraceEvents, each with its sequence, the probe's name and the call it recorded, which is how the engine's short-circuit becomes observable. From ProbeTest:

CallTrace trace = CallTrace.create();
GuardProbe<Entity, State, Id> first = GuardProbe.<Entity, State, Id>create("first", trace)
        .thenReturn(GuardResult.reject("no title"));
GuardProbe<Entity, State, Id> second = GuardProbe.<Entity, State, Id>create("second", trace)
        .otherwiseReturn(GuardResult.pass());
ActionProbe<Entity, State, Id> action = ActionProbe.<Entity, State, Id>create("prepare", trace)
        .otherwiseReturn(ActionOutcome.ok());
trace.assertNamesExactly("first");
second.calls().assertCount(0);
action.calls().assertCount(0);

Guard and action probes queue one answer per call, in order, with thenReturn and thenThrow, and set the standing answer used once the queue is empty with otherwiseReturn; a hook probe queues with thenSucceed and thenThrow and sets it with otherwiseSucceed. Every probe's onCall(consumer) sets the side effect run on each scripted call, with the live context, or the entity for a hook; a later onCall replaces it. A probe that runs out of answers says which probe and which call ran out, rather than letting the machine misbehave.

StateWriteProbe wraps the machine's state setter, which is how a test watches phase 2 and makes one write fail. Calls are numbered from 1, and an armed call throws before the wrapped setter is reached. From StateWriteProbeTest:

Entity entity = new Entity("e", State.NEW);
IllegalStateException boom = new IllegalStateException("setter down");
StateWriteProbe<Entity, State> writes =
        StateWriteProbe.<Entity, State>wrapping(Entity::setState).failOnCall(2, boom);
writes.accept(entity, State.READY);
assertSame(
    boom,
    assertThrows(IllegalStateException.class, () -> writes.accept(entity, State.DONE)));
assertEquals(State.READY, entity.state());
assertEquals(
    List.of(WriteStatus.RETURNED, WriteStatus.THREW),
    writes.writes().stream().map(StateWrite::status).toList());

Finish configuring a probe before a machine uses it; after that, it is safe to call from several threads, each served a different queued answer, and its name is never checked against the graph. A StateWriteProbe lists a write as RUNNING while the setter runs, then as RETURNED or THREW in the same place. One probe given to several machines numbers every write of the commit, failOnCall below 1 throws IllegalArgumentException, and arming the same call twice throws IllegalStateException.

Operation input in recorded calls

GuardCall and ActionCall capture Optional<?> input when the callback is entered. This works with GuardProbe, ActionProbe, ControlledAsyncGuard and ControlledAsyncAction, including calls in a CallTrace or a PendingInvocation. It stores the argument reference without retaining the live context; reading the history after the transaction ends is safe. The payload is not copied: later mutations of a mutable argument remain visible, so use an immutable value when the test needs a stable value snapshot.

The published consumer test invokes an operation with a string argument named input, then checks both recorded calls:

assertThat(guard.calls().single()).hasInput("approved").hasInputSameAs(input);
assertThat(action.calls().single()).inputSatisfies(CharSequence.class, value -> {
    if (value != input) { throw new AssertionError("input identity was lost"); }
});

hasInput compares by equality, hasInputSameAs checks identity, and hasNoInput requires absence. inputSatisfies checks presence and assignability before invoking the typed assertion; an absent or wrong input produces an inspectable GraphAssertionError. Null expected values are programming errors; use hasNoInput() to check a call that carried no operation argument, since the engine refuses a null one before the call starts. CallInputAssert.assertThat(call) is also available without the GraphAssertions facade.

The recorded input(Class) follows the context contract: empty remains empty, supertypes are supported, and incompatible present values throw ClassCastException. A null type token throws NullPointerException; primitive tokens (including void.class) throw IllegalArgumentException, even for an empty input. Use wrapper classes for primitive operation arguments.

Root guards, actions and failure actions record the root input, and the recovering action records the input of the invocation that failed. Cascades, the exits of sub-machines, watch reactions and reevaluation have their own calls with empty input; a later invocation never reuses a previous input. For a controlled async callback, inspect assertThat(pending.call()).hasInputSameAs(verdict) before answering it or after completion. The same reference remains in fixture.invocations() after close.

Both records carry the identifier that selected the edge: GuardCall<E, S, T>(entity, from, transition, to, input) and ActionCall<E, S, T>(entity, from, transition, to, depth, input). The shorter constructors — four arguments for a guard call, five for an action call — remain available and create calls with empty input. Record patterns must list every component, and generated equality, hash codes and string representations include them all.

Executable examples: ProbeInputTest and CallInputAssertionsTest. The published-artifact consumer also compiles and runs these input assertions directly from the staged JARs.

Controlled asynchronous invocations

A ControlledAsyncAction or ControlledAsyncGuard is declared on the edge in place of the real async callback. The test resumes when the engine has entered it, and the engine resumes when the test answers that very invocation, so an asynchronous transition is asserted without a single sleep. awaitInvocation and AsyncAssertions.await each take a budget that belongs to the test. The fixture is AutoCloseable; closing is idempotent, cancels the stages it created itself and rejects any invocation that arrives afterwards: the action with a GraphAssertionError, an Error that neither a recovery rule nor a failsOn route can take for a failure of the action, and the guard with an IllegalStateException, which aborts the transition. awaitInvocation on a closed fixture fails at once, and a wait already blocked when the fixture closes is woken and fails the same way. Concurrent invocations are independent: each arrives with its own handle and is answered on its own. From ControlledAsyncTest, where GENEROUS is that test's own two-second budget:

ControlledAsyncAction<Entity, State, Id> action = ControlledAsyncAction.create();
MachineRegistry registry = TestDomain.registry(TestDomain.graph(Duration.ofSeconds(5), action));
try (registry; action) {
    Entity first = new Entity("first", State.NEW);
    Entity second = new Entity("second", State.NEW);
    CompletableFuture<Outcome<Entity, State, Id>> firstResult =
            registry.of(KEY).async().execute(first, Id.PREPARE);
    CompletableFuture<Outcome<Entity, State, Id>> secondResult =
            registry.of(KEY).async().execute(second, Id.PREPARE);
    PendingInvocation<ActionCall<Entity, State, Id>, ActionOutcome> one =
            action.awaitInvocation(GENEROUS);
    PendingInvocation<ActionCall<Entity, State, Id>, ActionOutcome> other =
            action.awaitInvocation(GENEROUS);
    assertNotSame(one, other);
    assertNotSame(one.call().entity(), other.call().entity());
    assertEquals(2, action.invocations().size());

    PendingInvocation<ActionCall<Entity, State, Id>, ActionOutcome> firstCall =
            one.call().entity() == first ? one : other;
    PendingInvocation<ActionCall<Entity, State, Id>, ActionOutcome> secondCall =
            firstCall == one ? other : one;
    assertTrue(firstCall.complete(ActionOutcome.ok()));
    AsyncAssertions.await(firstResult, GENEROUS).isApplied().hasEntitySameAs(first);
    assertFalse(secondCall.isDone());
    assertFalse(secondResult.isDone());
    assertEquals(State.NEW, second.state());

    assertTrue(secondCall.complete(ActionOutcome.ok()));
    AsyncAssertions.await(secondResult, GENEROUS).isApplied().hasEntitySameAs(second);
}

List the registry first and the fixture second inside the try-with-resources header, as that sample does. The fixture is still constructed first — the graph is built from it, so it exists before the registry does — and only the order inside the header decides how the two are closed. Try-with-resources closes in reverse order, so the fixture is closed first, which is what ControlledAsyncAction asks for: closing cancels the invocations it is still holding, and a worker parked inside the action is released before the registry waits for it. Listed the other way round, a test that fails before answering an invocation makes the registry wait until each unanswered call gives up at its own deadline, the edge's timeout or the call's asyncTimeout, whichever ends first, before the fixture ever gets to cancel it. Calls that run side by side wait out their deadlines side by side, so two unanswered invocations started together cost about one such wait, not two. Only the default executors of the machines are awaited: closing the registry does not wait for an executor the application supplied.

awaitInvocation hands out handles in the order they were published, which can differ from the order of invocations(). complete, fail and cancelStage on a PendingInvocation return true only to the call that settled the stage, and are safe to call from any thread. awaitInvocation fails with GraphAssertionError when its budget expires or when the waiting thread is interrupted, which leaves the interrupt flag set.

The machine that holds an async edge must declare asyncTimeout(...), as any async machine does. When a call on a sub-machine can run that edge implicitly, as the exit of its binding or an edge that exit leads to, the sub-machine's machine must declare one too: the call runs the edge under its own deadline. The same applies to a caller whose own edge starts a binding with a terminal initial descendant that selects an async exit. That deadline is the engine's; the budgets above are the test's, and the two are unrelated — see what a check does not prove.


Next: Testing samples: recovery, sub-machines and the call's flow. Back to the documentation index.