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.

Enable Connectors

By default, the Connectors are disabled. You need to change the runtime configuration to enable them.

Spring SDK

Set the following property in your application.yml (or application.properties):

io:
  camunda:
    process:
      test:
        connectors-enabled: true

Or, set the property directly on your test class:

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

Java client

Register the JUnit extension in your test class with enabled Connectors:

// No annotation: @CamundaProcessTest
public class MyProcessTest {

    @RegisterExtension
    private final CamundaProcessTestExtension extension =
            new CamundaProcessTestExtension().withConnectorsEnabled(true);
}

Connector secrets

If you use Connectors secrets in your processes, you can define them in the test runtime.

Spring SDK

Add your secrets under the following property in your application.yml (or application.properties):

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

Or, set the property directly on your test class:

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

Java client

Add your secrets when you register the JUnit extension:

// No annotation: @CamundaProcessTest
public class MyProcessTest {

    @RegisterExtension
    private final CamundaProcessTestExtension extension =
            new CamundaProcessTestExtension()
                    .withConnectorsEnabled(true)
                    .withConnectorsSecret("GITHUB_TOKEN", "ghp_secret")
                    .withConnectorsSecret("SLACK_TOKEN", "xoxb-secret");
}

Invoke an inbound Connector

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

Spring SDK

@SpringBootTest
@CamundaSpringProcessTest
public class MyProcessTest {

    @Autowired private ZeebeClient 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
    }
}

Java client

@CamundaProcessTest
public class MyProcessTest {

    // to be injected
    private ZeebeClient client;
    private CamundaProcessTestContext processTestContext;

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

        // when
        final String connectorInboundAddress =
                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.

Custom Connectors

To use a custom Connectors bundle, replace the Connectors in the test runtime.

Spring SDK

Set the Docker image name and version of your custom Connector bundle under the following properties in your application.yml (or application.properties):

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

Java client

Set the Docker image name and version of your custom Connector bundle when you register the JUnit extension:

// No annotation: @CamundaProcessTest
public class MyProcessTest {

    @RegisterExtension
    private final CamundaProcessTestExtension extension =
            new CamundaProcessTestExtension()
                    .withConnectorsEnabled(true)
                    .withConnectorsDockerImageName("my-org/my-connectors")
                    .withConnectorsDockerImageVersion("1.0.0");
}