feat(testing)!: contract-aware fixtures and configurable environments

- item 27: createContractTest(contract, { workflowsPath, activities?,
  workerOptions? }) — new ./contract entry; vitest fixtures exposing
  { client, typedClient, worker } wired against the testcontainers server,
  reusing the ./extension connection fixtures
- item 27: runActivity(definition, implementation, input, { env? }) — new
  vitest-free ./activity entry executing a single AsyncResult activity
  implementation inside MockActivityEnvironment, with heartbeat and
  cancellation support via a caller-provided environment
- item 28: createTimeSkippingEnvironment forwards
  TimeSkippingTestWorkflowEnvironmentOptions; new createTimeSkippingTest
  fixture factory so suites can pin the test-server version
- item 28: extension throws a descriptive error naming
  @temporal-contract/testing/global-setup when inject values are missing;
  workerConnection is now closed in teardown inside try/catch (the known
  NativeConnection shutdown race is swallowed)
- item 28: createGlobalSetup({ postgresImage, temporalImage, temporalEnv,
  quiet }) factory; the default export becomes createGlobalSetup() with the
  previous defaults; add the ./package.json export
- item 29: time-skipping TSDoc examples use .get() and the new
  TypedClient.create({ client }) + for(contract) construction; README covers
  ./contract, ./activity, ./time-skipping and fixes the Client import
- deps: @temporal-contract/client|contract|worker and unthrown become peer
  dependencies (they appear in the new public types); the workspace siblings
  are resolved via tsconfig paths / vitest aliases locally because declaring
  them as dev deps would create a cycle in the package graph (client and
  worker already devDepend on this package)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: btravers

packages/testing/README.md

@@ -14,7 +14,7 @@ pnpm add -D @temporal-contract/testing
 
 ### Global Setup
 
-Configure Vitest to start a Temporal server before all tests:
+Configure Vitest to start a Temporal server (via testcontainers — requires Docker) before all tests:
 
 ```typescript
 // vitest.config.ts
@@ -28,18 +28,89 @@ export default defineConfig({
 });
 ```
 
-### Test Extension
+To pin container images, inject extra Temporal env, or silence the progress logs, reference your own module that default-exports `createGlobalSetup(options)`:
 
