Skip to content

9f · Automate it

Tests nobody runs protect nothing. This page sets the workshop project up so that every change is checked automatically, and shows each check catching a real mistake.

CheckGoalCatches
Validateeventconductor:validateA definition that does not parse, a dangling reference, a step nothing can ever start, an invalid expression
Testthe tests (mvn verify runs them)A definition that is valid but does the wrong thing: a lost compensation, a wrong failure policy, a broken branch
Check migrationeventconductor:check-migrationA change that would strand the processes already running the previous version
Coverageeventconductor:verifyA branch, a timeout route or a compensation no test ever takes

eventconductor:verify runs validate, check-migration and the coverage floors in one goal, so CI needs one command:

Terminal window
mvn verify -Deventconductor.migration.from=origin/main

The workshop’s pom.xml binds both goals — validate at process-resources, so a broken definition stops the build before any test runs, and verify at verify, after the tests, when the coverage they recorded is there to check:

<plugin>
<groupId>io.mateu.workflow</groupId>
<artifactId>workflow-maven-plugin</artifactId>
<version>${eventconductor.version}</version>
<executions>
<execution>
<goals><goal>validate</goal></goals>
</execution>
<execution>
<id>eventconductor-verify</id>
<goals><goal>verify</goal></goals>
<configuration>
<skipValidation>true</skipValidation> <!-- validate already ran, before the tests -->
<minStepCoverage>90</minStepCoverage>
<minBranchCoverage>75</minBranchCoverage>
</configuration>
</execution>
</executions>
</plugin>

Without -Deventconductor.migration.from the migration check is skipped; without floors, the coverage is reported and nothing more. mvn eventconductor:verify on its own runs the three checks against the last test run — validation included, since the skipValidation above belongs to the bound execution.

A typo in a reference — preconditionStepId: register-bookin in 01-first-booking.ec.yaml:

$ mvn eventconductor:validate
[ERROR] …/workflows/01-first-booking.ec.yaml:
[ERROR] - Step 'done' references unknown precondition step 'register-bookin'.
[INFO] BUILD FAILURE

A compensation that lost its link — remove compensable/compensationStepId from module 3’s rooms:

$ mvn verify
[ERROR] …/workflows/03-rooms-booking-safe.ec.yaml:
[ERROR] - Step 'cancel-room-booking' has no preconditions and is not a START, a WAIT_FOR_MESSAGE
or another step's compensation — nothing would ever start it.
[INFO] BUILD FAILURE

A change of behaviour — onIterationFailure: compensateAll instead of continue in module 3: the engine would cancel the booked rooms on its own instead of asking the guest. Valid, so only a test can catch it:

$ mvn verify
[ERROR] FailurePathsTest.aSoldOutRoomKeepsTheOthersAndAsksTheGuest:35 Expected process … (rooms-booking-safe, businessKey FAIL-1) to be waiting at 'wait-for-guest'.
[ERROR] FailurePathsTest.theGuestKeepingTheRoomsUndoesNothing:75 Expected process … (rooms-booking-safe, businessKey FAIL-3) to be COMPLETED but it is COMPENSATED.
[ERROR] ScenariosTest.scenario:16 [scenario 'a guest who never answers is not cancelled — the front desk follows up' (src/test/scenarios/rooms-booking.yaml)] Expected process … to be COMPLETED but it is COMPENSATED.
…
[ERROR] Tests run: 38, Failures: 10, Errors: 0, Skipped: 0
[INFO] BUILD FAILURE

(What that message tells you: Debugging a failing test.)

A rename that strands running processes — rename module 6’s approve step to manager-approval. The definition is valid and the tests can be updated, but bookings that are waiting for approval right now would have nowhere to go:

$ mvn verify -Deventconductor.migration.from=HEAD
[ERROR] EventConductor verify failed:
[ERROR]
[ERROR] [check-migration] EventConductor migration check HEAD → current: 6 workflow(s), 1 error(s), 0 warning(s).
[ERROR] hotel-booking: ERROR [approve]: step 'approve' (USER_TASK) has no compatible counterpart:
a process waiting in it could not be migrated

check-migration compares two versions of the definitions — -Deventconductor.migration.from takes a git ref, a path, or current — and fails when a step a process can be waiting in has no counterpart. If the rename is deliberate, a mapping file says so (-Deventconductor.migration.mapping=migration.yaml, hotel-booking: { approve: manager-approval }). The goal also runs alone, as mvn eventconductor:check-migration -Dfrom=HEAD. See Migrating running processes.

A path no test takes — every test of the kit records which steps its processes ran and which routes they took; after the tests, target/eventconductor-coverage/ holds the result — coverage.txt to read, coverage.json for the goal:

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%)
rooms-booking-http 13/13 (100.0%) 6/7 (85.7%) 12/13 (92.3%)
rooms-booking-safe 13/13 (100.0%) 6/7 (85.7%) 13/14 (92.9%)
…
TOTAL 74/75 (98.7%) 23/28 (82.1%) 68/74 (91.9%)
Not covered:
hotel-booking
guard wait-for-guest → remind-guest
guard wait-after-reminder → front-desk
compensation book-alternatives → cancel-room
rooms-booking-all-or-none
step done
sequence rooms → done
rooms-booking-http
compensation book-alternatives → cancel-room
rooms-booking-safe
guard wait-for-guest → tell-front-desk

