Skip to main content
Version: 8.8 (unreleased)

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 {
    //
}

Connector secrets​

If you use Connectors secrets in your processes, you can add the secrets to the test runtime in the following way.

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".

Custom connectors​

By default, the runtime uses the Camunda connectors bundle in the same version as the Maven module. You can change the version or 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