@temporalio/testing 1.11.8 → 1.12.0

package/src/ephemeral-server.ts

@@ -0,0 +1,185 @@
+import 'abort-controller/polyfill'; // eslint-disable-line import/no-unassigned-import
+import { Duration, SearchAttributeType } from '@temporalio/common';
+import { msToNumber } from '@temporalio/common/lib/time';
+import { native } from '@temporalio/core-bridge';
+import { SearchAttributeKey } from '@temporalio/common/lib/search-attributes';
+import pkg from './pkg';
+
+/**
+ * Configuration for the Temporal CLI Dev Server.
+ */
+export interface DevServerConfig {
+  type: 'dev-server';
+
+  executable?: EphemeralServerExecutable;
+
+  /**
+   * Sqlite DB filename if persisting or non-persistent if none (default).
+   */
+  dbFilename?: string;
+
+  /**
+   * Namespace to use - created at startup.
+   *
+   * @default "default"
+   */
+  namespace?: string;
+
+  /**
+   * IP to bind to.
+   *
+   * @default localhost
+   */
+  ip?: string;
+
+  /**
+   * Port to listen on; defaults to find a random free port.
+   */
+  port?: number;
+
+  /**
+   * Whether to enable the UI.
+   *
+   * @default true if `uiPort` is set; defaults to `false` otherwise.
+   */
+  ui?: boolean;
+
+  /**
+   * Port to listen on for the UI; if `ui` is true, defaults to `port + 1000`.
+   */
+  uiPort?: number;
+
+  /**
+   * Log format and level
+   * @default { format: "pretty", level" "warn" }
+   */
+  log?: { format: string; level: string };
+
+  /**
+   * Extra args to pass to the executable command.
+   *
+   * 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.
+   */
+  extraArgs?: string[];
+
+  /**
+   * Search attributes to be registered with the dev server.
+   */
+  searchAttributes?: SearchAttributeKey<SearchAttributeType>[];
+}
+
+/**
+ * Configuration for the time-skipping test server.
+ */
+export interface TimeSkippingServerConfig {
+  type: 'time-skipping';
+
+  executable?: EphemeralServerExecutable;
+
+  /**
+   * Optional port to listen on, defaults to find a random free port.
+   */
+  port?: number;
+
+  /**
+   * Extra args to pass to the executable command.
+   *
+   * Note that the Test Server implementation may be changed to another one in the future. Therefore, there is
+   * no guarantee that server options, and particularly those provided through the `extraArgs` array, will continue to
+   * be supported in the future.
+   */
+  extraArgs?: string[];
+}
+
+/**
+ * Which version of the executable to run.
+ */
+export type EphemeralServerExecutable =
+  | {
+      type: 'cached-download';
+      /**
+       * Download destination directory or the system's temp directory if none set.
+       */
+      downloadDir?: string;
+      /**
+       * Optional version, can be set to a specific server release or "default" or "latest".
+       *
+       * At the time of writing the the server is released as part of the
+       * Java SDK - (https://github.com/temporalio/sdk-java/releases).
+       *
+       * @default "default" - get the best version for the current SDK version.
+       */
+      version?: string;
+
+      /** How long to cache the download for. Default to 1 day. */
+      ttl?: Duration;
+    }
+  | {
+      type: 'existing-path';
+      /** Path to executable */
+      path: string;
+    };
+
+/**
+ * @internal
+ */
+export function toNativeEphemeralServerConfig(
+  server: DevServerConfig | TimeSkippingServerConfig
+): native.EphemeralServerConfig {
+  switch (server.type) {
+    case 'dev-server':
+      return {
+        type: 'dev-server',
+        exe: toNativeEphemeralServerExecutableConfig(server.executable),
+        ip: server.ip ?? '127.0.0.1',
+        port: server.port ?? null,
+        ui: server.ui ?? false,
+        uiPort: server.uiPort ?? null,
+        namespace: server.namespace ?? 'default',
+        dbFilename: server.dbFilename ?? null,
+        log: server.log ?? { format: 'pretty', level: 'warn' },
+        extraArgs: server.extraArgs ?? [],
+      };
+
+    case 'time-skipping':
+      return {
+        type: 'time-skipping',
+        exe: toNativeEphemeralServerExecutableConfig(server.executable),
+        port: server.port ?? null,
+        extraArgs: server.extraArgs ?? [],
+      };
+
+    default:
+      throw new TypeError(`Unsupported server type: ${String((server as any).type)}`);
+  }
+}
+
+/**
+ * @internal
+ */
+function toNativeEphemeralServerExecutableConfig(
+  executable: EphemeralServerExecutable = { type: 'cached-download' }
+): native.EphemeralServerExecutableConfig {
+  switch (executable.type) {
+    case 'cached-download':
+      return {
+        type: 'cached-download',
+        downloadDir: executable.downloadDir ?? null,
+        version: executable.version ?? 'default',
+        ttl: msToNumber(executable.ttl ?? '1d'),
+        sdkName: 'sdk-typescript',
+        sdkVersion: pkg.version,
+      };
+
+    case 'existing-path':
+      return {
+        type: 'existing-path',
+        path: executable.path,
+      };
+
+    default:
+      throw new TypeError(`Unsupported server executable type: ${String((executable as any).type)}`);
+  }
+}

