Merge upstream/main into gsoc-development

Author: tienquocbui

.github/ISSUE_TEMPLATE/config.yml

@@ -9,7 +9,7 @@
 blank_issues_enabled: true
 contact_links:
   - name: 🌐 Discuss an idea
-    url: https://forums.swift.org/c/related-projects/swift-testing
+    url: https://forums.swift.org/c/development/swift-testing/103
     about: >
       Share an idea with the Swift Testing community.
   - name: 📄 Formally propose a change
@@ -18,10 +18,10 @@ contact_links:
       Formally propose an addition, removal, or change to the APIs or features
       of Swift Testing.
   - name: 🙋 Ask a question
-    url: https://forums.swift.org/c/related-projects/swift-testing
+    url: https://forums.swift.org/c/swift-users/15
     about: >
-      Ask a question about or get help with Swift Testing. Beginner questions
-      welcome!
+      Ask a question or get help by starting a new Forum topic with the 'swift-testing' tag.
+      Beginner questions welcome!
   - name: 🪲 Report an issue with Swift Package Manager
     url: https://github.com/swiftlang/swift-package-manager/issues/new/choose
     about: >

Package.swift

@@ -92,6 +92,7 @@ let package = Package(
           "_Testing_CoreGraphics",
           "_Testing_CoreImage",
           "_Testing_UIKit",
+          "_Testing_WinSDK",
         ]
       )
     ]
@@ -135,6 +136,7 @@ let package = Package(
         "_Testing_CoreImage",
         "_Testing_Foundation",
         "_Testing_UIKit",
+        "_Testing_WinSDK",
         "MemorySafeTestingTests",
       ],
       swiftSettings: .packageSettings
@@ -246,6 +248,14 @@ let package = Package(
       path: "Sources/Overlays/_Testing_UIKit",
       swiftSettings: .packageSettings + .enableLibraryEvolution()
     ),
+    .target(
+      name: "_Testing_WinSDK",
+      dependencies: [
+        "Testing",
+      ],
+      path: "Sources/Overlays/_Testing_WinSDK",
+      swiftSettings: .packageSettings + .enableLibraryEvolution() + [.interoperabilityMode(.Cxx)]
+    ),
 
     // Utility targets: These are utilities intended for use when developing
     // this package, not for distribution.

Sources/Overlays/_Testing_WinSDK/Attachments/AttachableAsGDIPlusImage.swift

@@ -0,0 +1,129 @@
+//
+// 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 os(Windows)
+@_spi(Experimental) import Testing
+private import _TestingInternals.GDIPlus
+
+internal import WinSDK
+
+/// A protocol describing images that can be converted to instances of
+/// ``Testing/Attachment``.
+///
+/// Instances of types conforming to this protocol do not themselves conform to
+/// ``Testing/Attachable``. Instead, the testing library provides additional
+/// initializers on ``Testing/Attachment`` that take instances of such types and
+/// handle converting them to image data when needed.
+///
+/// The following system-provided image types conform to this protocol and can
+/// be attached to a test:
+///
+/// - [`HBITMAP`](https://learn.microsoft.com/en-us/windows/win32/gdi/bitmaps)
+/// - [`HICON`](https://learn.microsoft.com/en-us/windows/win32/menurc/icons)
+///
+/// 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)
+public protocol _AttachableByAddressAsGDIPlusImage {
+  /// Create a GDI+ image representing an instance of this type at the given
+  /// address.
+  ///
+  /// - Parameters:
+  ///   - imageAddress: The address of the instance of this type.
+  ///
+  /// - Returns: A pointer to a new GDI+ image representing this image. The
+  ///   caller is responsible for deleting this image when done with it.
+  ///
+  /// - Throws: Any error that prevented the creation of the GDI+ image.
+  ///
+  /// - Note: This function returns a value of C++ type `Gdiplus::Image *`. That
+  ///   type cannot be directly represented in Swift. If this function returns a
+  ///   value of any other concrete type, the result is undefined.
+  ///
+  /// The testing library automatically calls `GdiplusStartup()` and
+  /// `GdiplusShutdown()` before and after calling this function. This function
+  /// can therefore assume that GDI+ is correctly configured on the current
+  /// thread when it is called.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  static func _copyAttachableGDIPlusImage(at imageAddress: UnsafeMutablePointer<Self>) throws -> OpaquePointer
+
+  /// Clean up any resources at the given address.
+  ///
+  /// - Parameters:
+  ///   - imageAddress: The address of the instance of this type.
+  ///
+  /// The implementation of this function cleans up any resources (such as
+  /// handles or COM objects) associated with this value. The testing library
+  /// automatically invokes this function as needed.
+  ///
+  /// This function is not responsible for deleting the image returned from
+  /// `_copyAttachableGDIPlusImage(at:)`.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  static func _cleanUpAttachment(at imageAddress: UnsafeMutablePointer<Self>)
+}
+
+/// A protocol describing images that can be converted to instances of
+/// ``Testing/Attachment``.
+///
+/// Instances of types conforming to this protocol do not themselves conform to
+/// ``Testing/Attachable``. Instead, the testing library provides additional
+/// initializers on ``Testing/Attachment`` that take instances of such types and
+/// handle converting them to image data when needed.
+///
+/// The following system-provided image types conform to this protocol and can
+/// be attached to a test:
+///
+/// - [`HBITMAP`](https://learn.microsoft.com/en-us/windows/win32/gdi/bitmaps)
+/// - [`HICON`](https://learn.microsoft.com/en-us/windows/win32/menurc/icons)
+///
+/// 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)
+public protocol AttachableAsGDIPlusImage {
+  /// Create a GDI+ image representing this instance.
+  ///
+  /// - Returns: A pointer to a new GDI+ image representing this image. The
+  ///   caller is responsible for deleting this image when done with it.
+  ///
+  /// - Throws: Any error that prevented the creation of the GDI+ image.
+  ///
+  /// - Note: This function returns a value of C++ type `Gdiplus::Image *`. That
+  ///   type cannot be directly represented in Swift. If this function returns a
+  ///   value of any other concrete type, the result is undefined.
+  ///
+  /// The testing library automatically calls `GdiplusStartup()` and
+  /// `GdiplusShutdown()` before and after calling this function. This function
+  /// can therefore assume that GDI+ is correctly configured on the current
+  /// thread when it is called.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  func _copyAttachableGDIPlusImage() throws -> OpaquePointer
+
+  /// Clean up any resources associated with this instance.
+  ///
+  /// The implementation of this function cleans up any resources (such as
+  /// handles or COM objects) associated with this value. The testing library
+  /// automatically invokes this function as needed.
+  ///
+  /// This function is not responsible for deleting the image returned from
+  /// `_copyAttachableGDIPlusImage()`.
+  ///
+  /// This function is not part of the public interface of the testing library.
+  /// It may be removed in a future update.
+  func _cleanUpAttachment()
+}
+#endif