Add support for swift test --quiet. (#421)

This PR adds support for `swift test --quiet` and generalizes various
"is verbose" checks into "verbosity level" checks instead.

Several of the properties of `__CommandLineArguments_v0` have been made
optional because they are not required to be specified (and should never
have been non-optional.)

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

@@ -22,7 +22,7 @@ func entryPoint(passing args: consuming __CommandLineArguments_v0?, eventHandler
 
   do {
     let args = try args ?? parseCommandLineArguments(from: CommandLine.arguments())
-    if args.listTests {
+    if args.listTests ?? true {
       for testID in await listTestsForEntryPoint(Test.all) {
 #if SWT_TARGET_OS_APPLE && !SWT_NO_FILE_IO
         try? FileHandle.stdout.write("\(testID)\n")
@@ -55,7 +55,7 @@ func entryPoint(passing args: consuming __CommandLineArguments_v0?, eventHandler
 #if !SWT_NO_FILE_IO
       var options = Event.ConsoleOutputRecorder.Options()
       options = .for(.stderr)
-      options.isVerbose = args.verbose
+      options.verbosity = args.verbosity
       let eventRecorder = Event.ConsoleOutputRecorder(options: options) { string in
         try? FileHandle.stderr.write(string)
       }
@@ -143,13 +143,49 @@ public struct __CommandLineArguments_v0: Sendable {
   public init() {}
 
   /// The value of the `--list-tests` argument.
-  public var listTests = false
+  public var listTests: Bool? = false
 
   /// The value of the `--parallel` or `--no-parallel` argument.
-  public var parallel = true
+  public var parallel: Bool? = true
 
   /// The value of the `--verbose` argument.
-  public var verbose = false
+  public var verbose: Bool? = false
+
+  /// The value of the `--very-verbose` argument.
+  public var veryVerbose: Bool? = false
+
+  /// The value of the `--quiet` argument.
+  public var quiet: Bool? = false
+
+  /// Storage for the ``verbosity`` property.
+  private var _verbosity: Int?
+
+  /// The value of the `--verbosity` argument.
+  ///
+  /// The value of this property may be synthesized from the `--verbose`,
+  /// `--very-verbose`, or `--quiet` arguments.
+  ///
+  /// When the value of this property is greater than `0`, additional output
+  /// is provided. When the value of this property is less than `0`, some
+  /// output is suppressed. The exact effects of this property are
+  /// implementation-defined and subject to change.
+  public var verbosity: Int {
+    get {
+      if let _verbosity {
+        return _verbosity
+      } else if veryVerbose == true {
+        return 2
+      } else if verbose == true {
+        return 1
+      } else if quiet == true {
+        return -1
+      }
+      return 0
+    }
+    set {
+      _verbosity = newValue
+    }
+  }
 
   /// The value of the `--xunit-output` argument.
   public var xunitOutput: String?
@@ -201,7 +237,26 @@ public struct __CommandLineArguments_v0: Sendable {
   var xcTestCaseHostIdentifier: String?
 }
 
-extension __CommandLineArguments_v0: Codable {}
+extension __CommandLineArguments_v0: Codable {
+  // Explicitly list the coding keys so that storage properties like _verbosity
+  // do not end up with leading underscores when encoded.
+  enum CodingKeys: String, CodingKey {
+    case listTests
+    case parallel
+    case verbose
+    case veryVerbose
+    case quiet
+    case _verbosity = "verbosity"
+    case xunitOutput
+    case experimentalEventStreamOutput
+    case experimentalEventStreamVersion
+    case filter
+    case skip
+    case repetitions
+    case repeatUntil
+    case xcTestCaseHostIdentifier
+  }
+}
 
 /// Initialize this instance given a sequence of command-line arguments passed
 /// from Swift Package Manager.
@@ -268,9 +323,20 @@ func parseCommandLineArguments(from args: [String]) throws -> __CommandLineArgum
     result.parallel = false
   }
 
-  if args.contains("--verbose") || args.contains("-v") || args.contains("--very-verbose") || args.contains("--vv") {
+  // Verbosity
+  if let verbosityIndex = args.firstIndex(of: "--verbosity"), !isLastArgument(at: verbosityIndex),
+     let verbosity = Int(args[args.index(after: verbosityIndex)]) {
+    result.verbosity = verbosity
+  }
+  if args.contains("--verbose") || args.contains("-v") {
     result.verbose = true
   }
+  if args.contains("--very-verbose") || args.contains("--vv") {
+    result.veryVerbose = true
+  }
+  if args.contains("--quiet") || args.contains("-q") {
+    result.quiet = true
+  }
 
   // Filtering
   func filterValues(forArgumentsWithLabel label: String) -> [String] {
@@ -308,7 +374,7 @@ public func configurationForEntryPoint(from args: __CommandLineArguments_v0) thr
   var configuration = Configuration()
 
   // Parallelization (on by default)
-  configuration.isParallelizationEnabled = args.parallel
+  configuration.isParallelizationEnabled = args.parallel ?? true
 
 #if !SWT_NO_FILE_IO
   // XML output

Sources/Testing/EntryPoints/SwiftPMEntryPoint.swift

@@ -25,7 +25,7 @@ private import _TestingInternals
 ///
 /// - 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 {
+public func __swiftPMEntryPoint(passing args: __CommandLineArguments_v0? = nil) async -> CInt {
   await entryPoint(passing: args, eventHandler: nil)
 }
 

Sources/Testing/EntryPoints/XCTestScaffold.swift

@@ -106,6 +106,11 @@ public enum XCTestScaffold: Sendable {
   /// Private Use Area. To disable the use of SF Symbols on macOS, set the
   /// `SWT_SF_SYMBOLS_ENABLED` environment variable to `"false"` or `"0"`.
   ///
+  /// To adjust the verbosity of output, set the `SWT_VERBOSITY` environment
+  /// variable to an integer value greater or less than `0` (the default level.)
+  /// ``XCTestScaffold`` does not support the `--verbose`, `--very-verbose`, or
+  /// `--quiet` command-line arguments passed to `swift test`.
+  ///
   /// ## See Also
   ///
   /// - <doc:TemporaryGettingStarted>
@@ -135,7 +140,9 @@ public enum XCTestScaffold: Sendable {
 
     var args = __CommandLineArguments_v0()
     args.parallel = false
-    args.verbose = (Environment.flag(named: "SWT_VERBOSE_OUTPUT") == true)
+    if let verbosity = Environment.variable(named: "SWT_VERBOSITY").flatMap(Int.init) {
+      args.verbosity = verbosity
+    }
 
     // Specify the hosting XCTestCase instance. This value is currently only
     // used for exit tests.

Sources/Testing/Events/Recorder/Event.ConsoleOutputRecorder.swift

@@ -59,12 +59,13 @@ extension Event {
       public var useSFSymbols = false
 #endif
 
-      /// Whether or not to record verbose output.
+      /// The level of verbosity of the output.
       ///
-      /// When the value of this property is `true`, additional output is
-      /// provided. The exact nature of the additional output is
+      /// When the value of this property is greater than `0`, additional output
+      /// is provided. When the value of this property is less than `0`, some
+      /// output is suppressed. The exact effects of this property are
       /// implementation-defined and subject to change.
-      public var isVerbose = false
+      public var verbosity = 0
 
       /// Storage for ``tagColors``.
       private var _tagColors = Tag.Color.predefined
@@ -306,7 +307,7 @@ extension Event.ConsoleOutputRecorder {
   /// - Returns: Whether any output was produced and written to this instance's
   ///   destination.
   @discardableResult public func record(_ event: borrowing Event, in context: borrowing Event.Context) -> Bool {
-    let messages = _humanReadableOutputRecorder.record(event, in: context, verbosely: options.isVerbose)
+    let messages = _humanReadableOutputRecorder.record(event, in: context, verbosity: options.verbosity)
     for message in messages {
       let symbol = message.symbol?.stringValue(options: options) ?? " "