Skip to content

Testing Workflows

A workflow definition is code: it has branches, deadlines, retries and a rollback path, and every one of them deserves a test. The workflow-test module runs your definitions inside a JUnit 5 test — the real engine, in memory, with no server, broker or database — and gives the test three things a running deployment cannot:

Chapter 12 of EventConductor in N minutes (2:45) · English, with English and Spanish subtitles

  • A clock you move. advanceTime(Duration.ofDays(3)) jumps from one due moment to the next — every TIMER, step timeout, retry backoff and cron occurrence on the way fires at its own moment — and returns in milliseconds. It is the same idea as Temporal’s time-skipping test environment.
  • Mocks instead of workers. Answer each task with a completion, a failure or silence; stub HTTP_CALL and LLM_CALL steps so a test never reaches the network or a model.
  • Assertions on the process. assertThat(process).isCompensated().hasPassedSteps("refund"), in the spirit of Camunda’s process test assertions.
<dependency>
<groupId>io.mateu.workflow</groupId>
<artifactId>workflow-test</artifactId>
<version>${eventconductor.version}</version>
<scope>test</scope>
</dependency>

It brings the engine, JUnit 5, Spring’s test support and AssertJ with it. The kit lives in the package io.mateu.workflow.test.

A complete example: a saga with a three-day timer

Section titled “A complete example: a saga with a three-day timer”

The definition — a booking that reserves a room and charges a card, then waits out a three-day cooling-off period before capturing the payment. Both the reservation and the charge are compensable:

{
"id": "booking-saga",
"name": "Booking with a three-day cooling-off period",
"version": 1,
"steps": [
{ "id": "start", "type": "START", "name": "Start" },
{ "id": "reserve", "type": "ACTION", "name": "Reserve the room", "topic": "reserve-room",
"compensable": true, "compensationStepId": "release", "preconditionStepId": "start" },
{ "id": "charge", "type": "ACTION", "name": "Charge the card", "topic": "charge-card", "retries": 2,
"compensable": true, "compensationStepId": "refund", "preconditionStepId": "reserve" },
{ "id": "cooling-off", "type": "TIMER", "name": "Three days to change your mind", "duration": "P3D",
"preconditionStepId": "charge" },
{ "id": "capture", "type": "ACTION", "name": "Capture the payment", "topic": "capture-payment",
"retries": 0, "preconditionStepId": "cooling-off" },
{ "id": "release", "type": "ACTION", "name": "Release the room", "topic": "release-room" },
{ "id": "refund", "type": "ACTION", "name": "Refund the card", "topic": "refund" },
{ "id": "end", "type": "END", "name": "End", "preconditionStepId": "capture" }
]
}

Put it where the engine always looks, src/test/resources/workflows/booking-saga.json (or in src/main/resources/workflows/ if it ships with your application). Both directories are read; if the same definition id is in both, the test one wins (test output is first on the classpath — see Workflow definitions). The test:

import io.mateu.workflow.test.EventConductorTest;
import io.mateu.workflow.test.WorkflowTestRuntime;
import org.junit.jupiter.api.Test;
import java.time.Duration;
import java.util.Map;
import static io.mateu.workflow.test.WorkflowAssertions.assertThat;
import static org.assertj.core.api.Assertions.assertThat;
@EventConductorTest
class BookingSagaTest {
@Test
void capturesThePaymentOnceTheCoolingOffPeriodIsOver(WorkflowTestRuntime runtime) {
runtime.whenTask("reserve-room").thenComplete(Map.of("roomId", "R-12"));
runtime.whenTask("charge-card").thenComplete(Map.of("chargeId", "ch_1"));
runtime.whenTask("capture-payment").thenComplete();
var booking = runtime.start("booking-saga", "B-1", Map.of("amount", 120));
assertThat(booking).isWaitingAt("cooling-off").hasVariable("chargeId", "ch_1");
runtime.advanceTime(Duration.ofDays(2));
assertThat(booking).isWaitingAt("cooling-off"); // not yet
runtime.advanceTime(Duration.ofDays(1));
assertThat(booking).isCompleted()
.hasPassedSteps("reserve", "charge", "cooling-off", "capture");
}
@Test
void refundsAndReleasesWhenTheCaptureIsDeclined(WorkflowTestRuntime runtime) {
runtime.whenTask("reserve-room").thenComplete();
runtime.whenTask("charge-card").thenComplete(Map.of("chargeId", "ch_2"));
runtime.whenTask("capture-payment").thenFail("CARD_EXPIRED", false); // final: no retry
runtime.whenTask("refund").thenComplete();
runtime.whenTask("release-room").thenComplete();
var booking = runtime.start("booking-saga", "B-2", Map.of("amount", 120));
runtime.advanceTime(Duration.ofDays(3));
assertThat(booking).isCompensated()
.hasCompensatedInOrder("charge", "reserve") // the newest step is undone first
.hasNotPassedSteps("capture");
assertThat(runtime.invocationsOf("refund").getFirst().variable("chargeId")).isEqualTo("ch_2");
}
}

