Merge branch 'swiftlang:main' into feature/advanced-console-output-recorder

Author: tienquocbui

CONTRIBUTING.md

@@ -48,11 +48,10 @@ and install a toolchain.
 
 #### Installing a toolchain
 
-1. Download a toolchain. A recent **6.0 development snapshot** toolchain is
-   required to build the testing library. Visit
-   [swift.org](http://swift.org/install) and download the most recent toolchain
-   from the section titled **release/6.0** under **Development Snapshots** on
-   the page for your platform.
+1. Download a toolchain. A recent **development snapshot** toolchain is required
+   to build the testing library. Visit [swift.org](https://swift.org/install),
+   select your platform, and download the most recent toolchain from the section
+   titled **release/6.x** under **Development Snapshots**.
 
    Be aware that development snapshot toolchains aren't intended for day-to-day
    development and may contain defects that affect the programs built with them.

Package.swift

@@ -90,6 +90,8 @@ let package = Package(
         targets: [
           "_Testing_AppKit",
           "_Testing_CoreGraphics",
+          "_Testing_CoreImage",
+          "_Testing_UIKit",
         ]
       )
     ]
@@ -105,13 +107,6 @@ 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: "602.0.0-latest"),
   ],
@@ -137,7 +132,9 @@ let package = Package(
         "Testing",
         "_Testing_AppKit",
         "_Testing_CoreGraphics",
+        "_Testing_CoreImage",
         "_Testing_Foundation",
+        "_Testing_UIKit",
         "MemorySafeTestingTests",
       ],
       swiftSettings: .packageSettings
@@ -218,6 +215,15 @@ let package = Package(
       path: "Sources/Overlays/_Testing_CoreGraphics",
       swiftSettings: .packageSettings + .enableLibraryEvolution()
     ),
