Skip to main content

Setting up Flowable Inspect testing

2026.1.0+

Introduction​

Model testing lets modelers author tests for their process, case, service, agent and action models in Flowable Design and run them before an app is published. The tests are authored in Flowable Design but executed by Flowable Inspect on a connected Flowable Work runtime.

This page describes the end-to-end configuration needed to enable model testing across Flowable Design and Flowable Work.

How it works​

When a modeler runs a test in Flowable Design:

  1. Design assembles a temporary deployment containing the model under test together with the other models it references, and deploys it to Flowable Work.
  2. Design asks Flowable Inspect on Work to execute the test against that temporary deployment, over a REST call.
  3. Inspect runs the scenario, evaluates the assertions and returns the result, which Design shows in the editor.
  4. Design removes the temporary deployment again.

Because of this flow, Design needs a reachable, authenticated connection to Work, and Work needs Inspect enabled and licensed. No app has to be published for tests to run.

Prerequisites​

  • A license that includes both Flowable Design and Flowable Inspect. Test execution checks for both.
  • A running Flowable Work instance that Flowable Design can reach over HTTP.

Step 1 — Enable Inspect on Flowable Work​

On Flowable Work, enable Flowable Inspect. This activates the Inspect engine and the REST endpoints that Design calls to run tests:

flowable.inspect.enabled=true

To test service, agent and action models, also enable the matching feature on Work (process and case testing need only flowable.inspect.enabled):

flowable.service-registry.enable-service-test=true
flowable.agent.enable-agent-test=true
flowable.action.enable-action-test=true
note

When a service, agent or action is invoked from a form as part of a process or case test, the matching feature above must be enabled as well — otherwise those invocations will not run during test creation.

The maximum time a bulk test run may stay in progress before it is forced to finish can be tuned with flowable.inspect.max-test-run-duration (default PT1H, one hour).

Step 2 — Configure Flowable Design​

On Flowable Design, turn on Inspect-based testing and point Design at the Flowable Work runtime.

# Master switch for model testing in Design.
# Registers the test-execution endpoints and shows the Tests UI.
flowable.design.inspect.enabled=true

# Base URL of the Flowable Work runtime that runs the tests.
flowable.design.remote.idm-url=http://localhost:8090/flowable-work

# Credentials Design uses for the REST calls to Work.
flowable.design.remote.authentication.user=admin
flowable.design.remote.authentication.password=  # must be set

As with process and case testing, enable the extra features for the other model types on the Design side too:

flowable.design.service-registry.enable-service-test=true
flowable.design.agent.enable-agent-test=true
flowable.design.action.enable-action-test=true

A few points worth knowing:

  • The URL that Design uses to reach Inspect is derived from flowable.design.remote.idm-url by appending the Inspect API context path (flowable.design.remote.inspect-api-context-path, default inspect-api/). You normally only set idm-url.
  • The remote calls are authenticated with the flowable.design.remote.authentication settings. With the default type=basic, the password has no default and must be set, otherwise the calls to Work are rejected. Token-based mechanisms (bearer, oauth2, oauth2CurrentUser) are also supported.
  • The Publish Tests action in the app menu is controlled by the flowable.design.frontend.features.testPublish frontend feature flag (default true); set it to false to hide publishing to Inspect while still allowing tests to be run.

For the complete list of properties and their defaults, see the Flowable Design properties and Flowable Work properties references.

Enablement matrix​

For each model type, testing works only when its properties are set on both Design and Work:

Model typeFlowable DesignFlowable Work
Process (BPMN)flowable.design.inspect.enabled=trueflowable.inspect.enabled=true
Case (CMMN)flowable.design.inspect.enabled=trueflowable.inspect.enabled=true
Serviceflowable.design.inspect.enabled=true
flowable.design.service-registry.enable-service-test=true		flowable.inspect.enabled=true
flowable.service-registry.enable-service-test=true
AI Agentflowable.design.inspect.enabled=true
flowable.design.agent.enable-agent-test=true		flowable.inspect.enabled=true
flowable.agent.enable-agent-test=true
Actionflowable.design.inspect.enabled=true
flowable.design.action.enable-action-test=true		flowable.inspect.enabled=true
flowable.action.enable-action-test=true

The deployment target for tests​

The temporary test deployment is published to one of Flowable Design's configured deployment targets (the flowable.design.deployment.<key> entries, the same targets used when publishing apps). By default it uses the default deployment target; to send test deployments to a specific target, set:

flowable.design.inspect.deployment-key=<key>

where <key> matches one of the configured flowable.design.deployment.<key> entries.

Troubleshooting​

  • Design fails to start with a message that flowable.design.remote.idm-url must be set — Design always needs the URL of the Work runtime. Set flowable.design.remote.idm-url.
  • Design fails to start with "Invalid flowable.design.inspect.deployment-key" — the configured deployment key does not match any flowable.design.deployment.<key> target. Use a valid key, or leave it unset to use the default target.
  • Tests fail immediately with an authentication (401) error from Work — the remote credentials are wrong or the password is missing. With the default basic authentication, set flowable.design.remote.authentication.password.
  • The Tests UI does not appear in Design — flowable.design.inspect.enabled is not true, or the license does not include Flowable Inspect.
  • A specific model type cannot be tested — check that its enable-*-test flag is set on both Design and Work (see the enablement matrix).