package/src/index.ts

@@ -8,109 +8,35 @@
  * @module
  */
 
-import 'abort-controller/polyfill'; // eslint-disable-line import/no-unassigned-import
 import path from 'node:path';
-import events from 'node:events';
-import * as activity from '@temporalio/activity';
-import {
-  AsyncCompletionClient,
-  Client,
-  ClientOptions,
-  WorkflowClient,
-  WorkflowClientOptions,
-  WorkflowResultOptions,
-} from '@temporalio/client';
-import {
-  ActivityFunction,
-  Duration,
-  SdkComponent,
-  Logger,
-  defaultFailureConverter,
-  defaultPayloadConverter,
-} from '@temporalio/common';
-import { msToNumber, msToTs, tsToMs } from '@temporalio/common/lib/time';
-import { ActivityInterceptorsFactory, DefaultLogger, NativeConnection, Runtime } from '@temporalio/worker';
-import { withMetadata } from '@temporalio/worker/lib/logger';
-import { Activity } from '@temporalio/worker/lib/activity';
-import {
-  EphemeralServer,
-  EphemeralServerConfig,
-  getEphemeralServerTarget,
-  DevServerConfig,
-  TimeSkippingServerConfig,
-} from '@temporalio/core-bridge';
-import { filterNullAndUndefined } from '@temporalio/common/lib/internal-non-workflow';
-import { Connection, TestService } from './connection';
 
-export { TimeSkippingServerConfig, DevServerConfig, EphemeralServerExecutable } from '@temporalio/core-bridge';
-export { EphemeralServerConfig };
-
-export interface TimeSkippingWorkflowClientOptions extends WorkflowClientOptions {
-  connection: Connection;
-  enableTimeSkipping: boolean;
-}
-
-export interface TestEnvClientOptions extends ClientOptions {
-  connection: Connection;
-  enableTimeSkipping: boolean;
-}
-
-/**
- * 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.
- */
-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,
-    });
-  }
-}
+export {
+  TestWorkflowEnvironment,
+  type LocalTestWorkflowEnvironmentOptions,
+  type TimeSkippingTestWorkflowEnvironmentOptions,
+  type ExistingServerTestWorkflowEnvironmentOptions,
+} from './testing-workflow-environment';
+
+export {
+  type DevServerConfig,
+  type TimeSkippingServerConfig,
+  type EphemeralServerExecutable,
+} from './ephemeral-server';
+
+export {
+  // FIXME: Revise the pertinence of these types
+  type ClientOptionsForTestEnv,
+  type TestEnvClientOptions,
+  type TimeSkippingWorkflowClientOptions,
+  TestEnvClient,
+  TimeSkippingWorkflowClient,
+} from './client';
+
+export {
+  type MockActivityEnvironmentOptions,
+  MockActivityEnvironment,
+  defaultActivityInfo,
+} from './mocking-activity-environment';
 
 /**
  * Convenience workflow interceptors
@@ -119,341 +45,3 @@ class TestEnvClient extends Client {
  * retryable `ApplicationFailure`s.
  */
 export const workflowInterceptorModules = [path.join(__dirname, 'assert-to-failure-interceptor')];
