When saving a String as an attachment, assume ".txt" as a path extension. (#1404)

When a string is attached to a test, we encode it as UTF-8 (as is
tradition). This PR adjusts `String`'s conformance to `Attachable` so
that it uses the `".txt"` extension (unless the user specifies something
else). This improves usability in Xcode test reports by making these
attachments double-clickable and QuickLookable (is that a word?)

### 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

Sources/Testing/Attachments/Attachable.swift

@@ -103,17 +103,37 @@ public protocol Attachable: ~Copyable {
 
 // MARK: - Default implementations
 
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+///   @Available(Xcode, introduced: 26.0)
+/// }
 extension Attachable where Self: ~Copyable {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  ///   @Available(Xcode, introduced: 26.0)
+  /// }
   public var estimatedAttachmentByteCount: Int? {
     nil
   }
 
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  ///   @Available(Xcode, introduced: 26.0)
+  /// }
   public borrowing func preferredName(for attachment: borrowing Attachment<Self>, basedOn suggestedName: String) -> String {
     suggestedName
   }
 }
 
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+///   @Available(Xcode, introduced: 26.0)
+/// }
 extension Attachable where Self: Collection, Element == UInt8 {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  ///   @Available(Xcode, introduced: 26.0)
+  /// }
   public var estimatedAttachmentByteCount: Int? {
     count
   }
@@ -125,37 +145,88 @@ extension Attachable where Self: Collection, Element == UInt8 {
   // (potentially expensive!) copy of the collection.
 }
 
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+///   @Available(Xcode, introduced: 26.0)
+/// }
 extension Attachable where Self: StringProtocol {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  ///   @Available(Xcode, introduced: 26.0)
+  /// }
   public var estimatedAttachmentByteCount: Int? {
     // NOTE: utf8.count may be O(n) for foreign strings.
     // SEE: https://github.com/swiftlang/swift/blob/main/stdlib/public/core/StringUTF8View.swift
     utf8.count
   }
+
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  ///   @Available(Xcode, introduced: 26.0)
+  /// }
+  public borrowing func preferredName(for attachment: borrowing Attachment<Self>, basedOn suggestedName: String) -> String {
+    if suggestedName.contains(".") {
+      return suggestedName
+    }
+    return "\(suggestedName).txt"
+  }
 }
 
 // MARK: - Default conformances
 
 // Implement the protocol requirements for byte arrays and buffers so that
 // developers can attach raw data when needed.
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+///   @Available(Xcode, introduced: 26.0)
+/// }
 extension Array<UInt8>: Attachable {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  ///   @Available(Xcode, introduced: 26.0)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     try withUnsafeBytes(body)
   }
 }
 
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+///   @Available(Xcode, introduced: 26.0)
+/// }
 extension ContiguousArray<UInt8>: Attachable {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  ///   @Available(Xcode, introduced: 26.0)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     try withUnsafeBytes(body)
   }
 }
 
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+///   @Available(Xcode, introduced: 26.0)
+/// }
 extension ArraySlice<UInt8>: Attachable {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  ///   @Available(Xcode, introduced: 26.0)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     try withUnsafeBytes(body)
   }
 }
 
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+///   @Available(Xcode, introduced: 26.0)
+/// }
 extension String: Attachable {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  ///   @Available(Xcode, introduced: 26.0)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     var selfCopy = self
     return try selfCopy.withUTF8 { utf8 in
@@ -164,7 +235,15 @@ extension String: Attachable {
   }
 }
 
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+///   @Available(Xcode, introduced: 26.0)
+/// }
 extension Substring: Attachable {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  ///   @Available(Xcode, introduced: 26.0)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     var selfCopy = self
     return try selfCopy.withUTF8 { utf8 in

Tests/TestingTests/AttachmentTests.swift

@@ -62,6 +62,14 @@ struct AttachmentTests {
   }
 #endif
 
+  @Test func preferredNameOfStringAttachment() {
+    let attachment1 = Attachment("", named: "abc123")
+    #expect(attachment1.preferredName == "abc123.txt")
+
+    let attachment2 = Attachment("", named: "abc123.html")
+    #expect(attachment2.preferredName == "abc123.html")
+  }
+
 #if !SWT_NO_FILE_IO
   func compare(_ attachableValue: borrowing MySendableAttachable, toContentsOfFileAtPath filePath: String) throws {
     let file = try FileHandle(forReadingAtPath: filePath)

Tests/TestingTests/Traits/AttachmentSavingTraitTests.swift

@@ -130,27 +130,27 @@ extension `AttachmentSavingTrait tests` {
   @Suite(.hidden, currentAttachmentSavingTrait)
   struct FixtureSuite {
     @Test(.hidden) func `Records an attachment (passing)`() {
-      Attachment.record("", named: "PASSING TEST")
+      Attachment.record([], named: "PASSING TEST")
     }
 
     @Test(.hidden) func `Records an attachment (warning)`() {
-      Attachment.record("", named: "PASSING TEST")
+      Attachment.record([], named: "PASSING TEST")
       Issue.record("", severity: .warning)
     }
 
     @Test(.hidden) func `Records an attachment (failing)`() {
-      Attachment.record("", named: "FAILING TEST")
+      Attachment.record([], named: "FAILING TEST")
       Issue.record("")
     }
 
     @Test(.hidden, arguments: 0 ..< 5)
     func `Records an attachment (passing, parameterized)`(i: Int) async {
-      Attachment.record("\(i)", named: "PASSING TEST")
+      Attachment.record([UInt8(i)], named: "PASSING TEST")
     }
 
     @Test(.hidden, arguments: 0 ..< 7) // intentionally different count
     func `Records an attachment (failing, parameterized)`(i: Int) async {
-      Attachment.record("\(i)", named: "FAILING TEST")
+      Attachment.record([UInt8(i)], named: "FAILING TEST")
       Issue.record("\(i)")
     }
   }