Guide / Test and run

Process tests and coverage

Penstock lists every way through a process, writes a JUnit test for each, and shows on the diagram what your tests reach.

Pro Team in a pipeline

Three tools, one idea

A process with two gateways has several ways through it. Each way is a scenario. Penstock finds them all, and then:

• Listing the scenarios gives a test plan you can read. In a terminal it is penstock scenarios list.
• JUnit tests are written for each scenario. In a terminal it is penstock junit.
• Coverage shows which elements your tests reached.

Running the scenarios against an engine, without JUnit, is Scenarios. The older command names paths and tests still work and are left out of the help.

List the ways through

Each scenario shows the decision taken at each gateway and its condition. You can print the list as text, as a Markdown checklist to paste into a test plan, or as JSON for a tool. An AI assistant gets it from the MCP tool list_scenarios.

$ penstock scenarios list .
src/main/resources/order-process.bpmn  2 scenario(s)
   1. Order received → Approve order → Charge card → Decide shipping method → Shipment confirmed → Send receipt → Order completed
   2. Order received → Approve order → Charge card → Card declined → Payment declined
        Card declined fires on Charge card

$ penstock scenarios list . --format md
### 1. Order received → Order completed

- [ ] runs Approve order → Charge card → Decide shipping method → Shipment confirmed → Send receipt

Write the tests

Penstock writes one JUnit class per process, with a test for every way through it. It names the test dependencies your build is missing. Add them, then run the tests with your normal test runner.

Each test starts the process with variables chosen to take that way: a value just past each condition, and at a default flow a value no other condition accepts. It completes the jobs, user tasks and external tasks, correlates messages, moves time past timers, throws errors from jobs where an error boundary is taken, and checks the elements the run passed.

$ penstock junit .
wrote src/test/java/io/penstock/example/process/OrderProcessTest.java  2 scenario(s)

The tests need these test dependencies in pom.xml:
  io.camunda:camunda-process-test-java:8.9.21

2 test(s) in 1 class(es), one per way through each process.

If the guess is wrong, set tests in penstock.yaml: language (java or kotlin), out (the source folder) and package. See penstock.yaml.

Run and debug tests from the diagram

Pro

From an element on the canvas you can run or debug the test methods that name the element or its process, with your project's own test runner. When you debug, the diagram shows where the process stops.

Coverage

Pro

1. Run your process tests with your build. Use Camunda Process Test, or on Camunda 7 the process test coverage extension.
2. A button Coverage appears on the toolbar. Press it.
3. The diagram colours what the tests reached and dims what they did not.
4. The panel lists the tests with how much of the diagram each covers. Pick one to see the way it takes. It also lists the elements no test reaches.
5. Run the tests again. Coverage follows.

Penstock reads the reports under target or build, and follows them as the tests run again.

What you see

• A test class file in your test sources, with one test for each way through the process.
• After a test run, a Coverage button. Pressed, it colours what was reached and dims the rest.

Common problems

There is no Coverage button.

No test report was found yet. Run the process tests first. Reports must be under target or build.

The generated test does not compile.

Add the test dependencies the command printed to your build file.

The tests went to the wrong place.

Set tests.out and tests.package in penstock.yaml.

"To fill in".

A way that the data cannot choose is marked for you to finish. Fill in the variables that take it.

I want to run scenarios against a live engine without JUnit.

Use Scenarios. They need no build setup.