Both tests together run in well under a second once the context is up: three days of business time are three jumps of the clock.

@EventConductorTest is a @SpringBootTest that boots the engine in embedded mode with memory persistence, with:

  • the test clock as the engine clock. Every moment the engine records or compares — process start and finish, a TIMER’s due moment, a timeout deadline, a retry’s backoff, a cron occurrence — is read from it, and it only moves when the test moves it;
  • no scheduler running on its own (workflow.schedulers.background=false). The kit runs every scheduler pass itself, when the test asks for time to pass;
  • every task answered on the calling thread. A call returns once the engine has done all it can at the current time, so there is nothing to await.

Definitions load from classpath:/workflows/ as in any embedded application — src/main/resources/workflows/ and src/test/resources/workflows/ both, the test copy winning when an id is in both. Add others from files or directories with @EventConductorTest(definitions = {"src/test/flows", "classpath:extra/order.json"}), or at run time with runtime.deploy(...).

The Spring context is cached between test classes with the same configuration, like any Spring test context. Each test starts with no mocks and an empty record of task invocations; the clock carries on from where the last test left it (it never goes backwards); processes started by earlier tests are left alone — their tasks are never answered by the current test’s mocks. Business keys are unique per engine, so give each test its own, or pass null for a generated one.

The engine clock is one per JVM, so run these tests one at a time — JUnit’s default. Do not turn on JUnit’s parallel execution (junit.jupiter.execution.parallel.enabled) or Surefire’s parallel for test classes that use the kit; to spread them over cores, parallelise by JVM instead — Surefire’s <forkCount>1C</forkCount> with <reuseForks>true</reuseForks> gives each fork its own JVM (and so its own clock), with the classes of one fork still running one after another.

CallWhat it does
advanceTime(Duration)Moves the clock forward, stopping at every due moment on the way and letting the engine act there
advanceTimeTo(LocalDateTime)The same, to an absolute moment in the engine’s zone
runUntilIdle()Runs every scheduler pass at the current time until nothing changes (rarely needed: every other call already does)
now() / clock()The engine’s current time, and the TestClock itself

A TIMER fires at its due moment. A timeout expires strictly after its limit, so it fires one millisecond later: a step with a one-hour timeout is still waiting at exactly sixty minutes and has timed out after sixty-one. Retry backoffs use the engine’s real backoff policy (workflow.retry.backoff-*, jitter included), and each dispatch records the time it happened, so a test can measure them:

runtime.whenTask("charge-card").thenFail("GATEWAY_DOWN").thenFail("GATEWAY_DOWN").thenComplete();
var charge = runtime.start("flaky-charge", "C-1", Map.of());
runtime.advanceTime(Duration.ofMinutes(1));
var calls = runtime.invocationsOf("charge");
assertThat(Duration.between(calls.get(0).at(), calls.get(1).at()))
.isBetween(Duration.ofMillis(800), Duration.ofMillis(1200)); // 1 s ± 20 % jitter

Loops are skipped the same way: a repeat or loopBack with a delay parks its next run until the delay is over, and advanceTime stops there. Each run is its own step execution, so assertThat(process).stepExecutions("poll").hasSize(3) counts the runs of a repeated step; each forEach instance is dispatched — and mocked, or answered with completeTask — on its own.

