Add time-skipping client interceptor for test environments (#86)

FranzBusch · web-flow · commit 39f3a9f8e23e · 2026-03-06T16:38:22.000+01:00
Adds `TimeSkippingClientInterceptor` that automatically unlocks time
skipping when waiting for workflow results in time-skipping test
servers. Adds programmatic time control methods (sleep, currentTime) on
`TemporalTestServer`.
diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml
@@ -13,6 +13,7 @@ jobs:
     uses: swiftlang/github-workflows/.github/workflows/soundness.yml@0.0.7
     with:
       license_header_check_project_name: "Swift Temporal SDK"
+      api_breakage_check_enabled: false
 
   unit-tests:
     name: Unit tests
diff --git a/Package.swift b/Package.swift
@@ -109,6 +109,7 @@ let package = Package(
             name: "TemporalTestKit",
             dependencies: [
                 .product(name: "GRPCNIOTransportHTTP2", package: "grpc-swift-nio-transport"),
+                .product(name: "GRPCServiceLifecycle", package: "grpc-swift-extras"),
                 .target(name: "Temporal"),
             ]
         ),
diff --git a/Sources/TemporalTestKit/TemporalTestServer.swift b/Sources/TemporalTestKit/TemporalTestServer.swift
@@ -15,7 +15,9 @@
 #if canImport(Testing)
 import GRPCNIOTransportHTTP2Posix
 import GRPCCore
+import GRPCServiceLifecycle
 import NIOPosix
+import SwiftProtobuf
 public import Logging
 public import Temporal
 public import Testing
@@ -108,7 +110,20 @@ public struct TemporalTestServer: Sendable {
     @TaskLocal
     public static var timeSkippingTestServer: TemporalTestServer? = nil
 
+    /// Whether this server supports time skipping.
+    public var supportsTimeSkipping: Bool {
+        self.testServiceClient != nil
+    }
+
     private let serverTarget: String
+    private let testServiceClient: Api.Testservice.V1.TestService.Client<HTTP2ClientTransport.Posix>?
+    @TaskLocal
+    private static var autoTimeSkippingDisabled: Bool = false
+
+    /// Whether automatic time skipping is currently enabled.
+    var isAutoTimeSkippingEnabled: Bool {
+        self.supportsTimeSkipping && !Self.autoTimeSkippingDisabled
+    }
 
     // tune the dev server for high throughput during parallel testing, otherwise running into "resource exhausted" errors
     private static let devServerOptions: BridgeTestServer.DevServerOptions = {
@@ -159,7 +174,8 @@ public struct TemporalTestServer: Sendable {
             devServerOptions: Self.devServerOptions,
         ) { bridgeTestServer, target in
             let testServer = TemporalTestServer(
-                serverTarget: target
+                serverTarget: target,
+                testServiceClient: nil
             )
             return try await body(testServer)
         }
@@ -205,10 +221,38 @@ public struct TemporalTestServer: Sendable {
         _ body: (borrowing TemporalTestServer) async throws -> Void
     ) async throws {
         try await BridgeTestServer.withBridgeTestServer { bridgeTestServer, target in
-            let testServer = TemporalTestServer(
-                serverTarget: target
+            let parts = target.split(separator: ":", maxSplits: 1, omittingEmptySubsequences: false)
+            guard let host = parts.first.map(String.init),
+                parts.count > 1,
+                let port = Int(parts[1])
+            else {
+                fatalError("Invalid host and port received from test server.")
+            }
+
+            let grpcClient = GRPCClient(
+                transport: try .http2NIOPosix(
+                    target: .dns(host: host, port: port),
+                    transportSecurity: .plaintext,
+                    config: .defaults,
+                    resolverRegistry: .defaults,
+                    serviceConfig: .init(),
+                    eventLoopGroup: .singletonMultiThreadedEventLoopGroup
+                )
             )
-            return try await body(testServer)
+
+            return try await withThrowingTaskGroup(of: Void.self) { group in
+                group.addTask {
+                    try await grpcClient.run()
+                }
+
+                let testServer = TemporalTestServer(
+                    serverTarget: target,
+                    testServiceClient: .init(wrapping: grpcClient)
+                )
+                try await body(testServer)
+
+                grpcClient.beginGracefulShutdown()
+            }
         }
     }
 
@@ -273,6 +317,14 @@ public struct TemporalTestServer: Sendable {
     ) async throws -> Result {
         let (host, port) = self.hostAndPort()
 
+        // Auto-inject the time-skipping interceptor when connected to a
+        // time-skipping server. It is placed first so it wraps all other
+        // interceptors, matching the behavior of the C# and Ruby SDKs.
+        var allInterceptors: [any Temporal.ClientInterceptor] = interceptors
+        if self.supportsTimeSkipping {
+            allInterceptors.insert(TimeSkippingClientInterceptor(testServer: self), at: 0)
+        }
+
         return try await TemporalClient.connect(
             transport: .http2NIOPosix(
                 target: .dns(host: host, port: port),
@@ -284,7 +336,7 @@ public struct TemporalTestServer: Sendable {
             ),
             configuration: .init(
                 instrumentation: .init(serverHostname: host),
-                interceptors: interceptors
+                interceptors: allInterceptors
             ),
             logger: logger,
         ) { client in
@@ -424,6 +476,98 @@ public struct TemporalTestServer: Sendable {
         }
     }
 
+    // MARK: - Time Control
+
+    /// Advances the test server time by the specified duration.
+    ///
+    /// When connected to a time-skipping test server, this method instructs the server to
+    /// fast-forward its internal clock by the given duration. This causes any pending timers
+    /// or scheduled events within that time window to fire immediately.
+    ///
+    /// - Parameter duration: The amount of time to advance the server clock.
+    /// - Throws: An error if the server does not support time skipping or the RPC fails.
+    public func sleep(_ duration: Duration) async throws {
+        guard let testServiceClient else {
+            preconditionFailure("sleep(_:) is only supported on time-skipping test servers")
+        }
+        _ = try await testServiceClient.unlockTimeSkippingWithSleep(
+            .with {
+                $0.duration = .with {
+                    $0.seconds = duration.components.seconds
+                    $0.nanos = Int32(duration.components.attoseconds / 1_000_000_000)
+                }
+            }
+        )
+    }
+
+    /// Returns the current time as known to the test server.
+    ///
+    /// When connected to a time-skipping test server, this returns the server's internal
+    /// time, which may differ from wall-clock time due to time skipping.
+    ///
+    /// - Returns: The current server time.
+    /// - Throws: An error if the server does not support time skipping or the RPC fails.
+    public func currentTime() async throws -> Date {
+        guard let testServiceClient else {
+            preconditionFailure("currentTime() is only supported on time-skipping test servers")
+        }
+        return try await testServiceClient.getCurrentTime(.init()).time.date
+    }
+
+    /// Executes a closure with automatic time skipping temporarily disabled.
+    ///
+    /// While automatic time skipping is disabled, calls to `handle.result`
+    /// will not unlock the time-skipping server's clock. Time will only advance through
+    /// explicit calls to ``sleep(_:)`` or real-time passage.
+    ///
+    /// This is useful when you need to observe intermediate workflow states without
+    /// time being advanced automatically.
+    ///
+    /// - Parameter body: The closure to execute with auto-time-skipping disabled.
+    /// - Returns: The result of the closure.
+    /// - Throws: Any error thrown by the closure.
+    public func withAutoTimeSkippingDisabled<Result: Sendable>(
+        _ body: () async throws -> Result
+    ) async rethrows -> Result {
+        try await Self.$autoTimeSkippingDisabled.withValue(true) {
+            try await body()
+        }
+    }
+
+    /// Unlocks time skipping for the duration of the given closure, then re-locks it.
+    ///
+    /// This is used internally by ``TimeSkippingClientInterceptor`` to allow time to
+    /// advance while waiting for workflow results.
+    func withTimeSkippingUnlocked<Result: Sendable>(
+        _ body: () async throws -> Result
+    ) async throws -> Result {
+        guard let testServiceClient else {
+            return try await body()
+        }
+
+        _ = try await testServiceClient.unlockTimeSkipping(.init())
+
+        var userCodeSucceeded = false
+        do {
+            let result = try await body()
+            userCodeSucceeded = true
+            _ = try await testServiceClient.lockTimeSkipping(.init())
+            return result
+        } catch {
+            // Re-lock time skipping. If user code failed, swallow lock errors
+            // to preserve the original error.
+            do {
+                _ = try await testServiceClient.lockTimeSkipping(.init())
+            } catch {
+                if userCodeSucceeded {
+                    throw error
+                }
+                // Swallow lock error when user code already failed
+            }
+            throw error
+        }
+    }
+
     /// Provides the host and port information from the server target address.
     ///
     /// - Returns: A tuple containing the host string and port number for the test server.
diff --git a/Sources/TemporalTestKit/TimeSkippingClientInterceptor.swift b/Sources/TemporalTestKit/TimeSkippingClientInterceptor.swift
@@ -0,0 +1,66 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Temporal SDK open source project
+//
+// Copyright (c) 2026 Apple Inc. and the Swift Temporal SDK project authors
+// Licensed under MIT License
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift Temporal SDK project authors
+//
+// SPDX-License-Identifier: MIT
+//
+//===----------------------------------------------------------------------===//
+
+#if canImport(Testing)
+import Temporal
+
+/// A client interceptor that automatically unlocks time skipping on the
+/// Temporal time-skipping test server when waiting for workflow results.
+///
+/// When the time-skipping test server is active, timers in workflows only advance
+/// when time skipping is unlocked. This interceptor unlocks time skipping around
+/// ``fetchWorkflowHistoryEvents`` calls that are waiting for a workflow close event
+/// (which is the pattern used by ``UntypedWorkflowHandle/result(followRuns:resultTypes:callOptions:)``).
+///
+/// This interceptor is auto-injected by ``TemporalTestServer`` when connecting to
+/// a time-skipping test server. You do not need to add it manually.
+struct TimeSkippingClientInterceptor: Temporal.ClientInterceptor, Sendable {
+    private let testServer: TemporalTestServer
+
+    package init(testServer: TemporalTestServer) {
+        self.testServer = testServer
+    }
+
+    func makeClientOutboundInterceptor() -> Outbound? {
+        Outbound(testServer: self.testServer)
+    }
+
+    struct Outbound: Temporal.ClientOutboundInterceptor {
+        private let testServer: TemporalTestServer
+
+        init(testServer: TemporalTestServer) {
+            self.testServer = testServer
+        }
+
+        func fetchWorkflowHistoryEvents(
+            input: FetchWorkflowHistoryEventsInput,
+            next: (FetchWorkflowHistoryEventsInput) async throws -> [Api.History.V1.HistoryEvent]
+        ) async throws -> [Api.History.V1.HistoryEvent] {
+            // Only unlock time skipping when waiting for a close event, which
+            // is the pattern used by result() to poll for workflow completion.
+            guard input.waitNewEvent && input.eventFilterType == .closeEvent else {
+                return try await next(input)
+            }
+
+            guard testServer.isAutoTimeSkippingEnabled else {
+                return try await next(input)
+            }
+
+            return try await testServer.withTimeSkippingUnlocked {
+                try await next(input)
+            }
+        }
+    }
+}
+#endif
diff --git a/Tests/TemporalTests/TestHelpers/WorkerTestHelper.swift b/Tests/TemporalTests/TestHelpers/WorkerTestHelper.swift
@@ -21,7 +21,14 @@ import Testing
 
 import protocol GRPCCore.ClientTransport
 
-@Suite(.temporalTestServer, .temporalTimeSkippingTestServer, .timeLimit(.minutes(1)))
+// Serialized: Makes it easier to understand which test fails and doesn't overwhelm the Temporal test server
+// TimeLimit: Ensures that nothing gets stuck forever
+@Suite(
+    .temporalTestServer,
+    .temporalTimeSkippingTestServer,
+    .serialized,
+    .timeLimit(.minutes(2))
+)
 enum TestServerDependentTests {}
 
 func withTestClient<Result: Sendable>(
diff --git a/Tests/TemporalTests/Worker/Workflow/TimeSkippingInterceptorTests.swift b/Tests/TemporalTests/Worker/Workflow/TimeSkippingInterceptorTests.swift
@@ -0,0 +1,70 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift Temporal SDK open source project
+//
+// Copyright (c) 2026 Apple Inc. and the Swift Temporal SDK project authors
+// Licensed under MIT License
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift Temporal SDK project authors
+//
+// SPDX-License-Identifier: MIT
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+import Temporal
+import TemporalTestKit
+import Testing
+
+extension TestServerDependentTests {
+    @Suite(.tags(.workflowTests))
+    struct TimeSkippingInterceptorTests {
+        @Workflow
+        final class LongTimerWorkflow {
+            func run(input: Void) async throws -> String {
+                // Sleep for 1 hour in workflow time
+                try await Workflow.sleep(for: .seconds(3600))
+                return "completed"
+            }
+        }
+
+        @Test
+        func longTimerCompletesQuicklyWithTimeSkipping() async throws {
+            let start = ContinuousClock.now
+            try await withTimeSkippingTestWorkerAndClient(
+                workflows: [LongTimerWorkflow.self]
+            ) { taskQueue, client in
+                let handle = try await client.startWorkflow(
+                    type: LongTimerWorkflow.self,
+                    options: .init(id: "time-skip-\(UUID())", taskQueue: taskQueue)
+                )
+                let result = try await handle.result()
+                #expect(result == "completed")
+            }
+            let elapsed = ContinuousClock.now - start
+            // The 1-hour timer should complete well under 60 seconds of wall clock time
+            #expect(elapsed < .seconds(60))
+        }
+
+        @Test
+        func currentTimeReturnsValue() async throws {
+            let testServer = TemporalTestServer.timeSkippingTestServer!
+            let time = try await testServer.currentTime()
+            // The time should be a reasonable date (after 2020)
+            let referenceDate = Date(timeIntervalSince1970: 1_577_836_800)  // 2020-01-01
+            #expect(time > referenceDate)
+        }
+
+        @Test
+        func sleepAdvancesTime() async throws {
+            let testServer = TemporalTestServer.timeSkippingTestServer!
+            let timeBefore = try await testServer.currentTime()
+            try await testServer.sleep(.seconds(3600))
+            let timeAfter = try await testServer.currentTime()
+            // Time should have advanced by at least 1 hour
+            let elapsed = timeAfter.timeIntervalSince(timeBefore)
+            #expect(elapsed >= 3599)
+        }
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -109,6 +109,7 @@ let package = Package(`
`109`	`109`	`name: "TemporalTestKit",`
`110`	`110`	`dependencies: [`
`111`	`111`	`.product(name: "GRPCNIOTransportHTTP2", package: "grpc-swift-nio-transport"),`
	`112`	`+ .product(name: "GRPCServiceLifecycle", package: "grpc-swift-extras"),`
`112`	`113`	`.target(name: "Temporal"),`
`113`	`114`	`]`
`114`	`115`	`),`