Branches are the routes that are decisions: CHOICE branches, guarded links, timeout routes, compensations and loop-backs. Most of what is left here is deliberate: the "false" guards into remind-guest, front-desk and tell-front-desk are never taken as links — those steps are reached by their onTimeoutStepId route, which the tests do take — and nothing after the alternatives fails, so their compensation never runs. That is why the floor is 75% and not 100%. Delete the scenarios and tests that cancel a booking, and cancel-room and cancel-room-booking join the list; below the floor, eventconductor:verify fails the build:

[ERROR] EventConductor verify failed:
[ERROR]
[ERROR] [coverage] branches coverage is …%, below the minimum of 75.0%

See Workflow coverage.

With everything fixed, all four pass:

$ mvn verify -Deventconductor.migration.from=HEAD
[INFO] EventConductor: 6 definition(s) validated successfully.
[INFO] Tests run: 38, Failures: 0, Errors: 0, Skipped: 0
[INFO] EventConductor migration check HEAD → current: 6 workflow(s), 0 error(s), 0 warning(s).
[INFO] EventConductor workflow coverage: steps 74/75 (98.7%), branches 23/28 (82.1%), edges 68/74 (91.9%)
[INFO] EventConductor verify: every check passed.
[INFO] BUILD SUCCESS

A test case does not have to be Java. src/test/scenarios/ holds scenarios written as data — what to start, how each task and HTTP call answers, what happens next and how it must end — and ScenariosTest runs every one of them as a test of its own:

@EventConductorTest
class ScenariosTest {
@ParameterizedTest(name = "{0}")
@ScenarioSource("src/test/scenarios")
void scenario(Scenario scenario, WorkflowTestRuntime runtime) {
runtime.run(scenario);
}
}

So the person who knows the business — “what if the manager rejects it?” — adds a case to src/test/scenarios/hotel-booking.yaml:

workflow: hotel-booking
variables:
guest: Erin
rooms: [ { number: "101", type: double }, { number: "102", type: double } ]
http:
rooms: { status: 201, body: { id: HB-1 } }
cancel-room: { status: 204 }
scenarios:
- name: a rejected booking books nothing
then:
- completeUserTask: { step: approve, values: { approved: "false" } }
expect:
status: COMPLETED
passedSteps: [rejected]
notPassedSteps: [rooms, notify-guest]
invocations: { rooms: 0 }

The file’s settings are shared by its scenarios, and a scenario adds to them or overrides them. An answer can depend on what the task was sent — the first answer whose when holds is the one given, and ${…} in a completion is filled in from the task’s variables:

steps:
create-room-booking:
- { when: "room.type == 'penthouse'", fail: SOLD_OUT, retryable: false }
- { complete: { roomBookingId: "RB-${room.number}" } }

A failing scenario fails like any test, with its name and file in the message; scenarios count towards the coverage like any test. The whole format: Scenarios as data.

The workshop project ships the GitHub Actions workflow in ci/github-actions-workflows.yml. In a repository of your own it goes in .github/workflows/workflows.yml:

name: Workflows CI
on:
pull_request:
push:
branches: [main]
jobs:
verify:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # check-migration reads the previous version from git
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: 21
cache: maven
- name: Validate, test, check migrations and coverage
run: mvn -B verify -Deventconductor.migration.from="$FROM"
env:
FROM: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || 'HEAD~1' }}
- name: Keep the coverage report
if: always()
uses: actions/upload-artifact@v4
with:
name: workflow-coverage
path: target/eventconductor-coverage/

On a pull request, migrations are checked against the branch it targets; on main, against the previous commit. If what is deployed can lag behind main, tag the deployed commit and pass that tag instead.

Put it together with the Git import of module 10, and a change to a process travels like any code change:

  1. A branch, a pull request. The reviewer reads the definition — and its graph in the IDE — in the diff.
  2. CI runs the four checks, in one mvn verify. Red means it cannot merge.
  3. Merge to main. The branch is protected: Settings → Branches → require the “verify” check to pass.
  4. The repository’s webhook tells the engine, which imports main, records a new version, and starts new bookings on it. Bookings already running keep their version, or are migrated deliberately.

The protected branch plus the pipeline is what keeps a broken definition out of production: the engine only ever imports what main holds, and nothing reaches main without passing validation, the tests, the migration check and the coverage floors.

The kit tests your definitions’ logic, in the build. The test worker is a deployed service that answers tasks according to a scenario in the process’s variables — use it to check a running deployment: transport, persistence, recovery, the console.

workflow-test (this part)Test worker
Where it runsInside a JUnit test, in memoryA deployed service, against a real engine, broker and database
How scenarios are statedJava mocks per test, or scenario filesA TEST_CONFIG JSON variable on the process
TimeA test clock: days pass in millisecondsReal time
What it testsBranches, timeouts, retries, compensationThe whole deployment
HTTP / LLM callsStubbed, never leave the testReal calls through the built-in workers
AssertionsAssertJ, on the processYou look at the process (console, API, MCP)

Use the kit in CI, for every definition; use the test worker in a test environment, after deploying.