Cron schedules fire once per occurrence on the way: advanceTime(Duration.ofDays(3)) over a 0 0 9 * * * schedule starts three processes, each at 09:00. Find them with runtime.processes("nightly-report"). Retention purges run too, when they are enabled.

Flow control too: advanceTime stops where a startPolicy debounce window closes or a throttle window opens, and where a rate-limited topic has permits again.

MockMatches
whenStep("charge")the step with that id — wins over everything else
whenTask("charge-card")a step whose task is charge-card (any version), or — for a step with no task — whose id is charge-card, or whose topic is charge-card. A USER_TASK, HTTP_CALL or other built-in step names no task of its own either, so whenTask("approve") matches the USER_TASK approve (whenTask("complete-form") matches every USER_TASK)

Each mock is a list of answers, consumed in order; the last one repeats:

AnswerEffect
thenComplete() / thenComplete(Map)The task completes, writing the variables onto the process (non-text values as JSON)
thenFail(code) / thenFail(code, retryable)The task fails with code, as a TaskFailure would: a retryable failure spends the step’s retries, a final one fails it at once
thenTimeout()The worker never answers: the step waits until its timeout fires under advanceTime
thenAnswer(invocation -> TaskOutcome...)Whatever the function decides from what the task was sent (invocation.variable("amount"), invocation.attempt() …)

A task nothing mocks is answered by the application’s real TaskHandler, when the test boots one (see below); otherwise it waits, like a step whose worker has not answered yet. Answer it by hand with completeTask(process, stepId, variables) or failTask(process, stepId, code, retryable). A USER_TASK always waits unless mocked; complete it with completeUserTask(process, stepId, submittedValues).

Two things that differ from Mockito:

  • Stubbing the same step or task again adds answers; it does not replace them. whenStep("charge") returns the same stub each time, so a helper’s thenComplete() followed by a test’s own thenFail(…) answers the first dispatch with the helper’s answer and the following ones with the test’s. Give each test the answers it needs, or decide in one thenAnswer(…).
  • The answers are counted per stub, across every process and every forEach iteration of the test. whenStep("reserve").thenFail("BUSY").thenComplete() over three rooms fails the first dispatch — whichever room it is for — not each room’s first attempt. To answer per item, decide from what the task was sent: thenAnswer(task -> "102".equals(task.variable("room")) ? … : …); an HTTP_CALL has per-iteration stubs.

invocations() and invocationsOf(stepId) list every dispatch the test saw — process, step, task id, topic, attempt, the variables it was sent and the engine time it happened.

An HTTP_CALL or LLM_CALL step never reaches the network in a test: without a stub it fails at once, with a reason that names the stub to add.

var payments = runtime.whenHttpCall("charge")
.thenRespond(503, "busy") // retried: 5xx is in retryOn
.thenRespond(201, "{\"id\":\"ch_42\"}");
var process = runtime.start("http-charge", "H-1", Map.of("bookingId", "B-1", "amount", 99.5));
runtime.advanceTime(Duration.ofMinutes(1));
assertThat(process).isCompleted().hasVariable("chargeId", "ch_42");
assertThat(payments.lastRequest()).containsEntry("method", "POST");

The request is rendered by the engine exactly as in production, and the stubbed response goes through the step’s own successStatus, retryOn and output mapping — a 404 fails the step for good, a 503 or thenIoError() is retried.

One iteration, item or request apart. A forEach HTTP_CALL makes one call per item; a scoped stub answers some of them differently, with answers of its own (consumed and repeated on their own, so each scope can have its own retries). The first scope that matches a call answers it; any other call gets the stub’s own answers:

var hotel = runtime.whenHttpCall("book").thenRespond(201, "{\"id\":\"H-1\"}"); // every room…
hotel.whenIteration(1).thenRespond(409, "sold out"); // …but the second
hotel.whenItemHas("number", "900").thenRespond(503, "busy").thenRespond(201, "{\"id\":\"H-9\"}");
hotel.whenRequest(request -> String.valueOf(request.get("body")).contains("VIP")).thenRespond(201, "{\"id\":\"V\"}");

