@temporal-contract/testing

---

@temporal-contract/testing / time-skipping

time-skipping

Type Aliases

CreateTimeSkippingContractTestOptions

type CreateTimeSkippingContractTestOptions<TContract> = object;

Defined in: time-skipping.ts:115

Options for createTimeSkippingContractTest.

Type Parameters

Type Parameter
TContract extends ContractDefinition

Properties

Property	Type	Description	Defined in
activities?	ActivitiesHandler<TContract>	Activities handler built with declareActivitiesHandler. Omit it for a workflow-only worker.	time-skipping.ts:126
contract	TContract	The contract under test — its task queue names the worker's queue.	time-skipping.ts:117
environment?	TimeSkippingTestWorkflowEnvironmentOptions	Forwarded to TestWorkflowEnvironment.createTimeSkipping.	time-skipping.ts:134
replaySkipAllowlist?	Readonly<Record<string, string>>	Workflow-ID prefixes whose executions are deliberately left non-terminal, with a reason — forwarded to testRig, which fails a test that leaves an unlisted execution unreplayable.	time-skipping.ts:132
workflowsPath	string	Path to the workflows file to bundle — typically built with workflowsPathFromURL(import.meta.url, "./x.workflows.js") from @temporal-contract/worker/worker, or fixturePath from @temporal-contract/testing/workflow-bundle.	time-skipping.ts:124

Variables

it

const it: TestAPI<{
  testEnv: TestWorkflowEnvironment;
}>;

Defined in: time-skipping.ts:110

Ready-made it with the worker-scoped testEnv fixture and default environment options — createTimeSkippingTest with no arguments.

consumed from sibling packages' suites; the tsconfig paths indirection hides that usage from knip.

Functions

createTimeSkippingContractTest()

function createTimeSkippingContractTest<TContract>(options): TestAPI<{
  bundle: WorkflowBundleWithSourceMap;
  client: ContractClient<TContract>;
  rig: {
     client: ContractClient<TContract>;
     worker: TypedWorker;
  };
  testEnv: TestWorkflowEnvironment;
  worker: TypedWorker;
}>;

Defined in: time-skipping.ts:182

The one-call fixture for the time-skipping tier: a bundled worker, the contract-bound client, and the replay-on-finish check, with no Docker and no server to run.

The counterpart to createContractTest from @temporal-contract/testing/contract, which wires the same stack against the testcontainers-provided real server. Reach for that one when a test needs what only a real cluster has — visibility, search attributes, schedules, retention; reach for this one for everything else, which is most workflow tests.

The environment and the workflow bundle are worker-scoped (built once per Vitest worker process, since bundling dominates the runtime); the worker and client are per-test.

Like testRig, this deliberately does not scope the task queue: a same-workflow continue-as-new must land on the contract's static queue, because the contract is closed over inside the bundled workflow module and a test-side copy can never reach it. Suites needing isolation keep calling withTaskQueue themselves.

Type Parameters

Type Parameter
TContract extends ContractDefinition

Parameters

Parameter	Type
options	CreateTimeSkippingContractTestOptions<TContract>

Returns

TestAPI<{ bundle: WorkflowBundleWithSourceMap; client: ContractClient<TContract>; rig: { client: ContractClient<TContract>; worker: TypedWorker; }; testEnv: TestWorkflowEnvironment; worker: TypedWorker; }>

Example

import { createTimeSkippingContractTest } from "@temporal-contract/testing/time-skipping";
import { workflowsPathFromURL } from "@temporal-contract/worker/worker";
import { describe, expect } from "vitest";

const it = createTimeSkippingContractTest({
  contract: orderContract,
  workflowsPath: workflowsPathFromURL(import.meta.url, "./order.workflows.js"),
  activities,
});

describe("order processing", () => {
  it("processes an order end-to-end", async ({ client }) => {
    const result = await client.executeWorkflow("processOrder", {
      workflowId: `order-${Date.now()}`,
      args: { orderId: "ORD-1" },
    });
    await expect(result).toBeOk();
  });
});

---

createTimeSkippingEnvironment()

function createTimeSkippingEnvironment(options?): Promise<TestWorkflowEnvironment>;

Defined in: time-skipping.ts:64

Create a time-skipping TestWorkflowEnvironment directly — for suites that prefer explicit beforeAll/afterAll management over the it fixture (remember to call env.teardown()). Options are forwarded to TestWorkflowEnvironment.createTimeSkipping unchanged (e.g. to pin the test-server version via server.executable).

Parameters

Parameter	Type
options?	TimeSkippingTestWorkflowEnvironmentOptions

Returns

Promise<TestWorkflowEnvironment>

---

createTimeSkippingTest()

function createTimeSkippingTest(options?): TestAPI<{
  testEnv: TestWorkflowEnvironment;
}>;

Defined in: time-skipping.ts:87

Build a Vitest it with a worker-scoped testEnv fixture backed by a time-skipping environment created with the given options — use this instead of the ready-made it when a suite needs to pin the test server version or otherwise configure the environment:

Parameters

Parameter	Type
options?	TimeSkippingTestWorkflowEnvironmentOptions

Returns

TestAPI<{ testEnv: TestWorkflowEnvironment; }>

Example

import { createTimeSkippingTest } from "@temporal-contract/testing/time-skipping";

const it = createTimeSkippingTest({
  server: { executable: { type: "cached-download", version: "v1.3.0" } },
});

it("runs against the pinned server", async ({ testEnv }) => { ... });