@temporalio/testing 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporalio/testing",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Temporal.io SDK Testing sub-package",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -9,27 +9,16 @@
     "workflow",
     "testing"
   ],
-  "scripts": {
-    "install": "node ./scripts/download-test-server.mjs",
-    "build": "npm-run-all build:protos install",
-    "build:protos": "node ./scripts/compile-proto.mjs"
-  },
   "author": "Temporal Technologies Inc. <sdk@temporal.io>",
   "license": "MIT",
   "dependencies": {
     "@grpc/grpc-js": "^1.6.7",
-    "@temporalio/activity": "^1.1.0",
-    "@temporalio/client": "^1.2.0",
-    "@temporalio/common": "^1.1.0",
-    "@temporalio/worker": "^1.2.0",
-    "@types/long": "^4.0.2",
+    "@temporalio/activity": "^1.4.0",
+    "@temporalio/client": "^1.4.0",
+    "@temporalio/common": "^1.4.0",
+    "@temporalio/worker": "^1.4.0",
     "abort-controller": "^3.0.0",
-    "get-port": "^5.0.0",
-    "got": "^12.1.0",
-    "long": "^5.2.0",
-    "protobufjs": "^7.0.0",
-    "tar-stream": "^2.2.0",
-    "unzipper": "^0.10.11"
+    "ms": "^2.1.3"
   },
   "bugs": {
     "url": "https://github.com/temporalio/sdk-typescript/issues"
@@ -37,12 +26,10 @@
   "homepage": "https://github.com/temporalio/sdk-typescript/tree/main/packages/testing",
   "files": [
     "lib",
-    "src",
-    "generated-protos",
-    "scripts"
+    "src"
   ],
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9790992f0a7da1638cd3db99518e414107651630"
+  "gitHead": "4b757ebbc052f327cc37e5693f46c8127c156b0c"
 }

package/src/{test-service-client.ts → connection.ts}

@@ -1,7 +1,7 @@
 import * as grpc from '@grpc/grpc-js';
 import { Connection as BaseConnection, ConnectionOptions } from '@temporalio/client';
 import { ConnectionCtorOptions as BaseConnectionCtorOptions } from '@temporalio/client/lib/connection';
-import { temporal } from '../generated-protos';
+import { temporal } from '@temporalio/proto';
 
 export type TestService = temporal.api.testservice.v1.TestService;
 export const { TestService } = temporal.api.testservice.v1;

package/src/index.ts

@@ -11,54 +11,41 @@
 import * as activity from '@temporalio/activity';
 import {
   AsyncCompletionClient,
-  WorkflowClient as BaseWorkflowClient,
-  WorkflowClientOptions as BaseWorkflowClientOptions,
-  WorkflowResultOptions as BaseWorkflowResultOptions,
-  WorkflowStartOptions as BaseWorkflowStartOptions,
+  Client,
+  ClientOptions,
+  ConnectionLike,
+  WorkflowClient,
+  WorkflowClientOptions,
+  WorkflowResultOptions,
 } from '@temporalio/client';
-import { ActivityFunction, CancelledFailure, msToTs, Workflow, WorkflowResultType } from '@temporalio/common';
-import { NativeConnection, Logger, DefaultLogger } from '@temporalio/worker';
+import { ActivityFunction, CancelledFailure } from '@temporalio/common';
+import { msToTs, tsToMs } from '@temporalio/common/lib/time';
+import { NativeConnection, Runtime } from '@temporalio/worker';
+import {
+  EphemeralServer,
+  EphemeralServerConfig,
+  getEphemeralServerTarget,
+  TemporaliteConfig,
+  TimeSkippingServerConfig,
+} from '@temporalio/core-bridge';
 import path from 'path';
-import os from 'os';
 import { AbortController } from 'abort-controller';
-import { ChildProcess, spawn, StdioOptions } from 'child_process';
 import events from 'events';
-import { kill, waitOnChild } from './child-process';
-import getPort from 'get-port';
-import { Connection, TestService } from './test-service-client';
-
-const TEST_SERVER_EXECUTABLE_NAME = os.platform() === 'win32' ? 'test-server.exe' : 'test-server';
+import { Connection, TestService } from './connection';
+import { filterNullAndUndefined } from '@temporalio/common/lib/internal-non-workflow';
+import ms from 'ms';
 
-export const DEFAULT_TEST_SERVER_PATH = path.join(__dirname, `../${TEST_SERVER_EXECUTABLE_NAME}`);
+export { TimeSkippingServerConfig, TemporaliteConfig, EphemeralServerExecutable } from '@temporalio/core-bridge';
+export { EphemeralServerConfig };
 