whenIteration(index) (0-based) and whenItem(predicate) / whenItemHas(field, value) read the iteration from the step’s own forEach; for an HTTP_CALL inside an inline PROCESS body, match the rendered request with whenRequest(…). Each scope records its own requests(); the stub’s requests() has every call.

whenLlmCall("triage").thenAnswer("{\"category\":\"noise\"}") does the same for a model: outputVariable, usageVariable and output expressions over text, json, usage and model are applied. The answer is validated against the step’s responseSchema, as the built-in task validates a real model’s: an answer the schema refuses is a mistake in the test, so the step fails (LLM_STUB_INVALID, not retried) and the test fails, with what the schema says —

The test's stubs answered what their steps cannot take:
LLM_CALL step 'triage': the stubbed answer does not match the step's responseSchema —
/category: does not have a value in the enumeration ["noise", "cleaning", "other"]; : required
property 'urgent' not found. Fix the stub, or stub it with thenInvalidAnswer(…) to test an
invalid model answer. Answer: {"category": "party"}

— and a failed process assertion lists it under Stub problems. To test what the step does with a model that answers badly, say so: thenInvalidAnswer(text) fails the call with LLM_INVALID_OUTPUT and the schema’s errors, retryably, as in production (runtime.stubProblems() stays empty).

An AGENT step never reaches the IA catalogue or an agent runtime in a test. The kit’s catalogue takes every reference a definition names as published, and whenAgent scripts what the runtime answers. Each invocation takes the next answer, so a forEach gets one per item. Without a stub the step fails.

var agent = runtime.whenAgent("assess").thenOutput("{\"decision\":\"accept\"}");
var process = runtime.start("claim-assessment", "C-1", Map.of("claimId", "C-1"));
assertThat(process).isCompleted().hasVariable("assessment", Map.of("decision", "accept"));
assertThat(agent.lastRequest()).containsEntry("taskPrompt", "Assess claim C-1");

A review holds the process until the runtime reconciles it. resolveAgentReview does that with the next answer of the script:

runtime.whenAgent("assess").thenReviewRequired().thenOutput("{\"decision\":\"refer\"}");
var process = runtime.start("claim-assessment", "C-2", Map.of("claimId", "C-2"));
assertThat(process).hasStatus(ProcessStatus.PAUSED).hasStepStatus("assess", StepExecutionStatus.REVIEW_REQUIRED);
runtime.resolveAgentReview(process, "assess");
assertThat(process).isCompleted();

thenFail(code, message) fails the step (agent failures are final). thenNoReply() leaves the invocation in flight: advanceTime past its timeout holds it for review, and a following thenCancelled() is the runtime confirming it stopped, which times the step out (onTimeoutStepId applies). Every reply names the invocation, so a parked agent task can also be answered with completeTask(process, "assess", Map.of("assessment", json)).

CallWhat it does
sendMessage(name, correlationKey, variables)Delivers a message, as MessageReceived or POST /workflow/api/messages would
publishEvent(destination, type, data)Delivers a domain event as if it arrived on its topic: starts the processes whose triggers match and resumes the steps whose onEvent does
publishedEvents(process)What the process’s PUBLISH_EVENT steps published
cancel(process)Cancels it, as an operator would
process(businessKey) / processes(definitionId)Finds processes the test did not start itself (triggers, cron, children)

Updates are applied at once, as the owner of the process would, and the engine then runs as far as the update lets it. A refusal is an outcome to assert on, not an exception.

CallWhat it does
update(process, "changeAddress", payload)Sends the update (payload: a map, a value, or JSON text) and returns its UpdateOutcome: status() (COMPLETED, REFUSED, NOT_ACCEPTED, FAILED, INVALID_PAYLOAD, UNKNOWN_UPDATE, KEY_REUSED), result() (JSON), resultValue() (parsed), error()
update(process, name, payload, idempotencyKey)The same with a key: the same key again is the same update
updateWithStart(definitionId, businessKey, variables, name, payload)Update-with-start: started() says whether it started the process, process() is the process
process.updates()The process’s recorded updates, oldest first
var outcome = runtime.update(order, "changeAddress", Map.of("address", "Elm Street 2"));
assertThat(outcome).isCompleted().hasResult("{\"address\": \"Elm Street 2\", \"changes\": \"1\"}");
assertThat(runtime.update(order, "changeAddress", Map.of("address", "Elm Street 2")))
.isRefusedWith("already the shipping address");
assertThat(order).hasAppliedUpdates("changeAddress");

