Introducing Camunda Process Test—The Next Generation Testing Library

At Camunda, we’re committed to continuously improving the developer experience and ensuring our customers have robust tools to build, test, and deploy processes with confidence. This year, we’re streamlining our architecture, APIs, and testing libraries to help developers build process applications more efficiently.

As part of this commitment, we are excited to announce a significant evolution in our testing libraries: Camunda Process Test, designed specifically for Camunda 8.

Why the change?

Until now, Camunda 8 users have relied on the Zeebe Process Test (ZPT) library to unit test BPMN processes. ZPT served us well, leveraging an in-memory Zeebe engine with gRPC to run tests and verify process behavior.

However, as our platform evolved, ZPT could no longer fully support the latest Camunda 8 features, including our new REST API and user task functionalities. Additionally, as part of our API streamlining strategy, most of our gRPC endpoints will be phased out by version 8.10, making ZPT incompatible moving forward.

To address these challenges and provide our customers with enhanced testing capabilities, we’ve developed a completely new testing library: Camunda Process Test (CPT).

Introducing Camunda Process Test

The Camunda Process Test library is our next-generation testing framework, designed and built for our customers’ evolving needs. CPT offers powerful testing capabilities and fully aligns with the new Camunda 8 REST API, enabling comprehensive testing of BPMN processes, connectors, user tasks, and more.

Here are some highlights of what CPT offers:

• Improved developer experience: By leveraging technologies like TestContainers, CPT ensures faster test execution, simpler environment setup, and smoother integration into modern CI/CD workflows. Also, by using the in-memory H2 database as a secondary storage, the testing library keeps a small memory footprint.
• REST API integration: CPT fully integrates with the Camunda 8 REST API, providing extensive test coverage for the latest features, including Camunda user tasks, connectors, and advanced client commands.
• Enhanced assertions and test coverage: CPT provides a rich set of assertions and generates detailed test coverage reports after each test run. These enable developers to quickly pinpoint testing gaps and verify process behaviour more accurately.
• Automatic wait handling: CPT automatically manages process wait states, eliminating the need for manual waitForIdleState() or waitForBusyState() calls, significantly simplifying your test code.

Deprecation timeline for Zeebe Process Test (ZPT)

With the introduction of CPT in Camunda 8.8, we’re officially deprecating the Zeebe Process Test library. Here’s a clear timeline to help you plan your migration:

Camunda 8.8 (October 2025)

• Introduce CPT as the recommended testing library.
• Mark ZPT as deprecated (available but no longer actively enhanced).
• Provide a comprehensive migration guide and assertion mapping documentation.

Camunda 8.9 (April 2026)

• Transition: Both CPT and ZPT remain available and fully supported, allowing ample time for migration and testing.

Camunda 8.10 (October 2026)

• Fully remove Zeebe Process Test library from repositories and documentation.
• Customers must complete the migration to CPT before upgrading to 8.10.

Migration made simple

We understand that migrating to a new testing framework involves effort. To ensure a smooth transition, we’ll develop detailed resources, including:

• A comprehensive step-by-step migration guide from ZPT to CPT. It will include:
  • Clear mapping of existing ZPT assertions and utilities to their CPT counterparts
  • Practical example code snippets covering common migration scenarios
• Documentation featuring CPT’s new capabilities and best practices

These resources will be available together with the 8.8 release.

The migration involves the following steps:

1. Review existing test cases: Identify ZPT usage and custom assertions within your test suite.
2. Replace ZPT assertions with CPT equivalents: Use our assertion mapping guide for straightforward replacements.
3. Adapt to structural changes: Remove manual wait states and leverage CPT’s built-in automatic handling.
4. Migrate from Zeebe client to Camunda client: The Zeebe client is deprecated in favor of the Camunda client. CPT supports both clients until version 8.10.
5. Transition to TestContainers: Update local development environments and CI pipelines to use TestContainers, enabling consistent and fast test environments.
6. Utilize CPT’s enhanced capabilities: Leverage new test coverage reports, granular task lifecycle assertions, and improved connector testing.

Looking ahead

By transitioning to the Camunda Process Test, you’ll gain a more robust, flexible, and powerful testing framework aligned with the latest Camunda 8 features. While migration requires initial effort, the long-term benefits of improved test coverage, clearer assertions, and enhanced developer productivity are substantial.

We strongly encourage all customers to begin the migration process with the 8.8 release. Our documentation team and support resources will be ready to assist you in making this transition smoothly. Camunda documentation will provide detailed migration instructions and more information.

As always, we welcome your feedback and questions.

Happy testing!