Add a new _TestDiscovery library/target. (#981)

This PR factors out our test discovery logic into a separate module that
can be imported and linked to without needing to build all of Swift
Syntax and Swift Testing.

This allows test library developers to start experimenting with using
the new (still experimental) test content section without needing to
link to a package copy of Swift Testing.

Resolves rdar://145694068.

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

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

@@ -32,22 +32,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"),
@@ -57,6 +71,7 @@ let package = Package(
     .target(
       name: "Testing",
       dependencies: [
+        "_TestDiscovery",
         "_TestingInternals",
         "TestingMacros",
       ],
@@ -108,13 +123,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

@@ -83,8 +83,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
@@ -107,6 +106,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)
@@ -121,8 +121,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
+)