-/**
- * Options passed to {@link WorkflowClient.result}, these are the same as the
- * {@link BaseWorkflowResultOptions} with an additional option that controls
- * whether to toggle time skipping in the Test server while waiting on a
- * Workflow's result.
- */
-export interface WorkflowResultOptions extends BaseWorkflowResultOptions {
-  /**
-   * If set to `true`, waiting for the result does not enable time skipping
-   */
-  runInNormalTime?: boolean;
+export interface TimeSkippingWorkflowClientOptions extends WorkflowClientOptions {
+  connection: Connection;
+  enableTimeSkipping: boolean;
 }
 
-/**
- * Options passed to {@link WorkflowClient.execute}, these are the same as the
- * {@link BaseWorkflowStartOptions} with an additional option that controls
- * whether to toggle time skipping in the Test server while waiting on a
- * Workflow's result.
- */
-export type WorkflowStartOptions<T extends Workflow> = BaseWorkflowStartOptions<T> & {
-  /**
-   * If set to `true`, waiting for the result does not enable time skipping
-   */
-  runInNormalTime?: boolean;
-};
-
-export interface WorkflowClientOptions extends BaseWorkflowClientOptions {
+export interface TestEnvClientOptions extends ClientOptions {
   connection: Connection;
+  enableTimeSkipping: boolean;
 }
 
 /**
@@ -66,48 +53,63 @@ export interface WorkflowClientOptions extends BaseWorkflowClientOptions {
  * When this client waits on a Workflow's result, it will enable time skipping
  * in the test server.
  */
-export class WorkflowClient extends BaseWorkflowClient {
+export class TimeSkippingWorkflowClient extends WorkflowClient {
   protected readonly testService: TestService;
+  protected readonly enableTimeSkipping: boolean;
 
-  constructor(options: WorkflowClientOptions) {
+  constructor(options: TimeSkippingWorkflowClientOptions) {
     super(options);
+    this.enableTimeSkipping = options.enableTimeSkipping;
     this.testService = options.connection.testService;
   }
 
-  /**
-   * Execute a Workflow and wait for completion.
-   *
-   * @see {@link BaseWorkflowClient.execute}
-   */
-  public async execute<T extends Workflow>(
-    workflowTypeOrFunc: string | T,
-    options: WorkflowStartOptions<T>
-  ): Promise<WorkflowResultType<T>> {
-    return super.execute(workflowTypeOrFunc, options);
-  }
-
   /**
    * Gets the result of a Workflow execution.
    *
-   * @see {@link BaseWorkflowClient.result}
+   * @see {@link WorkflowClient.result}
    */
   override async result<T>(
     workflowId: string,
     runId?: string | undefined,
     opts?: WorkflowResultOptions | undefined
   ): Promise<T> {
-    if (opts?.runInNormalTime) {
-      return await super.result(workflowId, runId, opts);
-    }
-    await this.testService.unlockTimeSkipping({});
-    try {
+    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);
-    } finally {
-      await this.testService.lockTimeSkipping({});
     }
   }
 }
 
+/**
+ * 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.
+ */
+class TestEnvClient extends Client {
+  constructor(options: TestEnvClientOptions) {
+    super(options);
+
+    const { workflow, loadedDataConverter, interceptors, ...base } = this.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({
+      ...base,
+      ...workflow,
+      connection: options.connection,
+      dataConverter: loadedDataConverter,
+      interceptors: interceptors.workflow,
+      enableTimeSkipping: options.enableTimeSkipping,
+    });
+  }
+}
+
 /**
  * Convenience workflow interceptors
  *
@@ -116,48 +118,44 @@ export class WorkflowClient extends BaseWorkflowClient {
  */
 export const workflowInterceptorModules = [path.join(__dirname, 'assert-to-failure-interceptor')];
 
-export interface TestServerSpawnerOptions {
-  /**
-   * @default {@link DEFAULT_TEST_SERVER_PATH}
-   */
-  path?: string;
-  /**
-   * @default ignore
-   */
-  stdio?: StdioOptions;
-}
-
 /**
- * A generic callback that returns a child process
+ * Subset of the "normal" client options that are used to create a client for the test environment.
  */
-export type TestServerSpawner = (port: number) => ChildProcess;
+export type ClientOptionsForTestEnv = Omit<ClientOptions, 'namespace' | 'connection'>;
 
 /**
  * Options for {@link TestWorkflowEnvironment.create}
  */
-export interface TestWorkflowEnvironmentOptions {
-  testServer?: TestServerSpawner | TestServerSpawnerOptions;
-  logger?: Logger;
-}
+type TestWorkflowEnvironmentOptions = {
+  server?: EphemeralServerConfig;
+  client?: ClientOptionsForTestEnv;
+};
 
-interface TestWorkflowEnvironmentOptionsWithDefaults {
-  testServerSpawner: TestServerSpawner;
-  logger: Logger;
-}
+/**
+ * Options for {@link TestWorkflowEnvironment.createTimeSkipping}
+ */
+export type TimeSkippingTestWorkflowEnvironmentOptions = {
+  server?: Omit<TimeSkippingServerConfig, 'type'>;
+  client?: ClientOptionsForTestEnv;
+};
+
+/**
+ * Options for {@link TestWorkflowEnvironment.createLocal}
+ */
+export type LocalTestWorkflowEnvironmentOptions = {
+  server?: Omit<TemporaliteConfig, 'type'>;
+  client?: ClientOptionsForTestEnv;
+};
 
-function addDefaults({
-  testServer,
-  logger,
-}: TestWorkflowEnvironmentOptions): TestWorkflowEnvironmentOptionsWithDefaults {
+export type TestWorkflowEnvironmentOptionsWithDefaults = Required<TestWorkflowEnvironmentOptions>;
+
+function addDefaults(opts: TestWorkflowEnvironmentOptions): TestWorkflowEnvironmentOptionsWithDefaults {
   return {
-    testServerSpawner:
-      typeof testServer === 'function'
-        ? testServer
-        : (port: number) =>
-            spawn(testServer?.path || DEFAULT_TEST_SERVER_PATH, [`${port}`], {
-              stdio: testServer?.stdio || 'ignore',
-            }),
-    logger: logger ?? new DefaultLogger('INFO'),
+    server: {
+      type: 'time-skipping',
+    },
+    client: {},
+    ...opts,
   };
 }
 
@@ -169,17 +167,30 @@ function addDefaults({
  */
 export class TestWorkflowEnvironment {
   /**
-   * Get an extablished {@link Connection} to the test server
+   * Namespace used in this environment (taken from {@link TestWorkflowEnvironmentOptions})
+   */
+  public readonly namespace?: string;
+  /**
+   * Get an established {@link Connection} to the ephemeral server
+   */
+  public readonly connection: ConnectionLike;
+
+  /**
+   * A {@link TestEnvClient} for interacting with the ephemeral server
    */
-  public readonly connection: Connection;
+  public readonly client: Client;
 
   /**
    * An {@link AsyncCompletionClient} for interacting with the test server
+   *
+   * @deprecated - use `client.activity` instead
    */
   public readonly asyncCompletionClient: AsyncCompletionClient;
 
   /**
-   * A {@link WorkflowClient} for interacting with the test server
+   * A {@link TimeSkippingWorkflowClient} for interacting with the test server
+   *
+   * @deprecated - use `client.workflow` instead
    */
   public readonly workflowClient: WorkflowClient;
 
@@ -191,49 +202,91 @@ export class TestWorkflowEnvironment {
   public readonly nativeConnection: NativeConnection;
 
   protected constructor(
-    protected readonly serverProc: ChildProcess,
+    public readonly options: TestWorkflowEnvironmentOptionsWithDefaults,
+    public readonly supportsTimeSkipping: boolean,
+    protected readonly server: EphemeralServer,
     connection: Connection,
     nativeConnection: NativeConnection
   ) {
     this.connection = connection;
     this.nativeConnection = nativeConnection;
-    this.workflowClient = new WorkflowClient({ connection });
-    this.asyncCompletionClient = new AsyncCompletionClient({ connection });
+    this.namespace = options.server.type === 'temporalite' ? options.server.namespace : undefined;
+    this.client = new TestEnvClient({
+      connection,
+      namespace: this.namespace,
+      enableTimeSkipping: options.server.type === 'time-skipping',
+      ...options.client,
+    });
+    // eslint-disable-next-line deprecation/deprecation
+    this.asyncCompletionClient = this.client.activity;
+    // eslint-disable-next-line deprecation/deprecation
+    this.workflowClient = this.client.workflow;
   }
 
   /**
-   * Create a new test environment
+   * Start a time skipping workflow environment.
+   *
+   * By default, this environment will automatically skip 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}.
+   *
+   * Internally, this environment lazily downloads a test-server binary for the current OS/arch from the [Java SDK
+   * releases](https://github.com/temporalio/sdk-java/releases) into the temp directory if it is not already there.
+   * Then the executable is started and will be killed when {@link teardown} is called.
+   *
+   * 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.
+   *
+   * In the future, the test server implementation may be changed to another implementation.
    */
-  static async create(opts?: TestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment> {
-    const port = await getPort();
-
-    const { testServerSpawner, logger } = addDefaults(opts ?? {});
-
-    const child = testServerSpawner(port);
+  static async createTimeSkipping(opts?: TimeSkippingTestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment> {
+    // eslint-disable-next-line deprecation/deprecation
+    return await this.create({ server: { type: 'time-skipping', ...opts?.server }, client: opts?.client });
+  }
 
-    const address = `127.0.0.1:${port}`;
-    const connPromise = Connection.connect({ address });
+  /**
+   * Start a full Temporal server locally, downloading if necessary.
+   *
+   * 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.
+   *
+   * Internally, this uses [Temporalite](https://github.com/temporalio/temporalite). Which is a self-contained binary
+   * for Temporal using Sqlite persistence. This will download Temporalite to a temporary directory by default if it
+   * has not already been downloaded before and {@link LocalTestWorkflowEnvironmentOptions.server.executable.type} is
+   * `'cached-download'`.
+   *
+   * In the future, the Temporalite implementation may be changed to another implementation.
+   */
+  static async createLocal(opts?: LocalTestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment> {
+    // eslint-disable-next-line deprecation/deprecation
+    return await this.create({ server: { type: 'temporalite', ...opts?.server }, client: opts?.client });
+  }
 
-    try {
-      await Promise.race([
-        connPromise,
-        waitOnChild(child).then(() => {
-          throw new Error('Test server child process exited prematurely');
-        }),
-      ]);
-    } catch (err) {
-      try {
-        await kill(child);
-      } catch (error) {
-        logger.error('Failed to kill test server child process', { error });
-      }
-      throw err;
-    }
+  /**
+   * Create a new test environment
+   *
+   * @deprecated - use {@link createTimeSkipping} or {@link createLocal}
+   */
+  static async create(opts?: TestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment> {
+    const optsWithDefaults = addDefaults(filterNullAndUndefined(opts ?? {}));
+    const server = await Runtime.instance().createEphemeralServer(optsWithDefaults.server);
+    const address = getEphemeralServerTarget(server);
 
-    const conn = await connPromise;
     const nativeConnection = await NativeConnection.connect({ address });
-
-    return new this(child, conn, nativeConnection);
+    const connection = await Connection.connect({ address });
+
+    return new this(
+      optsWithDefaults,
+      optsWithDefaults.server.type === 'time-skipping',
+      server,
+      connection,
+      nativeConnection
+    );
   }
 
   /**
@@ -242,20 +295,23 @@ export class TestWorkflowEnvironment {
   async teardown(): Promise<void> {
     await this.connection.close();
     await this.nativeConnection.close();
-    // TODO: the server should return exit code 0
-    await kill(this.serverProc, 'SIGINT', { validReturnCodes: [0, 130] });
+    await Runtime.instance().shutdownEphemeralServer(this.server);
   }
 
   /**
-   * Wait for `durationMs` in "test server time".
+   * Wait for `durationMs` in "server time".
    *
-   * The test 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".
+   * 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.
    *
-   * @param durationMs {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds
+   * **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
    *
@@ -287,8 +343,27 @@ export class TestWorkflowEnvironment {
    * ```
    */
   sleep = async (durationMs: number | string): Promise<void> => {
-    await this.connection.testService.unlockTimeSkippingWithSleep({ duration: msToTs(durationMs) });
+    if (this.supportsTimeSkipping) {
+      await (this.connection as Connection).testService.unlockTimeSkippingWithSleep({ duration: msToTs(durationMs) });
+    } else {
+      await new Promise((resolve) => setTimeout(resolve, typeof durationMs === 'string' ? ms(durationMs) : 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(): Promise<number> {
+    if (this.supportsTimeSkipping) {
+      const { time } = await (this.connection as Connection).testService.getCurrentTime({});
+      return tsToMs(time);
+    } else {
+      return Date.now();
+    }
+  }
 }
 
 /**

package/src/utils.ts

@@ -1,5 +1,5 @@
 import { Connection } from '@temporalio/client';
-import { msToTs } from '@temporalio/internal-workflow-common';
+import { msToTs } from '@temporalio/common/lib/time';
 
 export async function waitOnNamespace(
   connection: Connection,