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

Testing GraphMaquina machines

graphmaquina-test is a test-scoped module of typed assertions, probes and graph snapshots for machines built with GraphMaquina. It asserts over the runtime's own values — definitions, edges, node policies, outcomes, transition records, reactions, sub-machine starts, engine exceptions, the flow of a call and its trail — and reports every unmet expectation as a GraphAssertionError carrying the context, the property, the expected value and the actual one.

It brings no test framework of its own. Nothing in its public API mentions JUnit or AssertJ, so it works under whatever runner your project already uses; the examples here are JUnit 5 because the repository's own example module is.

Every Java sample of the testing pages runs in this repository. Most are copied verbatim out of a test; the samples of failure kinds and recovery rules, of sub-machines and of the call's flow and its trail go the other way: they are cut out of testing-advanced.md and run by a test. Each section names the test file.

Contents

Install

Maven Central publishes graphmaquina-test with the other modules of every release, at the same version. Its coordinates follow the same version convention as the rest of the guide: a graphmaquinaVersion Gradle property or a graphmaquina.version Maven property, set once per build, never a literal repeated per dependency.

dependencies {
    testImplementation("io.github.graphmaquina:graphmaquina-test:$graphmaquinaVersion")
}
<dependency>
  <groupId>io.github.graphmaquina</groupId>
  <artifactId>graphmaquina-test</artifactId>
  <version>${graphmaquina.version}</version>
  <scope>test</scope>
</dependency>

The module is test-scoped: it depends on graphmaquina-core and adds nothing to your application's runtime classpath. Its POM pins graphmaquina-core at its own version, so keep it equal to the runtime, generator and processor versions you already align. Inside this repository no publication is needed at all: graphmaquina-example depends on the project directly with testImplementation(project(":graphmaquina-test")).

Your first test

The machines under test are built exactly as the application builds them: a real registry, real entities, and test doubles only where the domain reaches outside the process. A TransitionRecorder is a MachineObserver, so it is installed the way any observer is, and recordTrail() makes every call of the set record its trail. From OrderFlowTest:

final FakeGateway gateway = new FakeGateway();
final FakeCarrier carrier = new FakeCarrier();
final TransitionRecorder recorder = TransitionRecorder.create();
final ShopMachines shop = ShopMachinesRuntime
        .builder(Duration.ofSeconds(10), new OrderActions(gateway, carrier), new ItemActions())
        .observer(recorder)
        .recordTrail()
        .build();
final Orders orders = shop.orders();
final Items items = shop.items();

One static import, io.github.graphmaquina.test.GraphAssertions.assertThat, reaches the views for every subject a test holds directly: a definition, an outcome, an action or guard result, a recorded guard or action call, a throwable or an InvalidGraphException, an entity, the flow of a call, an eligibility answer. A bare list of transition records, of reactions, of automatic steps, of sub-machine starts, of journal entries or of trail entries would need overloads with the same erasure, so each keeps its own factory, TransitionRecordsAssert.assertThat, ReactionsAssert.assertThat, AutomaticStepsAssert.assertThat, StartsAssert.assertThat, JournalAssert.assertThat and TrailAssert.assertThat; inside a chain they are reached as records(), reactions(), automaticSteps(), starts(), journal() and trail(). The overload is chosen from the subject's static type, and the chain keeps the entity, state and transition types of that subject, so the two enums of the machine under test are the only ones the compiler accepts along it:

@Test
void anIdentifierWithNoEdgeFromTheCurrentStateIsRejectedByTheNodePolicy() {
    Order order = new Order("o1");

    assertThat(orders.ship(order)).isRejected()
            .hasReason("cannot ship without payment")
            .hasNoTransition()
            .requestedTransition(OrderTransition.SHIP);
    assertThat(order, Order::status).isIn(OrderStatus.NEW);
}

The chain carries three type parameters — the entity, the state enum and the transition enum — so a constant of another machine's catalogue does not compile inside it.

What each entry point checks

