Test Your Processes With JUnit 5

If you’re a fan of JUnit5 for testing on the JVM, we have good news — there’s a brand-new library available: camunda-bpm-junit5, published as a community extension for Camunda BPM. The project is now available on Maven central, so you can start testing your processes with the latest technology.

Getting started

To add the extension to your project, just add the Maven dependency to your pom file:

<dependency>
  <groupId>org.camunda.bpm.extension</groupId>
  <artifactId>camunda-bpm-junit5</artifactId>
  <version>1.0.0</version>
  <scope>test</scope>
</dependency>

Add the dependencies to JUnit 5 if you don’t already have them (they are included in the spring-boot-starter-test artifact):

<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter</artifactId>
  <version>5.6.2</version>
  <scope>test</scope>
</dependency>

To start testing you can extend your test class with the ProcessEngineExtension:

@ExtendWith(ProcessEngineExtension.class)
public class SimpleTestCase {
  ...
}

This injects the ProcessEngine configured in the camunda.cfg.xml file into your test class and you can use it right away:

public ProcessEngine processEngine;

If you need a more fine-grained setup of the process engine, you can register the extension with a custom configuration file like this:

@RegisterExtension
ProcessEngineExtension extension = ProcessEngineExtension.builder()
  .configurationResource("audithistory.camunda.cfg.xml")
  .build();

Then you can access the process engine from the extension:

RuntimeService runtimeService = extension.getProcessEngine().getRuntimeService();

Why make the jump to JUnit 5?

The goal of this extension is to allow you to use the latest technology for testing. During my journey, I honestly didn’t find any killer features of JUnit 5 that make you need to migrate to JUnit 5 right away.

But it makes a lot of things easier:

• Clearer lifecycle annotation names (@BeforeEach, @BeforeAll, …)
• Improved support for parameterized tests
• Annotate tests with @DisplayName("my name") or @Disabled("for some reason")

Internally, JUnit 5 provides easier support for your own annotations. The internal implementation of the @Deployment annotation, to detect if it is used on a method or a class, became easier than the JUnit 4 support.

With this community extension, there is no reason to use legacy technology for your process tests anymore. It works well together with camunda-bpm-assert, as you can see in this example: https://github.com/camunda/camunda-bpm-junit5/tree/master/examples/camunda-bpm-assert

When you start converting your tests to JUnit 5, just remember that the @Test annotation has a new package and the import changed to:

import org.junit.jupiter.api.Test;

If you have questions or find any issues, please file them in the GitHub repository: https://github.com/camunda/camunda-bpm-junit5/issues. I’m looking forward to any feedback.

Happy testing!

Camunda Developer Community

Join Camunda’s global community of developers sharing code, advice, and meaningful experiences

Get Involved