Make Test.Attachment generic. (#814)

This PR makes `Test.Attachment` generic over its attachable value type.
It gains conditional conformance to `Copyable` and `Sendable` depending
on the attachable value and if you call `attach()` on a move-only or
non-sendable attachment, will eagerly serialize the attachable value at
that point (rather than during initialization.)

There are a few benefits here:

1. Callers can statically know the type of the attachable value in an
attachment rather than needing to always deal with an existential box;
2. We can add associated types to `Test.Attachable` that will be readily
accessible in `withUnsafeBufferPointer(for:_:)` again without needing an
existential; and
3. When we eventually add support for image attachments, we won't need a
bunch of additional initializers or intermediate box types or
what-have-you; and
4. For Embedded Swift or other environments where existentials are
problematic, we can eagerly serialize all attachments and pass a
consistent type (~~`Test.Attachment<[UInt8]>`~~
`Test.Attachment<Test.AnyAttachable>`) to the event handler.

There are also some drawbacks:

1. Because conformance to `Copyable` and `Sendable` is conditional, we
lose a bit of flexibility if you have a non-sendable `Test.Attachment`
instance or whatnot;
2. We still need a lazy, type-erased attachment type that can be passed
to the event handler. I played around with `Test.Attachment<Any>` but
that causes as many problems as it solves.

~~We end up with `Test.Attachment<any Test.Attachable & Sendable &
Copyable>` but, because that's an existential type that doesn't conform
to itself, the generic parameter `AttachableValue` is not constrained to
`Test.Attachable`. We only provide initializers for types that do
conform though (plus the existential one internally) so in practice it's
not a huge issue.~~

I replaced `any Test.Attachable & Sendable & Copyable` with a dedicated
type-erasing box type, `Test.AnyAttachable`, that wraps the existential.
In Embedded Swift, it wraps a `[UInt8]` instead.

3. There is some code duplication necessary (i.e. multiple
implementations of `attach()` ~~and `write()`~~.)
4. Non-final classes cannot conform to `Test.Attachable`. You can work
around this with a box type that's generic over the class and conforms
to `Test.Attachable`: the `Test.AttachableContainer` protocol now exists
to make this easier.

### Checklist:

- [x] Code and documentation should follow the style of the [Style
Guide](https://github.com/apple/swift-testing/blob/main/Documentation/StyleGuide.md).
- [x] If public symbols are renamed or modified, DocC references should
be updated.

Author: grynspan

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 }
+  }
+}