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.

Camunda Spring Boot 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 static 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.

Camunda Spring Boot 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 static 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.

Camunda Spring Boot SDK

@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
    }
}

Java client

@CamundaProcessTest
public class MyProcessTest {

    // to be injected
    private CamundaClient client;
    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.

Camunda Spring Boot SDK

@WireMockTest(httpPort = 9999)
@SpringBootTest(
    properties = {
        "io.camunda.process.test.connectors-enabled=true",
        "io.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")));
    }
}

Java client

@WireMockTest(httpPort = 9999)
public class MyProcessTest {

    @RegisterExtension
    private static final CamundaProcessTestExtension EXTENSION =
        new CamundaProcessTestExtension()
            .withConnectorsEnabled(true)
            .withConnectorsSecret("BASE_URL", "http://host.testcontainers.internal:9999");

    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 using Connectors secrets to replace it in your process tests, for example, URL = "{{secrets.BASE_URL}}" + "/test".

Custom connectors

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

Camunda Spring Boot 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 static final CamundaProcessTestExtension EXTENSION =
        new CamundaProcessTestExtension()
            .withConnectorsEnabled(true)
            .withConnectorsDockerImageName("my-org/my-connectors")
            .withConnectorsDockerImageVersion("1.0.0");
}