Skip to content

Testing Module ​

Beta

This module is in beta. The API may change in a future release. Leave feedback if you're using it.

The bpmn-to-code-testing library lets you write architecture tests for your BPMN process models, the same way ArchUnit lets you write architecture tests for Java code.

Add it to your test scope, write a test, and your CI will catch modeling issues before they reach production.

Dependency ​

kotlin
dependencies {
    testImplementation("io.miragon:bpmn-to-code-testing:7.0.1")
}
xml
<dependency>
    <groupId>io.miragon</groupId>
    <artifactId>bpmn-to-code-testing</artifactId>
    <version>7.0.1</version>
    <scope>test</scope>
</dependency>

Basic Usage ​

kotlin
import io.miragon.bpmn.testing.BpmnValidator
import io.miragon.bpmn.domain.shared.ProcessEngine

@Test
fun `BPMN models should have no violations`() {
    BpmnValidator
        .fromClasspath("bpmn/")           // loads all .bpmn files from classpath:bpmn/
        .engine(ProcessEngine.ZEEBE)
        .validate()
        .assertNoViolations()
}

Loading BPMN Files ​

MethodWhat it does
BpmnValidator.fromClasspath("bpmn/")Loads all .bpmn files from the given classpath path
BpmnValidator.fromDirectory(path)Loads all .bpmn files from a filesystem path (java.nio.file.Path)

Selecting Rules ​

By default, validate() runs BpmnRules.all(). You can override the rule set:

kotlin
BpmnValidator
    .fromClasspath("bpmn/")
    .engine(ProcessEngine.CAMUNDA_7)
    .withRules(BpmnRules.MISSING_SERVICE_TASK_IMPLEMENTATION, BpmnRules.MISSING_MESSAGE_NAME)
    .validate()
    .assertNoViolations()

Or pass a list:

kotlin
.withRules(BpmnRules.all().filter { it.severity == Severity.ERROR })

Disabling Rules ​

kotlin
BpmnValidator
    .fromClasspath("bpmn/")
    .engine(ProcessEngine.ZEEBE)
    .disableRules("empty-process")
    .validate()
    .assertNoViolations()

Mandatory rules cannot be disabled, as during generation: listing one logs a warning and keeps it active. They also run when withRules(...) leaves them out.

Treating Warnings as Failures ​

kotlin
BpmnValidator
    .fromClasspath("bpmn/")
    .engine(ProcessEngine.ZEEBE)
    .failOnWarning()
    .validate()
    .assertNoViolations()

Assertions ​

validate() returns a BpmnValidationAssert with AssertJ-style assertions:

AssertionWhat it checks
.assertNoViolations()No violations at all (neither errors nor warnings)
.assertNoViolations("rule-id")No violations for the given rule
.assertHasViolations()At least one violation
.assertViolation("rule-id", elementId, messageContains)Exactly one violation of the rule; elementId and messageContains are optional and narrow the match
.assertViolationCount(n)Exactly n violations in total
.assertNoErrors()No ERROR-severity violations
.assertNoWarnings()No WARN-severity violations
.result()Returns the raw ValidationResult for custom assertions
kotlin
val result = BpmnValidator
    .fromClasspath("bpmn/")
    .engine(ProcessEngine.ZEEBE)
    .validate()

result.assertNoErrors()
result.assertNoViolations("empty-process")

Built-in Rules ​

BpmnRules.all() holds the rules described in the rule table, each as a constant named after its ID (missing-message-name is BpmnRules.MISSING_MESSAGE_NAME). It adds one rule to those of generation and the validate task: UNREFERENCED_ROOT_ELEMENT (WARN), a message, signal, error or escalation that no element references, usually left over from an earlier version of the model.

Optional Rules (opt-in) ​

These rules are not part of BpmnRules.all(). Enable them via withRules(...).

RuleBpmnRules constantSeverityTrigger
Timer cycle is not valid cronTIMER_CRON_SYNTAXERRORA timeCycle timer whose value is not a valid cron expression
Timer value is not valid ISO-8601TIMER_ISO8601_SYNTAXERRORA timer value that is not valid ISO-8601 for its type (Date → date/time, Duration → duration, Cycle → repeating interval)
Call activity target is missingCALL_ACTIVITY_TARGET_EXISTSERRORA call activity references a process that is not among the loaded models (a dangling call activity)
Thrown message has no catcherUNCAUGHT_MESSAGE_THROWWARNA message is thrown (message end / intermediate throw event, send task) but no message start, intermediate catch or boundary event and no receive task catches it among the loaded models
Thrown signal has no subscriberUNCAUGHT_SIGNAL_THROWWARNA signal is thrown (signal end / intermediate throw event) but no catching event subscribes to it among the loaded models
Caught signal is never thrownUNPUBLISHED_SIGNAL_CATCHWARNA signal is caught (signal start / intermediate catch / boundary event) but no throwing event publishes it among the loaded models

The last four compare processes with each other, so they only hold when all related files are loaded together: point fromClasspath / fromDirectory at the folder that holds them. That is why they are opt-in. The three WARN rules are warnings because the counterpart may live outside the loaded files. They run only when no single-model rule reports an ERROR.

kotlin
BpmnValidator
    .fromClasspath("bpmn/")
    .engine(ProcessEngine.ZEEBE)
    .withRules(*BpmnRules.all().toTypedArray(), BpmnRules.TIMER_CRON_SYNTAX)
    .validate()
    .assertNoViolations()

Cron and ISO-8601 are mutually exclusive for timeCycle timers, so enable one of the two depending on your scheduling convention. Dynamic timer expressions (Camunda ${...}, Zeebe FEEL =...) are skipped, since their value is only known at runtime.

Custom Rules ​

For conventions of your own, implement a rule and pass it to withRules(...). See Custom Rules.