Merge pull request #468 from apple/jgrynspan/XCTMain-signature

Make `XCTMain()` return its exit code instead of calling `exit()`.

Author: grynspan

Sources/XCTest/Public/XCTestMain.swift

@@ -32,7 +32,6 @@
 
 /// Starts a test run for the specified test cases.
 ///
-/// This function will not return. If the test cases pass, then it will call `exit(EXIT_SUCCESS)`. If there is a failure, then it will call `exit(EXIT_FAILURE)`.
 /// Example usage:
 ///
 ///     class TestFoo: XCTestCase {
@@ -50,28 +49,33 @@
 ///         // etc...
 ///     }
 ///
-///     XCTMain([ testCase(TestFoo.allTests) ])
+///     let exitCode = XCTMain([ testCase(TestFoo.allTests) ])
 ///
-/// Command line arguments can be used to select a particular test case or class to execute. For example:
+/// Command line arguments can be used to select a particular test case or class
+/// to execute. For example:
 ///
 ///     ./FooTests FooTestCase/testFoo  # Run a single test case
 ///     ./FooTests FooTestCase          # Run all the tests in FooTestCase
 ///
-/// - Parameter testCases: An array of test cases run, each produced by a call to the `testCase` function
-/// - seealso: `testCase`
-public func XCTMain(_ testCases: [XCTestCaseEntry]) -> Never {
-    XCTMain(testCases, arguments: CommandLine.arguments)
-}
-
-public func XCTMain(_ testCases: [XCTestCaseEntry], arguments: [String]) -> Never {
-    XCTMain(testCases, arguments: arguments, observers: [PrintObserver()])
-}
-
+/// - Parameters:
+///     - testCases: An array of test cases run, each produced by a call to the
+///         `testCase` function.
+///     - arguments: Command-line arguments to pass to XCTest. By default, the
+///         arguments passed to the process are used.
+///     - observers: Zero or more observers that should observe events that
+///         occur while testing. If `nil` (the default), events are written to
+///         the console.
+///
+/// - Returns: The exit code to use when the process terminates. `EXIT_SUCCESS`
+///     indicates success, while any other value (including `EXIT_FAILURE`)
+///     indicates failure.
+@_disfavoredOverload
 public func XCTMain(
     _ testCases: [XCTestCaseEntry],
-    arguments: [String],
-    observers: [XCTestObservation]
-) -> Never {
+    arguments: [String] = CommandLine.arguments,
+    observers: [XCTestObservation]? = nil
+) -> CInt {
+    let observers = observers ?? [PrintObserver()]
     let testBundle = Bundle.main
 
     let executionMode = ArgumentParser(arguments: arguments).executionMode
@@ -99,10 +103,10 @@ public func XCTMain(
     switch executionMode {
     case .list(type: .humanReadable):
         TestListing(testSuite: rootTestSuite).printTestList()
-        exit(EXIT_SUCCESS)
+        return EXIT_SUCCESS
     case .list(type: .json):
         TestListing(testSuite: rootTestSuite).printTestJSON()
-        exit(EXIT_SUCCESS)
+        return EXIT_SUCCESS
     case let .help(invalidOption):
         if let invalid = invalidOption {
             let errMsg = "Error: Invalid option \"\(invalid)\"\n"
@@ -133,7 +137,7 @@ public func XCTMain(
 
                      > \(exeName) \(sampleTests)
               """)
-        exit(invalidOption == nil ? EXIT_SUCCESS : EXIT_FAILURE)
+        return invalidOption == nil ? EXIT_SUCCESS : EXIT_FAILURE
     case .run(selectedTestNames: _):
         // Add a test observer that prints test progress to stdout.
         let observationCenter = XCTestObservationCenter.shared
@@ -145,6 +149,25 @@ public func XCTMain(
         rootTestSuite.run()
         observationCenter.testBundleDidFinish(testBundle)
 
-        exit(rootTestSuite.testRun!.totalFailureCount == 0 ? EXIT_SUCCESS : EXIT_FAILURE)
+        return rootTestSuite.testRun!.totalFailureCount == 0 ? EXIT_SUCCESS : EXIT_FAILURE
     }
 }
+
+// @available(*, deprecated, message: "Call the overload of XCTMain() that returns an exit code instead.")
+public func XCTMain(_ testCases: [XCTestCaseEntry]) -> Never {
+    exit(XCTMain(testCases, arguments: CommandLine.arguments, observers: nil) as CInt)
+}
+
+// @available(*, deprecated, message: "Call the overload of XCTMain() that returns an exit code instead.")
+public func XCTMain(_ testCases: [XCTestCaseEntry], arguments: [String]) -> Never {
+    exit(XCTMain(testCases, arguments: arguments, observers: nil) as CInt)
+}
+
+// @available(*, deprecated, message: "Call the overload of XCTMain() that returns an exit code instead.")
+public func XCTMain(
+    _ testCases: [XCTestCaseEntry],
+    arguments: [String],
+    observers: [XCTestObservation]
+) -> Never {
+    exit(XCTMain(testCases, arguments: arguments, observers: observers) as CInt)
+}