Make Test.Attachment generic.

Documentation/Proposals/0005-ranged-confirmations.md

@@ -65,7 +65,7 @@ A new overload of `confirmation()` is added:
 ///   - comment: An optional comment to apply to any issues generated by this
 ///     function.
 ///   - expectedCount: A range of integers indicating the number of times the
-///   	expected event should occur when `body` is invoked.
+///     expected event should occur when `body` is invoked.
 ///   - isolation: The actor to which `body` is isolated, if any.
 ///   - sourceLocation: The source location to which any recorded issues should
 ///     be attributed.
@@ -93,7 +93,7 @@ A new overload of `confirmation()` is added:
 /// let minBuns = 5
 /// let maxBuns = 10
 /// await confirmation(
-/// 	"Baked between \(minBuns) and \(maxBuns) buns",
+///   "Baked between \(minBuns) and \(maxBuns) buns",
 ///   expectedCount: minBuns ... maxBuns
 /// ) { bunBaked in
 ///   foodTruck.eventHandler = { event in

Package.swift

@@ -124,6 +124,7 @@ extension Array where Element == PackageDescription.SwiftSetting {
     availabilityMacroSettings + [
       .unsafeFlags(["-require-explicit-sendable"]),
       .enableUpcomingFeature("ExistentialAny"),
+      .enableExperimentalFeature("SuppressedAssociatedTypes"),
 
       .enableExperimentalFeature("AccessLevelOnImport"),
       .enableUpcomingFeature("InternalImportsByDefault"),

Sources/Testing/ABI/v0/Encoded/ABIv0.EncodedAttachment.swift

@@ -21,7 +21,7 @@ extension ABIv0 {
     /// The path where the attachment was written.
     var path: String?
 
-    init(encoding attachment: borrowing Test.Attachment, in eventContext: borrowing Event.Context) {
+    init(encoding attachment: borrowing Test.Attachment<Test.AnyAttachable>, in eventContext: borrowing Event.Context) {
       path = attachment.fileSystemPath
     }
   }

Sources/Testing/Attachments/Test.Attachable.swift

@@ -15,14 +15,18 @@ extension Test {
   ///
   /// 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.
+  /// ``Test/Attachment/attach(sourceLocation:)``. An attachment can only be
+  /// attached once.
   ///
   /// The testing library provides default conformances to this protocol for a
   /// variety of standard library types. Most user-defined types do not need to
   /// conform to this protocol.
   ///
   /// A type should conform to this protocol if it can be represented as a
-  /// sequence of bytes that would be diagnostically useful if a test fails.
+  /// sequence of bytes that would be diagnostically useful if a test fails. If
+  /// a type cannot conform directly to this protocol (such as a non-final class
+  /// or a type declared in a third-party module), you can create a container
+  /// type that conforms to ``Test/AttachableContainer`` to act as a proxy.
   public protocol Attachable: ~Copyable {
     /// An estimate of the number of bytes of memory needed to store this value
     /// as an attachment.
@@ -61,7 +65,7 @@ extension Test {
     /// 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
+    borrowing func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R
   }
 }
 
@@ -103,56 +107,28 @@ extension Test.Attachable where Self: StringProtocol {
 // developers can attach raw data when needed.
 @_spi(Experimental)
 extension Array<UInt8>: Test.Attachable {
-  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     try withUnsafeBytes(body)
   }
 }
 
 @_spi(Experimental)
 extension ContiguousArray<UInt8>: Test.Attachable {
-  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     try withUnsafeBytes(body)
   }
 }
 
 @_spi(Experimental)
 extension ArraySlice<UInt8>: Test.Attachable {
-  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ 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 UnsafeMutableBufferPointer<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)
-  }
-}
-
-@_spi(Experimental)
-extension UnsafeMutableRawBufferPointer: Test.Attachable {
-  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
-    try body(.init(self))
-  }
-}
-
 @_spi(Experimental)
 extension String: Test.Attachable {
-  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     var selfCopy = self
     return try selfCopy.withUTF8 { utf8 in
       try body(UnsafeRawBufferPointer(utf8))
@@ -162,7 +138,7 @@ extension String: Test.Attachable {
 
 @_spi(Experimental)
 extension Substring: Test.Attachable {
-  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     var selfCopy = self
     return try selfCopy.withUTF8 { utf8 in
       try body(UnsafeRawBufferPointer(utf8))

Sources/Testing/Attachments/Test.AttachableContainer.swift

@@ -0,0 +1,37 @@
+//
+// 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 and which contains another value that
+  /// it stands in for.
+  ///
+  /// 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(sourceLocation:)``. An attachment can only be
+  /// attached once.
+  ///
+  /// A type can conform to this protocol if it represents another type that
+  /// cannot directly conform to ``Test/Attachable``, such as a non-final class
+  /// or a type declared in a third-party module.
+  public protocol AttachableContainer<AttachableValue>: Attachable, ~Copyable {
+#if hasFeature(SuppressedAssociatedTypes)
+    /// The type of the attachable value represented by this type.
+    associatedtype AttachableValue: ~Copyable
+#else
+    /// The type of the attachable value represented by this type.
+    associatedtype AttachableValue
+#endif
+
+    /// The attachable value represented by this instance.
+    var attachableValue: AttachableValue { get }
+  }
+}