Attachments!

This PR introduces a new experimental feature, attachments. With this feature,
you can "attach" values that conform to a new `Test.Attachable` protocol to a
test. With the right command-line incantation (TBD), Swift Testing will
automatically write attachments to disk for you.

> ![NOTE]
> This PR does not teach Xcode or VS Code how to handle attachments produced by
> Swift Testing, nor does it add the necessary command-line arguments to the
> `swift test` command-line tool.

This PR is one of a series that I'll be posting to build out this feature.

As always, keep in mind that symbols marked `@_spi(Experimental)` are subject to
change or removal without notice.

Resolves #714.
Resolves rdar://88648735.

Author: grynspan

Diff for: Documentation/ABI/JSON.md

@@ -193,8 +193,8 @@ sufficient information to display the event in a human-readable format.
 }
 
 <event-kind> ::= "runStarted" | "testStarted" | "testCaseStarted" |
-  "issueRecorded" | "testCaseEnded" | "testEnded" | "testSkipped" |
-  "runEnded" ; additional event kinds may be added in the future
+  "issueRecorded" | "valueAttached" | "testCaseEnded" | "testEnded" |
+  "testSkipped" | "runEnded" ; additional event kinds may be added in the future
 
 <issue> ::= {
   "isKnown": <bool>, ; is this a known issue or not?
@@ -207,7 +207,7 @@ sufficient information to display the event in a human-readable format.
 }
 
 <message-symbol> ::= "default" | "skip" | "pass" | "passWithKnownIssue" |