Subject Entry point What the view can expect
Graph definition assertThat(definition) initial state, terminal set, presence or absence of async, the identifiers declared from a state, the absence of one identifier, the absence of a watch or of a sub-machine, and automaticFrom(state): the automatic identifiers of a state in the order they are tried
One edge assertThat(definition).transition(from, id) destination, kind, action name and sync/async mode, guard names and modes in order, fallback failure identifier, failsOn classes, recovery rules in declaration order, timeout, after-commit hook, isAutomatic() or isManual(), and whether the onFailure route or a recovery rule continues the chain
One node's policy assertThat(definition).policy(state) hasDefaultReason, and rejects(id, reason): the reason that identifier gets, its own or the default, which also requires that no edge is keyed by it
A watched state assertThat(definition).watch(state) the peer machine and the ordered watch rules, each naming the identifier it executes
A bound state assertThat(definition).submachine(state, childKey) that the state holds that child machine, and its exits in declaration order, each the identifier of the parent that a terminal state of the child selects
Reachability assertThat(definition).topology() nodes, successors, reachable set, an explicit walk, the shortest path, absence of a path, cycles
Outcome assertThat(outcome) the variant, then from, the requested identifier, recorded state, live entity state, entity identity, hasStatus, hasCode, hasExplanation or hasNoExplanation, plus records(), reactions(), automaticSteps(), starts() and flow(), and the searches automaticFailure(), automaticAbort() and automaticBlock(), also with a MachineKey to select one machine's attempts, with their hasNoAutomatic… counterparts
Applied outcome assertThat(outcome).isApplied() movedTo
Failed outcome assertThat(outcome).isFailed() hasTarget, hasFailureTransition, movedTo, failure kind, reason, cause
Rejected outcome assertThat(outcome).isRejected() reason, hasNoTransition() for RejectionKind.NO_TRANSITION, isRejectedByGuardNamed for GUARD, isDetached() for DETACHED and isReservedExit() for RESERVED_EXIT
Ignored outcome assertThat(outcome).isIgnored() hasReason(IgnoreReason.NO_WATCH), NO_RULE_MATCHED, NO_AUTOMATIC_TRANSITION or NO_CANDIDATE_ADMITTED, and for the last rejections(), one eligibility view per edge the advance tried
Eligibility assertThat(eligibility) isEligible() or isIneligible(); of a refusal, hasNoTransition(), isRejectedByGuardNamed, isDetached(), isReservedExit() and hasReason; of both, from and transition
Transition records .records(), a trail's .hops(), or TransitionRecordsAssert.assertThat(list) size, exact content, and per entity: from, transition, to, kind, action, depth
Reactions .reactions(), or ReactionsAssert.assertThat(list) size, absence of aborts directly or recursively, and per entity: isDone() with its nested outcome, or isAborted() with its cause
Automatic steps .automaticSteps(), or AutomaticStepsAssert.assertThat(list) size, absence of aborts directly or recursively, and per entity: isDone() with its nested outcome, or isAborted() with its cause; details
Sub-machine starts .starts(), or StartsAssert.assertThat(list) size, and per child: the state it started at, its state before, the parent and the bound state that started it, and the depth
The call's flow .flow(), or assertThat(flow) the root entity by reference, the value of a key by equality, the absence of a value, the keys in the order of their writes, plus trail()
The call's trail .trail(), or TrailAssert.assertThat(list) size, the class of every entry in order, the identifier of every hop in order, that no instant goes back, and the kind of the final rejection or the phase of the final failure, plus hops(), the records of its hops
Engine failure assertThat(captureFailure(() -> ...)) abort, cascade abort, commit failure, after-commit failure, invalid graph; cause identity or type; cascade path; journal; phase, states written and the failing call; the hops and starts of an after-commit failure; the call's flow
Action result, guard result assertThat(actionOutcome), assertThat(guardResult) ok or failed, pass or rejected, the reason, and the failure kind of a failed action
Live entity assertThat(entity, Order::status) the state the getter reads at that moment
Completed calls TransitionRecorder.assertRecorded() size, the sequence of machine keys, the sequence of outcome statuses, and the outcome sequence of one entity
Tracked entities StateSnapshot which of the tracked entities moved since the capture, and that none did
Completion stage AsyncAssertions.await, AsyncAssertions.awaitFailure the outcome, or the throwable, the stage ended with inside the test's budget
Guard, action, hook GuardProbe, ActionProbe, HookProbe, CallTrace scripted answers per call, the calls each probe recorded, and the order callbacks were entered in
State setter StateWriteProbe every write in entry order with its status, and a failure armed on one call
Async callback ControlledAsyncAction, ControlledAsyncGuard that the engine entered the callback, with the test deciding when and how it answers
Rendered diagram GraphGoldens.assertMatches visual DOT output only; not machine logic
Whole definition GraphSnapshots.assertMatches the fields the definition declares against a checked-in resource, a sub-machine by its child's key and exits only, so the child's graph needs a snapshot of its own

Asserting on identity

Six expectations answer six different questions about an edge that may or may not be there. They are easy to confuse, so keep them apart:

