Add a new _TestDiscovery library/target.

Documentation/ABI/TestContent.md

@@ -200,7 +200,9 @@ Third-party test content should set the `kind` field to a unique value only used
 by that tool, or used by that tool in collaboration with other compatible tools.
 At runtime, Swift Testing ignores test content records with unrecognized `kind`
 values. To reserve a new unique `kind` value, open a [GitHub issue](https://github.com/swiftlang/swift-testing/issues/new/choose)
-against Swift Testing.
+against Swift Testing. The value you reserve does not need to be representable
+as a [FourCC](https://en.wikipedia.org/wiki/FourCC) value, but it can be helpful
+for debugging purposes.
 
 The layout of third-party test content records must be compatible with that of
 `TestContentRecord` as specified above. Third-party tools are ultimately
@@ -213,3 +215,78 @@ TODO: elaborate further, give examples
 TODO: standardize a mechanism for third parties to produce `Test` instances
       since we don't have a public initializer for the `Test` type.
 -->
+
+## Discovering previously-emitted test content
+
+<!--
+TODO: add more detail here about how to set up a package 
+-->
+
+To add test content discovery support to your package, add a dependency on the
+`_TestDiscovery` module in the `swift-testing` package (not the copy of Swift
+Testing included with the Swift toolchain or Xcode), then import the module with
+SPI enabled:
+
+```swift
+@_spi(Experimental) @_spi(ForToolsIntegrationOnly) import _TestDiscovery
+```
+
+> [!IMPORTANT]
+> Don't add a dependency on the `swift-testing` package's `Testing` module. If
+> you add a dependency on this module, it will cause you to build and link Swift
+> Testing every time you build your package. You only need the `_TestDiscovery`
+> module in order to discover your own test content types.
+
+After importing `_TestDiscovery`, find the type in your module that should be
+discoverable at runtime and add conformance to the `DiscoverableAsTestContent`
+protocol:
+
+```swift
+extension FoodTruckDiagnostic: DiscoverableAsTestContent {
+  static var testContentKind: UInt32 { /* Your `kind` value here. */ }
+}
+```
+
+This type does not need to be publicly visible. However, if the values produced
+by your accessor functions are members of a public type, you may be able to
+simplify your code by using the same type.
+
+If you have defined a custom `context` type other than `UInt`, you can specify
+it here by setting the associated `TestContentContext` type. If you have defined
+a custom `hint` type for your accessor functions, you can set
+`TestContentAccessorHint`:
+
+```swift
+extension FoodTruckDiagnostic: DiscoverableAsTestContent {
+  static var testContentKind: UInt32 { /* Your `kind` value here. */ }
+
+  typealias TestContentContext = UnsafePointer<FoodTruck.Name>
+  typealias TestContentAccessorHint = String
+}
+```
+
+If you customize `TestContentContext`, be aware that the type you specify must
+have the same stride and alignment as `UInt`.
+
+When you are done configuring your type's protocol conformance, you can then
+enumerate all test content records matching it as instances of
+`TestContentRecord`.
+
+You can use the `context` property to access the `context` field of the record
+(as emitted into the test content section). The testing library will
+automatically cast the value of the field to an instance of `TestContentContext`
+for you.
+
+If you find a record you wish to resolve to an instance of your conforming type,
+call its `load()` function. `load()` calls the record's accessor function and,
+if you have set a hint type, lets you pass an optional instance of that type: 
+
+```swift
+for diagnosticRecord in FoodTruckDiagnostic.allTestContentRecords() {
+  if diagnosticRecord.context.pointee == .briansBranMuffins {
+    if let diagnostic = diagnosticRecord.load(withHint: "...") {
+      diagnostic.run()
+    }
+  }
+}
+```

Package.swift

@@ -25,22 +25,36 @@ let package = Package(
     .visionOS(.v1),
   ],
 
-  products: [
-    {
+  products: {
+    var result = [Product]()
+
 #if os(Windows)
+    result.append(
       .library(
         name: "Testing",
         type: .dynamic, // needed so Windows exports ABI entry point symbols
         targets: ["Testing"]
       )
+    )
 #else
+    result.append(
       .library(
         name: "Testing",
         targets: ["Testing"]
       )
+    )
 #endif
-    }()
-  ],
+
+    result.append(
+      .library(
+        name: "_TestDiscovery",
+        type: .static,
+        targets: ["_TestDiscovery"]
+      )
+    )
+
+    return result
+  }(),
 
   dependencies: [
     .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "601.0.0-latest"),
@@ -50,6 +64,7 @@ let package = Package(
     .target(
       name: "Testing",
       dependencies: [
+        "_TestDiscovery",
         "_TestingInternals",
         "TestingMacros",
       ],
@@ -101,13 +116,20 @@ let package = Package(
       ]
     ),
 
-    // "Support" targets: These contain C family code and are used exclusively
-    // by other targets above, not directly included in product libraries.
+    // "Support" targets: These targets are not meant to be used directly by
+    // test authors.
     .target(
       name: "_TestingInternals",
       exclude: ["CMakeLists.txt"],
       cxxSettings: .packageSettings
     ),
+    .target(
+      name: "_TestDiscovery",
+      dependencies: ["_TestingInternals",],
+      exclude: ["CMakeLists.txt"],
+      cxxSettings: .packageSettings,
+      swiftSettings: .packageSettings
+    ),
 
     // Cross-import overlays (not supported by Swift Package Manager)
     .target(

Sources/CMakeLists.txt

@@ -103,6 +103,7 @@ endif()
 
 include(AvailabilityDefinitions)
 include(CompilerSettings)
+add_subdirectory(_TestDiscovery)
 add_subdirectory(_TestingInternals)
 add_subdirectory(Overlays)
 add_subdirectory(Testing)

Sources/Testing/CMakeLists.txt

@@ -82,8 +82,7 @@ add_library(Testing
   Support/Locked.swift
   Support/Locked+Platform.swift
   Support/Versions.swift
-  Discovery.swift
-  Discovery+Platform.swift
+  Discovery+Macro.swift
   Test.ID.Selection.swift
   Test.ID.swift
   Test.swift
@@ -106,6 +105,7 @@ add_library(Testing
   Traits/TimeLimitTrait.swift
   Traits/Trait.swift)
 target_link_libraries(Testing PRIVATE
+  _TestDiscovery
   _TestingInternals)
 if(NOT APPLE)
   if(NOT CMAKE_SYSTEM_NAME STREQUAL WASI)
@@ -120,8 +120,9 @@ if(NOT APPLE)
 endif()
 if(NOT BUILD_SHARED_LIBS)
   # When building a static library, tell clients to autolink the internal
-  # library.
+  # libraries.
   target_compile_options(Testing PRIVATE
+    "SHELL:-Xfrontend -public-autolink-library -Xfrontend _TestDiscovery"
     "SHELL:-Xfrontend -public-autolink-library -Xfrontend _TestingInternals")
 endif()
 add_dependencies(Testing

Sources/Testing/Discovery+Macro.swift

@@ -0,0 +1,48 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// 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
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+//
+
+@_spi(Experimental) @_spi(ForToolsIntegrationOnly) internal import _TestDiscovery
+
+/// A shadow declaration of `_TestDiscovery.DiscoverableAsTestContent` that
+/// allows us to add public conformances to it without causing the
+/// `_TestDiscovery` module to appear in `Testing.private.swiftinterface`.
+///
+/// This protocol is not part of the public interface of the testing library.
+protocol DiscoverableAsTestContent: _TestDiscovery.DiscoverableAsTestContent, ~Copyable {}
+
+/// The type of the accessor function used to access a test content record.
+///
+/// The signature of this function type must match that of the corresponding
+/// type in the `_TestDiscovery` module. For more information, see
+/// `ABI/TestContent.md`.
+///
+/// - Warning: This type is used to implement the `@Test` macro. Do not use it
+///   directly.
+public typealias __TestContentRecordAccessor = @convention(c) (
+  _ outValue: UnsafeMutableRawPointer,
+  _ type: UnsafeRawPointer,
+  _ hint: UnsafeRawPointer?
+) -> CBool
+
+/// The content of a test content record.
+///
+/// The layout of this type must match that of the corresponding type
+/// in the `_TestDiscovery` module. For more information, see
+/// `ABI/TestContent.md`.
+///
+/// - Warning: This type is used to implement the `@Test` macro. Do not use it
+///   directly.
+public typealias __TestContentRecord = (
+  kind: UInt32,
+  reserved1: UInt32,
+  accessor: __TestContentRecordAccessor?,
+  context: UInt,
+  reserved2: UInt
+)