Add a dedicated TestContentKind type to _TestDiscovery. (#1019)

This PR adds a `TestContentKind` type to `_TestDiscovery` that
represents the `kind` field of a record and allows initialization from a
string literal (i.e. a FourCC) or an integer literal:

```swift
extension MyType: DiscoverableAsTestContent {
  static var testContentKind: TestContentKind {
    "moof"
  }
}
```

At this time, it's not possible to use this type directly in test
content records emitted by our macros because the type cannot be made
public, but it allows for types conforming to
`DiscoverableAsTestContent` to be a bit more expressive. Test library
authors who are experimenting with `_TestDiscovery` may opt to export
the symbols from `_TestDiscovery` and thus could use the type directly
in their emitted records (but keep in mind this module is still
experimental!)

The new type is `@frozen` and mostly `@inlinable` because its layout is
set in stone by virtue of the test content record `kind` field having a
fixed layout.

Resolves rdar://146855125.

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

@@ -243,7 +243,7 @@ protocol:
 
 ```swift
 extension FoodTruckDiagnostic: DiscoverableAsTestContent {
-  static var testContentKind: UInt32 { /* Your `kind` value here. */ }
+  static var testContentKind: TestContentKind { /* Your `kind` value here. */ }
 }
 ```
 
@@ -258,7 +258,7 @@ a custom `hint` type for your accessor functions, you can set
 
 ```swift
 extension FoodTruckDiagnostic: DiscoverableAsTestContent {
-  static var testContentKind: UInt32 { /* Your `kind` value here. */ }
+  static var testContentKind: TestContentKind { /* Your `kind` value here. */ }
 
   typealias TestContentContext = UnsafePointer<FoodTruck.Name>
   typealias TestContentAccessorHint = String

Sources/Testing/ExitTests/ExitTest.swift

@@ -239,11 +239,11 @@ extension ExitTest {
 // MARK: - Discovery
 
 extension ExitTest: DiscoverableAsTestContent {
-  static var testContentKind: UInt32 {
-    0x65786974
+  fileprivate static var testContentKind: TestContentKind {
+    "exit"
   }
 
-  typealias TestContentAccessorHint = ID
+  fileprivate typealias TestContentAccessorHint = ID
 
   /// Store the exit test into the given memory.
   ///

Sources/Testing/Test+Discovery.swift

@@ -20,8 +20,8 @@ extension Test {
   /// instances of ``Test``, but functions are non-nominal types and cannot
   /// directly conform to protocols.
   fileprivate struct Generator: DiscoverableAsTestContent, RawRepresentable {
-    static var testContentKind: UInt32 {
-      0x74657374
+    static var testContentKind: TestContentKind {
+      "test"
     }
 
     var rawValue: @Sendable () async -> Test

Sources/TestingMacros/Support/TestContentGeneration.swift

@@ -17,6 +17,9 @@ import SwiftSyntaxMacros
 ///
 /// When adding cases to this enumeration, be sure to also update the
 /// corresponding enumeration in TestContent.md.
+///
+/// - Bug: This type should be imported directly from `_TestDiscovery` instead
+///   of being redefined (differently) here.
 enum TestContentKind: UInt32 {
   /// A test or suite declaration.
   case testDeclaration = 0x74657374

Sources/_TestDiscovery/CMakeLists.txt

@@ -10,6 +10,7 @@ add_library(_TestDiscovery STATIC
   Additions/WinSDKAdditions.swift
   DiscoverableAsTestContent.swift
   SectionBounds.swift
+  TestContentKind.swift
   TestContentRecord.swift)
 
 target_link_libraries(_TestDiscovery PRIVATE

Sources/_TestDiscovery/DiscoverableAsTestContent.swift

@@ -22,7 +22,7 @@ public protocol DiscoverableAsTestContent: Sendable, ~Copyable {
   ///
   /// The value of this property is reserved for each test content type. See
   /// `ABI/TestContent.md` for a list of values and corresponding types.
-  static var testContentKind: UInt32 { get }
+  static var testContentKind: TestContentKind { get }
 
   /// The type of the `context` field in test content records associated with
   /// this type.

Sources/_TestDiscovery/TestContentKind.swift

@@ -0,0 +1,102 @@
+//
+// 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
+//
+
+private import _TestingInternals
+
+/// A type representing a test content record's `kind` field.
+///
+/// Test content kinds are 32-bit unsigned integers and are stored as such when
+/// test content records are emitted at compile time.
+///
+/// This type lets you represent a kind value as an integer literal or as a
+/// string literal in Swift code. In particular, when adding a conformance to
+/// the ``DiscoverableAsTestContent`` protocol, the protocol's
+/// ``DiscoverableAsTestContent/testContentKind`` property must be an instance
+/// of this type.
+///
+/// For a list of reserved values, or to reserve a value for your own use, see
+/// `ABI/TestContent.md`.
+///
+/// @Comment {
+///   This type is `@frozen` and most of its members are `@inlinable` because it
+///   represents the underlying `kind` field which has a fixed layout. In the
+///   future, we may want to use this type in test content records, but that
+///   will require the type be publicly visible and that `@const` is implemented
+///   in the compiler.
+/// }
+@_spi(Experimental) @_spi(ForToolsIntegrationOnly)
+@frozen public struct TestContentKind: Sendable, RawRepresentable {
+  public var rawValue: UInt32
+
+  @inlinable public init(rawValue: UInt32) {
+    self.rawValue = rawValue
+  }
+}
+
+// MARK: - Equatable, Hashable
+
+extension TestContentKind: Equatable, Hashable {
+  @inlinable public static func ==(lhs: Self, rhs: Self) -> Bool {
+    lhs.rawValue == rhs.rawValue
+  }
+
+  @inlinable public func hash(into hasher: inout Hasher) {
+    hasher.combine(rawValue)
+  }
+}
+
+// MARK: - Codable
+
+extension TestContentKind: Codable {}
+
+// MARK: - ExpressibleByStringLiteral, ExpressibleByIntegerLiteral
+
+extension TestContentKind: ExpressibleByStringLiteral, ExpressibleByIntegerLiteral {
+  @inlinable public init(stringLiteral stringValue: StaticString) {
+    precondition(stringValue.utf8CodeUnitCount == MemoryLayout<UInt32>.stride, #""\#(stringValue)".utf8CodeUnitCount = \#(stringValue.utf8CodeUnitCount), expected \#(MemoryLayout<UInt32>.stride)"#)
+    let rawValue = stringValue.withUTF8Buffer { stringValue in
+      let bigEndian = UnsafeRawBufferPointer(stringValue).loadUnaligned(as: UInt32.self)
+      return UInt32(bigEndian: bigEndian)
+    }
+    self.init(rawValue: rawValue)
+  }
+
+  @inlinable public init(integerLiteral: UInt32) {
+    self.init(rawValue: integerLiteral)
+  }
+}
+
+// MARK: - CustomStringConvertible
+
+extension TestContentKind: CustomStringConvertible {
+  /// This test content type's kind value as an ASCII string (of the form
+  /// `"abcd"`) if it looks like it might be a [FourCC](https://en.wikipedia.org/wiki/FourCC)
+  /// value, or `nil` if not.
+  private var _fourCCValue: String? {
+    withUnsafeBytes(of: rawValue.bigEndian) { bytes in
+      if bytes.allSatisfy(Unicode.ASCII.isASCII) {
+        let characters = String(decoding: bytes, as: Unicode.ASCII.self)
+        let allAlphanumeric = characters.allSatisfy { $0.isLetter || $0.isWholeNumber }
+        if allAlphanumeric {
+          return characters
+        }
+      }
+      return nil
+    }
+  }
+
+  public var description: String {
+    let hexValue = "0x" + String(rawValue, radix: 16)
+    if let fourCCValue = _fourCCValue {
+      return "'\(fourCCValue)' (\(hexValue))"
+    }
+    return hexValue
+  }
+}

Sources/_TestDiscovery/TestContentRecord.swift

@@ -108,17 +108,22 @@ public struct TestContentRecord<T> where T: DiscoverableAsTestContent & ~Copyabl
   }
 
   fileprivate init(imageAddress: UnsafeRawPointer?, recordAddress: UnsafePointer<_TestContentRecord>) {
-    precondition(recordAddress.pointee.kind == T.testContentKind)
+    precondition(recordAddress.pointee.kind == T.testContentKind.rawValue)
     self.imageAddress = imageAddress
     self._recordStorage = .atAddress(recordAddress)
   }
 
   fileprivate init(imageAddress: UnsafeRawPointer?, record: _TestContentRecord) {
-    precondition(record.kind == T.testContentKind)
+    precondition(record.kind == T.testContentKind.rawValue)
     self.imageAddress = imageAddress
     self._recordStorage = .inline(record)
   }
 
+  /// The kind of this test content record.
+  public var kind: TestContentKind {
+    TestContentKind(rawValue: _record.kind)
+  }
+
   /// The type of the ``context`` property.
   public typealias Context = T.TestContentContext
 
@@ -181,28 +186,8 @@ extension TestContentRecord: Sendable where Context: Sendable {}
 // MARK: - CustomStringConvertible
 
 extension TestContentRecord: CustomStringConvertible {
-  /// This test content type's kind value as an ASCII string (of the form
-  /// `"abcd"`) if it looks like it might be a [FourCC](https://en.wikipedia.org/wiki/FourCC)
-  /// value, or `nil` if not.
-  private static var _asciiKind: String? {
-    return withUnsafeBytes(of: T.testContentKind.bigEndian) { bytes in
-      if bytes.allSatisfy(Unicode.ASCII.isASCII) {
-        let characters = String(decoding: bytes, as: Unicode.ASCII.self)
-        let allAlphanumeric = characters.allSatisfy { $0.isLetter || $0.isWholeNumber }
-        if allAlphanumeric {
-          return characters
-        }
-      }
-      return nil
-    }
-  }
-
   public var description: String {
     let typeName = String(describing: Self.self)
-    let hexKind = "0x" + String(T.testContentKind, radix: 16)
-    let kind = Self._asciiKind.map { asciiKind in
-      "'\(asciiKind)' (\(hexKind))"
-    } ?? hexKind
     switch _recordStorage {
     case let .atAddress(recordAddress):
       let recordAddress = imageAddress.map { imageAddress in
@@ -232,11 +217,14 @@ extension DiscoverableAsTestContent where Self: ~Copyable {
   /// }
   public static func allTestContentRecords() -> AnySequence<TestContentRecord<Self>> {
     validateMemoryLayout()
+
+    let kind = testContentKind.rawValue
+
     let result = SectionBounds.all(.testContent).lazy.flatMap { sb in
       sb.buffer.withMemoryRebound(to: _TestContentRecord.self) { records in
         (0 ..< records.count).lazy
           .map { (records.baseAddress! + $0) as UnsafePointer<_TestContentRecord> }
-          .filter { $0.pointee.kind == testContentKind }
+          .filter { $0.pointee.kind == kind }
           .map { TestContentRecord<Self>(imageAddress: sb.imageAddress, recordAddress: $0) }
       }
     }
@@ -275,7 +263,7 @@ extension DiscoverableAsTestContent where Self: ~Copyable {
     validateMemoryLayout()
 
     let typeNameHint = _testContentTypeNameHint
-    let kind = testContentKind
+    let kind = testContentKind.rawValue
     let loader: @Sendable (Any.Type) -> _TestContentRecord? = { type in
       withUnsafeTemporaryAllocation(of: _TestContentRecord.self, capacity: 1) { buffer in
         // Load the record from the container type.