Part 8: Testing BPMN semantics, DI, and visual output

“Generated XML that parses” is a low bar — an XML file that parses and produces a blank canvas has passed it. The real contract is stronger: every semantic node has a BPMNShape, every flow has a BPMNEdge, every reference resolves, every container contains. This part turns that contract into tests, then verifies the output against the reference implementation of the BPMN spec’s own tooling.

The test matrix

The happy-path test is the hardest to write first

The full example is the best fixture precisely because it’s the hardest thing the pipeline produces — 68 flow elements, 2 processes, 7 message flows, 3 boundary events:

1
@Test
2
fun `procurement collaboration validates clean`() {
3
    val c = enterpriseProcurementCollaboration()
4
    val diags = validator.validate(c)
5
    assertEquals(emptyList(), diags.filter { it.severity == Severity.ERROR },
6
        "unexpected errors: $diags")
7
    assertEquals(emptyList(), diags.filter { it.severity == Severity.WARNING },
8
        "unexpected warnings: $diags")
9
}

Zero warnings is the meaningful assertion — a “passes validation with warnings” gate silently accumulates debt.

The DI-invariant test

The expensive property isn’t that XML parses; it’s that every semantic element has corresponding DI geometry. The test walks the DOM for all ids, then walks the DI section checking every bpmnElement reference:

1
@Test
2
fun `generated xml parses and di references resolve`() {
3
    val c = enterpriseProcurementCollaboration()
4
    val layout = LayeredLayoutEngine().layout(c)
5
    val xml = BpmnXmlWriter(FlowableExtensionSerializer).writeToString(c, layout)
6

7
    val doc = DocumentBuilderFactory.newInstance()
8
        .apply { isNamespaceAware = true }
9
        .newDocumentBuilder()
10
        .parse(InputSource(StringReader(xml)))
11

12
    // collect every semantic id
13
    val ids = mutableSetOf<String>()
14
    val all = doc.getElementsByTagName("*")
15
    for (i in 0 until all.length) {
16
        all.item(i).attributes?.getNamedItem("id")?.nodeValue?.let(ids::add)
17
    }
18

19
    // every DI element references a real semantic element
20
    val shapes = doc.getElementsByTagNameNS(BpmnNs.BPMNDI, "BPMNShape")
21
    val edges  = doc.getElementsByTagNameNS(BpmnNs.BPMNDI, "BPMNEdge")
22
    for (i in 0 until shapes.length + edges.length) {
23
        val el = if (i < shapes.length) shapes.item(i) else edges.item(i - shapes.length)
24
        val ref = el.attributes.getNamedItem("bpmnElement").nodeValue
25
        assertTrue(ref in ids, "BPMN DI element references missing semantic id $ref")
26
    }
27

28
    // every visible node has a shape; every edge endpoint has a route
29
    for (n in c.processes.flatMap { it.allNodes() }) {
30
        assertTrue(n.id in layout.shapes, "no shape for ${n.id}")
31
    }
32
    for (f in c.processes.flatMap { it.allSequenceFlows() } + c.messageFlows.map {
33
        SequenceFlow(it.id, it.name, it.sourceRef, it.targetRef)
34
    }) {
35
        assertTrue(f.id in layout.edges, "no edge for ${f.id}")
36
    }
37
}

The dual direction matters: DI → semantic (every shape’s bpmnElement resolves) and semantic → DI (every node has a shape). Catching only one direction lets a node exist in XML but not in the diagram, or a shape exist for nothing.

Determinism

1
@Test
2
fun `generation is deterministic`() {
3
    val a = BpmnXmlWriter(FlowableExtensionSerializer)
4
        .writeToString(enterpriseProcurementCollaboration(), layout(enterpriseProcurementCollaboration()))
5
    val b = BpmnXmlWriter(FlowableExtensionSerializer)
6
        .writeToString(enterpriseProcurementCollaboration(), layout(enterpriseProcurementCollaboration()))
7
    assertEquals(a, b)
8
}