assertThat(outcome) offers isCompleted(), isRefused(), isRefusedWith(fragment), isNotAccepted(), isFailed(), isInvalidPayload(), hasStatus(s), hasResult(json) (compared as JSON), hasErrorContaining(fragment) and startedTheProcess().

import static io.mateu.workflow.test.WorkflowAssertions.assertThat; — every assertion reads the process from the engine when it runs, and a failure prints its steps and variables.

AssertionPasses when
isCompleted() / isCompensated() / isCompensationFailed() / isFailed() / isCancelled() / isRunning() / hasStatus(s)The process has that status
hasPassedSteps("a", "b") / hasNotPassedSteps(...)Each step completed (or none did)
isWaitingAt("step")The process is running and the step is in flight: a TIMER or message wait, an unanswered task, a retry’s backoff, a lock
hasStepStatus("step", StepExecutionStatus.TIMEOUT)The step’s latest execution has that status
stepExecutions("step").hasSize(n)Any AssertJ list assertion on the step’s executions
hasVariable(name, value) / hasVariables(map) / hasVariable(name) / doesNotHaveVariable(name)Variables are text in the engine: a text value is compared as text, anything else as the JSON it is stored as (hasVariable("nights", 3))
hasReplied() / hasReplied(json) / hasReplyOutcome(outcome)A REPLY step answered (compared as JSON), or the engine answered for the process
hasPublishedEvent(type)A PUBLISH_EVENT step published an event of that type
hasAppliedUpdates("a", "b")The process applied exactly these updates, in this order
hasCompensated("charge", "reserve") / hasNotCompensated(...)The saga undid each step — the compensation it declares ran and completed — or none of them
hasCompensatedInOrder("charge", "reserve") / hasNoCompensations()The saga undid exactly these steps, in this order (the newest first), or ran no compensation at all
hasEscalated("approve") / hasEscalated("approve", 2) / hasNotEscalated("approve")A USER_TASK’s escalation fired — at least one level, exactly n levels, or none yet
iterations("rooms")The iterations of a forEach, item by item

A failure message lists the process’s steps, a forEach’s iterations under their step named by index and label (or item), and its variables:

Expected process 7c311a8e-… (rooms-booking-safe, businessKey FAIL-1) to be COMPLETED but it is COMPENSATED.
Steps:
start COMPLETED
register-booking COMPLETED
rooms ERROR
#0 "Room 101" COMPLETED
#1 "Room 102" COMPLETED
#2 "Room 900" ERROR
notify-guest CANCELLED
done CANCELLED
cancel-room-booking COMPLETED
#0 room={"number":"102","type":"double"} COMPLETED
#1 room={"number":"101","type":"double"} COMPLETED
Variables: {…}

The compensation assertions name the compensated steps, not their compensations, and read the order from the order the compensations’ tasks were dispatched; a failure shows every compensation that ran:

Expected process … to have compensated [reserve, charge], in this order, but it compensated [charge, reserve].
Compensations, in the order they ran:
refund undoing charge COMPLETED
release undoing reserve COMPLETED

assertThat(process).iterations("rooms") asserts on each item of a forEach. Name an iteration by its 0-based index (1), its label — what the forEach’s label made of its item ("Room 102") — or its item itself ("2", Map.of("number", "102"), compared as JSON):

