@temporalio/testing 1.11.8 → 1.12.0-rc.0

package/lib/testing-workflow-environment.d.ts

@@ -0,0 +1,205 @@
+import 'abort-controller/polyfill';
+import { AsyncCompletionClient, Client, WorkflowClient } from '@temporalio/client';
+import { Duration } from '@temporalio/common';
+import { NativeConnection, Runtime } from '@temporalio/worker';
+import { native } from '@temporalio/core-bridge';
+import { Connection } from './connection';
+import { DevServerConfig, TimeSkippingServerConfig } from './ephemeral-server';
+import { ClientOptionsForTestEnv } from './client';
+/**
+ * Options for {@link TestWorkflowEnvironment.createLocal}
+ */
+export type LocalTestWorkflowEnvironmentOptions = {
+    server?: Omit<DevServerConfig, 'type'>;
+    client?: ClientOptionsForTestEnv;
+};
+/**
+ * Options for {@link TestWorkflowEnvironment.createTimeSkipping}
+ */
+export type TimeSkippingTestWorkflowEnvironmentOptions = {
+    server?: Omit<TimeSkippingServerConfig, 'type'>;
+    client?: ClientOptionsForTestEnv;
+};
+/**
+ * Options for {@link TestWorkflowEnvironment.createExistingServer}
+ */
+export type ExistingServerTestWorkflowEnvironmentOptions = {
+    /** If not set, defaults to localhost:7233 */
+    address?: string;
+    /** If not set, defaults to default */
+    namespace?: string;
+    client?: ClientOptionsForTestEnv;
+};
+/**
+ * An execution environment for running Workflow integration tests.
+ *
+ * Runs an external server.
+ * By default, the Java test server is used which supports time skipping.
+ */
+export declare class TestWorkflowEnvironment {
+    private readonly runtime;
+    readonly options: TestWorkflowEnvironmentOptionsWithDefaults;
+    readonly supportsTimeSkipping: boolean;
+    protected readonly server: native.EphemeralServer | 'existing';
+    /**
+     * Namespace used in this environment (taken from {@link TestWorkflowEnvironmentOptions})
+     */
+    readonly namespace?: string;
+    /**
+     * Get an established {@link Connection} to the ephemeral server
+     */
+    readonly connection: Connection;
+    /**
+     * A {@link TestEnvClient} for interacting with the ephemeral server
+     */
+    readonly client: Client;
+    /**
+     * An {@link AsyncCompletionClient} for interacting with the test server
+     *
+     * @deprecated - use `client.activity` instead
+     */
+    readonly asyncCompletionClient: AsyncCompletionClient;
+    /**
+     * A {@link TimeSkippingWorkflowClient} for interacting with the test server
+     *
+     * @deprecated - use `client.workflow` instead
+     */
+    readonly workflowClient: WorkflowClient;
+    /**
+     * A {@link NativeConnection} for interacting with the test server.
+     *
+     * Use this connection when creating Workers for testing.
+     */
+    readonly nativeConnection: NativeConnection;
+    protected constructor(runtime: Runtime, options: TestWorkflowEnvironmentOptionsWithDefaults, supportsTimeSkipping: boolean, server: native.EphemeralServer | 'existing', connection: Connection, nativeConnection: NativeConnection, namespace: string | undefined);
+    /**
+     * Start a time skipping workflow environment.
+     *
+     * This environment automatically skips to the next events in time when a workflow handle's `result` is awaited on
+     * (which includes {@link WorkflowClient.execute}). Before the result is awaited on, time can be manually skipped
+     * forward using {@link sleep}. The currently known time can be obtained via {@link currentTimeMs}.
+     *
+     * This environment will be powered by the Temporal Time Skipping Test Server (part of the [Java SDK](https://github.com/temporalio/sdk-java)).
+     * Note that the Time Skipping Test Server does not support full capabilities of the regular Temporal Server, and may
+     * occasionally present different behaviors. For general Workflow testing, it is generally preferable to use {@link createLocal}
+     * instead.
+     *
+     * Users can reuse this environment for testing multiple independent workflows, but not concurrently. Time skipping,
+     * which is automatically done when awaiting a workflow result and manually done on sleep, is global to the
+     * environment, not to the workflow under test. We highly recommend running tests serially when using a single
+     * environment or creating a separate environment per test.
+     *
+     * By default, the latest release of the Test Server will be downloaded and cached to a temporary directory
+     * (e.g. `$TMPDIR/temporal-test-server-sdk-typescript-*` or `%TEMP%/temporal-test-server-sdk-typescript-*.exe`). Note
+     * that existing cached binaries will be reused without validation that they are still up-to-date, until the SDK
+     * itself is updated. Alternatively, a specific version number of the Test Server may be provided, or the path to an
+     * existing Test Server binary may be supplied; see {@link LocalTestWorkflowEnvironmentOptions.server.executable}.
+     *
+     * Note that the Test Server implementation may be changed to another one in the future. Therefore, there is no
+     * guarantee that Test Server options, and particularly those provided through the `extraArgs` array, will continue to
+     * be supported in the future.
+     *
+     * IMPORTANT: At this time, the Time Skipping Test Server is not supported on ARM platforms. Execution on Apple
+     * silicon Macs will work if Rosetta 2 is installed.
+     */
+    static createTimeSkipping(opts?: TimeSkippingTestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment>;
+    /**
+     * Start a full Temporal server locally.
+     *
+     * This environment is good for testing full server capabilities, but does not support time skipping like
+     * {@link createTimeSkipping} does. {@link supportsTimeSkipping} will always return `false` for this environment.
+     * {@link sleep} will sleep the actual amount of time and {@link currentTimeMs} will return the current time.
+     *
+     * This local environment will be powered by [Temporal CLI](https://github.com/temporalio/cli), which is a
+     * self-contained executable for Temporal. By default, Temporal's database will not be persisted to disk, and no UI
+     * will be launched.
+     *
+     * By default, the latest release of the CLI will be downloaded and cached to a temporary directory
+     * (e.g. `$TMPDIR/temporal-sdk-typescript-*` or `%TEMP%/temporal-sdk-typescript-*.exe`). Note that existing cached
+     * binaries will be reused without validation that they are still up-to-date, until the SDK itself is updated.
+     * Alternatively, a specific version number of the CLI may be provided, or the path to an existing CLI binary may be
+     * supplied; see {@link LocalTestWorkflowEnvironmentOptions.server.executable}.
+     *
+     * Note that the Dev Server implementation may be changed to another one in the future. Therefore, there is no
+     * guarantee that Dev Server options, and particularly those provided through the `extraArgs` array, will continue to
+     * be supported in the future.
+     */
+    static createLocal(opts?: LocalTestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment>;
+    /**
+     * Create a new test environment using an existing server. You must already be running a server, which the test
+     * environment will connect to.
+     */
+    static createFromExistingServer(opts?: ExistingServerTestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment>;
+    /**
+     * Create a new test environment
+     */
+    private static create;
+    /**
+     * Kill the test server process and close the connection to it
+     */
+    teardown(): Promise<void>;
+    /**
+     * Wait for `durationMs` in "server time".
+     *
+     * This awaits using regular setTimeout in regular environments or manually skips time in time-skipping environments.
+     *
+     * Useful for simulating events far into the future like completion of long running activities.
+     *
+     * **Time skippping**:
+     *
+     * The time skippping server toggles between skipped time and normal time depending on what it needs to execute.
+     *
+     * This method is _likely_ to resolve in less than `durationMs` of "real time".
+     *
+     * @param durationMs number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     *
+     * @example
+     *
+     * `workflow.ts`
+     *
+     * ```ts
+     * const activities = proxyActivities({ startToCloseTimeout: 2_000_000 });
+     *
+     * export async function raceActivityAndTimer(): Promise<string> {
+     *   return await Promise.race([
+     *     wf.sleep(500_000).then(() => 'timer'),
+     *     activities.longRunning().then(() => 'activity'),
+     *   ]);
+     * }
+     * ```
+     *
+     * `test.ts`
+     *
+     * ```ts
+     * const worker = await Worker.create({
+     *   connection: testEnv.nativeConnection,
+     *   activities: {
+     *     async longRunning() {
+     *       await testEnv.sleep(1_000_000); // <-- sleep called here
+     *     },
+     *   },
+     *   // ...
+     * });
+     * ```
+     */
+    sleep: (durationMs: Duration) => Promise<void>;
+    /**
+     * Get the current time known to this environment.
+     *
+     * For non-time-skipping environments this is simply the system time. For time-skipping environments this is whatever
+     * time has been skipped to.
+     */
+    currentTimeMs(): Promise<number>;
+}
+/**
+ * Options for {@link TestWorkflowEnvironment.create}
+ */
+type TestWorkflowEnvironmentOptions = {
+    server: DevServerConfig | TimeSkippingServerConfig | ExistingServerConfig;
+    client?: ClientOptionsForTestEnv;
+};
+type ExistingServerConfig = {
+    type: 'existing';
+};
+type TestWorkflowEnvironmentOptionsWithDefaults = Required<TestWorkflowEnvironmentOptions>;
+export {};

package/lib/testing-workflow-environment.js

@@ -0,0 +1,278 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestWorkflowEnvironment = void 0;
+require("abort-controller/polyfill"); // eslint-disable-line import/no-unassigned-import
+const common_1 = require("@temporalio/common");
+const time_1 = require("@temporalio/common/lib/time");
+const worker_1 = require("@temporalio/worker");
+const core_bridge_1 = require("@temporalio/core-bridge");
+const internal_workflow_1 = require("@temporalio/common/lib/internal-workflow");
+const connection_1 = require("./connection");
+const ephemeral_server_1 = require("./ephemeral-server");
+const client_1 = require("./client");
+/**
+ * An execution environment for running Workflow integration tests.
+ *
+ * Runs an external server.
+ * By default, the Java test server is used which supports time skipping.
+ */
+class TestWorkflowEnvironment {
+    runtime;
+    options;
+    supportsTimeSkipping;
+    server;
+    /**
+     * Namespace used in this environment (taken from {@link TestWorkflowEnvironmentOptions})
+     */
+    namespace;
+    /**
+     * Get an established {@link Connection} to the ephemeral server
+     */
+    connection;
+    /**
+     * A {@link TestEnvClient} for interacting with the ephemeral server
+     */
+    client;
+    /**
+     * An {@link AsyncCompletionClient} for interacting with the test server
+     *
+     * @deprecated - use `client.activity` instead
+     */
+    asyncCompletionClient;
+    /**
+     * A {@link TimeSkippingWorkflowClient} for interacting with the test server
+     *
+     * @deprecated - use `client.workflow` instead
+     */
+    workflowClient;
+    /**
+     * A {@link NativeConnection} for interacting with the test server.
+     *
+     * Use this connection when creating Workers for testing.
+     */
+    nativeConnection;
+    constructor(runtime, options, supportsTimeSkipping, server, connection, nativeConnection, namespace) {
+        this.runtime = runtime;
+        this.options = options;
+        this.supportsTimeSkipping = supportsTimeSkipping;
+        this.server = server;
+        this.connection = connection;
+        this.nativeConnection = nativeConnection;
+        this.namespace = namespace;
+        this.client = new client_1.TestEnvClient({
+            connection,
+            namespace: this.namespace,
+            enableTimeSkipping: supportsTimeSkipping,
+            ...options.client,
+        });
+        this.asyncCompletionClient = this.client.activity; // eslint-disable-line deprecation/deprecation
+        this.workflowClient = this.client.workflow; // eslint-disable-line deprecation/deprecation
+    }
+    /**
+     * Start a time skipping workflow environment.
+     *
+     * This environment automatically skips to the next events in time when a workflow handle's `result` is awaited on
+     * (which includes {@link WorkflowClient.execute}). Before the result is awaited on, time can be manually skipped
+     * forward using {@link sleep}. The currently known time can be obtained via {@link currentTimeMs}.
+     *
+     * This environment will be powered by the Temporal Time Skipping Test Server (part of the [Java SDK](https://github.com/temporalio/sdk-java)).
+     * Note that the Time Skipping Test Server does not support full capabilities of the regular Temporal Server, and may
+     * occasionally present different behaviors. For general Workflow testing, it is generally preferable to use {@link createLocal}
+     * instead.
+     *
+     * Users can reuse this environment for testing multiple independent workflows, but not concurrently. Time skipping,
+     * which is automatically done when awaiting a workflow result and manually done on sleep, is global to the
+     * environment, not to the workflow under test. We highly recommend running tests serially when using a single
+     * environment or creating a separate environment per test.
+     *
+     * By default, the latest release of the Test Server will be downloaded and cached to a temporary directory
+     * (e.g. `$TMPDIR/temporal-test-server-sdk-typescript-*` or `%TEMP%/temporal-test-server-sdk-typescript-*.exe`). Note
+     * that existing cached binaries will be reused without validation that they are still up-to-date, until the SDK
+     * itself is updated. Alternatively, a specific version number of the Test Server may be provided, or the path to an
+     * existing Test Server binary may be supplied; see {@link LocalTestWorkflowEnvironmentOptions.server.executable}.
+     *
+     * Note that the Test Server implementation may be changed to another one in the future. Therefore, there is no
+     * guarantee that Test Server options, and particularly those provided through the `extraArgs` array, will continue to
+     * be supported in the future.
+     *
+     * IMPORTANT: At this time, the Time Skipping Test Server is not supported on ARM platforms. Execution on Apple
+     * silicon Macs will work if Rosetta 2 is installed.
+     */
+    static async createTimeSkipping(opts) {
+        return await this.create({
+            server: { type: 'time-skipping', ...opts?.server },
+            client: opts?.client,
+            supportsTimeSkipping: true,
+        });
+    }
+    /**
+     * Start a full Temporal server locally.
+     *
+     * This environment is good for testing full server capabilities, but does not support time skipping like
+     * {@link createTimeSkipping} does. {@link supportsTimeSkipping} will always return `false` for this environment.
+     * {@link sleep} will sleep the actual amount of time and {@link currentTimeMs} will return the current time.
+     *
+     * This local environment will be powered by [Temporal CLI](https://github.com/temporalio/cli), which is a
+     * self-contained executable for Temporal. By default, Temporal's database will not be persisted to disk, and no UI
+     * will be launched.
+     *
+     * By default, the latest release of the CLI will be downloaded and cached to a temporary directory
+     * (e.g. `$TMPDIR/temporal-sdk-typescript-*` or `%TEMP%/temporal-sdk-typescript-*.exe`). Note that existing cached
+     * binaries will be reused without validation that they are still up-to-date, until the SDK itself is updated.
+     * Alternatively, a specific version number of the CLI may be provided, or the path to an existing CLI binary may be
+     * supplied; see {@link LocalTestWorkflowEnvironmentOptions.server.executable}.
+     *
+     * Note that the Dev Server implementation may be changed to another one in the future. Therefore, there is no
+     * guarantee that Dev Server options, and particularly those provided through the `extraArgs` array, will continue to
+     * be supported in the future.
+     */
+    static async createLocal(opts) {
+        return await this.create({
+            server: { type: 'dev-server', ...opts?.server },
+            client: opts?.client,
+            namespace: opts?.server?.namespace,
+            supportsTimeSkipping: false,
+        });
+    }
+    /**
+     * Create a new test environment using an existing server. You must already be running a server, which the test
+     * environment will connect to.
+     */
+    static async createFromExistingServer(opts) {
+        return await this.create({
+            server: { type: 'existing' },
+            client: opts?.client,
+            namespace: opts?.namespace ?? 'default',
+            supportsTimeSkipping: false,
+            address: opts?.address,
+        });
+    }
+    /**
+     * Create a new test environment
+     */
+    static async create(opts) {
+        const { supportsTimeSkipping, namespace, ...rest } = opts;
+        const optsWithDefaults = addDefaults((0, internal_workflow_1.filterNullAndUndefined)(rest));
+        let address;
+        const runtime = worker_1.Runtime.instance();
+        let server;
+        if (optsWithDefaults.server.type !== 'existing') {
+            // Add search attributes to CLI server arguments
+            if ('searchAttributes' in optsWithDefaults.server && optsWithDefaults.server.searchAttributes) {
+                let newArgs = [];
+                for (const { name, type } of optsWithDefaults.server.searchAttributes) {
+                    newArgs.push('--search-attribute');
+                    newArgs.push(`${name}=${common_1.TypedSearchAttributes.toMetadataType(type)}`);
+                }
+                newArgs = newArgs.concat(optsWithDefaults.server.extraArgs ?? []);
+                optsWithDefaults.server.extraArgs = newArgs;
+            }
+            server = await runtime.createEphemeralServer((0, ephemeral_server_1.toNativeEphemeralServerConfig)(optsWithDefaults.server));
+            address = core_bridge_1.native.ephemeralServerGetTarget(server);
+        }
+        else {
+            address = opts.address ?? 'localhost:7233';
+            server = 'existing';
+        }
+        const nativeConnection = await worker_1.NativeConnection.connect({ address });
+        const connection = await connection_1.Connection.connect({ address });
+        return new this(runtime, optsWithDefaults, supportsTimeSkipping, server, connection, nativeConnection, namespace);
+    }
+    /**
+     * Kill the test server process and close the connection to it
+     */
+    async teardown() {
+        await this.connection.close().catch((e) => {
+            console.error(e);
+            /* ignore */
+        });
+        await this.nativeConnection.close().catch((e) => {
+            console.error(e);
+            /* ignore */
+        });
+        if (this.server !== 'existing') {
+            await this.runtime.shutdownEphemeralServer(this.server).catch((e) => {
+                console.error(e);
+                /* ignore */
+            });
+        }
+    }
+    /**
+     * Wait for `durationMs` in "server time".
+     *
+     * This awaits using regular setTimeout in regular environments or manually skips time in time-skipping environments.
+     *
+     * Useful for simulating events far into the future like completion of long running activities.
+     *
+     * **Time skippping**:
+     *
+     * The time skippping server toggles between skipped time and normal time depending on what it needs to execute.
+     *
+     * This method is _likely_ to resolve in less than `durationMs` of "real time".
+     *
+     * @param durationMs number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
+     *
+     * @example
+     *
+     * `workflow.ts`
+     *
+     * ```ts
+     * const activities = proxyActivities({ startToCloseTimeout: 2_000_000 });
+     *
+     * export async function raceActivityAndTimer(): Promise<string> {
+     *   return await Promise.race([
+     *     wf.sleep(500_000).then(() => 'timer'),
+     *     activities.longRunning().then(() => 'activity'),
+     *   ]);
+     * }
+     * ```
+     *
+     * `test.ts`
+     *
+     * ```ts
+     * const worker = await Worker.create({
+     *   connection: testEnv.nativeConnection,
+     *   activities: {
+     *     async longRunning() {
+     *       await testEnv.sleep(1_000_000); // <-- sleep called here
+     *     },
+     *   },
+     *   // ...
+     * });
+     * ```
+     */
+    sleep = async (durationMs) => {
+        if (this.supportsTimeSkipping) {
+            await this.connection.testService.unlockTimeSkippingWithSleep({ duration: (0, time_1.msToTs)(durationMs) });
+        }
+        else {
+            await new Promise((resolve) => setTimeout(resolve, (0, time_1.msToNumber)(durationMs)));
+        }
+    };
+    /**
+     * Get the current time known to this environment.
+     *
+     * For non-time-skipping environments this is simply the system time. For time-skipping environments this is whatever
+     * time has been skipped to.
+     */
+    async currentTimeMs() {
+        if (this.supportsTimeSkipping) {
+            const { time } = await this.connection.testService.getCurrentTime({});
+            return (0, time_1.tsToMs)(time);
+        }
+        else {
+            return Date.now();
+        }
+    }
+}
+exports.TestWorkflowEnvironment = TestWorkflowEnvironment;
+function addDefaults(opts) {
+    return {
+        client: {},
+        ...opts,
+        server: {
+            ...opts.server,
+        },
+    };
+}
+//# sourceMappingURL=testing-workflow-environment.js.map

package/lib/testing-workflow-environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing-workflow-environment.js","sourceRoot":"","sources":["../src/testing-workflow-environment.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/testing",
-  "version": "1.11.8",
+  "version": "1.12.0-rc.0",
   "description": "Temporal.io SDK Testing sub-package",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -12,13 +12,13 @@
   "author": "Temporal Technologies Inc. <sdk@temporal.io>",
   "license": "MIT",
   "dependencies": {
-    "@temporalio/activity": "1.11.8",
-    "@temporalio/client": "1.11.8",
-    "@temporalio/common": "1.11.8",
-    "@temporalio/core-bridge": "1.11.8",
-    "@temporalio/proto": "1.11.8",
-    "@temporalio/worker": "1.11.8",
-    "@temporalio/workflow": "1.11.8",
+    "@temporalio/activity": "1.12.0-rc.0",
+    "@temporalio/client": "1.12.0-rc.0",
+    "@temporalio/common": "1.12.0-rc.0",
+    "@temporalio/core-bridge": "1.12.0-rc.0",
+    "@temporalio/proto": "1.12.0-rc.0",
+    "@temporalio/worker": "1.12.0-rc.0",
+    "@temporalio/workflow": "1.12.0-rc.0",
     "abort-controller": "^3.0.0"
   },
   "bugs": {
@@ -30,6 +30,9 @@
     "directory": "packages/testing"
   },
   "homepage": "https://github.com/temporalio/sdk-typescript/tree/main/packages/testing",
+  "engines": {
+    "node": ">= 18.0.0"
+  },
   "files": [
     "lib",
     "src"
@@ -37,5 +40,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "0a757c370012d89babb668fbd799d83b55c83a1b"
+  "gitHead": "3e02f59f5c3edbdd3a4d05bc77c3bee9dbdc1226"
 }

package/src/client.ts

@@ -0,0 +1,81 @@
+import 'abort-controller/polyfill'; // eslint-disable-line import/no-unassigned-import
+import {
+  Client,
+  ClientOptions,
+  WorkflowClient,
+  WorkflowClientOptions,
+  WorkflowResultOptions,
+} from '@temporalio/client';
+import { Connection, TestService } from './connection';
+
+export interface TimeSkippingWorkflowClientOptions extends WorkflowClientOptions {
+  connection: Connection;
+  enableTimeSkipping: boolean;
+}
+
+export interface TestEnvClientOptions extends ClientOptions {
+  connection: Connection;
+  enableTimeSkipping: boolean;
+}
+
+/**
+ * Subset of the "normal" client options that are used to create a client for the test environment.
+ */
+export type ClientOptionsForTestEnv = Omit<ClientOptions, 'namespace' | 'connection'>;
+
+/**
+ * A client with the exact same API as the "normal" client with 1 exception,
+ * When this client waits on a Workflow's result, it will enable time skipping
+ * in the test server.
+ */
+export class TimeSkippingWorkflowClient extends WorkflowClient {
+  protected readonly testService: TestService;
+  protected readonly enableTimeSkipping: boolean;
+
+  constructor(options: TimeSkippingWorkflowClientOptions) {
+    super(options);
+    this.enableTimeSkipping = options.enableTimeSkipping;
+    this.testService = options.connection.testService;
+  }
+
+  /**
+   * Gets the result of a Workflow execution.
+   *
+   * @see {@link WorkflowClient.result}
+   */
+  override async result<T>(
+    workflowId: string,
+    runId?: string | undefined,
+    opts?: WorkflowResultOptions | undefined
+  ): Promise<T> {
+    if (this.enableTimeSkipping) {
+      await this.testService.unlockTimeSkipping({});
+      try {
+        return await super.result(workflowId, runId, opts);
+      } finally {
+        await this.testService.lockTimeSkipping({});
+      }
+    } else {
+      return await super.result(workflowId, runId, opts);
+    }
+  }
+}
+
+/**
+ * A client with the exact same API as the "normal" client with one exception:
+ * when `TestEnvClient.workflow` (an instance of {@link TimeSkippingWorkflowClient}) waits on a Workflow's result, it will enable time skipping
+ * in the Test Server.
+ */
+export class TestEnvClient extends Client {
+  constructor(options: TestEnvClientOptions) {
+    super(options);
+
+    // Recreate the client (this isn't optimal but it's better than adding public methods just for testing).
+    // NOTE: we cast to "any" to work around `workflow` being a readonly attribute.
+    (this as any).workflow = new TimeSkippingWorkflowClient({
+      ...this.workflow.options,
+      connection: options.connection,
+      enableTimeSkipping: options.enableTimeSkipping,
+    });
+  }
+}