Serialization traits for data dependencies

Documentation/EnvironmentVariables.md

@@ -63,4 +63,5 @@ names prefixed with `SWT_`.
 | `HOME`[\*](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html) | `String` | Used to determine the user's home directory. |
 | `SIMULATOR_RUNTIME_BUILD_VERSION`\* | `String` | Used when running in the iOS (etc.) Simulator to determine the simulator's version. |
 | `SIMULATOR_RUNTIME_VERSION`\* | `String` | Used when running in the iOS (etc.) Simulator to determine the simulator's version. |
+| `SWT_SERIALIZED_TRAIT_APPLIES_GLOBALLY` | `Bool` | Whether or not `.serialized` applies globally or just to its branch of the test graph. |
 | `SWT_USE_LEGACY_TEST_DISCOVERY` | `Bool` | Used to explicitly enable or disable legacy test discovery. |

Sources/Testing/CMakeLists.txt

@@ -119,6 +119,7 @@ add_library(Testing
   Traits/HiddenTrait.swift
   Traits/IssueHandlingTrait.swift
   Traits/ParallelizationTrait.swift
+  Traits/ReducibleTrait.swift
   Traits/Tags/Tag.Color.swift
   Traits/Tags/Tag.Color+Loading.swift
   Traits/Tags/Tag.List.swift

Sources/Testing/Running/Runner.Plan.swift

@@ -147,6 +147,46 @@ extension Runner.Plan {
     }
   }
 
+  /// Recursively deduplicate traits on the given test by calling
+  /// ``ReducibleTrait/reduce(_:)`` across all nodes in the graph.
+  ///
+  /// - Parameters:
+  ///   - testGraph: The graph of tests to modify.
+  private static func _recursivelyReduceTraits(in testGraph: inout Graph<String, Test?>) {
+    testGraph = testGraph.mapValues { _, test in
+      guard var test else {
+        return nil
+      }
+
+      var traits = test.traits.map { $0 as Optional }
+      for i in traits.indices {
+        guard var trait = traits[i] as? any ReducibleTrait else {
+          // The trait is not reducible, so preserve it verbatim and move on.
+          continue
+        }
+        defer {
+          traits[i] = trait
+        }
+
+        func open<T>(_ trait: inout T) where T: ReducibleTrait {
+          for j in traits.index(after: i) ..< traits.endIndex {
+            if let other = traits[j] as? T,
+               let replacement = other.reduce(into: trait) {
+              // Reduction occurred, so remove the other trait and replace this one
+              // with the reduced trait.
+              trait = replacement
+              traits[j] = nil
+            }
+          }
+        }
+        open(&trait)
+      }
+      test.traits = traits.compactMap(\.self)
+
+      return test
+    }
+  }
+
   /// Recursively synthesize test instances representing suites for all missing
   /// values in the specified test graph.
   ///
