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