@btravstack/temporal-testing

---

@btravstack/temporal-testing

Type Aliases

TemporalEnvironment

type TemporalEnvironment = object;

Defined in: index.ts:39

The environment a spec spreads into start's env: the server, and a namespace of the spec file's own.

Properties

Property	Modifier	Type	Defined in
TEMPORAL_ADDRESS	readonly	string	index.ts:40
TEMPORAL_NAMESPACE	readonly	string	index.ts:41

---

TemporalServerOptions

type TemporalServerOptions = object;

Defined in: index.ts:18

Options for temporalServer.

Properties

Property	Modifier	Type	Default value	Description	Defined in
reuse?	readonly	boolean	true	true attaches to the server an earlier or a concurrent run on the same Docker host started, and leaves it running for the next one. false starts a server for this run alone and stops it when the run ends.	index.ts:35
startupTimeoutMs?	readonly	number	60_000	How long the container may take to report healthy, in milliseconds: the Docker health check's start period and retry count, testcontainers' own wait, and how long a run refused the shared name waits for the winner's container, all take it.	index.ts:27

Variables

default

default: (__namedParameters) => Promise<(() => Promise<void>) | undefined>;

Defined in: index.ts:101

Parameters

Parameter	Type
__namedParameters	TestProject

Returns

Promise<(() => Promise<void>) | undefined>

Functions

temporalEnvironment()

function temporalEnvironment(prefix?): [(context, use) => Promise<void>, {
  scope: "file";
}];

Defined in: index.ts:223

A file-scoped Vitest fixture answering the TemporalEnvironment of a namespace registered for the spec file, on the server temporalServer provided. The namespace is the isolation boundary: the starter reads its task queue off the contract, so two spec files polling the same queue are kept apart by namespace, and so are suites listing workflows on a shared server. Nothing is cleaned up.

Parameters

Parameter	Type	Default value
prefix?	string	"spec"

Returns

[(context, use) => Promise<void>, { scope: "file"; }]

Example

export const it = test.extend<{ temporal: TemporalEnvironment; boot: Boot }>({
  temporal: temporalEnvironment("orders"),
  boot: bootFixture(),
});

it("fulfils", async ({ temporal, boot }) => {
  const app = boot(OrderWorker, { env: { ...temporal } });
});

---

temporalNamespace()

function temporalNamespace(address, prefix?): Promise<string>;

Defined in: index.ts:174

Registers the namespace <prefix>-<uuid> on the Temporal server at address, and answers its name once every Temporal service can use it. It needs no test context, so a Vitest globalSetup can register one namespace for the whole run, for workers it starts once and shares across spec files.

Registering a namespace is not the same as being able to use one: each Temporal service refreshes its namespace registry on its own interval, so a namespace-scoped read is retried for up to a minute, each read under that deadline. A namespace that never becomes usable, or a server that stops answering, rejects with an error naming the namespace, the server's last answer as its cause.

Parameters

Parameter	Type	Default value
address	string	undefined
prefix?	string	"spec"

Returns

Promise<string>

Example

// workers-setup.ts, named in `globalSetup` after the server's setup
export default async (project: TestProject) => {
  const address = project.getProvidedContext().__BTRAVSTACK_TEMPORAL_ADDRESS__;
  const namespace = await temporalNamespace(address, "workers");
};

---

temporalServer()

function temporalServer(__namedParameters?): (__namedParameters) => Promise<(() => Promise<void>) | undefined>;

Defined in: index.ts:71

A Vitest globalSetup providing a Temporal server's address: the Temporal CLI's development server, one temporalio/temporal container started through testcontainers, in memory. The package default-exports it with the default options, so globalSetup: ["@btravstack/temporal-testing"] is the whole configuration.

By default the container is reused: every run on the Docker host, including concurrent ones in other processes, attaches to one server, which outlives the run. reuse: false owns a server for this run instead, and stops it at the run's end.

Parameters

Parameter	Type
__namedParameters?	TemporalServerOptions

Returns

(__namedParameters) => Promise<(() => Promise<void>) | undefined>

Example

// temporal-setup.ts, for a run that owns its server
import { temporalServer } from "@btravstack/temporal-testing";

export default temporalServer({ reuse: false });