Add an _ersatz_ filtering mechanism to XCTestScaffold.

Sources/Testing/Running/Configuration.swift

@@ -149,26 +149,23 @@ public struct Configuration: Sendable {
   public var testFilter: TestFilter?
 
   /// The granularity to enforce test filtering.
-  /// 
-  /// By default, all tests are run and no filter is set.
   /// - Parameters:
-  ///   - selection: An set of test ids to be filtered.
+  ///   - selection: A set of test IDs to be filtered. If `nil`, the current
+  ///     selection is cleared.
+  ///
+  /// By default, all tests are run and no filter is set.
   public mutating func setTestFilter(toMatch selection: Set<Test.ID>?) {
-      self.setTestFilter(toMatch: selection.map(Test.ID.Selection.init))
+    setTestFilter(toMatch: selection.map(Test.ID.Selection.init))
   }
 
   /// The granularity to enforce test filtering.
   ///
-  /// By default, all tests are run and no filter is set.
   /// - Parameters:
-  ///   - selection: An selection of test ids to be filtered.
+  ///   - selection: A selection of test IDs to be filtered. If `nil`, the
+  ///     current selection is cleared.
+  ///
+  /// By default, all tests are run and no filter is set.
   mutating func setTestFilter(toMatch selection: Test.ID.Selection?) {
-    guard let selectedTests = selection else {
-        self.testFilter = nil
-        return
-    }
-    self.testFilter = { test in
-        selectedTests.contains(test)
-    }
+    testFilter = selection.map { $0.contains }
   }
 }

Sources/Testing/Running/XCTestScaffold.swift

@@ -110,6 +110,33 @@ public enum XCTestScaffold: Sendable {
   ///   testing library with existing tools such as Swift Package Manager. It
   ///   will be removed in a future release.
   ///
+  /// ### Filtering tests
+  ///
+  /// This function does not support the `--filter` argument passed to
+  /// `swift test`. Instead, set the `SWT_SELECTED_TEST_IDS` environment
+  /// variable to the ``Test/ID`` of the test that should run (or, if multiple
+  /// tests should be run, their IDs separated by `";"`.)
+  ///
+  /// A test ID is composed of its module name, containing type name, and (if
+  /// the test is a function rather than a suite), the name of the function
+  /// including parentheses and any parameter labels. For example, given the
+  /// following test functions in a module named `"MyTests"`:
+  ///
+  /// ```swift
+  /// struct MySuite {
+  ///   @Test func hello() { ... }
+  ///   @Test(arguments: 0 ..< 10) func world(i: Int) { ... }
+  /// }
+  /// ```
+  ///
+  /// Their IDs are the strings `"MyTests/MySuite/hello()"` and
+  /// `"MyTests/MySuite/world(i:)"` respectively, and they can be passed as the
+  /// environment variable value
+  /// `"MyTests/MySuite/hello();MyTests/MySuite/world(i:)"`.
+  ///
+  /// - Note: The module name of a test target in a Swift package is typically
+  ///   the name of the test target.
+  ///
   /// ### Configuring output
   ///
   /// By default, this function uses
@@ -168,6 +195,20 @@ public enum XCTestScaffold: Sendable {
 #endif
     }
 
+    // If the SWT_SELECTED_TEST_IDS environment variable is set, split it into
+    // test IDs (separated by ";", test ID components separated by "/") and set
+    // the configuration's test filter to match it.
+    //
+    // This environment variable stands in for `swift test --filter`.
+    let testIDs: [Test.ID]? = Environment.variable(named: "SWT_SELECTED_TEST_IDS").map { testIDs in
+      testIDs.split(separator: ";", omittingEmptySubsequences: true).map { testID in
+        Test.ID(testID.split(separator: "/", omittingEmptySubsequences: true).map(String.init))
+      }
+    }
+    if let testIDs {
+      configuration.setTestFilter(toMatch: Set(testIDs))
+    }
+
     let runner = await Runner(configuration: configuration)
     await runner.run()
   }

