Only accept minute-granularity test time limit durations (#391)

This introduces a distinct type constraining the acceptable granularity
of `.timeLimit()` to minutes, and also improves API documentation around
test timeouts.

### Motivation:

The testing library is not capable of properly handling arbitrarily
short test time limit durations, such as `.seconds(1)` or
`.microseconds(20)`, due to variability in execution environments. Note
that the analogous XCTest API,
[`executionTimeAllowance`](https://developer.apple.com/documentation/xctest/xctestcase/3526064-executiontimeallowance?changes=lates_1),
behaves similarly.

### Modifications:

- Introduce a new `TimeLimitTrait.Duration` type which may only be
expressed in minutes, and change `.timeLimit(_:)` to accept this type
instead of `Swift.Duration`.
- Update existing documentation and add some new discussion about
limitations.
- Update tests.

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

Resolves rdar://122189336
Resolves rdar://122194368

Author: stmontgomery

Sources/Testing/Traits/TimeLimitTrait.swift

@@ -15,8 +15,32 @@
 /// - ``Trait/timeLimit(_:)``
 @available(_clockAPI, *)
 public struct TimeLimitTrait: TestTrait, SuiteTrait {
+  /// A type representing the duration of a time limit applied to a test.
+  ///
+  /// This type is intended for use specifically for specifying test timeouts
+  /// with ``TimeLimitTrait``. It is used instead of Swift's built-in `Duration`
+  /// type because test timeouts do not support high-precision, arbitrarily
+  /// short durations. The smallest allowed unit of time is minutes.
+  @_spi(Experimental)
+  public struct Duration: Sendable {
+    /// The underlying Swift `Duration` which this time limit duration
+    /// represents.
+    var underlyingDuration: Swift.Duration
+
+    /// Construct a time limit duration given a number of minutes.
+    ///
+    /// - Parameters:
+    ///   - minutes: The number of minutes the resulting duration should
+    ///     represent.
+    ///
+    /// - Returns: A duration representing the specified number of minutes.
+    public static func minutes(_ minutes: some BinaryInteger) -> Self {
+      Self(underlyingDuration: .seconds(60) * minutes)
+    }
+  }
+
   /// The maximum amount of time a test may run for before timing out.
-  public var timeLimit: Duration
+  public var timeLimit: Swift.Duration
 
   public var isRecursive: Bool {
     // Since test functions cannot be nested inside other test functions,
@@ -39,18 +63,123 @@ extension Trait where Self == TimeLimitTrait {
   ///
   /// - Returns: An instance of ``TimeLimitTrait``.
   ///
+  /// Test timeouts do not support high-precision, arbitrarily short durations
+  /// due to variability in testing environments. The time limit must be at
+  /// least one minute, and can only be expressed in increments of one minute.
+  ///
   /// When this trait is associated with a test, that test must complete within
   /// a time limit of, at most, `timeLimit`. If the test runs longer, an issue
   /// of kind ``Issue/Kind/timeLimitExceeded(timeLimitComponents:)`` is
   /// recorded. This timeout is treated as a test failure.
   ///
+  /// The time limit amount specified by `timeLimit` may be reduced if the
+  /// testing library is configured to enforce a maximum per-test limit. When
+  /// such a maximum is set, the effective time limit of the test this trait is
+  /// applied to will be the lesser of `timeLimit` and that maximum. This is a
+  /// policy which may be configured on a global basis by the tool responsible
+  /// for launching the test process. Refer to that tool's documentation for
+  /// more details.
+  ///
   /// If a test is parameterized, this time limit is applied to each of its
   /// test cases individually. If a test has more than one time limit associated
   /// with it, the shortest one is used. A test run may also be configured with
   /// a maximum time limit per test case.
   public static func timeLimit(_ timeLimit: Duration) -> Self {
     return Self(timeLimit: timeLimit)
   }
+
+  /// Construct a time limit trait that causes a test to time out if it runs for
+  /// too long.
+  ///
+  /// - Parameters:
+  ///   - timeLimit: The maximum amount of time the test may run for.
+  ///
+  /// - Returns: An instance of ``TimeLimitTrait``.
+  ///
+  /// Test timeouts do not support high-precision, arbitrarily short durations
+  /// due to variability in testing environments. The time limit must be at
+  /// least one minute, and can only be expressed in increments of one minute.
+  ///
+  /// When this trait is associated with a test, that test must complete within
+  /// a time limit of, at most, `timeLimit`. If the test runs longer, an issue
+  /// of kind ``Issue/Kind/timeLimitExceeded(timeLimitComponents:)`` is
+  /// recorded. This timeout is treated as a test failure.
+  ///
+  /// The time limit amount specified by `timeLimit` may be reduced if the
+  /// testing library is configured to enforce a maximum per-test limit. When
+  /// such a maximum is set, the effective time limit of the test this trait is
+  /// applied to will be the lesser of `timeLimit` and that maximum. This is a
+  /// policy which may be configured on a global basis by the tool responsible
+  /// for launching the test process. Refer to that tool's documentation for
+  /// more details.
+  ///
+  /// If a test is parameterized, this time limit is applied to each of its
+  /// test cases individually. If a test has more than one time limit associated
+  /// with it, the shortest one is used. A test run may also be configured with
+  /// a maximum time limit per test case.
+  @_spi(Experimental)
+  public static func timeLimit(_ timeLimit: Self.Duration) -> Self {
+    return Self(timeLimit: timeLimit.underlyingDuration)
+  }
+}
+
+@available(_clockAPI, *)
+extension TimeLimitTrait.Duration {
+  /// Construct a time limit duration given a number of seconds.
+  ///
+  /// This function is unavailable and is provided for diagnostic purposes only.
+  @available(*, unavailable, message: "Time limit must be specified in minutes")
+  public static func seconds(_ seconds: some BinaryInteger) -> Self {
+    fatalError("Unsupported")
+  }
+
+  /// Construct a time limit duration given a number of seconds.
+  ///
+  /// This function is unavailable and is provided for diagnostic purposes only.
+  @available(*, unavailable, message: "Time limit must be specified in minutes")
+  public static func seconds(_ seconds: Double) -> Self {
+    fatalError("Unsupported")
+  }
+
+  /// Construct a time limit duration given a number of milliseconds.
+  ///
+  /// This function is unavailable and is provided for diagnostic purposes only.
+  @available(*, unavailable, message: "Time limit must be specified in minutes")
+  public static func milliseconds(_ milliseconds: some BinaryInteger) -> Self {
+    fatalError("Unsupported")
+  }
+
+  /// Construct a time limit duration given a number of milliseconds.
+  ///
+  /// This function is unavailable and is provided for diagnostic purposes only.
+  @available(*, unavailable, message: "Time limit must be specified in minutes")
+  public static func milliseconds(_ milliseconds: Double) -> Self {
+    fatalError("Unsupported")
+  }
+
+  /// Construct a time limit duration given a number of microseconds.
+  ///
+  /// This function is unavailable and is provided for diagnostic purposes only.
+  @available(*, unavailable, message: "Time limit must be specified in minutes")
+  public static func microseconds(_ microseconds: some BinaryInteger) -> Self {
+    fatalError("Unsupported")
+  }
+
+  /// Construct a time limit duration given a number of microseconds.
+  ///
+  /// This function is unavailable and is provided for diagnostic purposes only.
+  @available(*, unavailable, message: "Time limit must be specified in minutes")
+  public static func microseconds(_ microseconds: Double) -> Self {
+    fatalError("Unsupported")
+  }
+
+  /// Construct a time limit duration given a number of nanoseconds.
+  ///
+  /// This function is unavailable and is provided for diagnostic purposes only.
+  @available(*, unavailable, message: "Time limit must be specified in minutes")
+  public static func nanoseconds(_ nanoseconds: some BinaryInteger) -> Self {
+    fatalError("Unsupported")
+  }
 }
 
 // MARK: -

Tests/TestingTests/Test.SnapshotTests.swift

@@ -8,7 +8,7 @@
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 //
 
-@_spi(ForToolsIntegrationOnly) @testable import Testing
+@_spi(Experimental) @_spi(ForToolsIntegrationOnly) @testable import Testing
 
 @Suite("Test.Snapshot tests")
 struct Test_SnapshotTests {
@@ -97,17 +97,12 @@ struct Test_SnapshotTests {
   private static let bug: Bug = Bug.bug(12345, "Lorem ipsum")
 
   @available(_clockAPI, *)
-  @Test("timeLimit property", .timeLimit(duration))
+  @Test("timeLimit property", .timeLimit(.minutes(999_999_999)))
   func timeLimit() async throws {
     let test = try #require(Test.current)
     let snapshot = Test.Snapshot(snapshotting: test)
 
-    #expect(snapshot.timeLimit == Self.duration)
-  }
-
-  @available(_clockAPI, *)
-  private static var duration: Duration {
-    .seconds(999_999_999)
+    #expect(snapshot.timeLimit == .seconds(60) * 999_999_999)
   }
 }
 

Tests/TestingTests/TestSupport/TestingAdditions.swift

@@ -364,3 +364,20 @@ extension JSON {
     }
   }
 }
+
+@available(_clockAPI, *)
+extension Trait where Self == TimeLimitTrait {
+  /// Construct a time limit trait that causes a test to time out if it runs for
+  /// too long.
+  ///
+  /// - Parameters:
+  ///   - timeLimit: The maximum amount of time the test may run for.
+  ///
+  /// - Returns: An instance of ``TimeLimitTrait``.
+  ///
+  /// This function is meant for use only in testing ``TimeLimitTrait`` itself,
+  /// and accepts any arbitrary Swift `Duration` value.
+  static func timeLimit(_ timeLimit: Swift.Duration) -> Self {
+    return Self(timeLimit: timeLimit)
+  }
+}

Tests/TestingTests/Traits/TimeLimitTraitTests.swift

@@ -15,36 +15,40 @@ struct TimeLimitTraitTests {
   @available(_clockAPI, *)
   @Test(".timeLimit() factory method")
   func timeLimitTrait() throws {
-    let test = Test(.timeLimit(.seconds(20))) {}
-    #expect(test.timeLimit == .seconds(20))
+    let test = Test(.timeLimit(.minutes(2))) {}
+    #expect(test.timeLimit == .seconds(60) * 2)
   }
 
   @available(_clockAPI, *)
   @Test("adjustedTimeLimit(configuration:) function")
   func adjustedTimeLimitMethod() throws {
-    for seconds in 1 ... 59 {
-      for milliseconds in 0 ... 100 {
-        let test = Test(.timeLimit(.seconds(seconds) + .milliseconds(milliseconds * 10))) {}
-        let adjustedTimeLimit = test.adjustedTimeLimit(configuration: .init())
-        #expect(adjustedTimeLimit == .seconds(60))
-      }
+    let oneHour = Duration.seconds(60 * 60)
+
+    var configuration = Configuration()
+    configuration.testTimeLimitGranularity = oneHour
+
+    for minutes in 1 ... 60 {
+      let test = Test(.timeLimit(.minutes(minutes))) {}
+      let adjustedTimeLimit = test.adjustedTimeLimit(configuration: configuration)
+      #expect(adjustedTimeLimit == oneHour)
     }
 
-    for seconds in 60 ... 119 {
-      let test = Test(.timeLimit(.seconds(seconds) + .milliseconds(1))) {}
-      let adjustedTimeLimit = test.adjustedTimeLimit(configuration: .init())
-      #expect(adjustedTimeLimit == .seconds(120))
+    for minutes in 61 ... 120 {
+      let test = Test(.timeLimit(.minutes(minutes))) {}
+      let adjustedTimeLimit = test.adjustedTimeLimit(configuration: configuration)
+      #expect(adjustedTimeLimit == oneHour * 2)
     }
   }
 
   @available(_clockAPI, *)
   @Test("Configuration.maximumTestTimeLimit property")
   func maximumTimeLimit() throws {
+    let tenMinutes = Duration.seconds(60 * 10)
     var configuration = Configuration()
-    configuration.maximumTestTimeLimit = .seconds(99)
-    let test = Test(.timeLimit(.seconds(100) + .milliseconds(100))) {}
+    configuration.maximumTestTimeLimit = tenMinutes
+    let test = Test(.timeLimit(.minutes(20))) {}
     let adjustedTimeLimit = test.adjustedTimeLimit(configuration: configuration)
-    #expect(adjustedTimeLimit == .seconds(99))
+    #expect(adjustedTimeLimit == tenMinutes)
   }
 
   @available(_clockAPI, *)
@@ -239,17 +243,17 @@ struct TimeLimitTraitTests {
 
 // MARK: - Fixtures
 
-func timeLimitIfAvailable(milliseconds: UInt64) -> any SuiteTrait {
+func timeLimitIfAvailable(minutes: UInt64) -> any SuiteTrait {
   // @available can't be applied to a suite type, so we can't mark the suite as
   // available only on newer OSes.
   if #available(_clockAPI, *) {
-    .timeLimit(.milliseconds(milliseconds))
+    .timeLimit(.minutes(minutes))
   } else {
     .disabled(".timeLimit() not available")
   }
 }
 
-@Suite(.hidden, timeLimitIfAvailable(milliseconds: 10))
+@Suite(.hidden, timeLimitIfAvailable(minutes: 10))
 struct TestTypeThatTimesOut {
   @available(_clockAPI, *)
   @Test(.hidden, arguments: 0 ..< 10)