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.
Four checks, one command
Section titled “Four checks, one command”| Check | Goal | Catches |
|---|---|---|
| Validate | eventconductor:validate | A definition that does not parse, a dangling reference, a step nothing can ever start, an invalid expression |
| Test | the 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 migration | eventconductor:check-migration | A change that would strand the processes already running the previous version |
| Coverage | eventconductor:verify | A 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:
mvn verify -Deventconductor.migration.from=origin/mainThe 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.
Each check, catching something
Section titled “Each check, catching something”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 FAILUREA 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 FAILUREA 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 migratedcheck-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 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%)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-deskBranches 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 SUCCESSCases anyone can add: scenarios
Section titled “Cases anyone can add: scenarios”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:
@EventConductorTestclass 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-bookingvariables: 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 pipeline
Section titled “The pipeline”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.
From a pull request to the engine
Section titled “From a pull request to the engine”Put it together with the Git import of module 10, and a change to a process travels like any code change:
- A branch, a pull request. The reviewer reads the definition — and its graph in the IDE — in the diff.
- CI runs the four checks, in one
mvn verify. Red means it cannot merge. - Merge to
main. The branch is protected: Settings → Branches → require the “verify” check to pass. - 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 or the test worker?
Section titled “The kit or the test worker?”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 runs | Inside a JUnit test, in memory | A deployed service, against a real engine, broker and database |
| How scenarios are stated | Java mocks per test, or scenario files | A TEST_CONFIG JSON variable on the process |
| Time | A test clock: days pass in milliseconds | Real time |
| What it tests | Branches, timeouts, retries, compensation | The whole deployment |
| 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 (console, API, MCP) |
Use the kit in CI, for every definition; use the test worker in a test environment, after deploying.