-
-/**
- * Subset of the "normal" client options that are used to create a client for the test environment.
- */
-export type ClientOptionsForTestEnv = Omit<ClientOptions, 'namespace' | 'connection'>;
-
-/**
- * Options for {@link TestWorkflowEnvironment.create}
- */
-export type TestWorkflowEnvironmentOptions = {
-  server: EphemeralServerConfig;
-  client?: ClientOptionsForTestEnv;
-};
-
-/**
- * Options for {@link TestWorkflowEnvironment.createTimeSkipping}
- */
-export type TimeSkippingTestWorkflowEnvironmentOptions = {
-  server?: Omit<TimeSkippingServerConfig, 'type'>;
-  client?: ClientOptionsForTestEnv;
-};
-
-/**
- * Options for {@link TestWorkflowEnvironment.createLocal}
- */
-export type LocalTestWorkflowEnvironmentOptions = {
-  server?: Omit<DevServerConfig, 'type'>;
-  client?: ClientOptionsForTestEnv;
-};
-
-export type TestWorkflowEnvironmentOptionsWithDefaults = Required<TestWorkflowEnvironmentOptions>;
-
-function addDefaults(opts: TestWorkflowEnvironmentOptions): TestWorkflowEnvironmentOptionsWithDefaults {
-  return {
-    client: {},
-    ...opts,
-  };
-}
-
-/**
- * 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 class TestWorkflowEnvironment {
-  /**
-   * 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: Connection;
-
-  /**
-   * A {@link TestEnvClient} for interacting with the ephemeral server
-   */
-  public readonly client: Client;
-
-  /**
-   * An {@link AsyncCompletionClient} for interacting with the test server
-   *
-   * @deprecated - use `client.activity` instead
-   */
-  public readonly asyncCompletionClient: AsyncCompletionClient;
-
-  /**
-   * A {@link TimeSkippingWorkflowClient} for interacting with the test server
-   *
-   * @deprecated - use `client.workflow` instead
-   */
-  public readonly workflowClient: WorkflowClient;
-
-  /**
-   * A {@link NativeConnection} for interacting with the test server.
-   *
-   * Use this connection when creating Workers for testing.
-   */
-  public readonly nativeConnection: NativeConnection;
-
-  protected constructor(
-    public readonly options: TestWorkflowEnvironmentOptionsWithDefaults,
-    public readonly supportsTimeSkipping: boolean,
-    protected readonly server: EphemeralServer,
-    connection: Connection,
-    nativeConnection: NativeConnection,
-    namespace: string | undefined
-  ) {
-    this.connection = connection;
-    this.nativeConnection = nativeConnection;
-    this.namespace = namespace;
-    this.client = new TestEnvClient({
-      connection,
-      namespace: this.namespace,
-      enableTimeSkipping: supportsTimeSkipping,
-      ...options.client,
-    });
-    // eslint-disable-next-line deprecation/deprecation
-    this.asyncCompletionClient = this.client.activity;
-    // eslint-disable-next-line deprecation/deprecation
-    this.workflowClient = this.client.workflow;
-  }
-
-  /**
-   * 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 Serveer 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 binairies 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?: TimeSkippingTestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment> {
-    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
-   * binairies 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?: LocalTestWorkflowEnvironmentOptions): Promise<TestWorkflowEnvironment> {
-    return await this.create({
-      server: { type: 'dev-server', ...opts?.server },
-      client: opts?.client,
-      namespace: opts?.server?.namespace,
-      supportsTimeSkipping: false,
-    });
-  }
-
-  /**
-   * Create a new test environment
-   */
-  private static async create(
-    opts: TestWorkflowEnvironmentOptions & {
-      supportsTimeSkipping: boolean;
-      namespace?: string;
-    }
-  ): Promise<TestWorkflowEnvironment> {
-    const { supportsTimeSkipping, namespace, ...rest } = opts;
-    const optsWithDefaults = addDefaults(filterNullAndUndefined(rest));
-    const server = await Runtime.instance().createEphemeralServer(optsWithDefaults.server);
-    const address = getEphemeralServerTarget(server);
-
-    const nativeConnection = await NativeConnection.connect({ address });
-    const connection = await Connection.connect({ address });
-
-    return new this(optsWithDefaults, supportsTimeSkipping, server, connection, nativeConnection, namespace);
-  }
-
-  /**
-   * Kill the test server process and close the connection to it
-   */
-  async teardown(): Promise<void> {
-    await this.connection.close();
-    await this.nativeConnection.close();
-    await Runtime.instance().shutdownEphemeralServer(this.server);
-  }
-
-  /**
-   * 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: Duration): Promise<void> => {
-    if (this.supportsTimeSkipping) {
-      await (this.connection as Connection).testService.unlockTimeSkippingWithSleep({ duration: msToTs(durationMs) });
-    } else {
-      await new Promise((resolve) => setTimeout(resolve, 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(): Promise<number> {
-    if (this.supportsTimeSkipping) {
-      const { time } = await (this.connection as Connection).testService.getCurrentTime({});
-      return tsToMs(time);
-    } else {
-      return Date.now();
-    }
-  }
-}
-
-export interface MockActivityEnvironmentOptions {
-  interceptors?: ActivityInterceptorsFactory[];
-  logger?: Logger;
-}
-
-/**
- * Used as the default activity info for Activities executed in the {@link MockActivityEnvironment}
- */
-export const defaultActivityInfo: activity.Info = {
-  attempt: 1,
-  taskQueue: 'test',
-  isLocal: false,
-  taskToken: Buffer.from('test'),
-  activityId: 'test',
-  activityType: 'unknown',
-  workflowType: 'test',
-  base64TaskToken: Buffer.from('test').toString('base64'),
-  heartbeatTimeoutMs: undefined,
-  heartbeatDetails: undefined,
-  activityNamespace: 'default',
-  workflowNamespace: 'default',
-  workflowExecution: { workflowId: 'test', runId: 'dead-beef' },
-  scheduledTimestampMs: 1,
-  startToCloseTimeoutMs: 1000,
-  scheduleToCloseTimeoutMs: 1000,
-  currentAttemptScheduledTimestampMs: 1,
-};
-
-/**
- * An execution environment for testing Activities.
- *
- * Mocks Activity {@link Context | activity.Context} and exposes hooks for cancellation and heartbeats.
- *
- * Note that the `Context` object used by this environment will be reused for all activities that are run in this
- * environment. Consequently, once `cancel()` is called, any further activity that gets executed in this environment
- * will immediately be in a cancelled state.
- */
-export class MockActivityEnvironment extends events.EventEmitter {
-  public cancel: (reason?: any) => void = () => undefined;
-  public readonly context: activity.Context;
-  private readonly activity: Activity;
-
-  constructor(info?: Partial<activity.Info>, opts?: MockActivityEnvironmentOptions) {
-    super();
-    const heartbeatCallback = (details?: unknown) => this.emit('heartbeat', details);
-    const loadedDataConverter = {
-      payloadConverter: defaultPayloadConverter,
-      payloadCodecs: [],
-      failureConverter: defaultFailureConverter,
-    };
-    this.activity = new Activity(
-      { ...defaultActivityInfo, ...info },
-      undefined,
-      loadedDataConverter,
-      heartbeatCallback,
-      withMetadata(opts?.logger ?? new DefaultLogger(), { sdkComponent: SdkComponent.worker }),
-      opts?.interceptors ?? []
-    );
-    this.context = this.activity.context;
-    this.cancel = this.activity.cancel;
-  }
-
-  /**
-   * Run a function in Activity Context
-   */
-  public async run<P extends any[], R, F extends ActivityFunction<P, R>>(fn: F, ...args: P): Promise<R> {
-    return this.activity.runNoEncoding(fn as ActivityFunction<any, any>, { args, headers: {} }) as Promise<R>;
-  }
-}