Package org.operaton.bpm.engine.test.junit5

Class ProcessEngineExtension

java.lang.Object
org.operaton.bpm.engine.test.junit5.ProcessEngineExtension
All Implemented Interfaces:
org.junit.jupiter.api.extension.AfterAllCallback, org.junit.jupiter.api.extension.AfterEachCallback, org.junit.jupiter.api.extension.BeforeAllCallback, org.junit.jupiter.api.extension.BeforeEachCallback, org.junit.jupiter.api.extension.Extension, org.junit.jupiter.api.extension.ParameterResolver, org.junit.jupiter.api.extension.TestInstancePostProcessor, org.junit.jupiter.api.extension.TestInstantiationAwareExtension, org.junit.jupiter.api.extension.TestWatcher, ProcessEngineProvider, ProcessEngineServices
Direct Known Subclasses:
CustomProcessEngineExtension
public class ProcessEngineExtension extends Object implements org.junit.jupiter.api.extension.TestWatcher, org.junit.jupiter.api.extension.TestInstancePostProcessor, org.junit.jupiter.api.extension.BeforeEachCallback, org.junit.jupiter.api.extension.AfterEachCallback, org.junit.jupiter.api.extension.BeforeAllCallback, org.junit.jupiter.api.extension.AfterAllCallback, org.junit.jupiter.api.extension.ParameterResolver, ProcessEngineServices, ProcessEngineProvider
JUnit 5 Extension to create and inject a ProcessEngine into test classes.

This extension provides a managed instance of ProcessEngine and its services, which can be automatically injected into test fields. The process engine configuration can be provided through an operaton.cfg.xml file on the classpath or customized using a builder pattern.

Basic Usage:

 @ExtendWith(ProcessEngineExtension.class)
 class YourTest {

   ProcessEngine processEngine;
   RuntimeService runtimeService;
   TaskService taskService;
   // other engine services
   ...
 }

For advanced usage, where specific configurations are required, the extension can be registered manually with a custom configuration file: 

 @RegisterExtension
 ProcessEngineExtension extension = ProcessEngineExtension.builder()
    .configurationResource("customConfiguration.xml")
    .build();

Annotations:

  • Deployment - Deploys a specified deployment before each test and cascades deletion after each test execution.
  • RequiredHistoryLevel - Skips tests if the engine's history level does not meet the required level.

Injected Services:

In addition to ProcessEngine, the extension also injects various BPM services: RepositoryService, RuntimeService, TaskService, HistoryService, IdentityService, ManagementService, FormService, FilterService, AuthorizationService, CaseService, ExternalTaskService, and DecisionService. Each of these services can be injected directly into the test class fields to simplify access within tests.

Builder Pattern:

This extension supports a fluent builder pattern for advanced configuration: 

 ProcessEngineExtension extension = ProcessEngineExtension.builder()
     .configurationResource("myCustomConfig.xml")
     .ensureCleanAfterTest(true)
     .build();
  • configurationResource(String) - Specifies a custom configuration file.
  • ensureCleanAfterTest(boolean) - Ensures a clean database state after each test.
  • useProcessEngine(ProcessEngine) - Reuses an existing process engine instance.
  • manageDeployment(Deployment) - Adds deployments that will be managed and cleaned up after tests.

Setting History Level:

If you need the history service for your tests then you can specify the required history level of the test method or class, using the RequiredHistoryLevel annotation. If the current history level of the process engine is lower than the specified one then the test is skipped.

Test Lifecycle Callbacks:

This extension implements multiple JUnit lifecycle callbacks:

  • TestInstancePostProcessor - Initializes and injects the process engine instance before each test.
  • BeforeEachCallback - Sets up deployment and history level requirements before each test.
  • AfterEachCallback - Cleans up deployments, services, and resets the engine state after each test.
  • AfterAllCallback - Clears service references once all tests in a class have been executed.

Database and Diagnostics:

After each test execution, the extension ensures a clean database state by validating and cleaning the engine's cache and database if configured to do so. This feature is particularly useful for tests that rely on database consistency. The extension also resets the engine’s diagnostic state to maintain a clean testing environment.