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_CALLandLLM_CALLsteps 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.
Add the dependency
Section titled “Add the dependency”<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;
@EventConductorTestclass 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.
How a test runs
Section titled “How a test runs”@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.
Moving time
Section titled “Moving time”| Call | What 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 % jitterLoops 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.
Mocking tasks
Section titled “Mocking tasks”| Mock | Matches |
|---|---|
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:
| Answer | Effect |
|---|---|
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’sthenComplete()followed by a test’s ownthenFail(…)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 onethenAnswer(…). - 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")) ? … : …); anHTTP_CALLhas 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.
HTTP and LLM calls
Section titled “HTTP and LLM calls”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 secondhotel.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).
Agents
Section titled “Agents”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)).
Messages, events and replies
Section titled “Messages, events and replies”| Call | What 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
Section titled “Updates”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.
| Call | What 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().
Assertions
Section titled “Assertions”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.
| Assertion | Passes 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"} COMPLETEDVariables: {…}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 COMPLETEDforEach iterations
Section titled “forEach iterations”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();| Assertion | Passes 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" ERRORA retried step is one step execution with several attempts, so stepExecutions("charge") has one
element after two retries; count dispatches with runtime.invocationsOf("charge").
Scenarios as data
Section titled “Scenarios as data”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.
workflow: booking-saga # shared by every scenario of the filetasks: 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:
@EventConductorTestclass 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.
| Key | What it says |
|---|---|
name | How the test is called (default: scenario <n>) |
workflow | The definition to start (required) |
businessKey | The process’s business key (default: generated) |
variables | The start variables; non-text values are stored as JSON |
tasks / steps | Task answers by task id or topic (whenTask) / by step id (whenStep) |
http / llm / agents | HTTP_CALL / LLM_CALL / AGENT answers, by step id |
then | What happens after the start, in order |
expect | How 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.
| Kind | Answers |
|---|---|
| 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.
Workflow coverage
Section titled “Workflow coverage”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 edgeshotel-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| Counted | Covered when, in one process … |
|---|---|
| a step | it ran (started, whatever it ended in) |
a choice branch — a link out of a CHOICE | the CHOICE completed and the step ran |
a guard — a link with a condition | its source completed and the step ran |
a timeout route (onTimeoutStepId) | the step and its timeout target ran |
a compensation | the step completed and its compensation ran |
a loopBack | the step completed and its target ran more than once |
a sequence — any other link | its 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.
Running your real task handlers
Section titled “Running your real task handlers”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.)
Properties
Section titled “Properties”@EventConductorTest(properties = {...}) adds Spring properties on top of the kit’s. Useful ones:
| Property | Why |
|---|---|
workflow.retry.backoff-jitter=0.0 | Exact retry moments, for tests that assert them |
workflow.cron-enabled=false | No cron starts at all in this test context |
workflow.processes.purge.* | Exercise retention under advanceTime |
How it differs from the test worker
Section titled “How it differs from the test worker”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 runs | Inside a JUnit test, in memory | A deployed service, against a real orchestrator, broker and database |
| How scenarios are stated | Java mocks per test | A TEST_CONFIG JSON variable on the process |
| Time | A test clock: days pass in milliseconds | Real time: durationMs waits really |
| What it tests | Your definitions’ logic: branches, timeouts, retries, compensation, replies | The whole deployment: transport, persistence, recovery, the UI |
| HTTP / LLM calls | Stubbed, never leave the test | Real calls through the built-in workers |
| Assertions | AssertJ, on the process | You 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.