Sources/Testing/Test.ID.Selection.swift

@@ -55,7 +55,7 @@ extension Test.ID {
     /// A test ID is considered contained in the selection if it has been
     /// explicitly added or if it has a descendant or ancestor which has been
     /// explicitly added.
-    func contains(_ test: Test) -> Bool {
+    @Sendable func contains(_ test: Test) -> Bool {
       contains(test.id)
     }
 
@@ -69,7 +69,7 @@ extension Test.ID {
     /// A test ID is considered contained in the selection if it has been
     /// explicitly added or if it has a descendant or ancestor which has been
     /// explicitly added.
-    func contains(_ testID: Test.ID) -> Bool {
+    @Sendable func contains(_ testID: Test.ID) -> Bool {
       contains(testID.keyPathRepresentation)
     }
 

Tests/TestingTests/PlanTests.swift

@@ -73,9 +73,7 @@ struct PlanTests {
 
     var configuration = Configuration()
     let selection = Test.ID.Selection(testIDs: [outerTestType.id, deeplyNestedTest.id])
-    configuration.testFilter = { test in
-      selection.contains(test)
-    }
+    configuration.setTestFilter(toMatch: selection)
 
     let plan = await Runner.Plan(tests: tests, configuration: configuration)
 
@@ -94,9 +92,7 @@ struct PlanTests {
 
     var configuration = Configuration()
     let selection = Test.ID.Selection(testIDs: [testSuiteA.id])
-    configuration.testFilter = { test in
-      selection.contains(test)
-    }
+    configuration.setTestFilter(toMatch: selection)
 
     let plan = await Runner.Plan(tests: tests, configuration: configuration)
     let testFuncXWithTraits = try #require(plan.steps.map(\.test).first { $0.name == "x()" })

Tests/TestingTests/RunnerTests.swift

@@ -251,9 +251,7 @@ final class RunnerTests: XCTestCase {
 
     var configuration = Configuration()
     let selection = Test.ID.Selection(testIDs: [testSuite.id])
-    configuration.testFilter = { test in
-      selection.contains(test)
-    }
+    configuration.setTestFilter(toMatch: selection)
 
     let runner = await Runner(testing: [
       testSuite,
@@ -304,9 +302,7 @@ final class RunnerTests: XCTestCase {
 
     var configuration = Configuration()
     let selection = Test.ID.Selection(testIDs: selectedTestIDs)
-    configuration.testFilter = { test in
-      selection.contains(test)
-    }
+    configuration.setTestFilter(toMatch: selection)
 
     let runner = await Runner(configuration: configuration)
     let plan = runner.plan

Tests/TestingTests/TestSupport/TestingAdditions.swift

@@ -67,10 +67,8 @@ func runTest(for containingType: Any.Type, configuration: Configuration = .init(
 /// If no test is found representing `containingType`, nothing is run.
 func runTestFunction(named name: String, in containingType: Any.Type, configuration: Configuration = .init()) async {
   var configuration = configuration
-  let testID = Test.ID.Selection(testIDs: [Test.ID(type: containingType).child(named: name)])
-  configuration.testFilter = { test in
-    testID.contains(test)
-  }
+  let selection = Test.ID.Selection(testIDs: [Test.ID(type: containingType).child(named: name)])
+  configuration.setTestFilter(toMatch: selection)
 
   let runner = await Runner(configuration: configuration)
   await runner.run()
@@ -109,9 +107,7 @@ extension Runner.Plan {
   init(selecting containingType: Any.Type, configuration: Configuration = .init()) async {
     var configuration = configuration
     let selection = Test.ID.Selection(testIDs: [Test.ID(type: containingType)])
-    configuration.testFilter = { test in
-      selection.contains(test)
-    }
+    configuration.setTestFilter(toMatch: selection)
 
     await self.init(configuration: configuration)
   }