Ensure that a CustomExecutionTrait's teardown logic occurs _after_ nested tests run. (#526)

This PR reorders operations in `Runner` such that a test with a custom
execution trait will execute operations in this order:

1. Custom execution trait "before" logic;
1. Test logic;
1. Child test logic; and finally
1. Custom execution trait "after" logic.

There is currently a bug here where child test logic runs _after_ the
custom execution trait runs its "after" logic, which is not intentional.

Resolves rdar://125115497.

### 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/Running/Runner.swift

@@ -209,11 +209,33 @@ extension Runner {
             if let testCases = step.test.testCases {
               try await _runTestCases(testCases, within: step)
             }
+
+            // Run the children of this test (i.e. the tests in this suite.)
+            try await _runChildren(of: stepGraph, depth: depth, lastAncestorStep: lastAncestorStep)
           }
         }
       }
+    } else {
+      // There is no test at this node in the graph, so just skip down to the
+      // child nodes.
+      try await _runChildren(of: stepGraph, depth: depth, lastAncestorStep: lastAncestorStep)
     }
+  }
 
+  /// Recursively run the tests that are children of a given plan step.
+  ///
+  /// - Parameters:
+  ///   - stepGraph: The subgraph whose root value, a step, is to be run.
+  ///   - depth: How deep into the step graph this call is. The first call has a
+  ///     depth of `0`.
+  ///   - lastAncestorStep: The last-known ancestral step, if any, of the step
+  ///     at the root of `stepGraph`. The options in this step (if its action is
+  ///     of case ``Runner/Plan/Action/run(options:)``) inform the execution of
+  ///     `stepGraph`.
+  ///
+  /// - Throws: Whatever is thrown from the test body. Thrown errors are
+  ///   normally reported as test failures.
+  private func _runChildren(of stepGraph: Graph<String, Plan.Step?>, depth: Int, lastAncestorStep: Plan.Step?) async throws {
     // Figure out the last-good step, either the one at the root of `stepGraph`
     // or, if it is nil, the one passed into this function. We need to track
     // this value in case we run into sparse sections of the graph so we don't

Tests/TestingTests/Traits/CustomExecutionTraitTests.swift

@@ -10,26 +10,6 @@
 
 @testable @_spi(Experimental) @_spi(ForToolsIntegrationOnly) import Testing
 
-private struct CustomTrait: CustomExecutionTrait, TestTrait {
-  var before: Confirmation
-  var after: Confirmation
-  func execute(_ function: @escaping @Sendable () async throws -> Void, for test: Test, testCase: Test.Case?) async throws {
-    before()
-    defer {
-      after()
-    }
-    try await function()
-  }
-}
-
-private struct CustomThrowingErrorTrait: CustomExecutionTrait, TestTrait {
-  fileprivate struct CustomTraitError: Error {}
-
-  func execute(_ function: @escaping @Sendable () async throws -> Void, for test: Test, testCase: Test.Case?) async throws {
-    throw CustomTraitError()
-  }
-}
-
 @Suite("CustomExecutionTrait Tests")
 struct CustomExecutionTraitTests {
   @Test("Execute code before and after a non-parameterized test.")
@@ -76,4 +56,49 @@ struct CustomExecutionTraitTests {
       }.run(configuration: configuration)
     }
   }
+
+  @Test("Teardown occurs after child tests run")
+  func teardownOccursAtEnd() async throws {
+    await runTest(for: TestsWithCustomTraitWithStrongOrdering.self, configuration: .init())
+  }
+}
+
+// MARK: - Fixtures
+
+private struct CustomTrait: CustomExecutionTrait, TestTrait {
+  var before: Confirmation
+  var after: Confirmation
+  func execute(_ function: @escaping @Sendable () async throws -> Void, for test: Test, testCase: Test.Case?) async throws {
+    before()
+    defer {
+      after()
+    }
+    try await function()
+  }
+}
+
+private struct CustomThrowingErrorTrait: CustomExecutionTrait, TestTrait {
+  fileprivate struct CustomTraitError: Error {}
+
+  func execute(_ function: @escaping @Sendable () async throws -> Void, for test: Test, testCase: Test.Case?) async throws {
+    throw CustomTraitError()
+  }
+}
+
+struct DoSomethingBeforeAndAfterTrait: CustomExecutionTrait, SuiteTrait, TestTrait {
+  static let state = Locked(rawValue: 0)
+
+  func execute(_ function: @escaping @Sendable () async throws -> Void, for test: Testing.Test, testCase: Testing.Test.Case?) async throws {
+    #expect(Self.state.increment() == 1)
+
+    try await function()
+    #expect(Self.state.increment() == 3)
+  }
+}
+
+@Suite(.hidden, DoSomethingBeforeAndAfterTrait())
+struct TestsWithCustomTraitWithStrongOrdering {
+  @Test(.hidden) func f() async {
+    #expect(DoSomethingBeforeAndAfterTrait.state.increment() == 2)
+  }
 }