+    .target(
+      name: "_Testing_CoreImage",
+      dependencies: [
+        "Testing",
+        "_Testing_CoreGraphics",
+      ],
+      path: "Sources/Overlays/_Testing_CoreImage",
+      swiftSettings: .packageSettings + .enableLibraryEvolution()
+    ),
     .target(
       name: "_Testing_Foundation",
       dependencies: [
@@ -230,6 +236,16 @@ let package = Package(
       // it can only enable Library Evolution itself on those platforms.
       swiftSettings: .packageSettings + .enableLibraryEvolution(.whenApple())
     ),
+    .target(
+      name: "_Testing_UIKit",
+      dependencies: [
+        "Testing",
+        "_Testing_CoreGraphics",
+        "_Testing_CoreImage",
+      ],
+      path: "Sources/Overlays/_Testing_UIKit",
+      swiftSettings: .packageSettings + .enableLibraryEvolution()
+    ),
 
     // Utility targets: These are utilities intended for use when developing
     // this package, not for distribution.
@@ -360,14 +376,6 @@ 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

@@ -23,6 +23,8 @@ Swift expressions and operators, and captures the evaluated values so you can
 quickly understand what went wrong when a test fails.
 
 ```swift
+import Testing
+
 @Test func helloWorld() {
   let greeting = "Hello, world!"
   #expect(greeting == "Hello") // Expectation failed: (greeting → "Hello, world!") == "Hello"
@@ -84,11 +86,19 @@ func mentionedContinents(videoName: String) async throws {
 
 ### Cross-platform support
 
-Swift Testing works on all major platforms supported by Swift, including Apple
-platforms, Linux, and Windows, so your tests can behave more consistently when
-moving between platforms. It’s developed as open source and discussed on the
-[Swift Forums](https://forums.swift.org/c/development/swift-testing/103) so the
-very best ideas, from anywhere, can help shape the future of testing in Swift.
+Swift Testing is included in officially-supported Swift toolchains, including
+those for Apple platforms, Linux, and Windows. To use the library, import the
+`Testing` module:
+
+```swift
+import Testing
+```
+
+You don't need to declare a package dependency to use Swift Testing. It's
+developed as open source and discussed on the
+[Swift Forums](https://forums.swift.org/c/development/swift-testing/103)
+so the 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:
@@ -101,6 +111,8 @@ for various platforms:
 | **tvOS** | | | Supported |
 | **visionOS** | | | 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 |
+| **FreeBSD** | | | Experimental |
+| **OpenBSD** | | | Experimental |
 | **Windows** | [![Build Status](https://ci-external.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 |
 

Sources/Overlays/_Testing_AppKit/Attachments/NSImage+AttachableAsCGImage.swift

@@ -12,6 +12,27 @@
 public import AppKit
 @_spi(Experimental) public import _Testing_CoreGraphics
 
+extension NSImageRep {
+  /// AppKit's bundle.
+  private static let _appKitBundle: Bundle = Bundle(for: NSImageRep.self)
+
+  /// Whether or not this image rep's class is effectively thread-safe and can
+  /// be treated as if it conforms to `Sendable`.
+  fileprivate var isEffectivelySendable: Bool {
+    if isMember(of: NSImageRep.self) || isKind(of: NSCustomImageRep.self) {
+      // NSImageRep itself is an abstract class. NSCustomImageRep includes an
+      // arbitrary rendering block that may not be concurrency-safe in Swift.
+      return false
+    }
+
+    // Treat all other classes declared in AppKit as safe. We can't reason about
+    // classes declared in other bundles, so treat them all as if they're unsafe.
+    return Bundle(for: Self.self) == Self._appKitBundle
+  }
+}
+
+// MARK: -
+
 @_spi(Experimental)
 extension NSImage: AttachableAsCGImage {
   public var attachableCGImage: CGImage {
@@ -32,29 +53,6 @@ extension NSImage: AttachableAsCGImage {
     return maxRepWidth ?? 1.0
   }
 
-  /// Get the base address of the loaded image containing `class`.
-  ///
-  /// - Parameters:
-  ///   - class: The class to look for.
-  ///
-  /// - Returns: The base address of the image containing `class`, or `nil` if
-  ///   no image was found (for instance, if the class is generic or dynamically
-  ///   generated.)
-  ///
-  /// "Image" in this context refers to a binary/executable image.
-  private static func _baseAddressOfImage(containing `class`: AnyClass) -> UnsafeRawPointer? {
-    let classAsAddress = Unmanaged.passUnretained(`class` as AnyObject).toOpaque()
-
-    var info = Dl_info()
-    guard 0 != dladdr(classAsAddress, &info) else {
-      return nil
-    }
-    return .init(info.dli_fbase)
-  }
-
-  /// The base address of the image containing AppKit's symbols, if known.
-  private static nonisolated(unsafe) let _appKitBaseAddress = _baseAddressOfImage(containing: NSImageRep.self)
-
   public func _makeCopyForAttachment() -> Self {
     // If this image is of an NSImage subclass, we cannot reliably make a deep
     // copy of it because we don't know what its `init(data:)` implementation
@@ -69,18 +67,7 @@ extension NSImage: AttachableAsCGImage {
 
     // Check whether the image contains any representations that we don't think
     // are safe. If it does, then make a "safe" copy.
-    let allImageRepsAreSafe = representations.allSatisfy { imageRep in
-      // NSCustomImageRep includes an arbitrary rendering block that may not be
-      // concurrency-safe in Swift.
-      if imageRep is NSCustomImageRep {
-        return false
-      }
-
-      // Treat all other classes declared in AppKit as safe. We can't reason
-      // about classes declared in other modules, so treat them all as if they
-      // are unsafe.
-      return Self._baseAddressOfImage(containing: type(of: imageRep)) == Self._appKitBaseAddress
-    }
+    let allImageRepsAreSafe = representations.allSatisfy(\.isEffectivelySendable)
     if !allImageRepsAreSafe, let safeCopy = tiffRepresentation.flatMap(Self.init(data:)) {
       // Create a "safe" copy of this image by flattening it to TIFF and then
       // creating a new NSImage instance from it.

Sources/Overlays/_Testing_AppKit/ReexportTesting.swift

@@ -8,5 +8,5 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-@_exported public import Testing
-@_exported public import _Testing_CoreGraphics
+@_exported @_spi(Experimental) @_spi(ForToolsIntegrationOnly) public import Testing
+@_exported @_spi(Experimental) @_spi(ForToolsIntegrationOnly) public import _Testing_CoreGraphics

Sources/Overlays/_Testing_CoreGraphics/Attachments/AttachableAsCGImage.swift

@@ -24,13 +24,17 @@ private import ImageIO
 /// be attached to a test:
 ///
 /// - [`CGImage`](https://developer.apple.com/documentation/coregraphics/cgimage)
+/// - [`CIImage`](https://developer.apple.com/documentation/coreimage/ciimage)
 /// - [`NSImage`](https://developer.apple.com/documentation/appkit/nsimage)
 ///   (macOS)
+/// - [`UIImage`](https://developer.apple.com/documentation/uikit/uiimage)
+///   (iOS, watchOS, tvOS, visionOS, and Mac Catalyst)
 ///
 /// You do not generally need to add your own conformances to this protocol. If
 /// you have an image in another format that needs to be attached to a test,
 /// first convert it to an instance of one of the types above.
 @_spi(Experimental)
+@available(_uttypesAPI, *)
 public protocol AttachableAsCGImage {
   /// An instance of `CGImage` representing this image.
   ///
@@ -73,6 +77,7 @@ public protocol AttachableAsCGImage {
   func _makeCopyForAttachment() -> Self
 }
 
+@available(_uttypesAPI, *)
 extension AttachableAsCGImage {
   public var _attachmentOrientation: UInt32 {
     CGImagePropertyOrientation.up.rawValue
@@ -83,6 +88,7 @@ extension AttachableAsCGImage {
   }
 }
 
+@available(_uttypesAPI, *)
 extension AttachableAsCGImage where Self: Sendable {
   public func _makeCopyForAttachment() -> Self {
     self

Sources/Overlays/_Testing_CoreGraphics/Attachments/AttachableImageFormat+UTType.swift

@@ -0,0 +1,100 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024–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
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+//
+
+#if SWT_TARGET_OS_APPLE && canImport(CoreGraphics)
+@_spi(Experimental) public import Testing
+
+public import UniformTypeIdentifiers
+
+@available(_uttypesAPI, *)
+extension AttachableImageFormat {
+  /// Get the content type to use when encoding the image, substituting a
+  /// concrete type for `UTType.image` in particular.
+  ///
+  /// - Parameters:
+  ///   - imageFormat: The image format to use, or `nil` if the developer did
+  ///     not specify one.
+  ///   - preferredName: The preferred name of the image for which a type is
+  ///     needed.
+  ///
+  /// - Returns: An instance of `UTType` referring to a concrete image type.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  static func computeContentType(for imageFormat: Self?, withPreferredName preferredName: String) -> UTType {
+    guard let imageFormat else {
+      // The developer didn't specify a type. Substitute the generic `.image`
+      // and solve for that instead.
+      return computeContentType(for: Self(.image, encodingQuality: 1.0), withPreferredName: preferredName)
+    }
+
+    switch imageFormat.kind {
+    case .png:
+      return .png
+    case .jpeg:
+      return .jpeg
+    case let .systemValue(contentType):
+      let contentType = contentType as! UTType
+      if contentType != .image {
+        // The developer explicitly specified a type.
+        return contentType
+      }
+
+      // The developer didn't specify a concrete type, so try to derive one from
+      // the preferred name's path extension.
+      let pathExtension = (preferredName as NSString).pathExtension
+      if !pathExtension.isEmpty,
+         let contentType = UTType(filenameExtension: pathExtension, conformingTo: .image),
+         contentType.isDeclared {
+        return contentType
+      }
+
+      // We couldn't derive a concrete type from the path extension, so pick
+      // between PNG and JPEG based on the encoding quality.
+      return imageFormat.encodingQuality < 1.0 ? .jpeg : .png
+    }
+  }
+
+  /// The content type corresponding to this image format.
+  ///
+  /// The value of this property always conforms to [`UTType.image`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/image).
+  public var contentType: UTType {
+    switch kind {
+    case .png:
+      return .png
+    case .jpeg:
+      return .jpeg
+    case let .systemValue(contentType):
+      return contentType as! UTType
+    }
+  }
+
+  /// Initialize an instance of this type with the given content type and
+  /// encoding quality.
+  ///
+  /// - Parameters:
+  ///   - contentType: The image format to use when encoding images.
+  ///   - encodingQuality: The encoding quality to use when encoding images. For
+  ///     the lowest supported quality, pass `0.0`. For the highest supported
+  ///     quality, pass `1.0`.
+  ///
+  /// If the target image format does not support variable-quality encoding,
+  /// the value of the `encodingQuality` argument is ignored.
+  ///
+  /// If `contentType` does not conform to [`UTType.image`](https://developer.apple.com/documentation/uniformtypeidentifiers/uttype-swift.struct/image),
+  /// the result is undefined.
+  public init(_ contentType: UTType, encodingQuality: Float = 1.0) {
+    precondition(
+      contentType.conforms(to: .image),
+      "An image cannot be attached as an instance of type '\(contentType.identifier)'. Use a type that conforms to 'public.image' instead."
+    )
+    self.init(kind: .systemValue(contentType), encodingQuality: encodingQuality)
+  }
+}
+#endif