Skip to content

How to test workflow engine changes manually

Jump to bottom
Ana edited this page Dec 20, 2023 · 18 revisions

If you implement an enhancement for the workflow engine or fix a bug then it is recommended to test the changes manually.

This guide shows you how to build the Zeebe distribution and how to test the changes locally by using either Operate/Tasklist or Zeebe-Play.

Step-by-step guide

Build Zeebe

  • Build Zeebe
    • Run the following Maven command in the project root directory
mvn clean install -DskipTests -DskipChecks
  • Build a Docker image
    • Run the following Docker build command in the project root directory
    • Use a custom image tag to identify the image (e.g. 8.1.0-issue-9185)
docker build --build-arg DISTBALL='dist/target/camunda-zeebe*.tar.gz' -t camunda/zeebe:8.1.0-issue-9185 --target app .

Test with the Camuda Platform

  • Check out the camunda-platform project
  • Change the version of the Zeebe image to the custom image tag that was used for the Docker image
    • Change the Zeebe docker image version in the docker-compose file manually (e.g. camunda/zeebe:8.1.0-issue-9185)
  • Start Docker containers
    • Run the following docker-compose command in the project root directory
    • (Optionally) Enable the profile kibana --profile kibana to include Kibana for inspecting Elasticsearch.
  • If you are using Colima on Mac then it is better to start Colima with colima start --memory 8 to give it enough resource (particularly if running with --profile kibana)
docker-compose -f docker-compose-core.yaml up -d

Test with Zeebe-Play

⚠️ Note that Zeebe-Play is a community project and not officially supported by Camunda. However, it can be very useful for manual testing.

Using the Zeebe distribution

  • Extract the Zeebe distribution form zeebe/dist/target/ (e.g. camunda-zeebe-8.1.0-SNAPSHOT.tar.gz)
  • Run the following command in the folder of the extracted distribution
    • Change the value of the environment variable ZEEBE_BROKER_EXPORTERS_HAZELCAST_JARPATH to the path of the exporter
export ZEEBE_BROKER_EXPORTERS_HAZELCAST_CLASSNAME=io.zeebe.hazelcast.exporter.HazelcastExporter
export ZEEBE_BROKER_EXPORTERS_HAZELCAST_JARPATH=/home/philipp/zeebe/exporters/zeebe-hazelcast-exporter-1.2.1-jar-with-dependencies.jar
export ZEEBE_CLOCK_CONTROLLED=true
./bin/broker

Using the StandaloneBroker

  • Run the Java class io.camunda.zeebe.broker.StandaloneBroker in the Zeebe module dist
    • Configure the Hazelcast exporter, for example, by setting the following environment variables (in IntelliJ IDEA Run/Debug Configurations > Build and run > Modify options > Environment variables)
    • Change the value of the environment variable ZEEBE_BROKER_EXPORTERS_HAZELCAST_JARPATH to the path of the exporter
ZEEBE_BROKER_EXPORTERS_HAZELCAST_JARPATH=/home/philipp/zeebe/exporters/zeebe-hazelcast-exporter-1.2.1-jar-with-dependencies.jar;ZEEBE_BROKER_EXPORTERS_HAZELCAST_CLASSNAME=io.zeebe.hazelcast.exporter.HazelcastExporter;ZEEBE_CLOCK_CONTROLLED=true

Start Zeebe-Play

For Linux systems and using the distribution, run the following Docker command:

docker run --network="host" -e ZEEBE_ENGINE=remote ghcr.io/camunda-community-hub/zeebe-play:latest

For other systems or using StandaloneBroker, run the following Docker command:

  • Change the value of <MY_BROKER_IP> to the IP of your broker
  • The IP is printed in the logs when the broker starts the Hazelcast exporter
docker run -p 8080:8080 \
-e ZEEBE_ENGINE=remote \
-e ZEEBE_CLIENT_BROKER_GATEWAYADDRESS=<MY_BROKER_IP>:26500 \
-e ZEEBE_CLOCK_ENDPOINT=<MY_BROKER_IP>:9600/actuator/clock \
-e ZEEBE_CLIENT_WORKER_HAZELCAST_CONNECTION=<MY_BROKER_IP>:5701 \
ghcr.io/camunda-community-hub/zeebe-play:latest

Open Zeebe-Play http://localhost:8080/

Inspect data in Elasticsearch

Zeebe has an official exporter for Elasticsearch (ES). It exports data to ES based on the exporter configuration. The inspection of this data in ES can be useful for manual testing of new or updated ES index templates. The inspection is based on Kibana.

docker-compose --profile kibana -f docker-compose-core.yaml up -d
  • Open the Kibana Web-App http://localhost:5601
  • In Kibana, configure the Data Views (formally index patterns)
    • Go to Management > Stack Management > Kibana > Data Views
    • Create a new Data View for zeebe-record-*
    • If you don't see any indexes then make sure to export some data first (e.g. deploy a process). The indexes of the records are created when the first record of this type is exported.
  • In Kibana, inspect the data
    • Go to Analytics > Discover
    • Select the Data View
    • Now, you should see some data
    • If you don't see any data then you should check the time selector
    • Check also the filter to limit the data

⚠️ Keep in mind to wipe the ES data before updating the ES index patterns of Zeebe (i.e. or before switching to a new Zeebe version).

Troubleshooting

Incompatible version between Zeebe and Operate/Tasklist

It can happen that the default version of Operate/Tasklist is incompatible with your local build Zeebe version.

How to detect? Check the Operate/Tasklist logs (e.g. docker logs operate), for Import is not possible for Zeebe version

2022-07-04 14:58:34.496 ERROR 7 --- [import_2] i.c.o.z.ImportJob : Import is not possible for Zeebe version: 8.1

How to solve? Switch the docker image to a newer Operate release/Tasklist release; or switch to their SNAPSHOT images:

  • camunda/operate:SNAPSHOT
  • camunda/tasklist:SNAPSHOT
Clone this wiki locally