Byte-identical output from two runs of the same input is a real property — it means a code reviewer’s diff of generated BPMN is a diff of intent, not of iteration order. It’s only true because LinkedHashMap and declaration-order iteration run end to end; one HashMap in the chain and this test fails.

Deliberately breaking things

Testing the validator means writing models that should fail — this is where the negative tests pay for themselves:

1
@Test
2
fun `diagram validation catches a missing shape`() {
3
    val c = enterpriseProcurementCollaboration()
4
    val layout = LayeredLayoutEngine().layout(c)
5
    val broken = layout.copy(shapes = layout.shapes - "sendRfq")   // drop one shape
6
    val diags = validator.validateDiagram(c, broken)
7
    assertTrue(diags.any {
8
        it.code == DiagnosticCodes.DI_MISSING_SHAPE && it.elementId == "sendRfq"
9
    })
10
}

The full suite has the same shape for each rule: build a model with exactly one defect, assert the defect’s code appears and nothing else spuriously fails. Thirteen tests total; the four shown here (clean validation, DI refs resolve, deterministic, DI missing-shape detected) cover the contract’s hardest surfaces.

Rendering verification — not just structure

XML that parses and satisfies DI invariants can still render as garbage. The closing step runs the output through the actual viewer technology:

1
tasks.register<JavaExec>("renderVerify") {
2
    classpath = sourceSets.main.get().runtimeClasspath
3
    mainClass.set("in.o612.eng.bpmn.MainKt")
4
}

and, in Node.js where bpmn-js lives:

1
import { BpmnModdle } from 'bpmn-moddle';
2
import fs from 'node:fs';
3

4
const xml = fs.readFileSync('build/procurement.bpmn', 'utf8');
5
const { rootElement, warnings } = await new BpmnModdle().fromXML(xml);
6
if (warnings?.length) throw new Error(`moddle warnings: ${warnings.length}`);
7
// then load into bpmn-js in a headless browser for an actual SVG render

For this series, the verification I ran:

• bpmn-moddle.fromXML on the generated file: 0 warnings
• bpmn-js NavigatedViewer importXML in headless Chromium (Playwright): 0 warnings, SVG produced
• Screenshot inspection: both pools render, all lanes labeled, all nodes visible, boundary events on their hosts, message flows dashed and crossing the pool gap

That is the honest level of the guarantee: it renders and it’s structurally sound — not pixel-perfect across tools, and Part 10 lists where a real product would push next (ELK for crossing minimization, golden SVG snapshots for layout regression).

Golden-file testing for layout

A layout engine that changes coordinates silently is a regression generator. The cheap defense is a golden test:

1
@Test
2
fun `layout is stable`() {
3
    val layout = LayeredLayoutEngine().layout(enterpriseProcurementCollaboration())
4
    val actual = layout.shapes.entries.sortedBy { it.key }
5
        .joinToString("\n") { (k, b) -> "$k ${b.x},${b.y} ${b.width}x${b.height}" }
6
    val golden = File("src/test/resources/procurement.layout.txt").readText()
7
    assertEquals(golden.trim(), actual)
8
}

Every intentional layout change then requires regenerating the golden file — a reviewed diff, not a silent drift.

Common pitfalls

• Only asserting on parse — a file can parse and still have no DI, wrong refs, or overlapping geometry. Parse + resolve + contain.
• Tests that only exercise the happy path — the validator’s value is finding defects; every diagnostic code deserves a negative test.
• Non-determinism treated as cosmetic — non-deterministic generated files destroy reviewability; test byte-equality.
• Skipping the viewer — structure checks can’t see “the diagram renders with everything overlapping”; import into real viewer tooling at least once.

Reference implementation

The full suite — 19 tests, including every negative case from Part 5 — is BpmnDslTest.kt and GoldenTest.kt, with the golden layout at procurement.layout.txt. The moddle + headless bpmn-js verification is scripts/render-verify.mjs. All in pcnixsys/bpmn-dsl-kotlin.

Next

Part 9 isolates engine specifics: how the flowable: namespace gets into the XML through the EngineExtensionSerializer seam, what process variables actually mean at runtime, and a minimal Spring Boot deployment of the buyer process.