Testing samples: recovery, sub-machines, automatic transitions and the call's flow
Contents
Failure kinds and recovery rules
An edge can declare recovery rules besides its onFailure fallback: a rule pairs a failure kind with the
identifier of its recovery edge, and may list the throwable types that select it. The
guide describes how the engine chooses. A test asserts the
route a call took on the call's outcome, and the rules an edge declares on the definition.
These samples use the publication machine of that guide section. graph(action) declares it with action on
PUBLISH, asyncGraph(action) declares it with an asynchronous one, and machine(graph) builds a standalone
machine with a five-second asyncTimeout.
TestingGuideFragmentsTest writes out
those helpers and the publication types, cuts the samples out of this page, compiles them against the published
jars and runs them.
A probe answers three calls in turn: a returned failure with a kind, a declared exception, and a returned failure without a kind, which the fallback takes:
ServiceUnavailableException down = new ServiceUnavailableException("provider down");
ActionProbe<Publication, PublicationState, PublicationChange> publish = ActionProbe
.<Publication, PublicationState, PublicationChange>create("publish", CallTrace.create())
.thenReturn(ActionOutcome.failed(PublicationFailures.Rejected.class, "content rejected"))
.thenThrow(down)
.thenReturn(ActionOutcome.failed("invalid response"));
StateMachine<Publication, PublicationState, PublicationChange> machine = machine(graph(publish));
assertThat(machine.execute(new Publication("p1"), PublicationChange.PUBLISH)).isFailed()
.hasFailureKind(PublicationFailures.Rejected.class)
.hasFailureTransition(PublicationChange.RECORD_REJECTION)
.movedTo(PublicationState.REJECTED_BY_PROVIDER)
.hasNoCause();
assertThat(machine.execute(new Publication("p2"), PublicationChange.PUBLISH)).isFailed()
.hasFailureKind(PublicationFailures.Unavailable.class)
.hasFailureTransition(PublicationChange.SCHEDULE_RETRY)
.movedTo(PublicationState.RETRY_PENDING)
.hasCauseSameAs(down);
assertThat(machine.execute(new Publication("p3"), PublicationChange.PUBLISH)).isFailed()
.hasNoFailureKind()
.hasFailureTransition(PublicationChange.MARK_INTEGRATION_FAILED)
.movedTo(PublicationState.INTEGRATION_FAILED)
.hasReason("invalid response");
hasFailureKind asserts the kind the failure carried, not the route that took it: a kind that no rule declares
reaches the fallback and keeps its kind. Assert hasFailureTransition beside it to pin the route.
The rules belong to the edge's declaration. recoversExactly compares them in declaration order, as
failsOnExactly compares the edge's own types; the order selects nothing, but the declaration keeps it.
failsOnExactly reads only the edge's own failsOn, never the types of its rules:
assertThat(machine.definition())
.transition(PublicationState.READY, PublicationChange.PUBLISH)
.recoversExactly(List.of(
new RecoveryRule<>(
PublicationFailures.Unavailable.class,
PublicationChange.SCHEDULE_RETRY,
List.of(ServiceUnavailableException.class),
false),
new RecoveryRule<>(
PublicationFailures.Rejected.class,
PublicationChange.RECORD_REJECTION,
List.of(ProviderRejectedException.class),
false)))
.failsOnExactly(InvalidResponseException.class)
.hasFailureTransition(PublicationChange.MARK_INTEGRATION_FAILED);
An action's result can be asserted on its own, before any machine runs it. On an action result both expectations
require the Failed variant, so ActionOutcome.ok() fails them:
assertThat(ActionOutcome.failed(PublicationFailures.Unavailable.class, "provider down"))
.isFailed()
.hasFailureKind(PublicationFailures.Unavailable.class)
.hasReason("provider down");
assertThat(ActionOutcome.failed("invalid response")).isFailed().hasNoFailureKind();
The same rules route an asynchronous action. A ControlledAsyncAction lets the test answer the stage with a
failure or complete it with an exception, and AsyncAssertions reads the outcome:
Duration testBudget = Duration.ofSeconds(10);
ControlledAsyncAction<Publication, PublicationState, PublicationChange> publish =
ControlledAsyncAction.create();
try (publish) {
StateMachine<Publication, PublicationState, PublicationChange> machine =
machine(asyncGraph(publish));
CompletableFuture<Outcome<Publication, PublicationState, PublicationChange>> rejected =
machine.async().execute(new Publication("p4"), PublicationChange.PUBLISH);
publish.awaitInvocation(testBudget)
.complete(ActionOutcome.failed(PublicationFailures.Rejected.class, "content rejected"));
AsyncAssertions.await(rejected, testBudget).isFailed()
.hasFailureKind(PublicationFailures.Rejected.class)
.hasFailureTransition(PublicationChange.RECORD_REJECTION)
.movedTo(PublicationState.REJECTED_BY_PROVIDER);
ProviderRejectedException refused = new ProviderRejectedException("content refused");
CompletableFuture<Outcome<Publication, PublicationState, PublicationChange>> thrown =
machine.async().execute(new Publication("p5"), PublicationChange.PUBLISH);
// this time the stage completes with an exception, not a returned failure
publish.awaitInvocation(testBudget).fail(refused);
AsyncAssertions.await(thrown, testBudget).isFailed()
.hasFailureKind(PublicationFailures.Rejected.class)
.hasFailureTransition(PublicationChange.RECORD_REJECTION)
.hasCauseSameAs(refused);
}
testBudget is how long the test waits, not the engine's deadline. The fixture is the only resource of the
try-with-resources header because a standalone machine has no registry to close.
Sub-machines
A state can hold a sub-machine, which the programmatic DSL declares with
submachine(...). These samples use an order whose PAYING state holds its payment. orders() declares the order
graph: its binding reaches the payment of an order and the order of a payment, and the payment's terminal states
CAPTURED and DECLINED exit through PAY and REFUSE. ORDERS and PAYMENTS are the keys of the two machines.
TestingGuideFragmentsTest writes out
those helpers and types, and the ones named below, cuts the samples out of this page, compiles them against the
published jars and runs them.
The binding of a state
submachine(state, childKey) narrows to the binding of one state. The view is typed by the child's key, so the
compiler accepts only a state of the child as a terminal state and only an identifier of the parent as its exit:
assertThat(orders())
.hasNoSubmachine(OrderState.CART)
.submachine(OrderState.PAYING, PAYMENTS)
.hasExitsExactly(
exit(PaymentState.CAPTURED, OrderChange.PAY),
exit(PaymentState.DECLINED, OrderChange.REFUSE))
.hasExit(PaymentState.DECLINED, OrderChange.REFUSE);
exit is the static factory of ExitExpectation. hasExitsExactly compares the exits in declaration order. Each
expectation of the view first checks that the state holds the child of that key, so a binding of another child fails
on the property child, and a state that holds no sub-machine fails as a view without a subject. None of them runs
the binding's lookups.
Starts and exits
registry(orders) registers the order machine built from orders and the payment machine, each with a five-second
asyncTimeout. An outcome's starts() holds the sub-machines its call started. forChild selects them by the child's
key and identity, as records().forEntity does, and a child can start more than once in one call, so the selection
is read with single() or atIndex(i). A start is no hop: when a later call ends the child, the exit is one more
record of that call:
Payment payment = new Payment("p1");
Order order = new Order("o1", payment);
try (MachineRegistry registry = registry(orders())) {
assertThat(registry.of(ORDERS).execute(order, OrderChange.CHECKOUT)).isApplied()
.movedTo(OrderState.PAYING)
.starts().forChild(PAYMENTS, payment).single()
.startedAt(PaymentState.AUTHORIZING)
.hadPrevious(PaymentState.AUTHORIZING)
.byParent(ORDERS, order, OrderState.PAYING)
.atDepth(0);
assertThat(registry.of(PAYMENTS).execute(payment, PaymentChange.CAPTURE)).isApplied()
.records().forEntity(ORDERS, order).single()
.hasTransition(OrderChange.PAY).to(OrderState.PAID).hasDepth(1);
}
hadPrevious is the child's state before the start, here the payment's own initial state. A call whose hook threw
after its states were written keeps its starts too: isAfterCommit().starts() reads them.
Refused requests and an ambiguous parent
A sub-machine refuses two kinds of request, and the rejected view names each kind. A child whose parent is no longer in the bound state is detached, and an exit requested on the parent is reserved, since only the end of the child runs it:
Payment payment = new Payment("p2");
Order order = new Order("o2", payment);
try (MachineRegistry registry = registry(orders())) {
registry.of(ORDERS).execute(order, OrderChange.CHECKOUT);
assertThat(registry.of(ORDERS).execute(order, OrderChange.PAY)).isRejected()
.isReservedExit()
.hasReason("PAY leaves PAYING only when its sub-machine ends");
registry.of(ORDERS).execute(order, OrderChange.ABANDON);
assertThat(registry.of(PAYMENTS).execute(payment, PaymentChange.CAPTURE)).isRejected()
.isDetached()
.hasReason("no parent holds it in PAYING");
}
A payment has one active parent at a time. invoices() declares an invoice whose SETTLING state holds its payment
too, and registryWithInvoices(orders) registers the invoice machine beside the other two. Once an order and an
invoice both hold the same payment in their bound states, a call to the payment cannot tell whose exit to run: it
throws before any edge is looked up, and captureFailure hands back what it threw:
Payment payment = new Payment("p4");
Order order = new Order("o4", payment);
Invoice invoice = new Invoice("i4", payment);
try (MachineRegistry registry = registryWithInvoices(orders())) {
registry.of(ORDERS).execute(order, OrderChange.CHECKOUT);
registry.of(INVOICES).execute(invoice, InvoiceChange.SETTLE);
assertThat(captureFailure(() -> registry.of(PAYMENTS).execute(payment, PaymentChange.CAPTURE)))
.isAbort()
.hasPhase(CallPhase.RESOLVE)
.hasStatesWritten(StatesWritten.NONE)
.hasCause(AmbiguousParentException.class);
}
assertThat(payment, (Payment value) -> value.state).isIn(PaymentState.AUTHORIZING);
The abort's phase is RESOLVE because the payment's call is the root; inside a cascade or an exit it would be
ACTION.
Probes on an exit
An exit is an edge of the parent, so the probes stand on it as on any edge. orders(pay) declares the order graph with
pay applied to the declaration of the exit PAY, and registry(orders, observer) adds an observer to the registry.
The exit's guard, action and hook run in the payment's call, the action one level deeper and without input. A
TransitionRecorder counts that call once, so the checkout and the capture are its two calls, and the exit is a record
of the second:
CallTrace trace = CallTrace.create();
GuardProbe<Order, OrderState, OrderChange> inStock = GuardProbe
.<Order, OrderState, OrderChange>create("inStock", trace)
.otherwiseReturn(GuardResult.pass());
ActionProbe<Order, OrderState, OrderChange> confirm = ActionProbe
.<Order, OrderState, OrderChange>create("confirm", trace)
.otherwiseReturn(ActionOutcome.ok());
HookProbe<Order> receipt = HookProbe.<Order>create("receipt", trace).otherwiseSucceed();
TransitionRecorder recorder = TransitionRecorder.create();
Payment payment = new Payment("p5");
Order order = new Order("o5", payment);
try (MachineRegistry registry = registry(
orders((TransitionBuilder<Order, OrderState, OrderChange> pay) -> pay
.guard("inStock", inStock)
.action("confirm", confirm)
.afterCommit("receipt", receipt)),
recorder)) {
registry.of(ORDERS).execute(order, OrderChange.CHECKOUT);
registry.of(PAYMENTS).execute(payment, PaymentChange.CAPTURE);
}
trace.assertNamesExactly("inStock", "confirm", "receipt");
assertThat(confirm.calls().single()).hasNoInput();
recorder.assertRecorded()
.hasSize(2)
.hasKeysExactly(ORDERS, PAYMENTS)
.forEntity(PAYMENTS, payment).single()
.isApplied().records().forEntity(ORDERS, order).single()
.hasTransition(OrderChange.PAY).hasActionNamed("confirm").hasDepth(1);
An asynchronous exit
An exit can run an asynchronous action. asyncOrders(pay) declares the same order graph with pay as the
asynchronous action of PAY, so a capture waits for that action before it writes anything. A ControlledAsyncAction
holds the wait open without a sleep: while the exit is pending neither entity has moved, and once the test answers,
the call commits the payment and the order together:
Duration testBudget = Duration.ofSeconds(10);
ControlledAsyncAction<Order, OrderState, OrderChange> pay = ControlledAsyncAction.create();
Payment payment = new Payment("p3");
Order order = new Order("o3", payment);
try (MachineRegistry registry = registry(asyncOrders(pay)); pay) {
registry.of(ORDERS).execute(order, OrderChange.CHECKOUT);
StateSnapshot before = StateSnapshot.builder()
.track(ORDERS, order, (Order value) -> value.state)
.track(PAYMENTS, payment, (Payment value) -> value.state)
.capture();
CompletableFuture<Outcome<Payment, PaymentState, PaymentChange>> captured =
registry.of(PAYMENTS).async().execute(payment, PaymentChange.CAPTURE);
PendingInvocation<ActionCall<Order, OrderState, OrderChange>, ActionOutcome> pending =
pay.awaitInvocation(testBudget);
before.assertUnchanged();
pending.complete(ActionOutcome.ok());
AsyncAssertions.await(captured, testBudget).isApplied().movedTo(PaymentState.CAPTURED)
.records().forEntity(ORDERS, order).single().hasTransition(OrderChange.PAY);
assertThat(order, (Order value) -> value.state).isIn(OrderState.PAID);
}
The payment's machine declares an asyncTimeout, as
controlled asynchronous invocations explains, because its call runs the
order's asynchronous exit. That deadline is the engine's; testBudget is how long the test waits.
A child over its parent's own entity
A sub-machine can also govern a second state of its parent's own entity, as the
guide explains. Here the order charges itself: charge is a second
state of Order, which the payment graph governs under the key CHARGES. chargedOrders() declares the order graph
with PAYING bound to that graph through submachine(state, child), and chargeRegistry() registers both machines,
each with the accessors of its own field. A StateSnapshot tracks the one order under both keys, so a refused request
leaves both of its states unchanged:
Order order = new Order("o7", new Payment("p7"));
try (MachineRegistry registry = chargeRegistry()) {
registry.of(ORDERS).execute(order, OrderChange.CHECKOUT);
StateSnapshot before = StateSnapshot.builder()
.track(ORDERS, order, (Order value) -> value.state)
.track(CHARGES, order, (Order value) -> value.charge)
.capture();
assertThat(registry.of(ORDERS).execute(order, OrderChange.PAY)).isRejected().isReservedExit();
before.assertUnchanged();
assertThat(registry.of(CHARGES).execute(order, PaymentChange.CAPTURE)).isApplied()
.records().forEntity(ORDERS, order).single().hasTransition(OrderChange.PAY).hasDepth(1);
}
assertThat(order, (Order value) -> value.state).isIn(OrderState.PAID);
assertThat(order, (Order value) -> value.charge).isIn(PaymentState.CAPTURED);
Each key reads its own field, so changes() reports a moved state under its own key, even for one entity.
Automatic transitions
The graph declares an edge automatic, and an advance, or the chain that a commit triggers, takes it without a
request for its identifier, as automatic transitions explains. These are the views that
assert on that, none of which runs an action, a guard or a hook.
On the graph, assertThat(definition).automaticFrom(state).containsExactly(...) compares the identifiers of the
automatic edges that leave a state, in the order an advance tries them, which a state with two or more automatic edges
declares; with no argument it says the state has none. On an edge, isAutomatic() and isManual() read the mark,
onFailureContinues() says that its onFailure route continues the chain, and recoveryContinues(kind) that the
recovery rule it declares for that failure kind does.
On an outcome, automaticSteps() has the shape of reactions(): hasSize, isEmpty, hasNoAborted() for the list
alone, hasNoAbortedRecursively() for the steps of the attempts as well, though only through their
automaticSteps(), never through the reactions() of an attempt, which hasNoAutomaticAbort() also searches, and
forEntity(key, entity), which selects by key and by entity identity, then single() or atIndex(i) and isDone().outcome() or isAborted().hasCause(...).
The searches follow Outcome.automaticFailure(), automaticAbort() and automaticBlock() through the attempts of
the call, the nested ones included, and fail when they find nothing:
| Expectation | Returns |
|---|---|
automaticFailure() |
The view of a failed outcome: hasFailureTransition, movedTo, hasFailureKind and the rest |
automaticAbort() |
The view of an aborted step: hasCause and hasCauseSameAs |
automaticBlock() |
The view of an ignored outcome, whose rejections() has hasSize, single() and atIndex(i), each an eligibility view of the edge that was refused |
hasNoAutomaticFailure(), hasNoAutomaticAbort(), hasNoAutomaticBlock() |
The outcome view; they fail with what the search found |
The searches take the first attempt of any machine, and a watch reaction can run the chain of a peer machine before
the outcome's own. The three forms above without an argument take the attempt to belong to the machine of the outcome
and check its entity and its enums, so an attempt of another machine raises IllegalArgumentException, whose message
names that machine. automaticFailure(key), automaticBlock(key) and automaticAbort(key) search in the same order
but only among the steps of the machine that key names, and return views typed by that key; they fail, naming the
key, when that machine has no such step.
The call's flow and its trail
flow() opens the call's flow on every outcome view and on the view of the failure a call
throws; a failure of the call nested in it, such as error(i) of a cascade abort, holds the empty flow.
hasEntitySameAs compares the entity of the root call by reference, hasValue compares the value of a key with
equals, hasNoValue expects no value under a key, and hasKeysExactly compares the keys that hold a value, in the
order of the writes that set them. A key that holds no value fails hasValue with Optional.empty as its actual
value, and a key that holds another value with Optional[...] of that value.
trail() opens the trail, which a call records when its root machine was built with
recordTrail. hasEntryTypesExactly compares the class of every entry, in order.
hasHopsExactly compares the identifier of every hop, in order, and skips the sub-machine starts and the final
rejection or failure, so with no argument it expects a trail without a hop. hops() opens the records of those hops,
in the view that records() opens on an outcome: forEntity(key, entity) and containsExactly(records) read which
machine and entity took each hop and from which state to which, on the trail of a call that failed before its hooks
too, whose exception lists no records().
isInTimeOrder checks that no entry's at() is earlier than
the one of the entry before it, so equal instants pass. endsWithRejection(kind) and endsWithFailure(phase) read
the final entry. Build the machine on a clock the test controls.
These samples use the graph(action) helper, the publication types and their machine key KEY of
failure kinds and recovery rules, and build their machine here.
TestingGuideFragmentsTest writes out
that helper and those types, cuts the samples out of this page, compiles them against the published jars and runs
them, the four in one method.
The action of PUBLISH puts a receipt into the call's flow, and throws for a publication whose id starts with x.
Each call has a flow of its own: the second call, rejected because the article is already published, finds no
receipt, and its trail holds the rejection alone:
FlowKey<String> receipt = FlowKey.of("receipt", String.class);
StateMachine<Publication, PublicationState, PublicationChange> traced = StateMachines.from(graph(
(TransitionContext<Publication, PublicationState, PublicationChange> ctx) -> {
ctx.flow().put(receipt, "receipt of " + ctx.entity().id);
if (ctx.entity().id.startsWith("x")) {
throw new IllegalStateException("the outbox is closed");
}
return ActionOutcome.ok();
}))
.state(
(Publication publication) -> publication.state,
(Publication publication, PublicationState state) -> publication.state = state)
.recordTrail(InstantSource.fixed(Instant.parse("2026-10-10T09:00:00Z")))
.build();
Publication article = new Publication("p6");
assertThat(traced.execute(article, PublicationChange.PUBLISH)).isApplied().flow()
.hasEntitySameAs(article)
.hasValue(receipt, "receipt of p6")
.hasKeysExactly(receipt)
.trail()
.hasEntryTypesExactly(FlowEntry.Hop.class)
.hasHopsExactly(PublicationChange.PUBLISH)
.isInTimeOrder();
assertThat(traced.execute(article, PublicationChange.PUBLISH)).isRejected().flow()
.hasNoValue(receipt)
.trail()
.hasHopsExactly()
.endsWithRejection(RejectionKind.NO_TRANSITION);
A call that throws hands its flow out on its failure. The action throws a type its edge does not declare, so its
step aborts and nothing rolls it back: the flow keeps the receipt the action put before it threw, and the trail ends
with the failure. Its hop, read through hops(), says where the
aborted step was going:
Publication refused = new Publication("x1");
assertThat(captureFailure(() -> traced.execute(refused, PublicationChange.PUBLISH))).isAbort()
.hasPhase(CallPhase.ACTION)
.flow()
.hasEntitySameAs(refused)
.hasValue(receipt, "receipt of x1")
.trail()
.hasEntryTypesExactly(FlowEntry.Hop.class, FlowEntry.Failed.class)
.hasHopsExactly(PublicationChange.PUBLISH)
.endsWithFailure(CallPhase.ACTION)
.hops().forEntity(KEY, refused).single()
.from(PublicationState.READY)
.hasTransition(PublicationChange.PUBLISH)
.to(PublicationState.PUBLISHED);
assertThat also takes a flow on its own, such as the flow of a CommitContext built with its five-argument
constructor to call a hook by hand. That flow belongs to no call: it holds what the hook wrote, no entity and no
trail:
HookRef<Publication, PublicationState, PublicationChange> announce = new HookRef<>(
"announce",
(Publication publication, CommitContext<PublicationState, PublicationChange> commit) ->
commit.flow().put(receipt, "announced " + publication.id));
CommitContext<PublicationState, PublicationChange> commit = new CommitContext<>(
PublicationState.READY,
PublicationChange.PUBLISH,
PublicationState.PUBLISHED,
TransitionKind.ACTION,
true);
announce.run(new Publication("p7"), commit);
assertThat(commit.flow())
.hasValue(receipt, "announced p7")
.hasKeysExactly(receipt)
.trail()
.isEmpty();
A watch reaction is a call of its own: isDone().outcome().flow() reads the reaction's flow. A reaction whose
reevaluation threw has that reevaluation's CallFailedException as its cause, which hands out the reaction's own
flow and which assertThat(cause).isCallFailure().flow() reads; a reaction whose owner lookup threw ran no call.
A trail held as a list, such as the one trail() of a flow returns, has its own factory:
List<FlowEntry> entries =
traced.execute(new Publication("p8"), PublicationChange.PUBLISH).flow().trail();
TrailAssert.assertThat(entries)
.hasSize(1)
.hasHopsExactly(PublicationChange.PUBLISH)
.isInTimeOrder();
The shop's OrderFlowTest
asserts the flow and the trail of a cancellation that commits, and those of one that aborts, which
failures and the journal shows. Its set is built with recordTrail(), on the system
clock, so it asserts the entries of a trail and their order, never their instants.
Next: Building with the typed graph API. Back to the documentation index.