Skip to main content

Class: TestWorkflowEnvironment

testing.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​

asyncCompletionClient​

• Readonly asyncCompletionClient: AsyncCompletionClient

An AsyncCompletionClient for interacting with the test server

Deprecated

  • use client.activity instead

client​

• Readonly client: Client

A TestEnvClient for interacting with the ephemeral server

connection​

• Readonly connection: Connection

Get an established Connection to the ephemeral server

namespace​

• Optional Readonly 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: Required<TestWorkflowEnvironmentOptions>

sleep​

• sleep: (durationMs: Duration) => 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

number of milliseconds or ms-formatted string

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
    },
  },
  // ...
});

Type declaration​

▸ (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​
NameTypeDescription
durationMsDurationnumber 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​

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>

teardown​

▸ teardown(): Promise<void>

Kill the test server process and close the connection to it

Returns​

Promise<void>

createLocal​

▸ createLocal(opts?): Promise<TestWorkflowEnvironment>

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

The CLI executable will be downloaded and cached to a temporary directory. See LocalTestWorkflowEnvironmentOptions.server.executable.type if you'd prefer to provide the CLI executable yourself.

Parameters​

NameType
opts?LocalTestWorkflowEnvironmentOptions

Returns​

Promise<TestWorkflowEnvironment>

createTimeSkipping​

▸ createTimeSkipping(opts?): Promise<TestWorkflowEnvironment>

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

Internally, this environment lazily downloads a test-server binary for the current OS/arch from the Java SDK releases into the temp directory if it is not already there. Then the executable is started and will be killed when 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.

Parameters​

NameType
opts?TimeSkippingTestWorkflowEnvironmentOptions

Returns​

Promise<TestWorkflowEnvironment>