What you want to establish Expectation
This origin declares exactly these identifiers hasTransitionsExactly(from, ids...)
This identifier has no edge from this origin hasNoTransition(from, id)
The request was refused because nothing was keyed isRejected().hasNoTransition()
The request was refused by a guard on an edge that does exist isRejected().isRejectedByGuardNamed(name)
The request was refused because the entity is a sub-machine whose parent does not hold it isRejected().isDetached()
The request named an exit of the sub-machine bound to the origin, which only the end of that sub-machine runs isRejected().isReservedExit()

hasTransitionsExactly takes identifiers, so two edges that reach the same state are two entries.

An Ignored outcome says which case it is, through isIgnored().hasReason(...): NO_WATCH or NO_RULE_MATCHED for a reevaluation, NO_AUTOMATIC_TRANSITION or NO_CANDIDATE_ADMITTED for an advance. It is the only outcome with no requested identifier, so hasNoRequestedTransition() holds on it and requestedTransition(id) holds on every other variant.

Useful behavior to cover in your own domain:

Visual export tests may separately pin .dot goldens when changes to diagram output require review.

A passing runtime test does not replace compile-time graph validation. Conversely, a valid graph does not prove that your action performs the correct domain operation.

More expectations

The entry-point table names each view's main expectations. These complete them:

View Expectations
Graph definition hasNoAsync(), hasNoWatch(state)
One edge isMove(), hasNoAction(), hasNoGuards(), hasNoFailureTransition(), hasNoTimeout()
Topology hasNodesExactly(states), hasSuccessorsExactly(from, states), hasReachableExactly, hasNoCycles(), hasCyclesExactly(cycles), each cycle starting at its earliest declared state
One transition record hasKind(kind), hasNoAction()
Reactions hasNoAborted(), which looks at this list alone, not at the reactions' own reactions
Journal hasEntry(key, entity, from, id, to, action, depth, status), with the entity compared by reference
Abort at(key, entity, from, id, to) for the edge that was running; atUnresolved(...), atUnread(...) and atUnreadState(...) for an abort before the edge, the identifier or the state was read; hasActionNamed(name), hasNoAction(), hasCascadePathExactly(route)
Cascade abort error(i), the abort of the i-th failed element, counted among the failures rather than among the cascaded entities
Commit failure hasAppliedExactly(entities...), hasPendingExactly(entities...), hasFailedEntity(entity), hasNoFailedEntity()
After-commit failure hasHookNamed(name), at(key, entity, from, id, to) for the hop the hook ran for
Any failure isCommitFailure() and isInvalidGraph() narrow it, as isAbort(), isCascadeAbort(), isAfterCommit() and isCallFailure() do
Invalid graph hasCodesExactly(codes...), in order and with repeats, hasProblemCount(n)
Action and guard results isOk(), isPass()

captureFailure takes a ThrowingRunnable, whose run() may throw any exception, so the body can call code that declares checked exceptions. TransitionRecorder.snapshot() returns the calls recorded so far as RecordedTransitions. A StateWriteProbe records each write as a StateWrite: the entity, the requested state, its status and, when the write threw a RuntimeException, its cause. ControlledAsyncAction and ControlledAsyncGuard take an onCall(consumer) side effect too, which runs when the engine enters the callback; if it throws, the stage fails and the handle is never delivered. A PendingInvocation of a controlled asynchronous fixture can also cancelStage(), and isCancelled() says whether it did. GraphSnapshot exposes capture(definition), serialize() and parse(text), and GraphDiff.compare(expected, actual) returns the path-by-path differences of two snapshots, each a GraphDiff.Change of a path with its expected and actual values, render()ed as the lines a failing GraphSnapshots.assertMatches prints.

Goldens and structural snapshots

Machine contracts and visual output have separate tests. Do not use a graphical export to validate machine logic.

Snapshots are graphmaquina-snapshot-v1 documents; GraphSnapshot.parse refuses any other header. After that version line comes one path TAB value line per field, each ending in a line feed, with backslash, tab, line feed and carriage return escaped; GraphSnapshot.fields() returns the path-to-value map in that canonical order. Fields live under /machine/…, /states/<i>, /catalog/<i>, /transitions/<from>/<id>/…, with recovery rules under recoveries/<i>/kind, transition and failsOn, /policies/…, /watches/… and /submachines/<state>/{child/…, exits/<terminal>}; a missing edge has no path at all. An automatic edge adds /transitions/<from>/<id>/automatic, a continuing onFailure route onFailureContinues and a continuing rule recoveries/<i>/continues, each true and written only when set, and a state with two or more automatic edges the order they are tried in, at /automaticOrder/<state>/count and /automaticOrder/<state>/<i>. PublishedArtifactSmokeTest compiles and runs a semantic consumer after removing every graphic-export class from the core JAR; assertions, state observation and structural snapshots must still work.