-Use the `it` extension for automatic connection management:
+```typescript
+// temporal-global-setup.ts
+import { createGlobalSetup } from "@temporal-contract/testing/global-setup";
+
+export default createGlobalSetup({
+  temporalImage: "temporalio/auto-setup:1.28.0",
+  quiet: true,
+});
+```
+
+### Contract-Aware Fixtures
+
+`createContractTest` wires the whole stack for one contract — a running worker, the connection-scoped `TypedClient` root, and the contract-bound `ContractClient`:
+
+```typescript
+// order.spec.ts
+import { createContractTest } from "@temporal-contract/testing/contract";
+import { declareActivitiesHandler } from "@temporal-contract/worker/activity";
+import { workflowsPathFromURL } from "@temporal-contract/worker/worker";
+import { describe, expect } from "vitest";
+
+import { orderContract } from "./order.contract.js";
+
+const activities = declareActivitiesHandler({ contract: orderContract, activities: { ... } });
+
+const it = createContractTest(orderContract, {
+  workflowsPath: workflowsPathFromURL(import.meta.url, "./order.workflows.js"),
+  activities, // omit for a workflow-only worker
+});
+
+describe("order processing", () => {
+  it("processes an order", async ({ client, typedClient, worker }) => {
+    const result = await client.executeWorkflow("processOrder", {
+      workflowId: `order-${Date.now()}`,
+      args: { orderId: "ORD-1" },
+    });
+    expect(result.isOk()).toBe(true);
+  });
+});
+```
+
+### Unit-Testing a Single Activity
+
+`runActivity` executes one `AsyncResult`-returning activity implementation inside `@temporalio/testing`'s `MockActivityEnvironment` — no worker, no server, no Docker. Pass your own environment to observe heartbeats or trigger cancellation:
+
+```typescript
+import { runActivity } from "@temporal-contract/testing/activity";
+
+const result = await runActivity(chargeCardDefinition, chargeCard, { amount: 100 });
+expect(result.isOk()).toBe(true);
+```
+
+### Time-Skipping Environment (no Docker)
+
+The `./time-skipping` entry runs suites against Temporal's in-process time-skipping test server (downloaded and cached by `@temporalio/testing` on first use) — hour-long timers resolve instantly:
+
+```typescript
+import { it } from "@temporal-contract/testing/time-skipping";
+// or pin the server version:
+// const it = createTimeSkippingTest({ server: { executable: { type: "cached-download", version: "v1.3.0" } } });
+
+it("processes the order", async ({ testEnv }) => {
+  // testEnv.client, testEnv.nativeConnection, worker.runUntil(...)
+});
+```
+
+`createTimeSkippingEnvironment(options?)` creates the environment directly for suites preferring explicit `beforeAll`/`afterAll` management.
+
+### Connection Fixtures
+
+Use the `it` extension for automatic connection management against the testcontainers server:
 
 ```typescript
 // my-workflow.spec.ts
 import { it } from "@temporal-contract/testing/extension";
+import { Client } from "@temporalio/client";
 import { expect } from "vitest";
 
 it("should execute workflow", async ({ clientConnection, workerConnection }) => {
   // clientConnection: Connection from @temporalio/client (auto-connected, auto-closed)
-  // workerConnection: NativeConnection from @temporalio/worker (auto-connected)
+  // workerConnection: NativeConnection from @temporalio/worker (auto-connected, auto-closed)
 
   const client = new Client({ connection: clientConnection });
   // ... use client and workerConnection in your test

packages/testing/package.json

@@ -27,6 +27,14 @@
   "type": "module",
   "sideEffects": false,
   "exports": {
+    "./activity": {
+      "types": "./dist/activity.d.mts",
+      "import": "./dist/activity.mjs"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.mts",
+      "import": "./dist/contract.mjs"
+    },
     "./extension": {
       "types": "./dist/extension.d.mts",
       "import": "./dist/extension.mjs"
@@ -35,16 +43,18 @@
       "types": "./dist/global-setup.d.mts",
       "import": "./dist/global-setup.mjs"
     },
+    "./package.json": "./package.json",
     "./time-skipping": {
       "types": "./dist/time-skipping.d.mts",
       "import": "./dist/time-skipping.mjs"
     }
   },
   "scripts": {
-    "build": "tsdown src/global-setup.ts src/extension.ts src/time-skipping.ts --format esm --dts --clean",
+    "build": "tsdown src/global-setup.ts src/extension.ts src/time-skipping.ts src/contract.ts src/activity.ts --format esm --dts --clean",
     "build:docs": "typedoc",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:watch": "vitest --project unit",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
@@ -56,18 +66,25 @@
     "@temporalio/client": "catalog:",
     "@temporalio/testing": "catalog:",
     "@temporalio/worker": "catalog:",
+    "@temporalio/workflow": "catalog:",
     "@types/node": "catalog:",
     "@vitest/coverage-v8": "catalog:",
     "tsdown": "catalog:",
     "typedoc": "catalog:",
     "typedoc-plugin-markdown": "catalog:",
     "typescript": "catalog:",
-    "vitest": "catalog:"
+    "unthrown": "catalog:",
+    "vitest": "catalog:",
+    "zod": "catalog:"
   },
   "peerDependencies": {
+    "@temporal-contract/client": "workspace:^",
+    "@temporal-contract/contract": "workspace:^",
+    "@temporal-contract/worker": "workspace:^",
     "@temporalio/client": "^1",
     "@temporalio/testing": "^1",
     "@temporalio/worker": "^1",
+    "unthrown": "^5.0.0",
     "vitest": "^4"
   },
   "engines": {

packages/testing/src/__tests__/contract-test.spec.ts

@@ -0,0 +1,81 @@
+/**
+ * Integration coverage for `createContractTest` against the
+ * testcontainers-provided Temporal server (started by this package's own
+ * `global-setup`): the fixtures wire a running worker, the connection-scoped
+ * root, and the contract-bound client, and a workflow executes end-to-end
+ * through them.
+ */
+import { extname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { declareActivitiesHandler } from "@temporal-contract/worker/activity";
+import { Ok } from "unthrown";
+import { describe, expect } from "vitest";
+
+import { createContractTest } from "../contract.js";
+import { testContract } from "./test.contract.js";
+// The worker loads this module by path (`workflowsPath`); importing it here
+// too keeps its exports type-checked and visible to static analysis.
+import * as workflows from "./test.workflows.js";
+
+const activities = declareActivitiesHandler({
+  contract: testContract,
+  activities: {
+    greet: {
+      decorate: ({ name }) => Ok({ decorated: name.toUpperCase() }).toAsync(),
+    },
+  },
+});
+
+const it = createContractTest(testContract, {
+  workflowsPath: fileURLToPath(
+    new URL(`./test.workflows${extname(import.meta.url)}`, import.meta.url),
+  ),
+  activities,
+});
+
+describe("createContractTest", () => {
+  it("executes a workflow end-to-end through the contract-bound client", async ({ client }) => {
+    const result = await client.executeWorkflow("greet", {
+      workflowId: `greet-${Date.now()}`,
+      args: { name: "world" },
+    });
+
+    expect(result.isOk()).toBe(true);
+    if (result.isOk()) {
+      expect(result.value).toEqual({ message: "Hello, WORLD!" });
+    }
+  });
+
+  it("exposes the running worker and the connection-scoped root", async ({
+    worker,
+    typedClient,
+    client,
+  }) => {
+    expect(worker.getState()).toBe("RUNNING");
+    // The root memoizes contract bindings — the fixture's client is the
+    // same instance `for()` hands out.
+    expect(typedClient.for(testContract)).toBe(client);
+    // Sanity: the module registered via `workflowsPath` exports the
+    // workflow the contract declares.
+    expect(workflows.greet).toBeTypeOf("function");
+  });
+
+  it("starts a workflow and reads its result through a typed handle", async ({ client }) => {
+    const workflowId = `greet-handle-${Date.now()}`;
+    const handleResult = await client.startWorkflow("greet", {
+      workflowId,
+      args: { name: "fixtures" },
+    });
+
+    expect(handleResult.isOk()).toBe(true);
+    if (!handleResult.isOk()) return;
+
+    expect(handleResult.value.workflowId).toBe(workflowId);
+    const result = await handleResult.value.result();
+    expect(result.isOk()).toBe(true);
+    if (result.isOk()) {
+      expect(result.value).toEqual({ message: "Hello, FIXTURES!" });
+    }
+  });
+});

packages/testing/src/__tests__/test.contract.ts

@@ -0,0 +1,22 @@
+import { defineActivity, defineContract, defineWorkflow } from "@temporal-contract/contract";
+import { z } from "zod";
+
+// Minimal inline contract for exercising the contract-aware fixtures:
+// one workflow with one activity.
+
+const decorate = defineActivity({
+  input: z.object({ name: z.string() }),
+  output: z.object({ decorated: z.string() }),
+  defaultOptions: { startToCloseTimeout: "10 seconds" },
+});
+
+const greet = defineWorkflow({
+  input: z.object({ name: z.string() }),
+  output: z.object({ message: z.string() }),
+  activities: { decorate },
+});
+
+export const testContract = defineContract({
+  taskQueue: "testing-contract-fixtures",
+  workflows: { greet },
+});

packages/testing/src/__tests__/test.workflows.ts

@@ -0,0 +1,23 @@
+// Workflow implementation for the fixtures' integration test.
+//
+// Deliberately written with the raw `@temporalio/workflow` API (like
+// packages/client's integration workflows) rather than `declareWorkflow`:
+// Temporal's workflow bundler resolves imports through node_modules from
+// this file's location, and `@temporal-contract/worker` is a *peer* of this
+// package (a dev dep would put a cycle in the workspace package graph), so
+// it is not linked here. The typed surface under test — the contract-bound
+// client and the worker wiring — is unaffected.
+import { proxyActivities } from "@temporalio/workflow";
+
+type Activities = {
+  decorate(args: { name: string }): Promise<{ decorated: string }>;
+};
+
+const activities = proxyActivities<Activities>({
+  startToCloseTimeout: "10 seconds",
+});
+
+export async function greet(args: { name: string }): Promise<{ message: string }> {
+  const { decorated } = await activities.decorate({ name: args.name });
+  return { message: `Hello, ${decorated}!` };
+}