Package io.zeebe.containers.engine

Interface ContainerEngine.Builder

Enclosing interface:
ContainerEngine
public static interface ContainerEngine.Builder
A helper class to build ContainerEngine instances. A fresh, non-configured builder will always return one which has an idle period of 1 second, and uses a default ZeebeContainer as its gateway and broker.

The builder can wrap either a GenericContainer which implements ZeebeGatewayNode and ZeebeBrokerNode, or a ZeebeCluster, but not both. Setting one will overwrite and nullify any previous assignment to either.

The default idle period is 1 second, and the default grace period is 0.

  • Method Details

    • withContainer

      <T extends org.testcontainers.containers.GenericContainer<T> & ZeebeGatewayNode<T> & ZeebeBrokerNode<T>> ContainerEngine.Builder withContainer(T container)
      Sets the given container to be used as both gateway and broker. Will set any assigned cluster (via withCluster(ZeebeCluster) to null.
      Type Parameters:
      T - the concrete type of the container, e.g. ZeebeContainer
      Parameters:
      container - the container to use as a gateway and broker
      Returns:
      itself for chaining

    • withCluster

      ContainerEngine.Builder withCluster(ZeebeCluster cluster)
      Sets the given cluster to be used as engine(s)/gateway(s).

      When using a cluster, calls to ZeebeTestEngine.increaseTime(Duration) will increase the time on all nodes of the cluster. Additionally, calls to ZeebeTestEngine.getGatewayAddress() will return the address of a random, available gateway, and thus may not always return the same value if there are multiple gateways. Finally, calls to ZeebeTestEngine.createClient() will create a client pointing to a random available gateway. If that gateway shuts down (gracefully or not), the client will not know how to reconnect, and a new client must be obtained.

      Parameters:
      cluster - the cluster to wrap
      Returns:
      itself for chaining

    • withIdlePeriod

      ContainerEngine.Builder withIdlePeriod(Duration idlePeriod)
      Sets the idle period of the engine, used when calling ZeebeTestEngine.waitForIdleState(Duration). In a ContainerEngine, we define the engine to be idle if no records have been exported during the idle period. While this is not extremely accurate (there could be some issue with the engine, after all), it's the best we can do from the outside.

      By default, the idle period is 1 second.

      Parameters:
      idlePeriod - how long no records must have been exported for the engine to be considered idle
      Returns:
      itself for chaining

    • withGracePeriod

      ContainerEngine.Builder withGracePeriod(Duration gracePeriod)
      Sets the grace period to use when reaching the end of the underlying RecordStreamSource.

      When a positive grace period is configured, upon reaching the end of the stream, any assertion will wait for new records until the grace period is expired. If a record is appended to the stream during the grace period, the period is reset.

      What this means concretely is, if you call something like ProcessInstanceAssert.isCompleted() immediately after starting a process instance, it will block and wait up to the grace period for new records to be processed/emitted before returning.

      While not required, setting this can be a useful alternative to calling ZeebeTestEngine.waitForIdleState(Duration).

      NOTE: one of the pitfalls with this method however is that certain assertions, notably those7 which check for the absence of something, will typically block for the complete duration * of the grace period, thus slowing down your tests.

      Parameters:
      gracePeriod - the grace period to use when reaching the end of the record stream
      Returns:
      itself for chaining

    • withAutoAcknowledge

      ContainerEngine.Builder withAutoAcknowledge(boolean acknowledge)
      Sets whether records should be automatically acknowledged as they are exported by the broker. If true, then as soon as a record is received, it will be eligible for deletion in Zeebe. If false, then records must be explicitly acknowledged by the user via ContainerEngine.acknowledge(int, long).

      By default, this is true.

      Parameters:
      acknowledge - whether to automatically acknowledge exported records or not
      Returns:
      itself for chaining

    • withDebugReceiverPort

      ContainerEngine.Builder withDebugReceiverPort(int port)
      Pre-assigns the port to use for the debug receive, i.e. the socket used to receive exported records from the container(s). By default, this is 0, i.e. a random port.
      Parameters:
      port - the port to assign to the receiver
      Returns:
      itself for chaining

    • withDebugReceiver

      ContainerEngine.Builder withDebugReceiver(DebugReceiver receiver)
      The pre-configured DebugReceiver instance to use. Useful if you want to pre-assign ports or have fine-grained control over the acknowledgment process.
      Parameters:
      receiver - the debug receiver to use
      Returns:
      itself for chaining

    • build

      ContainerEngine build()
      Builds a ContainerEngine based on the configuration. If nothing else was called, will build an engine using a default ZeebeContainer, an idle period of 1 second, and a grace period of 0.
      Returns:
      a new, stopped container engine