Add support for attachments to the Foundation cross-import overlay.

Package.swift

@@ -96,6 +96,7 @@ let package = Package(
       dependencies: [
         "Testing",
       ],
+      path: "Sources/Overlays/_Testing_Foundation",
       swiftSettings: .packageSettings
     ),
   ],
@@ -124,6 +125,7 @@ extension Array where Element == PackageDescription.SwiftSetting {
     availabilityMacroSettings + [
       .unsafeFlags(["-require-explicit-sendable"]),
       .enableUpcomingFeature("ExistentialAny"),
+      //.enableExperimentalFeature("SuppressedAssociatedTypes"),
 
       .enableExperimentalFeature("AccessLevelOnImport"),
       .enableUpcomingFeature("InternalImportsByDefault"),
@@ -146,6 +148,7 @@ extension Array where Element == PackageDescription.SwiftSetting {
   private static var availabilityMacroSettings: Self {
     [
       .enableExperimentalFeature("AvailabilityMacro=_mangledTypeNameAPI:macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0"),
+      .enableExperimentalFeature("AvailabilityMacro=_uttypesAPI:macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0"),
       .enableExperimentalFeature("AvailabilityMacro=_backtraceAsyncAPI:macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0"),
       .enableExperimentalFeature("AvailabilityMacro=_clockAPI:macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0"),
       .enableExperimentalFeature("AvailabilityMacro=_regexAPI:macOS 13.0, iOS 16.0, tvOS 16.0, watchOS 9.0"),

Sources/Overlays/_Testing_Foundation/Attachments/Data+Test.Attachable.swift

@@ -0,0 +1,21 @@
+//
+// 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
+//
+
+#if canImport(Foundation)
+@_spi(Experimental) public import Testing
+public import Foundation
+
+@_spi(Experimental)
+extension Data: Test.Attachable {
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    try withUnsafeBytes(body)
+  }
+}
+#endif

Sources/Overlays/_Testing_Foundation/Attachments/EncodingFormat.swift

@@ -0,0 +1,84 @@
+//
+// 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
+//
+
+#if canImport(Foundation)
+@_spi(Experimental) import Testing
+import Foundation
+
+#if SWT_TARGET_OS_APPLE && canImport(UniformTypeIdentifiers)
+private import UniformTypeIdentifiers
+#endif
+
+/// An enumeration describing the encoding formats we support for `Encodable`
+/// and `NSSecureCoding` types that conform to `Test.Attachable`.
+enum EncodingFormat {
+  /// A property list format.
+  ///
+  /// - Parameters:
+  ///   - format: The corresponding property list format.
+  case propertyListFormat(_ format: PropertyListSerialization.PropertyListFormat)
+
+  /// The JSON format.
+  case json
+
+  /// The encoding format to use by default.
+  ///
+  /// The specific format this case corresponds to depends on if we are encoding
+  /// an `Encodable` value or an `NSSecureCoding` value.
+  case `default`
+
+  /// Initialize an instance of this type representing the content type or media
+  /// type of the specified attachment.
+  ///
+  /// - Parameters:
+  ///   - attachment: The attachment that will be encoded.
+  ///
+  /// - Throws: If the attachment's content type or media type is unsupported.
+  init(for attachment: borrowing Test.Attachment<some Test.Attachable>) throws {
+    let ext = (attachment.preferredName as NSString).pathExtension
+
+#if SWT_TARGET_OS_APPLE && canImport(UniformTypeIdentifiers)
+    // If the caller explicitly wants to encode their data as either XML or as a
+    // property list, use PropertyListEncoder. Otherwise, we'll fall back to
+    // JSONEncoder below.
+    if #available(_uttypesAPI, *), let contentType = UTType(filenameExtension: ext) {
+      if contentType == .data {
+        self = .default
+      } else if contentType.conforms(to: .json) {
+        self = .json
+      } else if contentType.conforms(to: .xml) {
+        self = .propertyListFormat(.xml)
+      } else if contentType.conforms(to: .binaryPropertyList) || contentType == .propertyList {
+        self = .propertyListFormat(.binary)
+      } else if contentType.conforms(to: .propertyList) {
+        self = .propertyListFormat(.openStep)
+      } else {
+        let contentTypeDescription = contentType.localizedDescription ?? contentType.identifier
+        throw CocoaError(.propertyListWriteInvalid, userInfo: [NSLocalizedDescriptionKey: "The content type '\(contentTypeDescription)' cannot be used to attach an instance of \(type(of: self)) to a test."])
+      }
+      return
+    }
+#endif
+
+    if ext.isEmpty {
+      // No path extension? No problem! Default data.
+      self = .default
+    } else if ext.caseInsensitiveCompare("plist") == .orderedSame {
+      self = .propertyListFormat(.binary)
+    } else if ext.caseInsensitiveCompare("xml") == .orderedSame {
+      self = .propertyListFormat(.xml)
+    } else if ext.caseInsensitiveCompare("json") == .orderedSame {
+      self = .json
+    } else {
+      throw CocoaError(.propertyListWriteInvalid, userInfo: [NSLocalizedDescriptionKey: "The path extension '.\(ext)' cannot be used to attach an instance of \(type(of: self)) to a test."])
+    }
+  }
+}
+#endif

Sources/Overlays/_Testing_Foundation/Attachments/Test.Attachable+Encodable&NSSecureCoding.swift

@@ -0,0 +1,22 @@
+//
+// 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
+//
+
+#if canImport(Foundation)
+@_spi(Experimental) public import Testing
+public import Foundation
+
+@_spi(Experimental)
+extension Test.Attachable where Self: Encodable & NSSecureCoding {
+  @_documentation(visibility: private)
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    try _Testing_Foundation.withUnsafeBufferPointer(encoding: self, for: attachment, body)
+  }
+}
+#endif

Sources/Overlays/_Testing_Foundation/Attachments/Test.Attachable+Encodable.swift

@@ -0,0 +1,97 @@
+//
+// 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
+//
+
+#if canImport(Foundation)
+@_spi(Experimental) public import Testing
+private import Foundation
+
+/// A common implementation of ``withUnsafeBufferPointer(for:_:)`` that is
+/// used when a type conforms to `Encodable`, whether or not it also conforms
+/// to `NSSecureCoding`.
+///
+/// - 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.
+func withUnsafeBufferPointer<E, R>(encoding attachableValue: borrowing E, for attachment: borrowing Test.Attachment<E>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R where E: Test.Attachable & Encodable {
+  let format = try EncodingFormat(for: attachment)
+
+  let data: Data
+  switch format {
+  case let .propertyListFormat(propertyListFormat):
+    let plistEncoder = PropertyListEncoder()
+    plistEncoder.outputFormat = propertyListFormat
+    data = try plistEncoder.encode(attachableValue)
+  case .default:
+    // The default format is JSON.
+    fallthrough
+  case .json:
+    // We cannot use our own JSON encoding wrapper here because that would
+    // require it be exported with (at least) package visibility which would
+    // create a visible external dependency on Foundation in the main testing
+    // library target.
+    data = try JSONEncoder().encode(attachableValue)
+  }
+
+  return try data.withUnsafeBytes(body)
+}
+
+// Implement the protocol requirements generically for any encodable value by
+// encoding to JSON. This lets developers provide trivial conformance to the
+// protocol for types that already support Codable.
+@_spi(Experimental)
+extension Test.Attachable where Self: Encodable {
+  /// Encode this value into a buffer using either [`PropertyListEncoder`](https://developer.apple.com/documentation/foundation/propertylistencoder)
+  /// or [`JSONEncoder`](https://developer.apple.com/documentation/foundation/jsonencoder),
+  /// then call a function and pass that buffer 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 encoding used depends on the path
+  /// extension specified by the value of `attachment`'s ``Testing/Test/Attachment/preferredName``
+  /// property:
+  ///
+  /// | Extension | Encoding Used | Encoder Used |
+  /// |-|-|-|
+  /// | `".xml"` | XML property list | [`PropertyListEncoder`](https://developer.apple.com/documentation/foundation/propertylistencoder) |
+  /// | `".plist"` | Binary property list | [`PropertyListEncoder`](https://developer.apple.com/documentation/foundation/propertylistencoder) |
+  /// | None, `".json"` | JSON | [`JSONEncoder`](https://developer.apple.com/documentation/foundation/jsonencoder) |
+  ///
+  /// OpenStep-style property lists are not supported. If a value conforms to
+  /// _both_ [`Encodable`](https://developer.apple.com/documentation/swift/encodable)
+  /// _and_ [`NSSecureCoding`](https://developer.apple.com/documentation/foundation/nssecurecoding),
+  /// the default implementation of this function uses the value's conformance
+  /// to `Encodable`.
+  ///
+  /// - Note: On Apple platforms, if the attachment's preferred name includes
+  ///   some other path extension, that path extension must represent a type
+  ///   that conforms to [`UTType.propertyList`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/propertylist)
+  ///   or to [`UTType.json`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/json).
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    try _Testing_Foundation.withUnsafeBufferPointer(encoding: self, for: attachment, body)
+  }
+}
+#endif

Sources/Overlays/_Testing_Foundation/Attachments/Test.Attachable+NSSecureCoding.swift

@@ -0,0 +1,78 @@
+//
+// 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
+//
+
+#if canImport(Foundation)
+@_spi(Experimental) public import Testing
+public import Foundation
+
+// As with Encodable, implement the protocol requirements for
+// NSSecureCoding-conformant classes by default. The implementation uses
+// NSKeyedArchiver for encoding.
+@_spi(Experimental)
+extension Test.Attachable where Self: NSSecureCoding {
+  /// Encode this object using [`NSKeyedArchiver`](https://developer.apple.com/documentation/foundation/nskeyedarchiver)
+  /// into a buffer, then call a function and pass that buffer 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 encoding used depends on the path
+  /// extension specified by the value of `attachment`'s ``Testing/Test/Attachment/preferredName``
+  /// property:
+  ///
+  /// | Extension | Encoding Used | Encoder Used |
+  /// |-|-|-|
+  /// | `".xml"` | XML property list | [`NSKeyedArchiver`](https://developer.apple.com/documentation/foundation/nskeyedarchiver) |
+  /// | None, `".plist"` | Binary property list | [`NSKeyedArchiver`](https://developer.apple.com/documentation/foundation/nskeyedarchiver) |
+  ///
+  /// OpenStep-style property lists are not supported. If a value conforms to
+  /// _both_ [`Encodable`](https://developer.apple.com/documentation/swift/encodable)
+  /// _and_ [`NSSecureCoding`](https://developer.apple.com/documentation/foundation/nssecurecoding),
+  /// the default implementation of this function uses the value's conformance
+  /// to `Encodable`.
+  ///
+  /// - Note: On Apple platforms, if the attachment's preferred name includes
+  ///   some other path extension, that path extension must represent a type
+  ///   that conforms to [`UTType.propertyList`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/propertylist).
+  public func withUnsafeBufferPointer<R>(for attachment: borrowing Test.Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
+    let format = try EncodingFormat(for: attachment)
+
+    var data = try NSKeyedArchiver.archivedData(withRootObject: self, requiringSecureCoding: true)
+    switch format {
+    case .default:
+      // The default format is just what NSKeyedArchiver produces.
+      break
+    case let .propertyListFormat(propertyListFormat):
+      // BUG: Foundation does not offer a variant of
+      // NSKeyedArchiver.archivedData(withRootObject:requiringSecureCoding:)
+      // that is Swift-safe (throws errors instead of exceptions) and lets the
+      // caller specify the output format. Work around this issue by decoding
+      // the archive re-encoding it manually.
+      if propertyListFormat != .binary {
+        let plist = try PropertyListSerialization.propertyList(from: data, format: nil)
+        data = try PropertyListSerialization.data(fromPropertyList: plist, format: propertyListFormat, options: 0)
+      }
+    case .json:
+      throw CocoaError(.propertyListWriteInvalid, userInfo: [NSLocalizedDescriptionKey: "An instance of \(type(of: self)) cannot be encoded as JSON. Specify a property list format instead."])
+    }
+
+    return try data.withUnsafeBytes(body)
+  }
+}
+#endif