@@ -356,6 +396,12 @@ extension Runner.Plan {
     // filtered out.
     _recursivelyApplyTraits(to: &testGraph)
 
+    // Recursively reduce traits in the graph.
+    //
+    // As with `_recursivelyApplyTraits(to:)`, we must call this function before
+    // calling `prepare(for:)` to ensure correct operation.
+    _recursivelyReduceTraits(in: &testGraph)
+
     // For each test value, determine the appropriate action for it.
     testGraph = await testGraph.mapValues { keyPath, test in
       // Skip any nil test, which implies this node is just a placeholder and

Sources/Testing/Running/Runner.swift

@@ -196,6 +196,61 @@ extension Runner {
     }
   }
 
+  /// Post `testStarted` and `testEnded` (or `testSkipped`) events for the test
+  /// at the given plan step.
+  ///
+  /// - Parameters:
+  ///   - step: The plan step for which events should be posted.
+  ///   - configuration: The configuration to use for running.
+  ///   - context: Context for the test run.
+  ///   - body: A function to execute between the started/ended events.
+  ///
+  /// - Throws: Whatever is thrown by `body` or while handling any issues
+  ///   recorded in the process.
+  ///
+  /// - Returns: Whatever is returned by `body`.
+  ///
+  /// This function does _not_ post the `planStepStarted` and `planStepEnded`
+  /// events.
+  private static func _postingTestStartedAndEndedEvents<R>(for step: Plan.Step, configuration: Configuration, context: _Context, _ body: @Sendable () async throws -> R) async throws -> R {
+    // Whether to send a `.testEnded` event at the end of running this step.
+    // Some steps' actions may not require a final event to be sent — for
+    // example, a skip event only sends `.testSkipped`.
+    let shouldSendTestEnded: Bool
+
+    // Determine what kind of event to send for this step based on its action.
+    switch step.action {
+    case .run:
+      Event.post(.testStarted, for: (step.test, nil), iteration: context.iteration, configuration: configuration)
+      shouldSendTestEnded = true
+    case let .skip(skipInfo):
+      Event.post(.testSkipped(skipInfo), for: (step.test, nil), iteration: context.iteration, configuration: configuration)
+      shouldSendTestEnded = false
+    case let .recordIssue(issue):
+      // Scope posting the issue recorded event such that issue handling
+      // traits have the opportunity to handle it. This ensures that if a test
+      // has an issue handling trait _and_ some other trait which caused an
+      // issue to be recorded, the issue handling trait can process the issue
+      // even though it wasn't recorded by the test function.
+      try await Test.withCurrent(step.test) {
+        try await _applyIssueHandlingTraits(for: step.test) {
+          // Don't specify `configuration` when posting this issue so that
+          // traits can provide scope and potentially customize the
+          // configuration.
+          Event.post(.issueRecorded(issue), for: (step.test, nil))
+        }
+      }
+      shouldSendTestEnded = false
+    }
+    defer {
+      if shouldSendTestEnded {
+        Event.post(.testEnded, for: (step.test, nil), iteration: context.iteration, configuration: configuration)
+      }
+    }
+
+    return try await body()
+  }
+
   /// Run this test.
   ///
   /// - Parameters:
@@ -216,67 +271,40 @@ extension Runner {
   ///
   /// - ``Runner/run()``
   private static func _runStep(atRootOf stepGraph: Graph<String, Plan.Step?>, context: _Context) async throws {
-    // Whether to send a `.testEnded` event at the end of running this step.
-    // Some steps' actions may not require a final event to be sent — for
-    // example, a skip event only sends `.testSkipped`.
-    let shouldSendTestEnded: Bool
+    // Exit early if the task has already been cancelled.
+    try Task.checkCancellation()
 
-    let configuration = _configuration
-
-    // Determine what action to take for this step.
     if let step = stepGraph.value {
+      let configuration = _configuration
       Event.post(.planStepStarted(step), for: (step.test, nil), configuration: configuration)
-
-      // Determine what kind of event to send for this step based on its action.
-      switch step.action {
-      case .run:
-        Event.post(.testStarted, for: (step.test, nil), iteration: context.iteration, configuration: configuration)
-        shouldSendTestEnded = true
-      case let .skip(skipInfo):
-        Event.post(.testSkipped(skipInfo), for: (step.test, nil), iteration: context.iteration, configuration: configuration)
-        shouldSendTestEnded = false
-      case let .recordIssue(issue):
-        // Scope posting the issue recorded event such that issue handling
-        // traits have the opportunity to handle it. This ensures that if a test
-        // has an issue handling trait _and_ some other trait which caused an
-        // issue to be recorded, the issue handling trait can process the issue
-        // even though it wasn't recorded by the test function.
-        try await Test.withCurrent(step.test) {
-          try await _applyIssueHandlingTraits(for: step.test) {
-            // Don't specify `configuration` when posting this issue so that
-            // traits can provide scope and potentially customize the
-            // configuration.
-            Event.post(.issueRecorded(issue), for: (step.test, nil))
-          }
-        }
-        shouldSendTestEnded = false
-      }
-    } else {
-      shouldSendTestEnded = false
-    }
-    defer {
-      if let step = stepGraph.value {
-        if shouldSendTestEnded {
-          Event.post(.testEnded, for: (step.test, nil), iteration: context.iteration, configuration: configuration)
-        }
+      defer {
         Event.post(.planStepEnded(step), for: (step.test, nil), configuration: configuration)
       }
-    }
 
-    if let step = stepGraph.value, case .run = step.action {
       await Test.withCurrent(step.test) {
         _ = await Issue.withErrorRecording(at: step.test.sourceLocation, configuration: configuration) {
           // Exit early if the task has already been cancelled.
           try Task.checkCancellation()
 
-          try await _applyScopingTraits(for: step.test, testCase: nil) {
-            // Run the test function at this step (if one is present.)
-            if let testCases = step.test.testCases {
-              await _runTestCases(testCases, within: step, context: context)
+          switch step.action {
+          case .run:
+            try await _applyScopingTraits(for: step.test, testCase: nil) {
+              try await _postingTestStartedAndEndedEvents(for: step, configuration: configuration, context: context) {
+                // Run the test function at this step (if one is present.)
+                if let testCases = step.test.testCases {
+                  await _runTestCases(testCases, within: step, context: context)
+                }
+
+                // Run the children of this test (i.e. the tests in this suite.)
+                try await _runChildren(of: stepGraph, context: context)
+              }
+            }
+          default:
+            // Skipping this step or otherwise not running it. Post appropriate
+            // started/ended events for the test and walk any child nodes.
+            try await _postingTestStartedAndEndedEvents(for: step, configuration: configuration, context: context) {
+              try await _runChildren(of: stepGraph, context: context)
             }
-
-            // Run the children of this test (i.e. the tests in this suite.)
-            try await _runChildren(of: stepGraph, context: context)
           }
         }
       }

Sources/Testing/Support/Environment.swift

@@ -93,24 +93,41 @@ package enum Environment {
   }()
 #endif
 
+  /// The address of the environment block, if available.
+  ///
+  /// The value of this property is always `nil` on Windows and on platforms
+  /// that do not support environment variables.
+  static var unsafeAddress: UnsafeMutablePointer<UnsafeMutablePointer<CChar>?>? {
+#if SWT_NO_ENVIRONMENT_VARIABLES
+    nil
+#elseif SWT_TARGET_OS_APPLE
+    _NSGetEnviron()?.pointee
+#elseif os(Linux) || os(FreeBSD) || os(OpenBSD) || os(Android)
+    swt_environ()
+#elseif os(WASI)
+    __wasilibc_get_environ()
+#elseif os(Windows)
+    nil
+#else
+#warning("Platform-specific implementation missing: environment variables unavailable")
+    nil
+#endif
+  }
+
   /// Get all environment variables in the current process.
   ///
   /// - Returns: A copy of the current process' environment dictionary.
   package static func get() -> [String: String] {
 #if SWT_NO_ENVIRONMENT_VARIABLES
     simulatedEnvironment.rawValue
-#elseif SWT_TARGET_OS_APPLE
-#if !SWT_NO_DYNAMIC_LINKING
+#elseif SWT_TARGET_OS_APPLE || os(Linux) || os(FreeBSD) || os(OpenBSD) || os(Android) || os(WASI)
+#if SWT_TARGET_OS_APPLE && !SWT_NO_DYNAMIC_LINKING
     _environ_lock_np?()
     defer {
       _environ_unlock_np?()
     }
 #endif
-    return _get(fromEnviron: _NSGetEnviron()!.pointee!)
-#elseif os(Linux) || os(FreeBSD) || os(OpenBSD) || os(Android)
-    _get(fromEnviron: swt_environ())
-#elseif os(WASI)
-    _get(fromEnviron: __wasilibc_get_environ())
+    return _get(fromEnviron: Self.unsafeAddress!)
 #elseif os(Windows)
     guard let environ = GetEnvironmentStringsW() else {
       return [:]
@@ -157,7 +174,9 @@ package enum Environment {
     defer {
       _environ_unlock_np?()
     }
-    let environ = _NSGetEnviron()!.pointee!
+    guard let environ = Self.unsafeAddress else {
+      return nil
+    }
 
     return name.withCString { name in
       for i in 0... {

Sources/Testing/Support/Serializer.swift

@@ -77,6 +77,9 @@ final actor Serializer<T> {
   /// - Returns: Whatever is returned from `workItem`.
   ///
   /// - Throws: Whatever is thrown by `workItem`.
+  ///
+  /// - Warning: Calling this function recursively on the same instance of
+  ///   ``Serializer`` will cause a deadlock.
   func run<R>(_ workItem: @isolated(any) @Sendable () async throws -> R) async rethrows -> R where R: Sendable {
 #if !SWT_NO_UNSTRUCTURED_TASKS
     _currentWidth += 1
@@ -105,4 +108,3 @@ final actor Serializer<T> {
     return try await workItem()
   }
 }
-

Sources/Testing/Testing.docc/Parallelization.md

@@ -19,6 +19,8 @@ accomplished by the testing library using task groups, and tests generally all
 run in the same process. The number of tests that run concurrently is controlled
 by the Swift runtime.
 
+<!-- TODO: discuss .serialized(for:) -->
+
 ## Disabling parallelization
 
 Parallelization can be disabled on a per-function or per-suite basis using the