Add timestamp to Attachment (#305)

davidjgoss · web-flow · commit 843ce7b5af03 · 2025-07-07T13:08:03.000+02:00
Fixes #304. > During test and step executions the execution might produce multiple attachments. For longer steps the exact timing of when the attachments were captured might be important. Currently the Attachment envelop[e] type does not have a timestamp and therefore this information cannot be captured and used. It makes sense to do this now because we already have the signature change for Attachment in #301 which isn't released yet.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 ### Added
 - Add `Attachment.testRunHookStartedId` for traceability of attachments to test run hooks ([#301](https://github.com/cucumber/messages/pull/301))
+- Add `Attachment.timestamp` ([#305](https://github.com/cucumber/messages/pull/305))
 
 ### Fixed
 - [python] Add a LICENSE file for Python ([#278](https://github.com/cucumber/messages/pull/278))
diff --git a/Makefile b/Makefile
@@ -1,7 +1,6 @@
 # The order is significant - ajv needs referenced schemas to be preceded by referencing schemas
 schemas = \
 	./jsonschema/Source.json \
-	./jsonschema/Attachment.json \
 	./jsonschema/Location.json \
 	./jsonschema/Exception.json \
 	./jsonschema/SourceReference.json \
@@ -14,6 +13,7 @@ schemas = \
 	./jsonschema/StepDefinition.json \
 	./jsonschema/TestCase.json \
 	./jsonschema/Timestamp.json \
+	./jsonschema/Attachment.json \
 	./jsonschema/TestCaseFinished.json \
 	./jsonschema/TestCaseStarted.json \
 	./jsonschema/TestRunFinished.json \
diff --git a/cpp/include/messages/cucumber/messages/attachment.hpp b/cpp/include/messages/cucumber/messages/attachment.hpp
@@ -8,6 +8,7 @@
 
 #include <cucumber/messages/attachment_content_encoding.hpp>
 #include <cucumber/messages/source.hpp>
+#include <cucumber/messages/timestamp.hpp>
 
 namespace cucumber::messages {
 
@@ -43,6 +44,7 @@ struct attachment
     std::optional<std::string> url;
     std::optional<std::string> test_run_started_id;
     std::optional<std::string> test_run_hook_started_id;
+    std::optional<cucumber::messages::timestamp> timestamp;
 
     std::string to_string() const;
 
diff --git a/cpp/src/lib/messages/cucumber/messages/attachment.cpp b/cpp/src/lib/messages/cucumber/messages/attachment.cpp
@@ -20,6 +20,7 @@ attachment::to_string() const
     cucumber::messages::to_string(oss, ", url=", url);
     cucumber::messages::to_string(oss, ", test_run_started_id=", test_run_started_id);
     cucumber::messages::to_string(oss, ", test_run_hook_started_id=", test_run_hook_started_id);
+    cucumber::messages::to_string(oss, ", timestamp=", timestamp);
 
     return oss.str();
 }
@@ -37,6 +38,7 @@ attachment::to_json(json& j) const
     cucumber::messages::to_json(j, camelize("url"), url);
     cucumber::messages::to_json(j, camelize("test_run_started_id"), test_run_started_id);
     cucumber::messages::to_json(j, camelize("test_run_hook_started_id"), test_run_hook_started_id);
+    cucumber::messages::to_json(j, camelize("timestamp"), timestamp);
 }
 
 std::string
diff --git a/dotnet/Cucumber.Messages/generated/Attachment.cs b/dotnet/Cucumber.Messages/generated/Attachment.cs
@@ -87,6 +87,10 @@ public sealed class Attachment
      * The identifier of the test run hook execution if the attachment was created during the execution of a test run hook
      */
     public string TestRunHookStartedId { get; private set; }
+    /**
+     * When the attachment was created
+     */
+    public Timestamp Timestamp { get; private set; }
 
 
     public Attachment(
@@ -99,7 +103,8 @@ public Attachment(
         string testStepId,
         string url,
         string testRunStartedId,
-        string testRunHookStartedId
+        string testRunHookStartedId,
+        Timestamp timestamp
     ) 
     {
         RequireNonNull<string>(body, "Body", "Attachment.Body cannot be null");
@@ -115,6 +120,7 @@ string testRunHookStartedId
         this.Url = url;
         this.TestRunStartedId = testRunStartedId;
         this.TestRunHookStartedId = testRunHookStartedId;
+        this.Timestamp = timestamp;
     }
 
     public override bool Equals(Object o) 
@@ -132,7 +138,8 @@ public override bool Equals(Object o)
             Object.Equals(TestStepId, that.TestStepId) &&         
             Object.Equals(Url, that.Url) &&         
             Object.Equals(TestRunStartedId, that.TestRunStartedId) &&         
-            Object.Equals(TestRunHookStartedId, that.TestRunHookStartedId);        
+            Object.Equals(TestRunHookStartedId, that.TestRunHookStartedId) &&         
+            Object.Equals(Timestamp, that.Timestamp);        
     }
 
     public override int GetHashCode() 
@@ -157,6 +164,8 @@ public override int GetHashCode()
           hash = hash * 31 + TestRunStartedId.GetHashCode();
         if (TestRunHookStartedId != null)
           hash = hash * 31 + TestRunHookStartedId.GetHashCode();
+        if (Timestamp != null)
+          hash = hash * 31 + Timestamp.GetHashCode();
         return hash;
     }
 
@@ -173,6 +182,7 @@ public override string ToString()
             ", url=" + Url +
             ", testRunStartedId=" + TestRunStartedId +
             ", testRunHookStartedId=" + TestRunHookStartedId +
+            ", timestamp=" + Timestamp +
             '}';
     }
 
diff --git a/go/messages.go b/go/messages.go
@@ -11,6 +11,7 @@ type Attachment struct {
 	Url                  string                    `json:"url,omitempty"`
 	TestRunStartedId     string                    `json:"testRunStartedId,omitempty"`
 	TestRunHookStartedId string                    `json:"testRunHookStartedId,omitempty"`
+	Timestamp            *Timestamp                `json:"timestamp,omitempty"`
 }
 
 type Duration struct {
diff --git a/java/src/generated/java/io/cucumber/messages/types/Attachment.java b/java/src/generated/java/io/cucumber/messages/types/Attachment.java
@@ -36,6 +36,7 @@ public final class Attachment {
     private final String url;
     private final String testRunStartedId;
     private final String testRunHookStartedId;
+    private final Timestamp timestamp;
 
     public Attachment(
         String body,
@@ -47,7 +48,8 @@ public Attachment(
         String testStepId,
         String url,
         String testRunStartedId,
-        String testRunHookStartedId
+        String testRunHookStartedId,
+        Timestamp timestamp
     ) {
         this.body = requireNonNull(body, "Attachment.body cannot be null");
         this.contentEncoding = requireNonNull(contentEncoding, "Attachment.contentEncoding cannot be null");
@@ -59,6 +61,7 @@ public Attachment(
         this.url = url;
         this.testRunStartedId = testRunStartedId;
         this.testRunHookStartedId = testRunHookStartedId;
+        this.timestamp = timestamp;
     }
 
     /**
@@ -150,6 +153,13 @@ public Optional<String> getTestRunHookStartedId() {
         return Optional.ofNullable(testRunHookStartedId);
     }
 
+    /**
+      * When the attachment was created
+     */
+    public Optional<Timestamp> getTimestamp() {
+        return Optional.ofNullable(timestamp);
+    }
+
     @Override
     public boolean equals(Object o) {
         if (this == o) return true;
@@ -165,7 +175,8 @@ public boolean equals(Object o) {
             Objects.equals(testStepId, that.testStepId) &&         
             Objects.equals(url, that.url) &&         
             Objects.equals(testRunStartedId, that.testRunStartedId) &&         
-            Objects.equals(testRunHookStartedId, that.testRunHookStartedId);        
+            Objects.equals(testRunHookStartedId, that.testRunHookStartedId) &&         
+            Objects.equals(timestamp, that.timestamp);        
     }
 
     @Override
@@ -180,7 +191,8 @@ public int hashCode() {
             testStepId,
             url,
             testRunStartedId,
-            testRunHookStartedId
+            testRunHookStartedId,
+            timestamp
         );
     }
 
@@ -197,6 +209,7 @@ public String toString() {
             ", url=" + url +
             ", testRunStartedId=" + testRunStartedId +
             ", testRunHookStartedId=" + testRunHookStartedId +
+            ", timestamp=" + timestamp +
             '}';
     }
 }
diff --git a/java/src/test/java/io/cucumber/messages/MessagesTest.java b/java/src/test/java/io/cucumber/messages/MessagesTest.java
@@ -10,7 +10,7 @@ public class MessagesTest {
     @Test
     void is_invalid_when_required_fields_are_missing() {
         assertThrows(NullPointerException.class, () -> {
-            new Attachment(null, null, null, null, null, null, null, null, null, null);
+            new Attachment(null, null, null, null, null, null, null, null, null, null, null);
         }, "Attachment.body cannot be null");
     }
 
diff --git a/javascript/src/messages.ts b/javascript/src/messages.ts
@@ -23,6 +23,9 @@ export class Attachment {
   testRunStartedId?: string
 
   testRunHookStartedId?: string
+
+  @Type(() => Timestamp)
+  timestamp?: Timestamp
 }
 
 export class Duration {
diff --git a/jsonschema/Attachment.json b/jsonschema/Attachment.json
@@ -52,6 +52,10 @@
     "testRunHookStartedId": {
       "description": "The identifier of the test run hook execution if the attachment was created during the execution of a test run hook",
       "type": "string"
+    },
+    "timestamp": {
+      "description": "When the attachment was created",
+      "$ref": "./Timestamp.json"
     }
   },
   "type": "object"
diff --git a/messages.md b/messages.md
@@ -17,6 +17,7 @@ will only have one of its fields set, which indicates the payload of the message
 | `url` | string | no | |
 | `testRunStartedId` | string | no | |
 | `testRunHookStartedId` | string | no | |
+| `timestamp` | [Timestamp](#timestamp) | no | |
 
 ## Duration
 
diff --git a/perl/lib/Cucumber/Messages.pm b/perl/lib/Cucumber/Messages.pm
@@ -88,6 +88,7 @@ my %types = (
    url => 'string',
    test_run_started_id => 'string',
    test_run_hook_started_id => 'string',
+   timestamp => 'Cucumber::Messages::Timestamp',
 );
 
 # This is a work-around for the fact that Moo doesn't have introspection
@@ -248,6 +249,16 @@ has test_run_hook_started_id =>
     );
 
 
+=head4 timestamp
+
+When the attachment was created
+=cut
+
+has timestamp =>
+    (is => 'ro',
+    );
+
+
 }
 
 package Cucumber::Messages::Duration {
diff --git a/php/src-generated/Attachment.php b/php/src-generated/Attachment.php
@@ -103,6 +103,11 @@ public function __construct(
          * The identifier of the test run hook execution if the attachment was created during the execution of a test run hook
          */
         public readonly ?string $testRunHookStartedId = null,
+
+        /**
+         * When the attachment was created
+         */
+        public readonly ?Timestamp $timestamp = null,
     ) {
     }
 
@@ -123,6 +128,7 @@ public static function fromArray(array $arr): self
         self::ensureUrl($arr);
         self::ensureTestRunStartedId($arr);
         self::ensureTestRunHookStartedId($arr);
+        self::ensureTimestamp($arr);
 
         return new self(
             (string) $arr['body'],
@@ -135,6 +141,7 @@ public static function fromArray(array $arr): self
             isset($arr['url']) ? (string) $arr['url'] : null,
             isset($arr['testRunStartedId']) ? (string) $arr['testRunStartedId'] : null,
             isset($arr['testRunHookStartedId']) ? (string) $arr['testRunHookStartedId'] : null,
+            isset($arr['timestamp']) ? Timestamp::fromArray($arr['timestamp']) : null,
         );
     }
 
@@ -246,4 +253,14 @@ private static function ensureTestRunHookStartedId(array $arr): void
             throw new SchemaViolationException('Property \'testRunHookStartedId\' was array');
         }
     }
+
+    /**
+     * @psalm-assert array{timestamp?: array} $arr
+     */
+    private static function ensureTimestamp(array $arr): void
+    {
+        if (array_key_exists('timestamp', $arr) && !is_array($arr['timestamp'])) {
+            throw new SchemaViolationException('Property \'timestamp\' was not array');
+        }
+    }
 }
diff --git a/python/src/cucumber_messages/_messages.py b/python/src/cucumber_messages/_messages.py
@@ -65,6 +65,7 @@ class Attachment:
     test_run_hook_started_id: Optional[str] = None  # The identifier of the test run hook execution if the attachment was created during the execution of a test run hook
     test_run_started_id: Optional[str] = None  # Not used; implementers should instead populate `testRunHookStartedId` if an attachment was created during the execution of a test run hook
     test_step_id: Optional[str] = None  # The identifier of the test step if the attachment was created during the execution of a test step
+    timestamp: Optional[Timestamp] = None  # When the attachment was created
     url: Optional[str] = None
     """
     *
diff --git a/ruby/lib/cucumber/messages/attachment.rb b/ruby/lib/cucumber/messages/attachment.rb
@@ -95,6 +95,11 @@ class Attachment < Message
       ##
       attr_reader :test_run_hook_started_id
 
+      ##
+      # When the attachment was created
+      ##
+      attr_reader :timestamp
+
       def initialize(
         body: '',
         content_encoding: AttachmentContentEncoding::IDENTITY,
@@ -105,7 +110,8 @@ def initialize(
         test_step_id: nil,
         url: nil,
         test_run_started_id: nil,
-        test_run_hook_started_id: nil
+        test_run_hook_started_id: nil,
+        timestamp: nil
       )
         @body = body
         @content_encoding = content_encoding
@@ -117,6 +123,7 @@ def initialize(
         @url = url
         @test_run_started_id = test_run_started_id
         @test_run_hook_started_id = test_run_hook_started_id
+        @timestamp = timestamp
         super()
       end
 
@@ -140,7 +147,8 @@ def self.from_h(hash)
           test_step_id: hash[:testStepId],
           url: hash[:url],
           test_run_started_id: hash[:testRunStartedId],
-          test_run_hook_started_id: hash[:testRunHookStartedId]
+          test_run_hook_started_id: hash[:testRunHookStartedId],
+          timestamp: Timestamp.from_h(hash[:timestamp])
         )
       end
     end

Original file line number	Diff line number	Diff line change
`@@ -20,6 +20,7 @@ attachment::to_string() const`
`20`	`20`	`cucumber::messages::to_string(oss, ", url=", url);`
`21`	`21`	`cucumber::messages::to_string(oss, ", test_run_started_id=", test_run_started_id);`
`22`	`22`	`cucumber::messages::to_string(oss, ", test_run_hook_started_id=", test_run_hook_started_id);`
	`23`	`+ cucumber::messages::to_string(oss, ", timestamp=", timestamp);`
`23`	`24`
`24`	`25`	`return oss.str();`
`25`	`26`	`}`
`@@ -37,6 +38,7 @@ attachment::to_json(json& j) const`
`37`	`38`	`cucumber::messages::to_json(j, camelize("url"), url);`
`38`	`39`	`cucumber::messages::to_json(j, camelize("test_run_started_id"), test_run_started_id);`
`39`	`40`	`cucumber::messages::to_json(j, camelize("test_run_hook_started_id"), test_run_hook_started_id);`
	`41`	`+ cucumber::messages::to_json(j, camelize("timestamp"), timestamp);`
`40`	`42`	`}`
`41`	`43`
`42`	`44`	`std::string`
Original file line number	Diff line number	Diff line change
`@@ -11,6 +11,7 @@ type Attachment struct {`
`11`	`11`	Url string `json:"url,omitempty"`
`12`	`12`	TestRunStartedId string `json:"testRunStartedId,omitempty"`
`13`	`13`	TestRunHookStartedId string `json:"testRunHookStartedId,omitempty"`
	`14`	+ Timestamp *Timestamp `json:"timestamp,omitempty"`
`14`	`15`	`}`
`15`	`16`
`16`	`17`	`type Duration struct {`
Original file line number	Diff line number	Diff line change
`@@ -10,7 +10,7 @@ public class MessagesTest {`
`10`	`10`	`@Test`
`11`	`11`	`void is_invalid_when_required_fields_are_missing() {`
`12`	`12`	`assertThrows(NullPointerException.class, () -> {`
`13`		`- new Attachment(null, null, null, null, null, null, null, null, null, null);`
	`13`	`+ new Attachment(null, null, null, null, null, null, null, null, null, null, null);`
`14`	`14`	`}, "Attachment.body cannot be null");`
`15`	`15`	`}`
`16`	`16`
Original file line number	Diff line number	Diff line change
`@@ -23,6 +23,9 @@ export class Attachment {`
`23`	`23`	`testRunStartedId?: string`
`24`	`24`
`25`	`25`	`testRunHookStartedId?: string`
	`26`	`+`
	`27`	`+ @Type(() => Timestamp)`
	`28`	`+ timestamp?: Timestamp`
`26`	`29`	`}`
`27`	`30`
`28`	`31`	`export class Duration {`