Merge branch 'main' into jgrynspan/162-redesign-value-capture

Author: grynspan

CODEOWNERS

@@ -8,4 +8,4 @@
 # See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 #
 
-* @stmontgomery @grynspan @briancroom @SeanROlszewski @suzannaratcliff
+* @stmontgomery @grynspan @briancroom @suzannaratcliff

Documentation/ABI/JSON.md

@@ -188,19 +188,24 @@ sufficient information to display the event in a human-readable format.
   "kind": <event-kind>,
   "instant": <instant>, ; when the event occurred
   ["issue": <issue>,] ; the recorded issue (if "kind" is "issueRecorded")
+  ["attachment": <attachment>,] ; the attachment (if kind is "valueAttached")
   "messages": <array:message>,
   ["testID": <test-id>,]
 }
 
 <event-kind> ::= "runStarted" | "testStarted" | "testCaseStarted" |
   "issueRecorded" | "testCaseEnded" | "testEnded" | "testSkipped" |
-  "runEnded" ; additional event kinds may be added in the future
+  "runEnded" | "valueAttached"; additional event kinds may be added in the future
 
 <issue> ::= {
   "isKnown": <bool>, ; is this a known issue or not?
   ["sourceLocation": <source-location>,] ; where the issue occurred, if known
 }
 
