Skip to main content

Class: TestWorkflowEnvironment

An execution environment for running Workflow integration tests.

Runs an external server. By default, the Java test server is used which supports time skipping.

Properties​

address​

readonly address: string

Address used when constructing connection and nativeConnection

asyncCompletionClient​

readonly asyncCompletionClient: AsyncCompletionClient

An AsyncCompletionClient for interacting with the test server

Deprecated​

  • use client.activity instead

client​

readonly client: Client

A TimeSkippingClient for interacting with the ephemeral server

connection​

readonly connection: Connection

Get an established Connection to the ephemeral server

connectionOptions​

readonly connectionOptions: ExistingServerConnectionOptions

Connection options used when constructing connection and nativeConnection.

namespace?​

readonly optional namespace?: string

Namespace used in this environment (taken from TestWorkflowEnvironmentOptions)

nativeConnection​

readonly nativeConnection: NativeConnection

A NativeConnection for interacting with the test server.

Use this connection when creating Workers for testing.

options​

readonly options: TestWorkflowEnvironmentOptionsWithDefaults

sleep​

sleep: (durationMs) => 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".

Parameters​

durationMs​

Duration

number of milliseconds or ms-formatted string

Returns​

Promise<void>

Example​

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

const worker = await Worker.create({
  connection: testEnv.nativeConnection,
  activities: {
    async longRunning() {
      await testEnv.sleep(1_000_000); // <-- sleep called here
    },
  },
  // ...
});

supportsTimeSkipping​

readonly supportsTimeSkipping: boolean

workflowClient​

readonly workflowClient: WorkflowClient

A TimeSkippingWorkflowClient for interacting with the test server

Deprecated​

  • use client.workflow instead

Methods​

createNexusEndpoint()​

createNexusEndpoint(name, taskQueue): Promise<NexusEndpointIdentifier>

Create a Nexus endpoint targeting a worker task queue.

This is a convenience method that wraps connection.operatorService.createNexusEndpoint for easier testing of Nexus services.

Parameters​

name​

string

The name of the Nexus endpoint

taskQueue​

string

The task queue that will handle Nexus operations

Returns​

Promise<NexusEndpointIdentifier>

The created Nexus endpoint

Example​

const endpoint = await testEnv.createNexusEndpoint('my-endpoint', 'my-task-queue');
const endpointId = endpoint.id;

currentTimeMs()​

currentTimeMs(): Promise<number>

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.

Returns​

Promise<number>

deleteNexusEndpoint()​

deleteNexusEndpoint(endpoint): Promise<void>

Delete a Nexus endpoint.

This is a convenience method that wraps connection.operatorService.deleteNexusEndpoint for easier testing of Nexus services.

Parameters​

endpoint​

Pick<NexusEndpointIdentifier, "id" | "version">

The endpoint to delete (can pass the full endpoint object or just an object with id and version)

Returns​

Promise<void>

Example​

const endpoint = await testEnv.createNexusEndpoint('my-endpoint', 'my-task-queue');
// ... use the endpoint ...
await testEnv.deleteNexusEndpoint(endpoint);

teardown()​

teardown(): Promise<void>

Kill the test server process and close the connection to it

Returns​

Promise<void>

createFromExistingServer()​

static createFromExistingServer(opts?): 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.

Parameters​

opts?​

ExistingServerTestWorkflowEnvironmentOptions

Returns​

Promise<TestWorkflowEnvironment>

createLocal()​

static createLocal(opts?): Promise<TestWorkflowEnvironment>

Start a full Temporal server locally.

This environment is good for testing full server capabilities, but does not support time skipping like createTimeSkipping does. supportsTimeSkipping will always return false for this environment. sleep will sleep the actual amount of time and currentTimeMs will return the current time.

This local environment will be powered by Temporal 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 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.

Parameters​

opts?​

LocalTestWorkflowEnvironmentOptions

Returns​

Promise<TestWorkflowEnvironment>

createTimeSkipping()​

static createTimeSkipping(opts?): Promise<TestWorkflowEnvironment>

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 WorkflowClient.execute). Before the result is awaited on, time can be manually skipped forward using sleep. The currently known time can be obtained via currentTimeMs.

This environment will be powered by the Temporal Time Skipping Test Server (part of the Java SDK). 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 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 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.

Parameters​

opts?​

TimeSkippingTestWorkflowEnvironmentOptions

Returns​

Promise<TestWorkflowEnvironment>