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: ConnectionLike

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: string | number) => Promise<void>

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

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
},
},
// ...
});
Parameters
NameTypeDescription
durationMsstring | numbernumber of milliseconds or ms-formatted string
Returns

Promise<void>


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>


create

Static create(opts?): Promise<TestWorkflowEnvironment>

Create a new test environment

Deprecated

Parameters

NameType
opts?TestWorkflowEnvironmentOptions

Returns

Promise<TestWorkflowEnvironment>


createLocal

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

Internally, this uses 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 LocalTestWorkflowEnvironmentOptions.server.executable.type is 'cached-download'.

In the future, the Temporalite implementation may be changed to another implementation.

Parameters

NameType
opts?LocalTestWorkflowEnvironmentOptions

Returns

Promise<TestWorkflowEnvironment>


createTimeSkipping

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