+<attachment> ::= {
+  "path": <string>, ; the absolute path to the attachment on disk
+}
+
 <message> ::= {
   "symbol": <message-symbol>,
   "text": <string>, ; the human-readable text of this message

Documentation/ABI/TestContent.md

@@ -100,9 +100,10 @@ record's kind is a 32-bit unsigned value. The following kinds are defined:
 | `0x00000000` | – | Reserved (**do not use**) |
 | `0x74657374` | `'test'` | Test or suite declaration |
 | `0x65786974` | `'exit'` | Exit test |
+| `0x706c6179` | `'play'` | [Playground](https://github.com/apple/swift-play-experimental) |
 
-<!-- When adding cases to this enumeration, be sure to also update the
-corresponding enumeration in TestContentGeneration.swift. -->
+<!-- The kind values listed in this table should be a superset of the cases in
+the `TestContentKind` enumeration. -->
 
 If a test content record's `kind` field equals `0x00000000`, the values of all
 other fields in that record are undefined.
@@ -149,25 +150,12 @@ The fourth argument to this function, `reserved`, is reserved for future use.
 Accessor functions should assume it is `0` and must not access it.
 
 The concrete Swift type of the value written to `outValue`, the type pointed to
-by `type`, and the value pointed to by `hint` depend on the kind of record:
+by `type`, and the value pointed to by `hint` depend on the kind of record.
 
-- For test or suite declarations (kind `0x74657374`), the accessor produces a
-  structure of type `Testing.Test.Generator` that the testing library can use
-  to generate the corresponding test[^notAccessorSignature].
-
-  [^notAccessorSignature]: This level of indirection is necessary because
-    loading a test or suite declaration is an asynchronous operation, but C
-    functions cannot be `async`.
-
-  Test content records of this kind do not specify a type for `hint`. Always
-  pass `nil`.
-
-- For exit test declarations (kind `0x65786974`), the accessor produces a
-  structure describing the exit test (of type `Testing.ExitTest`.)
-
-  Test content records of this kind accept a `hint` of type `Testing.ExitTest.ID`.
-  They only produce a result if they represent an exit test declared with the
-  same ID (or if `hint` is `nil`.)
+The record kinds defined by Swift Testing (kinds `0x74657374` and `0x65786974`)
+make use of the `DiscoverableAsTestContent` protocol in the `_TestDiscovery`
+module and do not publicly expose the types of their accessor functions'
+arguments. Do not call the accessor functions for these records directly.
 
 > [!WARNING]
 > Calling code should use [`withUnsafeTemporaryAllocation(of:capacity:_:)`](https://developer.apple.com/documentation/swift/withunsafetemporaryallocation(of:capacity:_:))
@@ -274,7 +262,8 @@ extension FoodTruckDiagnostic: DiscoverableAsTestContent {
 ```
 
 If you customize `TestContentContext`, be aware that the type you specify must
-have the same stride and alignment as `UInt`.
+have the same stride as `UInt` and must have an alignment less than or equal to
+that of `UInt`.
 
 When you are done configuring your type's protocol conformance, you can then
 enumerate all test content records matching it as instances of

Package.swift

@@ -1,9 +1,9 @@
-// swift-tools-version: 6.0
+// swift-tools-version: 6.1
 
 //
 // This source file is part of the Swift.org open source project
 //
-// Copyright (c) 2023 Apple Inc. and the Swift project authors
+// Copyright (c) 2023–2025 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
@@ -95,8 +95,15 @@ let package = Package(
     return result
   }(),
 
+  traits: [
+    .trait(
+      name: "ExperimentalExitTestValueCapture",
+      description: "Enable experimental support for capturing values in exit tests"
+    ),
+  ],
+
   dependencies: [
-    .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "601.0.0-latest"),
+    .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "602.0.0-latest"),
   ],
 
   targets: [
@@ -171,7 +178,7 @@ let package = Package(
       dependencies: ["_TestingInternals",],
       exclude: ["CMakeLists.txt"],
       cxxSettings: .packageSettings,
-      swiftSettings: .packageSettings
+      swiftSettings: .packageSettings + .enableLibraryEvolution()
     ),
 
     // Cross-import overlays (not supported by Swift Package Manager)
@@ -239,8 +246,9 @@ extension BuildSettingCondition {
       if let nonEmbeddedCondition = nonEmbeddedCondition() {
         nonEmbeddedCondition
       } else {
-        // The caller did not supply a fallback.
-        .when(platforms: [])
+        // The caller did not supply a fallback. Specify a non-existent platform
+        // to ensure this condition never matches.
+        .when(platforms: [.custom("DoesNotExist")])
       }
     } else {
       // Enable unconditionally because the target is Embedded Swift.
@@ -277,6 +285,17 @@ extension Array where Element == PackageDescription.SwiftSetting {
       // proposal via Swift Evolution.
       .enableExperimentalFeature("SymbolLinkageMarkers"),
 
+      // This setting is no longer needed when building with a 6.2 or later
+      // toolchain now that SE-0458 has been accepted and implemented, but it is
+      // needed in order to preserve support for building with 6.1 development
+      // snapshot toolchains. (Production 6.1 toolchains can build the testing
+      // library even without this setting since this experimental feature is
+      // _suppressible_.) This setting can be removed once the minimum supported
+      // toolchain for building the testing library is ≥ 6.2. It is not needed
+      // in the CMake settings since that is expected to build using a
+      // new-enough toolchain.
+      .enableExperimentalFeature("AllowUnsafeAttribute"),
+
       // When building as a package, the macro plugin always builds as an
       // executable rather than a library.
       .define("SWT_NO_LIBRARY_MACRO_PLUGINS"),
@@ -293,6 +312,14 @@ extension Array where Element == PackageDescription.SwiftSetting {
       .define("SWT_NO_LIBDISPATCH", .whenEmbedded()),
     ]
 
+    // Unconditionally enable 'ExperimentalExitTestValueCapture' when building
+    // for development.
+    if buildingForDevelopment {
+      result += [
+        .define("ExperimentalExitTestValueCapture")
+      ]
+    }
+
     return result
   }
 

README.md

@@ -93,15 +93,15 @@ very best ideas, from anywhere, can help shape the future of testing in Swift.
 The table below describes the current level of support that Swift Testing has
 for various platforms:
 
-| **Platform** | **CI Status (6.0)** | **CI Status (main)** | **Support Status** |
+| **Platform** | **CI Status (6.1)** | **CI Status (main)** | **Support Status** |
 |---|:-:|:-:|---|
-| **macOS** | [![Build Status](https://ci.swift.org/buildStatus/icon?job=swift-testing-main-swift-6.0-macos)](https://ci.swift.org/job/swift-testing-main-swift-6.0-macos/) | [![Build Status](https://ci.swift.org/buildStatus/icon?job=swift-testing-main-swift-main-macos)](https://ci.swift.org/view/Swift%20Packages/job/swift-testing-main-swift-main-macos/) | Supported |
+| **macOS** | [![Build Status](https://ci.swift.org/buildStatus/icon?job=swift-testing-main-swift-6.1-macos)](https://ci.swift.org/job/swift-testing-main-swift-6.1-macos/) | [![Build Status](https://ci.swift.org/buildStatus/icon?job=swift-testing-main-swift-main-macos)](https://ci.swift.org/view/Swift%20Packages/job/swift-testing-main-swift-main-macos/) | Supported |
 | **iOS** | | | Supported |
 | **watchOS** | | | Supported |
 | **tvOS** | | | Supported |
 | **visionOS** | | | Supported |
-| **Ubuntu 22.04** | [![Build Status](https://ci.swift.org/buildStatus/icon?job=swift-testing-main-swift-6.0-linux)](https://ci.swift.org/job/swift-testing-main-swift-6.0-linux/) | [![Build Status](https://ci.swift.org/buildStatus/icon?job=swift-testing-main-swift-main-linux)](https://ci.swift.org/view/Swift%20Packages/job/swift-testing-main-swift-main-linux/) | Supported |
-| **Windows** | | [![Build Status](https://ci-external.swift.org/buildStatus/icon?job=swift-testing-main-swift-main-windows)](https://ci-external.swift.org/job/swift-testing-main-swift-main-windows/) | Supported |
+| **Ubuntu 22.04** | [![Build Status](https://ci.swift.org/buildStatus/icon?job=swift-testing-main-swift-6.1-linux)](https://ci.swift.org/job/swift-testing-main-swift-6.1-linux/) | [![Build Status](https://ci.swift.org/buildStatus/icon?job=swift-testing-main-swift-main-linux)](https://ci.swift.org/view/Swift%20Packages/job/swift-testing-main-swift-main-linux/) | Supported |
+| **Windows** | [![Build Status](https://ci.swift.org/buildStatus/icon?job=swift-testing-main-swift-6.1-windows)](https://ci-external.swift.org/view/all/job/swift-testing-main-swift-6.1-windows/) | [![Build Status](https://ci-external.swift.org/buildStatus/icon?job=swift-testing-main-swift-main-windows)](https://ci-external.swift.org/job/swift-testing-main-swift-main-windows/) | Supported |
 | **Wasm** | | | Experimental |
 
 ### Works with XCTest

Sources/Overlays/_Testing_CoreGraphics/Attachments/Attachment+AttachableAsCGImage.swift

@@ -42,9 +42,9 @@ extension Attachment {
     contentType: (any Sendable)?,
     encodingQuality: Float,
     sourceLocation: SourceLocation
-  ) where AttachableValue == _AttachableImageContainer<T> {
-    let imageContainer = _AttachableImageContainer(image: attachableValue, encodingQuality: encodingQuality, contentType: contentType)
-    self.init(imageContainer, named: preferredName, sourceLocation: sourceLocation)
+  ) where AttachableValue == _AttachableImageWrapper<T> {
+    let imageWrapper = _AttachableImageWrapper(image: attachableValue, encodingQuality: encodingQuality, contentType: contentType)
+    self.init(imageWrapper, named: preferredName, sourceLocation: sourceLocation)
   }
 
   /// Initialize an instance of this type that encloses the given image.
@@ -79,7 +79,7 @@ extension Attachment {
     as contentType: UTType?,
     encodingQuality: Float = 1.0,
     sourceLocation: SourceLocation = #_sourceLocation
-  ) where AttachableValue == _AttachableImageContainer<T> {
+  ) where AttachableValue == _AttachableImageWrapper<T> {
     self.init(attachableValue: attachableValue, named: preferredName, contentType: contentType, encodingQuality: encodingQuality, sourceLocation: sourceLocation)
   }
 
@@ -109,7 +109,7 @@ extension Attachment {
     named preferredName: String? = nil,
     encodingQuality: Float = 1.0,
     sourceLocation: SourceLocation = #_sourceLocation
-  ) where AttachableValue == _AttachableImageContainer<T> {
+  ) where AttachableValue == _AttachableImageWrapper<T> {
     self.init(attachableValue: attachableValue, named: preferredName, contentType: nil, encodingQuality: encodingQuality, sourceLocation: sourceLocation)
   }
 }

Sources/Overlays/_Testing_CoreGraphics/Attachments/_AttachableImageContainer.swift renamed to Sources/Overlays/_Testing_CoreGraphics/Attachments/_AttachableImageWrapper.swift

@@ -9,7 +9,7 @@
 //
 
 #if SWT_TARGET_OS_APPLE && canImport(CoreGraphics)
-@_spi(Experimental) public import Testing
+public import Testing
 private import CoreGraphics
 
 private import ImageIO
@@ -48,7 +48,7 @@ import UniformTypeIdentifiers
 ///
 /// - [`CGImage`](https://developer.apple.com/documentation/coregraphics/cgimage)
 @_spi(Experimental)
-public struct _AttachableImageContainer<Image>: Sendable where Image: AttachableAsCGImage {
+public struct _AttachableImageWrapper<Image>: Sendable where Image: AttachableAsCGImage {
   /// The underlying image.
   ///
   /// `CGImage` and `UIImage` are sendable, but `NSImage` is not. `NSImage`
@@ -127,8 +127,8 @@ public struct _AttachableImageContainer<Image>: Sendable where Image: Attachable
 
 // MARK: -
 
-extension _AttachableImageContainer: AttachableContainer {
-  public var attachableValue: Image {
+extension _AttachableImageWrapper: AttachableWrapper {
+  public var wrappedValue: Image {
     image
   }
 

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

@@ -9,7 +9,7 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+public import Testing
 public import Foundation
 
 // This implementation is necessary to let the compiler disambiguate when a type
@@ -18,7 +18,9 @@ public import Foundation
 // (which explicitly document what happens when a type conforms to both
 // protocols.)
 
-@_spi(Experimental)
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+/// }
 extension Attachable where Self: Encodable & NSSecureCoding {
   @_documentation(visibility: private)
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {

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

@@ -9,7 +9,7 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+public import Testing
 private import Foundation
 
 /// A common implementation of ``withUnsafeBytes(for:_:)`` that is used when a
@@ -53,7 +53,10 @@ func withUnsafeBytes<E, R>(encoding attachableValue: borrowing E, for attachment
 // 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)
+
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+/// }
 extension 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),
@@ -86,6 +89,10 @@ extension Attachable where Self: Encodable {
   /// _and_ [`NSSecureCoding`](https://developer.apple.com/documentation/foundation/nssecurecoding),
   /// the default implementation of this function uses the value's conformance
   /// to `Encodable`.
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     try _Testing_Foundation.withUnsafeBytes(encoding: self, for: attachment, body)
   }

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

@@ -9,13 +9,16 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+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)
+
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+/// }
 extension 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.
@@ -46,6 +49,10 @@ extension Attachable where Self: NSSecureCoding {
   /// _and_ [`NSSecureCoding`](https://developer.apple.com/documentation/foundation/nssecurecoding),
   /// the default implementation of this function uses the value's conformance
   /// to `Encodable`.
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     let format = try EncodingFormat(for: attachment)
 

Sources/Overlays/_Testing_Foundation/Attachments/Attachment+URL.swift

@@ -9,7 +9,7 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+public import Testing
 public import Foundation
 
 #if !SWT_NO_PROCESS_SPAWNING && os(Windows)
@@ -32,8 +32,7 @@ extension URL {
   }
 }
 
-@_spi(Experimental)
-extension Attachment where AttachableValue == _AttachableURLContainer {
+extension Attachment where AttachableValue == _AttachableURLWrapper {
 #if SWT_TARGET_OS_APPLE
   /// An operation queue to use for asynchronously reading data from disk.
   private static let _operationQueue = OperationQueue()
@@ -51,6 +50,10 @@ extension Attachment where AttachableValue == _AttachableURLContainer {
   ///     attachment.
   ///
   /// - Throws: Any error that occurs attempting to read from `url`.
+  ///
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  /// }
   public init(
     contentsOf url: URL,
     named preferredName: String? = nil,
@@ -91,8 +94,8 @@ extension Attachment where AttachableValue == _AttachableURLContainer {
     }
 #endif
 
-    let urlContainer = _AttachableURLContainer(url: url, data: data, isCompressedDirectory: isDirectory)
-    self.init(urlContainer, named: preferredName, sourceLocation: sourceLocation)
+    let urlWrapper = _AttachableURLWrapper(url: url, data: data, isCompressedDirectory: isDirectory)
+    self.init(urlWrapper, named: preferredName, sourceLocation: sourceLocation)
   }
 }
 

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

@@ -9,11 +9,16 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) public import Testing
+public import Testing
 public import Foundation
 
-@_spi(Experimental)
+/// @Metadata {
+///   @Available(Swift, introduced: 6.2)
+/// }
 extension Data: Attachable {
+  /// @Metadata {
+  ///   @Available(Swift, introduced: 6.2)
+  /// }
   public func withUnsafeBytes<R>(for attachment: borrowing Attachment<Self>, _ body: (UnsafeRawBufferPointer) throws -> R) throws -> R {
     try withUnsafeBytes(body)
   }

Sources/Overlays/_Testing_Foundation/Attachments/EncodingFormat.swift

@@ -9,7 +9,7 @@
 //
 
 #if canImport(Foundation)
-@_spi(Experimental) import Testing
+import Testing
 import Foundation
 
 /// An enumeration describing the encoding formats we support for `Encodable`