Allow comments created via the test API to have a specific creation time

For some tests, the exact creation time of a comment matters. In the
past, we used workarounds like TestTimeUtil to fix issues with timing
in tests. Tests using the test API can do better, though. As it's an
API specific for tests, we can support the specification of
creation/update times even though we wouldn't do so in public APIs.

We decided to not use Timestamp as type in the API as:
1) It's a mutable type which should not be used in an AutoValue.
2) It's much more inconvenient to specify and less readable/descriptive
than the types of Java 8's date/time API.

Change-Id: Ib026677ce3cfa6ddc248d40e8b429c298c8ccf88

java/com/google/gerrit/acceptance/testsuite/change/PerPatchsetOperationsImpl.java

@@ -186,11 +186,13 @@ public class PerPatchsetOperationsImpl implements PerPatchsetOperations {
       short side = commentCreation.side().orElse(CommentSide.PATCHSET_COMMIT).getNumericSide();
       Boolean unresolved = commentCreation.unresolved().orElse(null);
       String parentUuid = commentCreation.parentUuid().orElse(null);
+      Timestamp createdOn =
+          commentCreation.createdOn().map(Timestamp::from).orElse(context.getWhen());
       HumanComment newComment =
           commentsUtil.newHumanComment(
               context.getNotes(),
               context.getUser(),
-              context.getWhen(),
+              createdOn,
               filePath,
               patchsetId,
               side,

java/com/google/gerrit/acceptance/testsuite/change/TestCommentCreation.java

@@ -21,6 +21,9 @@ import com.google.gerrit.common.Nullable;
 import com.google.gerrit.entities.Account;
 import com.google.gerrit.entities.Comment;
 import com.google.gerrit.entities.Patch;
+import java.time.Instant;
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
 import java.util.Optional;
 
 /**
@@ -49,6 +52,8 @@ public abstract class TestCommentCreation {
 
   public abstract Optional<Account.Id> author();
 
+  public abstract Optional<Instant> createdOn();
+
   abstract Comment.Status status();
 
   abstract ThrowingFunction<TestCommentCreation, String> commentCreator();
@@ -174,6 +179,22 @@ public abstract class TestCommentCreation {
     /** Author of the comment. Must be an existing user account. */
     public abstract Builder author(Account.Id accountId);
 
+    /**
+     * Creation time of the comment. Like {@link #createdOn(Instant)} but with an arbitrary, fixed
+     * time zone (-> deterministic test execution).
+     */
+    public Builder createdOn(LocalDateTime createdOn) {
+      // We don't care about the exact time zone in most tests, just that it's fixed so that tests
+      // are deterministic.
+      return createdOn(createdOn.atZone(ZoneOffset.UTC).toInstant());
+    }
+
+    /**
+     * Creation time of the comment. This may also lie in the past or future. Comments stored in
+     * NoteDb support only second precision.
+     */
+    public abstract Builder createdOn(Instant createdOn);
+
     /**
      * Status of the comment. Hidden in the API surface. Use {@link
      * PerPatchsetOperations#newComment()} or {@link PerPatchsetOperations#newDraftComment()}