-  "fail" | "difference" | "warning" | "details"
+  "fail" | "difference" | "warning" | "details" | "attachment"
 ```
 
 <!--

Diff for: Sources/Testing/ABI/EntryPoints/EntryPoint.swift

@@ -275,6 +275,9 @@ public struct __CommandLineArguments_v0: Sendable {
 
   /// The value of the `--repeat-until` argument.
   public var repeatUntil: String?
+
+  /// The value of the `--experimental-attachment-path` argument.
+  public var experimentalAttachmentPath: String?
 }
 
 extension __CommandLineArguments_v0: Codable {
@@ -295,6 +298,7 @@ extension __CommandLineArguments_v0: Codable {
     case skip
     case repetitions
     case repeatUntil
+    case experimentalAttachmentPath
   }
 }
 
@@ -355,6 +359,11 @@ func parseCommandLineArguments(from args: [String]) throws -> __CommandLineArgum
   if let xunitOutputIndex = args.firstIndex(of: "--xunit-output"), !isLastArgument(at: xunitOutputIndex) {
     result.xunitOutput = args[args.index(after: xunitOutputIndex)]
   }
+
+  // Attachment output
+  if let attachmentPathIndex = args.firstIndex(of: "--experimental-attachment-path"), !isLastArgument(at: attachmentPathIndex) {
+    result.experimentalAttachmentPath = args[args.index(after: attachmentPathIndex)]
+  }
 #endif
 
   if args.contains("--list-tests") {
@@ -464,6 +473,14 @@ public func configurationForEntryPoint(from args: __CommandLineArguments_v0) thr
     }
   }
 
+  // Attachment output.
+  if let attachmentPath = args.experimentalAttachmentPath {
+    guard fileExists(atPath: attachmentPath) else {
+      throw _EntryPointError.invalidArgument("--experimental-attachment-path", value: attachmentPath)
+    }
+    configuration.attachmentDirectoryPath = attachmentPath
+  }
+
 #if canImport(Foundation)
   // Event stream output (experimental)
   if let eventStreamOutputPath = args.eventStreamOutputPath {

Diff for: Sources/Testing/ABI/v0/Encoded/ABIv0.EncodedAttachment.swift

@@ -0,0 +1,32 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+//
+
+extension ABIv0 {
+  /// A type implementing the JSON encoding of ``Test/Attachment`` for the ABI
+  /// entry point and event stream output.
+  ///
+  /// This type is not part of the public interface of the testing library. It
+  /// assists in converting values to JSON; clients that consume this JSON are
+  /// expected to write their own decoders.
+  ///
+  /// - Warning: Attachments are not yet part of the JSON schema.
+  struct EncodedAttachment: Sendable {
+    /// The path where the attachment was written.
+    var path: String?
+
+    init(encoding attachment: borrowing Test.Attachment, in eventContext: borrowing Event.Context) {
+      path = attachment.fileSystemPath
+    }
+  }
+}
+
+// MARK: - Codable
+
+extension ABIv0.EncodedAttachment: Codable {}

Diff for: Sources/Testing/ABI/v0/Encoded/ABIv0.EncodedEvent.swift

@@ -27,6 +27,7 @@ extension ABIv0 {
       case testStarted
       case testCaseStarted
       case issueRecorded
+      case valueAttached
       case testCaseEnded
       case testEnded
       case testSkipped
@@ -45,6 +46,14 @@ extension ABIv0 {
     /// ``kind-swift.property`` property is ``Kind-swift.enum/issueRecorded``.
     var issue: EncodedIssue?
 
+    /// The value that was attached, if any.
+    ///
+    /// The value of this property is `nil` unless the value of the
+    /// ``kind-swift.property`` property is ``Kind-swift.enum/valueAttached``.
+    ///
+    /// - Warning: Attachments are not yet part of the JSON schema.
+    var _attachment: EncodedAttachment?
+
     /// Human-readable messages associated with this event that can be presented
     /// to the user.
     var messages: [EncodedMessage]
@@ -71,6 +80,9 @@ extension ABIv0 {
       case let .issueRecorded(recordedIssue):
         kind = .issueRecorded
         issue = EncodedIssue(encoding: recordedIssue, in: eventContext)
+      case let .valueAttached(attachment):
+        kind = .valueAttached
+        _attachment = EncodedAttachment(encoding: attachment, in: eventContext)
       case .testCaseEnded:
         if eventContext.test?.isParameterized == false {
           return nil

Diff for: Sources/Testing/ABI/v0/Encoded/ABIv0.EncodedMessage.swift

@@ -30,6 +30,7 @@ extension ABIv0 {
       case difference
       case warning
       case details
+      case attachment
 
       init(encoding symbol: Event.Symbol) {
         self = switch symbol {
@@ -51,6 +52,8 @@ extension ABIv0 {
           .warning
         case .details:
           .details
+        case .attachment:
+          .attachment
         }
       }
     }

Diff for: Sources/Testing/Attachments/Test.Attachable.swift

@@ -0,0 +1,72 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+//
+
+@_spi(Experimental)
+extension Test {
+  /// A protocol describing a type that can be attached to a test report or
+  /// written to disk when a test is run.
+  ///
+  /// To attach an attachable value to a test report or test run output, use it
+  /// to initialize a new instance of ``Test/Attachment``, then call
+  /// ``Test/Attachment/attach()``. An attachment can only be attached once.
+  ///
+  /// Generally speaking, you should not need to make new types conform to this
+  /// protocol.
+  // TODO: write more about this protocol, how it works, and list conforming
+  // types (including discussion of the Foundation cross-import overlay.)
+  public protocol Attachable: ~Copyable {
+    /// Call a function and pass a buffer representing this instance to it.
+    ///
+    /// - Parameters:
+    ///   - attachment: The attachment that is requesting a buffer (that is, the
+    ///     attachment containing this instance.)
+    ///   - body: A function to call. A temporary buffer containing a data
+    ///     representation of this instance is passed to it.
+    ///
+    /// - Returns: Whatever is returned by `body`.
+    ///
+    /// - Throws: Whatever is thrown by `body`, or any error that prevented the
+    ///   creation of the buffer.
+    ///
+    /// The testing library uses this function when writing an attachment to a
+    /// test report or to a file on disk. The format of the buffer is
+    /// implementation-defined, but should be "idiomatic" for this type: for
+    /// example, if this type represents an image, it would be appropriate for
+    /// the buffer to contain an image in PNG format, JPEG format, etc., but it
+    /// would not be idiomatic for the buffer to contain a textual description
+    /// of the image.
+    borrowing func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R
+  }
+}
+
+// MARK: - Default implementations
+
+// Implement the protocol requirements for byte arrays and buffers so that
+// developers can attach raw data when needed.
+@_spi(Experimental)
+extension [UInt8]: Test.Attachable {
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    try withUnsafeBytes(body)
+  }
+}
+
+@_spi(Experimental)
+extension UnsafeBufferPointer<UInt8>: Test.Attachable {
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    try body(.init(self))
+  }
+}
+
+@_spi(Experimental)
+extension UnsafeRawBufferPointer: Test.Attachable {
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    try body(self)
+  }
+}