assertThat(booking).iterations("rooms")
.hasSize(3)
.hasOnlyFailed("Room 900") // that one failed, no other did
.hasCompensated("Room 101", "Room 102"); // and the rollback undid the others
assertThat(booking).iterations("rooms").iteration("Room 101")
.isCompleted().hasOutput("roomBookingId", "RB-101").wasCompensated();
AssertionPasses when
hasSize(n)The forEach ran n iterations
allCompleted() / hasCompleted(...)Every iteration completed, or each of these did
hasFailed(...) / hasOnlyFailed(...) / hasNoFailures()Each of these failed (ERROR or TIMEOUT); these failed and no other; none failed
hasCompensated(...) / hasCompensatedInOrder(...) / hasNoneCompensated()The saga undid exactly these iterations (in any order, or in this one — newest first), or none
iteration(ref)One iteration: hasStatus(s), isCompleted(), isFailed(), isCancelled(), hasOutput(name, value), hasItem(item), wasCompensated(), wasNotCompensated()

Failure messages name iterations the same way — #2 "Room 900", or #1 room=2 without a label — and list every iteration with its status, what it reported and whether it was undone:

Expected only [#0 "Room 101"] of step 'book' of process … to have failed, but [#2 "Room 103"] failed:
#0 "Room 101" COMPLETED (compensated) {bookingId=H-1}
#1 "Room 102" COMPLETED (compensated) {bookingId=H-1}
#2 "Room 103" ERROR

A retried step is one step execution with several attempts, so stepExecutions("charge") has one element after two retries; count dispatches with runtime.invocationsOf("charge").

A test case can be a file instead of a method: what to start, how its tasks, HTTP calls, model calls and agents answer, what happens next and how it must end. Someone who does not write Java can then add a case — and review one — as easily as a definition.

src/test/scenarios/booking.yaml
workflow: booking-saga # shared by every scenario of the file
tasks:
reserve-room: { complete: { reservationId: R-1 } }
refund: { complete: {} }
release-room: { complete: {} }
scenarios:
- name: the payment is captured after the cooling-off period
variables: { amount: 120 }
tasks:
charge-card: { complete: { chargeId: ch_1 } }
capture-payment: { complete: {} }
then:
- advanceTime: P3D
expect:
status: COMPLETED
passedSteps: [reserve, charge, capture]
variables: { chargeId: ch_1 }
- name: a declined card releases the room
variables: { amount: 120 }
tasks:
charge-card: { fail: CARD_DECLINED, retryable: false }
expect:
status: COMPENSATED
passedSteps: [release]
notPassedSteps: [capture]

Run every scenario of a directory as a test of its own — each with fresh mocks — from a parameterized test:

@EventConductorTest
class BookingScenariosTest {
@ParameterizedTest(name = "{0}")
@ScenarioSource("src/test/scenarios") // files or directories; classpath: works too
void scenario(Scenario scenario, WorkflowTestRuntime runtime) {
runtime.run(scenario); // returns the TestProcess, for more assertions
}
}

or from a @TestFactory, return runtime.scenarios("src/test/scenarios");. A file is an object with scenarios (its other keys are defaults its scenarios share), a list of scenarios, or one scenario; YAML or JSON. Maps a scenario shares with its file (variables, tasks, steps, http …) are merged one level deep: the scenario adds entries and overrides them by key.

KeyWhat it says
nameHow the test is called (default: scenario <n>)
workflowThe definition to start (required)
businessKeyThe process’s business key (default: generated)
variablesThe start variables; non-text values are stored as JSON
tasks / stepsTask answers by task id or topic (whenTask) / by step id (whenStep)
http / llm / agentsHTTP_CALL / LLM_CALL / AGENT answers, by step id
thenWhat happens after the start, in order
expectHow it must end

Answers. One answer, or a list. A list is given in order — the n-th dispatch gets the n-th answer and the last one repeats, as with thenComplete(…).thenFail(…) — unless an answer has a when: then each dispatch gets the first answer whose when (JEXL, over the variables the task was sent; JSON values as structure) holds, and an answer without one is the fallback.

KindAnswers
task / step{complete: {var: value}} (${…} in a value is filled in from the task’s variables) · {fail: CODE, retryable: false} (retryable defaults to true) · {timeout: true} (never answers)
http{status: 201, body: {…} or "text", headers: {…}} (status defaults to 200) · {ioError: true}
llm{answer: "text" or {…}} (an object is answered as JSON) · {fail: CODE, retryable: false}
agents{output: … } · {fail: CODE, message: …} · {reviewRequired: true} · {cancelled: true}

then — each item one action: advanceTime: P3D · sendMessage: {name, correlationKey, variables} (the correlation key defaults to the business key) · completeTask: {step, variables} · failTask: {step, code, retryable} · completeUserTask: {step, values} · publishEvent: {destination, type, data} · update: {name, payload} · cancel: true · runUntilIdle: true.

expect — status (a ProcessStatus: COMPLETED, COMPENSATED, ERROR, RUNNING …) · passedSteps · notPassedSteps · waitingAt · variables (compared as hasVariable compares) · missingVariables · publishedEvents (CloudEvents types) · reply (JSON) · invocations: {step: count} (dispatches of the step in this process).

A key the format does not know is a mistake, reported with the scenario’s name and file — as is an expectation that does not hold, which fails the test like the assertion it stands for.

Every @EventConductorTest test records what its processes did. After each one, target/eventconductor-coverage/ holds the coverage of the run so far, for every definition the engine knows — one no test starts shows as 0%:

EventConductor workflow coverage — 35 test(s), 11 definition(s)
definition steps branches edges
hotel-booking 20/20 (100.0%) 10/13 (76.9%) 23/26 (88.5%)
rooms-booking-all-or-none 3/4 (75.0%) 1/1 (100.0%) 2/3 (66.7%)
…
TOTAL 74/75 (98.7%) 23/28 (82.1%) 68/74 (91.9%)
Not covered:
rooms-booking-all-or-none
step done
sequence rooms → done
CountedCovered when, in one process …
a stepit ran (started, whatever it ended in)
a choice branch — a link out of a CHOICEthe CHOICE completed and the step ran
a guard — a link with a conditionits source completed and the step ran
a timeout route (onTimeoutStepId)the step and its timeout target ran
a compensationthe step completed and its compensation ran
a loopBackthe step completed and its target ran more than once
a sequence — any other linkits source completed and the step ran

Branches are every route but the plain sequence links (which follow from the steps); edges are all of them. Inline PROCESS bodies are definitions of their own (hotel-booking.rooms). coverage.txt is for reading; coverage.json is what eventconductor:verify reads to fail the build under a floor (minStepCoverage, minBranchCoverage). In a test, WorkflowCoverage.current().report() returns the same numbers.

System properties (Surefire’s systemPropertyVariables): eventconductor.coverage.enabled=false turns it off, eventconductor.coverage.directory writes elsewhere. The report covers one JVM: with several Surefire forks, each overwrites it.

By default the test boots the engine alone. To have your TaskHandlers answer the tasks no mock does, boot them too — they run in-process through the worker SDK, exactly as in an embedded application:

@EventConductorTest(classes = {WorkflowTestApplication.class, PaymentHandlers.class})
class PaymentsTest { ... }

or classes = MyApplication.class for your own @WorkflowEmbeddedApplication. A mock always wins over a handler, so a test can replace one dependency and keep the rest real. (worker-embedded must be on the test classpath, as it is in any embedded application with handlers.)

@EventConductorTest(properties = {...}) adds Spring properties on top of the kit’s. Useful ones:

PropertyWhy
workflow.retry.backoff-jitter=0.0Exact retry moments, for tests that assert them
workflow.cron-enabled=falseNo cron starts at all in this test context
workflow.processes.purge.*Exercise retention under advanceTime

The test worker and the test kit answer the same question — what does this workflow do when a task fails, hangs or answers late? — at different levels.

workflow-test (this page)Test worker
Where it runsInside a JUnit test, in memoryA deployed service, against a real orchestrator, broker and database
How scenarios are statedJava mocks per testA TEST_CONFIG JSON variable on the process
TimeA test clock: days pass in millisecondsReal time: durationMs waits really
What it testsYour definitions’ logic: branches, timeouts, retries, compensation, repliesThe whole deployment: transport, persistence, recovery, the UI
HTTP / LLM callsStubbed, never leave the testReal calls through the built-in workers
AssertionsAssertJ, on the processYou look at the process (UI, API, MCP)

Use the kit in your build, for every definition; use the test worker to demonstrate and check a running deployment.