Unflake tests with published messages

examples/src/test/java/io/camunda/zeebe/process/test/examples/PullRequestProcessTest.java

@@ -225,12 +225,33 @@ private void waitForBusyState(final Duration duration)
   private PublishMessageResponse sendMessage(
       final String messageName, final String correlationKey, final Map<String, Object> variables)
       throws InterruptedException, TimeoutException {
+
+    /*
+     To avoid flaky tests, we recommend publishing messages without a time to live when using time
+     manipulation in the same test case. Alternatively, you could plan out the timings of your time
+     manipulation and the published message's expiry.
+
+     In these tests, we assume that a timer event has triggered after the {@code increaseTime}
+     method returns. However, this is not guaranteed if a time to live is set because the message
+     could expire. Depending on the time to live, the message can expire due to time manipulation.
+
+     The {@code increaseTime} method will return after waiting for the engine to become idle again.
+     However, message expiry can cause the engine to be busy followed by being idle again. So, the
+     increaseTime method can return before the timer event has triggered when a message expires
+     due to time manipulation. This can be the cause of a flaky test.
+
+     Note that by default, the time to live is set to 1 hour.
+     See {@code ZeebeClientBuilder#defaultTimeToLive}.
+    */
+    final Duration timeToLive = Duration.ZERO;
+
     final PublishMessageResponse response =
         client
             .newPublishMessageCommand()
             .messageName(messageName)
             .correlationKey(correlationKey)
             .variables(variables)
+            .timeToLive(timeToLive)
             .send()
             .join();
     waitForIdleState(Duration.ofSeconds(1));

qa/abstracts/src/main/java/io/camunda/zeebe/process/test/qa/abstracts/assertions/AbstractMessageAssertTest.java

@@ -136,7 +136,12 @@ void testHasNotExpired() throws InterruptedException, TimeoutException {
       // when
       final PublishMessageResponse response =
           Utilities.sendMessage(
-              engine, client, ProcessPackMessageEvent.MESSAGE_NAME, CORRELATION_KEY);
+              engine,
+              client,
+              ProcessPackMessageEvent.MESSAGE_NAME,
+              CORRELATION_KEY,
+              Duration.ofMinutes(1),
+              Collections.emptyMap());
 
       // then
       BpmnAssert.assertThat(response).hasNotExpired();
@@ -273,7 +278,12 @@ void testHasExpiredFailure() throws InterruptedException, TimeoutException {
       // when
       final PublishMessageResponse response =
           Utilities.sendMessage(
-              engine, client, ProcessPackMessageEvent.MESSAGE_NAME, CORRELATION_KEY);
+              engine,
+              client,
+              ProcessPackMessageEvent.MESSAGE_NAME,
+              CORRELATION_KEY,
+              Duration.ofMinutes(1),
+              Collections.emptyMap());
 
       // then
       assertThatThrownBy(() -> BpmnAssert.assertThat(response).hasExpired())

qa/abstracts/src/main/java/io/camunda/zeebe/process/test/qa/abstracts/util/Utilities.java

@@ -36,6 +36,7 @@
 import java.util.concurrent.TimeoutException;
 import java.util.stream.Collectors;
 
+/** This class contains utility methods for our own tests. */
 public class Utilities {
 
   public static DeploymentEvent deployResource(final ZeebeClient client, final String resource) {
@@ -117,16 +118,51 @@ public static void waitForBusyState(final ZeebeTestEngine engine, final Duration
     engine.waitForBusyState(duration);
   }
 
+  /**
+   * Publishes a message with the given name and correlation key. Waits for the engine to be idle
+   * afterward to ensure that the message publication is processed.
+   *
+   * <p>The message is published without a time to live and without variables. If you need to set a
+   * time to live or variables, use {@link #sendMessage(ZeebeTestEngine, ZeebeClient, String,
+   * String, Duration, Map)} instead.
+   *
+   * @param engine the engine to wait for to be idle
+   * @param client the client to use to publish the message
+   * @param messageName the name of the message to publish
+   * @param correlationKey the correlation key of the message to publish
+   * @return the response of the publish message command
+   * @throws InterruptedException if the thread is interrupted while waiting for the engine to be
+   *     idle
+   * @throws TimeoutException if the engine does not become idle within the timeout
+   */
   public static PublishMessageResponse sendMessage(
       final ZeebeTestEngine engine,
       final ZeebeClient client,
       final String messageName,
       final String correlationKey)
       throws InterruptedException, TimeoutException {
     return sendMessage(
-        engine, client, messageName, correlationKey, Duration.ofMinutes(1), Collections.emptyMap());
+        engine, client, messageName, correlationKey, Duration.ZERO, Collections.emptyMap());
   }
 
+  /**
+   * Publishes a message with the given name, correlation key, time to live, and variables. Waits
+   * for the engine to be idle afterward to ensure that the message publication is processed.
+   *
+   * <p>If you do not need to set a time to live or variables, use {@link
+   * #sendMessage(ZeebeTestEngine, ZeebeClient, String, String)} instead.
+   *
+   * @param engine the engine to wait for to be idle
+   * @param client the client to use to publish the message
+   * @param messageName the name of the message to publish
+   * @param correlationKey the correlation key of the message to publish
+   * @param timeToLive the time until the message expires after publication
+   * @param variables the variables to pass along as payload of the message to publish
+   * @return the response of the publish message command
+   * @throws InterruptedException if the thread is interrupted while waiting for the engine to be
+   *     idle
+   * @throws TimeoutException if the engine does not become idle within the timeout
+   */
   public static PublishMessageResponse sendMessage(
       final ZeebeTestEngine engine,
       final ZeebeClient client,