From DiagramsTest:

@Test
void orderDiagramMatchesGolden() {
    GraphGoldens.assertMatches(orderGraph(), "golden/order.dot");
}

From GraphContractsTest:

@Test
void orderContractMatchesSnapshot() {
    GraphSnapshots.assertMatches(orderGraph(), "contracts/order.graph");
}

A mismatch reports the lines that changed, or for a snapshot the field paths that differ — not both files in full, and both it and a missing golden end with the flags that rewrite the file. In read mode a stored snapshot of an unknown version or a broken format is reported as the fixture problem it is instead of being compared, and carries no such flags. An update run never reads the stored text as a snapshot: it replaces the file with a snapshot of the current version, so an unreadable one is overwritten rather than reported, and the review of the rewritten file is what checks the change.

Reading and updating

The two directions resolve differently. Read mode never writes, and update mode writes only under the source root. Nothing compares that root with the class path, so point it at the source directory, never at a class-path output:

Mode Resource resolved through Written to
Read (the default) the class loader, so the copy on the test class path nothing
Update the source file under the root, read only to skip an identical rewrite the source root named by graphmaquina.goldens.root; each rewritten file is reported as UPDATED <path>

false, the default

no

yes

yes

no

true

no

yes

yes

no

GraphGoldens.assertMatches or GraphSnapshots.assertMatches

graphmaquina.goldens.update?

read the resource through the class loader

is the resource there?

GraphAssertionError: missing,
with how to write it

same text, line endings aside?

the assertion passes

GraphAssertionError with the difference,
and how to regenerate it; for a snapshot
that cannot be read, IllegalArgumentException

graphmaquina.goldens.root set?

IllegalStateException: nowhere to write

does the source file already
hold this text?

nothing is written

write it under the root
and print UPDATED <path>

false, the default

no

yes

yes

no

true

no

yes

yes

no

GraphGoldens.assertMatches or GraphSnapshots.assertMatches

graphmaquina.goldens.update?

read the resource through the class loader

is the resource there?

GraphAssertionError: missing,
with how to write it

same text, line endings aside?

the assertion passes

GraphAssertionError with the difference,
and how to regenerate it; for a snapshot
that cannot be read, IllegalArgumentException

graphmaquina.goldens.root set?

IllegalStateException: nowhere to write

does the source file already
hold this text?

nothing is written

write it under the root
and print UPDATED <path>

Two system properties select the mode, named by GoldenOptions.UPDATE_PROPERTY and GoldenOptions.ROOT_PROPERTY. A resource name must be a relative, /-separated path: an empty name, a leading /, a \, a drive prefix such as C:, and an empty, . or .. segment are refused with IllegalArgumentException. graphmaquina.goldens.update accepts only the exact values true and false; graphmaquina.goldens.root names the source root an update writes into and is required when update mode is on. Read mode ignores it: GoldenOptions.defaults() makes it a path only in update mode, so in read mode sourceRoot() is empty and a value that is not a path fails nothing. The resource string is a class-path-relative path such as golden/order.dot, and update mode writes it at that same relative path under the root, so pointing the root at src/test/resources puts the file back where the class path picked it up.

Both assertMatches methods have an overload that takes GoldenOptions: GoldenOptions.defaults() reads the two properties each time it is called and uses the thread's context class loader, readOnly(loader) reads through a loader of your choice, and updating(loader, sourceRoot, reporter) hands the reporter the absolute path of each golden it writes; loader(), update() and reporter() expose them. An update writes a temporary file beside the golden and moves it over the target, atomically where the file system supports it; a source that is not valid UTF-8 is replaced, and a source root that is not a directory throws IllegalStateException. A golden is read as strict UTF-8, a leading byte-order mark dropped, and a resource that names a directory fails with GraphAssertionError.

Update mode writes through a symbolic link inside the root, at the golden itself or at a directory above it, and keeps the link. It does so even when what the link names does not exist yet: it creates that file, with any directory missing on the way, unless a . or .. follows a missing name in the path the link holds, which fails with IllegalStateException. A link that leads out of the root, a dangling one included, is refused with IllegalArgumentException, and nothing is written.

Gradle

The source root has to be resolved when the build is configured, because a test worker has no project to ask. An update run writes files instead of producing task outputs, so it must be neither skipped as up to date nor served from the build cache. This is the golden-update part of the test configuration graphmaquina-example applies:

