For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10

Connectors

You can run your process test with Connectors to verify the integration with external systems or the configuration of the connector tasks in your processes.

For more unit-focused tests, mock the interaction; for example, by completing connector jobs with an expected result.

note

The instructions on this page are based on the default Testcontainer runtime. If you are using a remote runtime, consult the relevant distribution documentation, such as Camunda 8 Run.

Enable connectors​

By default, the connectors are disabled. You need to change the configuration in the following way.

In your application.yml (or application.properties):

camunda:
  process-test:
    # Enable connectors
    connectors-enabled: true

Or, directly on your test class:

@SpringBootTest(properties = {"camunda.process-test.connectors-enabled=true"})
@CamundaSpringProcessTest
public class MyProcessTest {
    //
}

Set cluster secrets​

Cluster secrets are the default way to provide secrets in tests with Camunda 8.10+. They let processes that reference =camunda.secrets.<NAME> resolve in your tests. This feature requires Camunda Process Test 8.10.6+.

To learn more, see secrets and secret resolution.

In your application.yml (or application.properties):

camunda:
  process-test:
    connectors-enabled: true
    cluster-secrets:
      GITHUB_TOKEN: ghp_secret
      SLACK_TOKEN: xoxb-secret

Or, on your test class:

@SpringBootTest(
    properties = {
        "camunda.process-test.connectors-enabled=true",
        "camunda.process-test.cluster-secrets.GITHUB_TOKEN=ghp_secret",
        "camunda.process-test.cluster-secrets.SLACK_TOKEN=xoxb-secret"
    }
)
@CamundaSpringProcessTest
public class MyProcessTest {
    //
}

CPT drops trailing newlines from cluster secret values. For details, see the cluster secrets configuration.

In a remote runtime, for example a real cluster or Camunda 8 Run, the cluster owns its secret store. CPT ignores the test properties and logs a warning. Configure the secrets on the cluster instead.

If your process still uses the legacy {{secrets.X}} syntax, see Connector secrets. To move to cluster secrets, see migrate secrets.

Connector secrets​

If your processes use connector secrets with the legacy {{secrets.X}} syntax, you can add the secrets to the test runtime in the following way. These properties don't populate the cluster secret store. For =camunda.secrets.X references, use cluster secrets.

In your application.yml (or application.properties):

camunda:
  process-test:
    connectors-enabled: true
    connectors-secrets:
      GITHUB_TOKEN: ghp_secret
      SLACK_TOKEN: xoxb-secret

Or, on your test class:

@SpringBootTest(
    properties = {
        "camunda.process-test.connectors-enabled=true",
        "camunda.process-test.connectors-secrets.GITHUB_TOKEN=ghp_secret",
        "camunda.process-test.connectors-secrets.SLACK_TOKEN=xoxb-secret"
    }
)
@CamundaSpringProcessTest
public class MyProcessTest {
    //
}

Invoke an inbound connector​

You can retrieve the URL address to invoke an inbound connector in your test from the CamundaProcessTestContext.

@SpringBootTest
@CamundaSpringProcessTest
public class MyProcessTest {

    @Autowired private CamundaClient client;
    @Autowired private CamundaProcessTestContext processTestContext;

    @Test
    void shouldInvokeConnector() {
        // given: a process instance waiting at a connector event

        // when
        final String inboundConnectorAddress =
            processTestContext.getConnectorsAddress() + "/inbound/" + CONNECTOR_ID;
        // invoke the connector address, for example, via HTTP request

        // then: verify that the connector event is completed
    }
}
tip

You might need to wrap the invocation of the connector in a retry loop, for example, by using Awaitility.

There can be a delay between verifying that the connectors event is active and opening the connectors inbound subscription.

Access host ports​

By default, the connectors run inside the Testcontainers environment in isolation and can't access your local machine. However, you can expose host ports to the containers, for example, to invoke a mock HTTP server running on your local machine from an outbound REST connector.

Expose the host ports using TestContainers.exposeHostPorts(port). Inside the container, the local machine is available under the hostname host.testcontainers.internal.

@WireMockTest(httpPort = 9999)
@SpringBootTest(
    properties = {
        "camunda.process-test.connectors-enabled=true",
        "camunda.process-test.connectors-secrets.BASE_URL=http://host.testcontainers.internal:9999"
    })
@CamundaSpringProcessTest
public class MyProcessTest {

    @Autowired private CamundaClient client;

    @BeforeAll
    static void setup() {
        Testcontainers.exposeHostPorts(9999);
    }

    @Test
    void shouldInvokeUrlFromConnector() {
        // given: stub the HTTP server
        stubFor(
            get(urlPathMatching("/test"))
                .willReturn(
                    aResponse()
                        .withHeader("Content-Type", "application/json")
                        .withStatus(200)
                        .withBody("{\"status\":\"okay\"}")));

        // when: a process instance invoked the outbound connector

        // then: verify the HTTP request
        CamundaAssert.assertThat(processInstance)
            .isCompleted()
            .hasVariable("status", "okay");

        verify(getRequestedFor(urlEqualTo("/test")));
    }
}
tip

You can configure the URL of an outbound connector in your BPMN process using Connectors secrets to replace it in the tests, for example, setting the URL expression to "{{secrets.BASE_URL}}" + "/test".

If your process references the URL as a cluster secret, set the URL expression to =camunda.secrets.BASE_URL + "/test" and provide the value with cluster-secrets instead of connectors-secrets.

@SpringBootTest(
    properties = {
        "camunda.process-test.connectors-enabled=true",
        "camunda.process-test.cluster-secrets.BASE_URL=http://host.testcontainers.internal:9999"
    })

Custom connectors​

By default, the runtime uses the built-in connectors bundle in a fixed, published version. This version isn't tied to the Camunda version or the Maven module version. To use another version, set connectors-docker-image-version. You can also use a custom connectors bundle in the following way.

In your application.yml (or application.properties):

camunda:
  process-test:
    connectors-enabled: true
    connectors-docker-image-name: my-org/my-connectors
    connectors-docker-image-version: 1.0.0