Move __swiftPMEntryPoint() to its own file. (#384)

Tidying up the entry point code and moving the SwiftPM-specific entry
points to their own file. Renames internal functions to not mention
SwiftPM if they also support the general entry point mechanism.

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

Sources/Testing/EntryPoints/EntryPoint.swift

@@ -10,45 +10,6 @@
 
 private import TestingInternals
 
-/// The entry point to the testing library used by Swift Package Manager.
-///
-/// - Parameters:
-///   - args: A previously-parsed command-line arguments structure to interpret.
-///     If `nil`, a new instance is created from the command-line arguments to
-///     the current process.
-///
-/// - Returns: The result of invoking the testing library. The type of this
-///   value is subject to change.
-///
-/// This function examines the command-line arguments represented by `args` and
-/// then invokes available tests in the current process.
-///
-/// - Warning: This function is used by Swift Package Manager. Do not call it
-///   directly.
-@_disfavoredOverload public func __swiftPMEntryPoint(passing args: __CommandLineArguments_v0? = nil) async -> CInt {
-  await entryPoint(passing: args, eventHandler: nil)
-}
-
-/// The entry point to the testing library used by Swift Package Manager.
-///
-/// - Parameters:
-///   - args: A previously-parsed command-line arguments structure to interpret.
-///     If `nil`, a new instance is created from the command-line arguments to
-///     the current process.
-///
-/// This function examines the command-line arguments to the current process
-/// and then invokes available tests in the current process. When the tests
-/// complete, the process is terminated. If tests were successful, an exit code
-/// of `EXIT_SUCCESS` is used; otherwise, a (possibly platform-specific) value
-/// such as `EXIT_FAILURE` is used instead.
-///
-/// - Warning: This function is used by Swift Package Manager. Do not call it
-///   directly.
-public func __swiftPMEntryPoint(passing args: __CommandLineArguments_v0? = nil) async -> Never {
-  let exitCode: CInt = await __swiftPMEntryPoint(passing: args)
-  exit(exitCode)
-}
-
 /// The common implementation of the entry point functions in this file.
 ///
 /// - Parameters:
@@ -62,7 +23,7 @@ func entryPoint(passing args: consuming __CommandLineArguments_v0?, eventHandler
   do {
     let args = try args ?? parseCommandLineArguments(from: CommandLine.arguments())
     if args.listTests {
-      for testID in await listTestsForSwiftPM(Test.all) {
+      for testID in await listTestsForEntryPoint(Test.all) {
 #if SWT_TARGET_OS_APPLE && !SWT_NO_FILE_IO
         try? FileHandle.stdout.write("\(testID)\n")
 #else
@@ -72,13 +33,13 @@ func entryPoint(passing args: consuming __CommandLineArguments_v0?, eventHandler
     } else {
 #if !SWT_NO_EXIT_TESTS
       // If an exit test was specified, run it. `exitTest` returns `Never`.
-      if let exitTest = ExitTest.findInEnvironmentForSwiftPM() {
+      if let exitTest = ExitTest.findInEnvironmentForEntryPoint() {
         await exitTest()
       }
 #endif
 
       // Configure the test runner.
-      var configuration = try configurationForSwiftPMEntryPoint(from: args)
+      var configuration = try configurationForEntryPoint(from: args)
 
       // Set up the event handler.
       configuration.eventHandler = { [oldEventHandler = configuration.eventHandler] event, context in
@@ -138,7 +99,7 @@ func entryPoint(passing args: consuming __CommandLineArguments_v0?, eventHandler
 ///   - tests: The tests to list.
 ///
 /// - Returns: An array of strings representing the IDs of `tests`.
-func listTestsForSwiftPM(_ tests: some Sequence<Test>) -> [String] {
+func listTestsForEntryPoint(_ tests: some Sequence<Test>) -> [String] {
   // Filter out hidden tests and test suites. Hidden tests should not generally
   // be presented to the user, and suites (XCTestCase classes) are not included
   // in the equivalent XCTest-based output.
@@ -291,7 +252,7 @@ func parseCommandLineArguments(from args: [String]) throws -> __CommandLineArgum
 ///
 /// - Throws: If an argument is invalid, such as a malformed regular expression.
 @_spi(ForToolsIntegrationOnly)
-public func configurationForSwiftPMEntryPoint(from args: __CommandLineArguments_v0) throws -> Configuration {
+public func configurationForEntryPoint(from args: __CommandLineArguments_v0) throws -> Configuration {
   var configuration = Configuration()
 
   // Parallelization (on by default)
@@ -372,7 +333,7 @@ public func configurationForSwiftPMEntryPoint(from args: __CommandLineArguments_
 
 #if !SWT_NO_EXIT_TESTS
   // Enable exit test handling via __swiftPMEntryPoint().
-  configuration.exitTestHandler = ExitTest.handlerForSwiftPM(forXCTestCaseIdentifiedBy: args.xcTestCaseHostIdentifier)
+  configuration.exitTestHandler = ExitTest.handlerForEntryPoint(forXCTestCaseIdentifiedBy: args.xcTestCaseHostIdentifier)
 #endif
 
   return configuration

Sources/Testing/EntryPoints/SwiftPMEntryPoint.swift

@@ -0,0 +1,50 @@
+//
+// 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
+//
+
+private import TestingInternals
+
+/// The entry point to the testing library used by Swift Package Manager.
+///
+/// - Parameters:
+///   - args: A previously-parsed command-line arguments structure to interpret.
+///     If `nil`, a new instance is created from the command-line arguments to
+///     the current process.
+///
+/// - Returns: The result of invoking the testing library. The type of this
+///   value is subject to change.
+///
+/// This function examines the command-line arguments represented by `args` and
+/// then invokes available tests in the current process.
+///
+/// - Warning: This function is used by Swift Package Manager. Do not call it
+///   directly.
+@_disfavoredOverload public func __swiftPMEntryPoint(passing args: __CommandLineArguments_v0? = nil) async -> CInt {
+  await entryPoint(passing: args, eventHandler: nil)
+}
+
+/// The entry point to the testing library used by Swift Package Manager.
+///
+/// - Parameters:
+///   - args: A previously-parsed command-line arguments structure to interpret.
+///     If `nil`, a new instance is created from the command-line arguments to
+///     the current process.
+///
+/// This function examines the command-line arguments to the current process
+/// and then invokes available tests in the current process. When the tests
+/// complete, the process is terminated. If tests were successful, an exit code
+/// of `EXIT_SUCCESS` is used; otherwise, a (possibly platform-specific) value
+/// such as `EXIT_FAILURE` is used instead.
+///
+/// - Warning: This function is used by Swift Package Manager. Do not call it
+///   directly.
+public func __swiftPMEntryPoint(passing args: __CommandLineArguments_v0? = nil) async -> Never {
+  let exitCode: CInt = await __swiftPMEntryPoint(passing: args)
+  exit(exitCode)
+}

Sources/Testing/ExitTests/ExitTest.swift

@@ -218,7 +218,7 @@ extension ExitTest {
   /// This function should only be used when the process was started via the
   /// `__swiftPMEntryPoint()` function. The effect of using it under other
   /// configurations is undefined.
-  static func findInEnvironmentForSwiftPM() -> Self? {
+  static func findInEnvironmentForEntryPoint() -> Self? {
     if var sourceLocationString = Environment.variable(named: "SWT_EXPERIMENTAL_EXIT_TEST_SOURCE_LOCATION") {
       return try? sourceLocationString.withUTF8 { sourceLocationBuffer in
         let sourceLocationBuffer = UnsafeRawBufferPointer(sourceLocationBuffer)
@@ -238,7 +238,7 @@ extension ExitTest {
   ///
   /// For a description of the inputs and outputs of this function, see the
   /// documentation for ``ExitTest/Handler``.
-  static func handlerForSwiftPM(forXCTestCaseIdentifiedBy xcTestCaseIdentifier: String? = nil) -> Handler {
+  static func handlerForEntryPoint(forXCTestCaseIdentifiedBy xcTestCaseIdentifier: String? = nil) -> Handler {
     // The environment could change between invocations if a test calls setenv()
     // or unsetenv(), so we need to recompute the child environment each time.
     // The executable and XCTest bundle paths should not change over time, so we

Tests/TestingTests/ExitTestTests.swift

@@ -73,7 +73,7 @@ private import TestingInternals
           failed()
         }
       }
-      configuration.exitTestHandler = ExitTest.handlerForSwiftPM()
+      configuration.exitTestHandler = ExitTest.handlerForEntryPoint()
 
       await runTest(for: FailingExitTests.self, configuration: configuration)
     }

Tests/TestingTests/SwiftPMTests.swift

@@ -11,9 +11,9 @@
 @testable @_spi(Experimental) @_spi(ForToolsIntegrationOnly) import Testing
 private import TestingInternals
 
-private func configurationForSwiftPMEntryPoint(withArguments args: [String]) throws -> Configuration {
+private func configurationForEntryPoint(withArguments args: [String]) throws -> Configuration {
   let args = try parseCommandLineArguments(from: args)
-  return try configurationForSwiftPMEntryPoint(from: args)
+  return try configurationForEntryPoint(from: args)
 }
 
 @Suite("Swift Package Manager Integration Tests")
@@ -27,19 +27,19 @@ struct SwiftPMTests {
 
   @Test("--parallel/--no-parallel argument")
   func parallel() throws {
-    var configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH"])
+    var configuration = try configurationForEntryPoint(withArguments: ["PATH"])
     #expect(configuration.isParallelizationEnabled)
 
-    configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--parallel"])
+    configuration = try configurationForEntryPoint(withArguments: ["PATH", "--parallel"])
     #expect(configuration.isParallelizationEnabled)
 
-    configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--no-parallel"])
+    configuration = try configurationForEntryPoint(withArguments: ["PATH", "--no-parallel"])
     #expect(!configuration.isParallelizationEnabled)
   }
 
   @Test("No --filter or --skip argument")
   func defaultFiltering() async throws {
-    let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH"])
+    let configuration = try configurationForEntryPoint(withArguments: ["PATH"])
     let test1 = Test(name: "hello") {}
     let test2 = Test(name: "goodbye") {}
     let plan = await Runner.Plan(tests: [test1, test2], configuration: configuration)
@@ -51,7 +51,7 @@ struct SwiftPMTests {
   @Test("--filter argument")
   @available(_regexAPI, *)
   func filter() async throws {
-    let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--filter", "hello"])
+    let configuration = try configurationForEntryPoint(withArguments: ["PATH", "--filter", "hello"])
     let test1 = Test(name: "hello") {}
     let test2 = Test(name: "goodbye") {}
     let plan = await Runner.Plan(tests: [test1, test2], configuration: configuration)
@@ -63,7 +63,7 @@ struct SwiftPMTests {
   @Test("Multiple --filter arguments")
   @available(_regexAPI, *)
   func multipleFilter() async throws {
-    let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--filter", "hello", "--filter", "sorry"])
+    let configuration = try configurationForEntryPoint(withArguments: ["PATH", "--filter", "hello", "--filter", "sorry"])
     let test1 = Test(name: "hello") {}
     let test2 = Test(name: "goodbye") {}
     let test3 = Test(name: "sorry") {}
@@ -77,17 +77,17 @@ struct SwiftPMTests {
   @Test("--filter or --skip argument with bad regex")
   func badArguments() throws {
     #expect(throws: (any Error).self) {
-      _ = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--filter", "("])
+      _ = try configurationForEntryPoint(withArguments: ["PATH", "--filter", "("])
     }
     #expect(throws: (any Error).self) {
-      _ = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--skip", ")"])
+      _ = try configurationForEntryPoint(withArguments: ["PATH", "--skip", ")"])
     }
   }
 
   @Test("--skip argument")
   @available(_regexAPI, *)
   func skip() async throws {
-    let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--skip", "hello"])
+    let configuration = try configurationForEntryPoint(withArguments: ["PATH", "--skip", "hello"])
     let test1 = Test(name: "hello") {}
     let test2 = Test(name: "goodbye") {}
     let plan = await Runner.Plan(tests: [test1, test2], configuration: configuration)
@@ -98,7 +98,7 @@ struct SwiftPMTests {
 
   @Test(".hidden trait")
   func hidden() async throws {
-    let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH"])
+    let configuration = try configurationForEntryPoint(withArguments: ["PATH"])
     let test1 = Test(name: "hello") {}
     let test2 = Test(.hidden, name: "goodbye") {}
     let plan = await Runner.Plan(tests: [test1, test2], configuration: configuration)
@@ -110,7 +110,7 @@ struct SwiftPMTests {
   @Test("--filter/--skip arguments and .hidden trait")
   @available(_regexAPI, *)
   func filterAndSkipAndHidden() async throws {
-    let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--filter", "hello", "--skip", "hello2"])
+    let configuration = try configurationForEntryPoint(withArguments: ["PATH", "--filter", "hello", "--skip", "hello2"])
     let test1 = Test(name: "hello") {}
     let test2 = Test(name: "hello2") {}
     let test3 = Test(.hidden, name: "hello") {}
@@ -128,7 +128,7 @@ struct SwiftPMTests {
   func xunitOutputWithBadPath() {
     // Test that a bad path produces an error.
     #expect(throws: CError.self) {
-      _ = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--xunit-output", "/nonexistent/path/we/cannot/write/to"])
+      _ = try configurationForEntryPoint(withArguments: ["PATH", "--xunit-output", "/nonexistent/path/we/cannot/write/to"])
     }
   }
 
@@ -142,7 +142,7 @@ struct SwiftPMTests {
       _ = remove(temporaryFilePath)
     }
     do {
-      let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--xunit-output", temporaryFilePath])
+      let configuration = try configurationForEntryPoint(withArguments: ["PATH", "--xunit-output", temporaryFilePath])
       let eventContext = Event.Context()
       configuration.eventHandler(Event(.runStarted, testID: nil, testCaseID: nil), eventContext)
       configuration.eventHandler(Event(.runEnded, testID: nil, testCaseID: nil), eventContext)
@@ -176,7 +176,7 @@ struct SwiftPMTests {
       _ = remove(temporaryFilePath)
     }
     do {
-      let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--experimental-event-stream-output", temporaryFilePath])
+      let configuration = try configurationForEntryPoint(withArguments: ["PATH", "--experimental-event-stream-output", temporaryFilePath])
       let eventContext = Event.Context()
       configuration.handleEvent(Event(.runStarted, testID: nil, testCaseID: nil), in: eventContext)
       do {
@@ -197,23 +197,23 @@ struct SwiftPMTests {
   @Test("--repetitions argument (alone)")
   @available(_regexAPI, *)
   func repetitions() throws {
-    let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--repetitions", "2468"])
+    let configuration = try configurationForEntryPoint(withArguments: ["PATH", "--repetitions", "2468"])
     #expect(configuration.repetitionPolicy.maximumIterationCount == 2468)
     #expect(configuration.repetitionPolicy.continuationCondition == nil)
   }
 
   @Test("--repeat-until pass argument (alone)")
   @available(_regexAPI, *)
   func repeatUntilPass() throws {
-    let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--repeat-until", "pass"])
+    let configuration = try configurationForEntryPoint(withArguments: ["PATH", "--repeat-until", "pass"])
     #expect(configuration.repetitionPolicy.maximumIterationCount == .max)
     #expect(configuration.repetitionPolicy.continuationCondition == .whileIssueRecorded)
   }
 
   @Test("--repeat-until fail argument (alone)")
   @available(_regexAPI, *)
   func repeatUntilFail() throws {
-    let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--repeat-until", "fail"])
+    let configuration = try configurationForEntryPoint(withArguments: ["PATH", "--repeat-until", "fail"])
     #expect(configuration.repetitionPolicy.maximumIterationCount == .max)
     #expect(configuration.repetitionPolicy.continuationCondition == .untilIssueRecorded)
   }
@@ -222,21 +222,21 @@ struct SwiftPMTests {
   @available(_regexAPI, *)
   func repeatUntilGarbage() {
     #expect(throws: (any Error).self) {
-      _ = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--repeat-until", "qwertyuiop"])
+      _ = try configurationForEntryPoint(withArguments: ["PATH", "--repeat-until", "qwertyuiop"])
     }
   }
 
   @Test("--repetitions and --repeat-until arguments")
   @available(_regexAPI, *)
   func repetitionsAndRepeatUntil() throws {
-    let configuration = try configurationForSwiftPMEntryPoint(withArguments: ["PATH", "--repetitions", "2468", "--repeat-until", "pass"])
+    let configuration = try configurationForEntryPoint(withArguments: ["PATH", "--repetitions", "2468", "--repeat-until", "pass"])
     #expect(configuration.repetitionPolicy.maximumIterationCount == 2468)
     #expect(configuration.repetitionPolicy.continuationCondition == .whileIssueRecorded)
   }
 
   @Test("list subcommand")
   func list() async throws {
-    let testIDs = await listTestsForSwiftPM(Test.all)
+    let testIDs = await listTestsForEntryPoint(Test.all)
     let currentTestID = try #require(
       Test.current
         .flatMap(\.id.parent)