val updateGoldens = providers.systemProperty("graphmaquina.goldens.update")
    .map { it.toBooleanStrict() }.orElse(false)
tasks.test {
    systemProperty("graphmaquina.goldens.update", updateGoldens.get().toString())
    systemProperty(
        "graphmaquina.goldens.root",
        layout.projectDirectory.dir("src/test/resources").asFile.absolutePath)
    outputs.upToDateWhen { !updateGoldens.get() }
    outputs.doNotCacheIf("Golden update writes source resources") { updateGoldens.get() }
}

Rewrite the goldens with:

./gradlew test -Dgraphmaquina.goldens.update=true

Then read the diff and commit it. An update run is a deliberate act: it makes the test pass by definition, so the review of the rewritten file is the only thing that checks the change.

Maven

Surefire passes system properties to the test JVM through systemPropertyVariables. Add them to the Surefire configuration your project already has, and do not pin a Surefire version here without checking the one your build resolves:

<systemPropertyVariables>
  <graphmaquina.goldens.update>${graphmaquina.goldens.update}</graphmaquina.goldens.update>
  <graphmaquina.goldens.root>${project.basedir}/src/test/resources</graphmaquina.goldens.root>
</systemPropertyVariables>

Declare the default in <properties> so a normal build reads rather than writes:

<graphmaquina.goldens.update>false</graphmaquina.goldens.update>

Rewrite the goldens with mvn test -Dgraphmaquina.goldens.update=true.

This is property plumbing only. It replaces nothing in your project's GraphMaquina generation setup: the generate, prepare-compile and complete-compile lifecycle stays exactly as the build integration guide describes it.

A test that needs no properties at all can pass options explicitly — GoldenOptions.readOnly(loader) or GoldenOptions.updating(loader, sourceRoot, reporter) read none.

What a check does not prove

The check establishes It does not establish
topology().hasPath(...): the graph permits this walk that any run took it. Only an outcome or a transition record shows a hop that happened.
isApplied(): the root transition committed that everything it triggered did. A watch reaction inside an applied outcome may have aborted; reactions().hasNoAbortedRecursively() is the expectation that rules that out, and hasNoAutomaticAbort() and hasNoAutomaticFailure() do the same for the automatic attempts.
hasStatus(APPLIED) or hasCode(...): what the root call reported that its reactions committed, or where the entity is now. Read reactions() and hasEntityState(...) for those.
movedTo(...) and hasRecordedState(...): the state the outcome recorded where the entity is now. hasEntityState(getter, ...) reads the live entity, and the entity can move again right after.
hasTransitionsExactly(from, ids...): which identifiers the state declares that any of them would succeed for a given entity. It is structural; guards are not evaluated.
isRejected().hasNoTransition(): nothing was keyed by (from, id) that the entity cannot move at all. Another identifier may well have an edge from the same state.
calls().assertCount(n): a callback was entered n times that the machine wrote a state. Only StateWriteProbe.writes() sees the setter.
journal(): which actions the aborted attempt entered, and how each ended that the entities were put back. StateSnapshot.assertUnchanged() is the expectation that asserts the rollback.
flow().hasValue(key, value): the flow holds a value equal to that one that it is the object a step put. The flow keeps values by reference, and get(key) returns that very object.
trail().hasHopsExactly(ids...): the identifiers of the hops the call took, in order which machine or entity took each hop, or the states it joined. trail().hops() compares those field by field, on the trail of a failed call too.
the recorder: the outcome of every call that completed anything about a call that threw, such as one whose step aborts, whose commit fails, whose hook throws, or whose reaction raises an Error. The recorder keeps completed calls only; capture the throwable instead.
AsyncAssertions.await(stage, budget): the engine's transition finished that work the action started in the background ended. Neither wait ever cancels a stage it was handed.
that budget: how long the test is willing to wait the engine's deadline. That is asyncTimeout(...) on the machine and the edge's timeout, which hasTimeout(...) asserts, and an expired engine deadline leaves the user's stage alive.

Sharp edges

Maintaining test support

Every GraphMaquina feature or behavior change must provide its counterpart in graphmaquina-test in the same delivery. Extend the relevant assertions, probes, recorded calls or snapshots so a consuming project can verify the new behavior. Include regression coverage and documented consumer usage. When existing support already expresses the behavior, demonstrate it with an executable consumer test. Public test APIs must also be exercised against the staged artifacts by :graphmaquina-test:publishedArtifactTest.


Next: Testing samples: graphs, outcomes, probes and async. Back to the documentation index.