@temporal-contract/testing 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Benoit TRAVERS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# @temporal-contract/testing
+
+Shared testing utilities for temporal-contract integration tests.
+
+## Features
+
+- **Testcontainers Integration**: Automatically starts a Temporal server in a Docker container for integration tests
+- **Vitest Setup**: Pre-configured setup for Vitest with global test lifecycle
+- **Connection Management**: Handles Temporal connection setup and cleanup
+
+## Installation
+
+This package is internal to the monorepo and used by sample projects for integration testing.
+
+```bash
+pnpm add -D @temporal-contract/testing
+```
+
+## Usage
+
+### In vitest.config.ts
+
+```typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globalSetup: './vitest.global-setup.ts',
+    testTimeout: 60000,
+  },
+});
+```
+
+### In vitest.global-setup.ts
+
+```typescript
+import { setupTemporalTestContainer } from '@temporal-contract/testing';
+
+export default setupTemporalTestContainer;
+```
+
+### In your tests
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { getTemporalConnection } from '@temporal-contract/testing';
+import { TypedClient } from '@temporal-contract/client';
+
+describe('Order Processing Workflow', () => {
+  it('should process an order successfully', async () => {
+    const connection = await getTemporalConnection();
+    const client = TypedClient.create(myContract, { connection });
+
+    // Your test code here
+  });
+});
+```
+
+## API
+
+### `setupTemporalTestContainer()`
+
+Global setup function that starts a Temporal container before all tests and stops it after all tests.
+
+### `getTemporalConnection()`
+
+Returns a connection to the Temporal server running in the container.
+
+## Requirements
+
+- Docker must be running on the host machine
+- Testcontainers requires Docker API access
+
+## Environment Variables
+
+- `TESTCONTAINERS_RYUK_DISABLED`: Set to `true` to disable Ryuk container (useful in CI)

package/config/sql.yaml

@@ -0,0 +1,6 @@
+limit.maxIDLength:
+  - value: 255
+    constraints: {}
+system.forceSearchAttributesCacheRefreshOnRead:
+  - value: true # Dev setup only. Please don't turn this on in production.
+    constraints: {}

package/dist/extension.d.mts

@@ -0,0 +1,11 @@
+import { Connection } from "@temporalio/client";
+import { NativeConnection } from "@temporalio/worker/lib/connection.js";
+import * as vitest0 from "vitest";
+
+//#region src/extension.d.ts
+declare const it: vitest0.TestAPI<{
+  clientConnection: Connection;
+  workerConnection: NativeConnection;
+}>;
+//#endregion
+export { it };

package/dist/extension.mjs

@@ -0,0 +1,35 @@
+import { Connection } from "@temporalio/client";
+import { NativeConnection } from "@temporalio/worker/lib/connection.js";
+import { inject, it as it$1 } from "vitest";
+
+//#region src/extension.ts
+const it = it$1.extend({
+	clientConnection: async ({}, use) => {
+		const connection = await getTemporalConnection();
+		await use(connection);
+		await connection.close();
+	},
+	workerConnection: async ({}, use) => {
+		await use(await getTemporalWorkerConnection());
+	}
+});
+/**
+* Get a connection to the Temporal server (for client)
+* Must be called after setupTemporalTestContainer has been executed
+*/
+function getTemporalConnection() {
+	return Connection.connect({ address: getTemporalAddress() });
+}
+/**
+* Get a native connection to the Temporal server (for worker)
+* Must be called after setupTemporalTestContainer has been executed
+*/
+function getTemporalWorkerConnection() {
+	return NativeConnection.connect({ address: getTemporalAddress() });
+}
+function getTemporalAddress() {
+	return `${inject("__TESTCONTAINERS_TEMPORAL_IP__")}:${inject("__TESTCONTAINERS_TEMPORAL_PORT_7233__")}`;
+}
+
+//#endregion
+export { it };

package/dist/global-setup.d.mts

@@ -0,0 +1,18 @@
+import { TestProject } from "vitest/node";
+
+//#region src/global-setup.d.ts
+declare module "vitest" {
+  interface ProvidedContext {
+    __TESTCONTAINERS_TEMPORAL_IP__: string;
+    __TESTCONTAINERS_TEMPORAL_PORT_7233__: number;
+  }
+}
+/**
+ * Setup function for Vitest globalSetup
+ * Starts a Temporal server container before all tests
+ */
+declare function setup({
+  provide
+}: TestProject): Promise<() => Promise<void>>;
+//#endregion
+export { setup as default };

package/dist/global-setup.mjs

@@ -0,0 +1,70 @@
+import { GenericContainer, Network, Wait } from "testcontainers";
+
+//#region src/global-setup.ts
+/**
+* Setup function for Vitest globalSetup
+* Starts a Temporal server container before all tests
+*/
+async function setup({ provide }) {
+	console.log("🐳 Starting Temporal test environment...");
+	const network = await new Network().start();
+	console.log("🐳 Starting PostgreSQL container...");
+	const postgresContainer = await new GenericContainer("postgres:18.1").withNetwork(network).withNetworkAliases("postgres").withExposedPorts(5432).withEnvironment({
+		POSTGRES_DB: "temporal",
+		POSTGRES_USER: "temporal",
+		POSTGRES_PASSWORD: "temporal"
+	}).withHealthCheck({
+		test: ["CMD-SHELL", "pg_isready -U temporal"],
+		interval: 1e3,
+		retries: 30,
+		startPeriod: 1e3,
+		timeout: 1e3
+	}).withWaitStrategy(Wait.forHealthCheck()).withStartupTimeout(12e4).start();
+	console.log("✅ PostgreSQL container started");
+	console.log("🐳 Starting Temporal container...");
+	const temporalContainer = await new GenericContainer("temporalio/auto-setup:1.29.1").withNetwork(network).withExposedPorts(7233).withEnvironment({
+		DB: "postgres12",
+		DB_PORT: "5432",
+		POSTGRES_SEEDS: "postgres",
+		POSTGRES_USER: "temporal",
+		POSTGRES_PWD: "temporal",
+		BIND_ON_IP: "0.0.0.0",
+		TEMPORAL_BROADCAST_ADDRESS: "127.0.0.1"
+	}).withHealthCheck({
+		test: ["CMD-SHELL", "tctl --address 127.0.0.1:7233 workflow list"],
+		interval: 1e3,
+		retries: 30,
+		startPeriod: 1e3,
+		timeout: 1e3
+	}).withWaitStrategy(Wait.forHealthCheck()).start();
+	console.log("✅ Temporal container started");
+	const __TESTCONTAINERS_TEMPORAL_IP__ = temporalContainer.getHost();
+	const __TESTCONTAINERS_TEMPORAL_PORT_7233__ = temporalContainer.getMappedPort(7233);
+	provide("__TESTCONTAINERS_TEMPORAL_IP__", __TESTCONTAINERS_TEMPORAL_IP__);
+	provide("__TESTCONTAINERS_TEMPORAL_PORT_7233__", __TESTCONTAINERS_TEMPORAL_PORT_7233__);
+	console.log(`🚀 Temporal test environment is ready at ${__TESTCONTAINERS_TEMPORAL_IP__}:${__TESTCONTAINERS_TEMPORAL_PORT_7233__}`);
+	return async () => {
+		console.log("🧹 Cleaning up Temporal test environment...");
+		try {
+			await temporalContainer.stop();
+			console.log("✅ Temporal container stopped");
+		} catch (error) {
+			console.error("⚠️  Error stopping container:", error);
+		}
+		try {
+			await postgresContainer.stop();
+			console.log("✅ PostgreSQL container stopped");
+		} catch (error) {
+			console.error("⚠️  Error stopping PostgreSQL container:", error);
+		}
+		try {
+			await network.stop();
+			console.log("✅ Network stopped");
+		} catch (error) {
+			console.error("⚠️  Error stopping network:", error);
+		}
+	};
+}
+
+//#endregion
+export { setup as default };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@temporal-contract/testing",
+  "version": "0.0.1",
+  "description": "Shared testing utilities for temporal-contract",
+  "type": "module",
+  "exports": {
+    "./global-setup": {
+      "types": "./dist/global-setup.d.mts",
+      "import": "./dist/global-setup.mjs"
+    },
+    "./extension": {
+      "types": "./dist/extension.d.mts",
+      "import": "./dist/extension.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "config"
+  ],
+  "dependencies": {
+    "@temporalio/client": "1.13.2",
+    "@temporalio/worker": "1.13.2",
+    "testcontainers": "11.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.2",
+    "tsdown": "0.17.2",
+    "typescript": "5.9.3",
+    "vitest": "4.0.15",
+    "@temporal-contract/tsconfig": "0.0.1"
+  },
+  "peerDependencies": {
+    "vitest": "^4"
+  },
+  "scripts": {
+    "build": "tsdown src/global-setup.ts src/extension.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit"
+  }
+}