Add task names to structured tasks we create. (#1305)

This PR sets a task name for every child task created by Swift Testing.
These names are useful for debugging.

Example result:

<img width="440" height="132" alt="Screenshot 2025-09-10 at 11 49 42 AM"
src="https://github.com/user-attachments/assets/691d7e60-1fdc-4b31-bae7-baa99948123c"
/>

Resolves #1303.

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

---------

Co-authored-by: Stuart Montgomery <[email protected]>

Author: grynspan

Sources/Testing/CMakeLists.txt

@@ -76,6 +76,7 @@ add_library(Testing
   Support/Additions/CommandLineAdditions.swift
   Support/Additions/NumericAdditions.swift
   Support/Additions/ResultAdditions.swift
+  Support/Additions/TaskAdditions.swift
   Support/Additions/WinSDKAdditions.swift
   Support/CartesianProduct.swift
   Support/CError.swift

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

@@ -187,6 +187,26 @@ private func _capitalizedTitle(for test: Test?) -> String {
   test?.isSuite == true ? "Suite" : "Test"
 }
 
+extension Test {
+  /// The name to use for this test in a human-readable context such as console
+  /// output.
+  ///
+  /// - Parameters:
+  ///   - verbosity: The verbosity with which to describe this test.
+  ///
+  /// - Returns: The name of this test, suitable for display to the user.
+  func humanReadableName(withVerbosity verbosity: Int = 0) -> String {
+    switch displayName {
+    case let .some(displayName) where verbosity > 0:
+      #""\#(displayName)" (aka '\#(name)')"#
+    case let .some(displayName):
+      #""\#(displayName)""#
+    default:
+      name
+    }
+  }
+}
+
 extension Test.Case {
   /// The arguments of this test case, formatted for presentation, prefixed by
   /// their corresponding parameter label when available.
@@ -256,19 +276,7 @@ extension Event.HumanReadableOutputRecorder {
     let test = eventContext.test
     let testCase = eventContext.testCase
     let keyPath = eventContext.keyPath
-    let testName = if let test {
-      if let displayName = test.displayName {
-        if verbosity > 0 {
-          "\"\(displayName)\" (aka '\(test.name)')"
-        } else {
-          "\"\(displayName)\""
-        }
-      } else {
-        test.name
-      }
-    } else {
-      "«unknown»"
-    }
+    let testName = test?.humanReadableName(withVerbosity: verbosity) ?? "«unknown»"
     let instant = event.instant
     let iterationCount = eventContext.configuration?.repetitionPolicy.maximumIterationCount
 

Sources/Testing/ExitTests/ExitTest.swift

@@ -955,22 +955,22 @@ extension ExitTest {
         capturedValuesWriteEnd.close()
 
         // Await termination of the child process.
-        taskGroup.addTask {
+        taskGroup.addTask(name: decorateTaskName("exit test", withAction: "awaiting termination")) {
           let exitStatus = try await wait(for: processID)
           return { $0.exitStatus = exitStatus }
         }
 
         // Read back the stdout and stderr streams.
         if let stdoutReadEnd {
           stdoutWriteEnd?.close()
-          taskGroup.addTask {
+          taskGroup.addTask(name: decorateTaskName("exit test", withAction: "reading stdout")) {
             let standardOutputContent = try Self._trimToBarrierValues(stdoutReadEnd.readToEnd())
             return { $0.standardOutputContent = standardOutputContent }
           }
         }
         if let stderrReadEnd {
           stderrWriteEnd?.close()
-          taskGroup.addTask {
+          taskGroup.addTask(name: decorateTaskName("exit test", withAction: "reading stderr")) {
             let standardErrorContent = try Self._trimToBarrierValues(stderrReadEnd.readToEnd())
             return { $0.standardErrorContent = standardErrorContent }
           }
@@ -979,7 +979,7 @@ extension ExitTest {
         // Read back all data written to the back channel by the child process
         // and process it as a (minimal) event stream.
         backChannelWriteEnd.close()
-        taskGroup.addTask {
+        taskGroup.addTask(name: decorateTaskName("exit test", withAction: "processing events")) {
           Self._processRecords(fromBackChannel: backChannelReadEnd)
           return nil
         }

Sources/Testing/Running/Runner.Plan.swift

@@ -213,7 +213,14 @@ extension Runner.Plan {
     // FIXME: Parallelize this work. Calling `prepare(...)` on all traits and
     // evaluating all test arguments should be safely parallelizable.
     (test, result) = await withTaskGroup(returning: (Test, Action).self) { [test] taskGroup in
-      taskGroup.addTask {
+      let testName = test.humanReadableName()
+      let (taskName, taskAction) = if test.isSuite {
+        ("suite \(testName)", "evaluating traits")
+      } else {
+        // TODO: split the task group's single task into two serially-run subtasks
+        ("test \(testName)", "evaluating traits and test cases")
+      }
+      taskGroup.addTask(name: decorateTaskName(taskName, withAction: taskAction)) {
         var test = test
         var action = _runAction
 

Sources/Testing/Running/Runner.swift

@@ -149,17 +149,21 @@ extension Runner {
   ///
   /// - Parameters:
   ///   - sequence: The sequence to enumerate.
+  ///   - taskNamer: A function to invoke for each element in `sequence`. The
+  ///     result of this function is used to name each child task.
   ///   - body: The function to invoke.
   ///
   /// - Throws: Whatever is thrown by `body`.
   private static func _forEach<E>(
     in sequence: some Sequence<E>,
-    _ body: @Sendable @escaping (E) async throws -> Void
+    namingTasksWith taskNamer: (borrowing E) -> (taskName: String, action: String?)?,
+    _ body: @Sendable @escaping (borrowing E) async throws -> Void
   ) async rethrows where E: Sendable {
     try await withThrowingTaskGroup { taskGroup in
       for element in sequence {
         // Each element gets its own subtask to run in.
-        taskGroup.addTask {
+        let taskName = taskNamer(element)
+        taskGroup.addTask(name: decorateTaskName(taskName?.taskName, withAction: taskName?.action)) {
           try await body(element)
         }
 
@@ -314,8 +318,19 @@ extension Runner {
       }
     }
 
+    // Figure out how to name child tasks.
+    func taskNamer(_ childGraph: Graph<String, Plan.Step?>) -> (String, String?)? {
+      childGraph.value.map { step in
+        let testName = step.test.humanReadableName()
+        if step.test.isSuite {
+          return ("suite \(testName)", "running")
+        }
+        return ("test \(testName)", nil) // test cases have " - running" suffix
+      }
+    }
+
     // Run the child nodes.
-    try await _forEach(in: childGraphs) { _, childGraph in
+    try await _forEach(in: childGraphs.lazy.map(\.value), namingTasksWith: taskNamer) { childGraph in
       try await _runStep(atRootOf: childGraph)
     }
   }
@@ -335,7 +350,15 @@ extension Runner {
       testCaseFilter(testCase, step.test)
     }
 
-    await _forEach(in: testCases) { testCase in
+    // Figure out how to name child tasks.
+    let testName = "test \(step.test.humanReadableName())"
+    let taskNamer: (Int, Test.Case) -> (String, String?)? = if step.test.isParameterized {
+      { i, _ in (testName, "running test case #\(i + 1)") }
+    } else {
+      { _, _ in (testName, "running") }
+    }
+
+    await _forEach(in: testCases.enumerated(), namingTasksWith: taskNamer) { _, testCase in
       await _runTestCase(testCase, within: step)
     }
   }
@@ -418,14 +441,19 @@ extension Runner {
       }
 
       let repetitionPolicy = runner.configuration.repetitionPolicy
-      for iterationIndex in 0 ..< repetitionPolicy.maximumIterationCount {
+      let iterationCount = repetitionPolicy.maximumIterationCount
+      for iterationIndex in 0 ..< iterationCount {
         Event.post(.iterationStarted(iterationIndex), for: (nil, nil), configuration: runner.configuration)
         defer {
           Event.post(.iterationEnded(iterationIndex), for: (nil, nil), configuration: runner.configuration)
         }
 
         await withTaskGroup { [runner] taskGroup in
-          _ = taskGroup.addTaskUnlessCancelled {
+          var taskAction: String?
+          if iterationCount > 1 {
+            taskAction = "running iteration #\(iterationIndex + 1)"
+          }
+          _ = taskGroup.addTaskUnlessCancelled(name: decorateTaskName("test run", withAction: taskAction)) {
             try? await _runStep(atRootOf: runner.plan.stepGraph)
           }
           await taskGroup.waitForAll()

Sources/Testing/Support/Additions/TaskAdditions.swift

@@ -0,0 +1,27 @@
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 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
+//
+
+/// Make a (decorated) task name from the given undecorated task name.
+///
+/// - Parameters:
+///   - taskName: The undecorated task name to modify.
+///
+/// - Returns: A copy of `taskName` with a common prefix applied, or `nil` if
+///   `taskName` was `nil`.
+func decorateTaskName(_ taskName: String?, withAction action: String?) -> String? {
+  let prefix = "[Swift Testing]"
+  return taskName.map { taskName in
+#if DEBUG
+    precondition(!taskName.hasPrefix(prefix), "Applied prefix '\(prefix)' to task name '\(taskName)' twice. Please file a bug report at https://github.com/swiftlang/swift-testing/issues/new")
+#endif
+    let action = action.map { " - \($0)" } ?? ""
+    return "\(prefix) \(taskName)\(action)"
+  }
+}

Sources/Testing/Test+Discovery.swift

@@ -88,8 +88,10 @@ extension Test {
       if useNewMode {
         let generators = Generator.allTestContentRecords().lazy.compactMap { $0.load() }
         await withTaskGroup { taskGroup in
-          for generator in generators {
-            taskGroup.addTask { await generator.rawValue() }
+          for (i, generator) in generators.enumerated() {
+            taskGroup.addTask(name: decorateTaskName("test discovery", withAction: "loading test #\(i)")) {
+              await generator.rawValue()
+            }
           }
           result = await taskGroup.reduce(into: result) { $0.insert($1) }
         }
@@ -100,8 +102,10 @@ extension Test {
       if useLegacyMode && result.isEmpty {
         let generators = Generator.allTypeMetadataBasedTestContentRecords().lazy.compactMap { $0.load() }
         await withTaskGroup { taskGroup in
-          for generator in generators {
-            taskGroup.addTask { await generator.rawValue() }
+          for (i, generator) in generators.enumerated() {
+            taskGroup.addTask(name: decorateTaskName("type-based test discovery", withAction: "loading test #\(i)")) {
+              await generator.rawValue()
+            }
           }
           result = await taskGroup.reduce(into: result) { $0.insert($1) }
         }

Sources/Testing/Traits/TimeLimitTrait.swift

@@ -264,6 +264,7 @@ struct TimeoutError: Error, CustomStringConvertible {
 ///
 /// - Parameters:
 ///   - timeLimit: The amount of time until the closure times out.
+///   - taskName: The name of the child task that runs `body`, if any.
 ///   - body: The function to invoke.
 ///   - timeoutHandler: A function to invoke if `body` times out.
 ///
@@ -277,18 +278,19 @@ struct TimeoutError: Error, CustomStringConvertible {
 @available(_clockAPI, *)
 func withTimeLimit(
   _ timeLimit: Duration,
+  taskName: String? = nil,
   _ body: @escaping @Sendable () async throws -> Void,
   timeoutHandler: @escaping @Sendable () -> Void
 ) async throws {
   try await withThrowingTaskGroup { group in
-    group.addTask {
+    group.addTask(name: decorateTaskName(taskName, withAction: "waiting for timeout")) {
       // If sleep() returns instead of throwing a CancellationError, that means
       // the timeout was reached before this task could be cancelled, so call
       // the timeout handler.
       try await Test.Clock.sleep(for: timeLimit)
       timeoutHandler()
     }
-    group.addTask(operation: body)
+    group.addTask(name: decorateTaskName(taskName, withAction: "running"), operation: body)
 
     defer {
       group.cancelAll()