@temporal-contract/testing 0.0.7 → 0.2.0

package/README.md

@@ -12,18 +12,40 @@ pnpm add -D @temporal-contract/testing
 
 ## Quick Example
 
+### Global Setup
+
+Configure Vitest to start a Temporal server before all tests:
+
 ```typescript
 // vitest.config.ts
-import { defineConfig } from 'vitest/config';
+import { defineConfig } from "vitest/config";
 
 export default defineConfig({
   test: {
-    globalSetup: '@temporal-contract/testing/global-setup',
+    globalSetup: "@temporal-contract/testing/global-setup",
     testTimeout: 60000,
   },
 });
 ```
 
+### Test Extension
+
+Use the `it` extension for automatic connection management:
+
+```typescript
+// my-workflow.spec.ts
+import { it } from "@temporal-contract/testing/extension";
+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)
+
+  const client = new Client({ connection: clientConnection });
+  // ... use client and workerConnection in your test
+});
+```
+
 ## Documentation
 
 📖 **[Read the full documentation →](https://btravers.github.io/temporal-contract)**

package/dist/extension.d.mts

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

package/dist/extension.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.mts","names":[],"sources":["../src/extension.ts"],"mappings":";;;;;cAIa,EAAA,SAAE,OAAA"}

package/dist/extension.mjs

@@ -32,4 +32,5 @@ function getTemporalAddress() {
 }
 
 //#endregion
-export { it };
+export { it };
+//# sourceMappingURL=extension.mjs.map

package/dist/extension.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.mjs","names":["vitestIt"],"sources":["../src/extension.ts"],"sourcesContent":["import { Connection } from \"@temporalio/client\";\nimport { NativeConnection } from \"@temporalio/worker/lib/connection.js\";\nimport { inject, it as vitestIt } from \"vitest\";\n\nexport const it = vitestIt.extend<{\n  clientConnection: Connection;\n  workerConnection: NativeConnection;\n}>({\n  // oxlint-disable-next-line no-empty-pattern\n  clientConnection: async ({}, use) => {\n    const connection = await getTemporalConnection();\n    await use(connection);\n    await connection.close();\n  },\n  // oxlint-disable-next-line no-empty-pattern\n  workerConnection: async ({}, use) => {\n    const connection = await getTemporalWorkerConnection();\n    await use(connection);\n    // Note: NativeConnection.close() may cause issues in test cleanup,\n    // let the test framework handle cleanup instead\n  },\n});\n\n/**\n * Get a connection to the Temporal server (for client)\n * Must be called after setupTemporalTestContainer has been executed\n */\nfunction getTemporalConnection(): Promise<Connection> {\n  return Connection.connect({\n    address: getTemporalAddress(),\n  });\n}\n\n/**\n * Get a native connection to the Temporal server (for worker)\n * Must be called after setupTemporalTestContainer has been executed\n */\nfunction getTemporalWorkerConnection(): Promise<NativeConnection> {\n  return NativeConnection.connect({\n    address: getTemporalAddress(),\n  });\n}\n\nfunction getTemporalAddress(): string {\n  return `${inject(\"__TESTCONTAINERS_TEMPORAL_IP__\")}:${inject(\"__TESTCONTAINERS_TEMPORAL_PORT_7233__\")}`;\n}\n"],"mappings":";;;;;AAIA,MAAa,KAAKA,KAAS,OAGxB;CAED,kBAAkB,OAAO,IAAI,QAAQ;EACnC,MAAM,aAAa,MAAM,uBAAuB;AAChD,QAAM,IAAI,WAAW;AACrB,QAAM,WAAW,OAAO;;CAG1B,kBAAkB,OAAO,IAAI,QAAQ;AAEnC,QAAM,IADa,MAAM,6BAA6B,CACjC;;CAIxB,CAAC;;;;;AAMF,SAAS,wBAA6C;AACpD,QAAO,WAAW,QAAQ,EACxB,SAAS,oBAAoB,EAC9B,CAAC;;;;;;AAOJ,SAAS,8BAAyD;AAChE,QAAO,iBAAiB,QAAQ,EAC9B,SAAS,oBAAoB,EAC9B,CAAC;;AAGJ,SAAS,qBAA6B;AACpC,QAAO,GAAG,OAAO,iCAAiC,CAAC,GAAG,OAAO,wCAAwC"}

package/dist/global-setup.d.mts

@@ -15,4 +15,5 @@ declare function setup({
   provide
 }: TestProject): Promise<() => Promise<void>>;
 //#endregion
-export { setup as default };
+export { setup as default };
+//# sourceMappingURL=global-setup.d.mts.map

package/dist/global-setup.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-setup.d.mts","names":[],"sources":["../src/global-setup.ts"],"mappings":";;;;YAKmB,eAAA;IACf,8BAAA;IACA,qCAAA;EAAA;AAAA;;;;;iBAQ0B,KAAA,CAAA;EAAQ;AAAA,GAAW,WAAA,GAAW,OAAA,OAAA,OAAA"}

package/dist/global-setup.mjs

@@ -67,4 +67,5 @@ async function setup({ provide }) {
 }
 
 //#endregion
-export { setup as default };
+export { setup as default };
+//# sourceMappingURL=global-setup.mjs.map

package/dist/global-setup.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-setup.mjs","names":[],"sources":["../src/global-setup.ts"],"sourcesContent":["import { GenericContainer, Wait, Network } from \"testcontainers\";\nimport type { TestProject } from \"vitest/node\";\n\ndeclare module \"vitest\" {\n  // oxlint-disable-next-line typescript/consistent-type-definitions -- module augmentation requires interface\n  export interface ProvidedContext {\n    __TESTCONTAINERS_TEMPORAL_IP__: string;\n    __TESTCONTAINERS_TEMPORAL_PORT_7233__: number;\n  }\n}\n\n/**\n * Setup function for Vitest globalSetup\n * Starts a Temporal server container before all tests\n */\nexport default async function setup({ provide }: TestProject) {\n  console.log(\"🐳 Starting Temporal test environment...\");\n\n  // Create a network for containers to communicate\n  const network = await new Network().start();\n\n  // Start PostgreSQL container first\n  console.log(\"🐳 Starting PostgreSQL container...\");\n  const postgresContainer = await new GenericContainer(\"postgres:18.1\")\n    .withNetwork(network)\n    .withNetworkAliases(\"postgres\")\n    .withExposedPorts(5432)\n    .withEnvironment({\n      POSTGRES_DB: \"temporal\",\n      POSTGRES_USER: \"temporal\",\n      POSTGRES_PASSWORD: \"temporal\",\n    })\n    .withHealthCheck({\n      test: [\"CMD-SHELL\", \"pg_isready -U temporal\"],\n      interval: 1_000,\n      retries: 30,\n      startPeriod: 1_000,\n      timeout: 1_000,\n    })\n    .withWaitStrategy(Wait.forHealthCheck())\n    .start();\n\n  console.log(\"✅ PostgreSQL container started\");\n\n  // Start Temporal container\n  console.log(\"🐳 Starting Temporal container...\");\n  const temporalContainer = await new GenericContainer(\"temporalio/auto-setup:1.29.1\")\n    .withNetwork(network)\n    .withExposedPorts(7233)\n    .withEnvironment({\n      DB: \"postgres12\",\n      DB_PORT: \"5432\",\n      POSTGRES_SEEDS: \"postgres\",\n      POSTGRES_USER: \"temporal\",\n      POSTGRES_PWD: \"temporal\",\n      BIND_ON_IP: \"0.0.0.0\",\n      TEMPORAL_BROADCAST_ADDRESS: \"127.0.0.1\",\n    })\n    .withHealthCheck({\n      test: [\"CMD-SHELL\", \"tctl --address 127.0.0.1:7233 workflow list\"],\n      interval: 1_000,\n      retries: 30,\n      startPeriod: 1_000,\n      timeout: 1_000,\n    })\n    .withWaitStrategy(Wait.forHealthCheck())\n    .start();\n\n  console.log(\"✅ Temporal container started\");\n\n  const __TESTCONTAINERS_TEMPORAL_IP__ = temporalContainer.getHost();\n  const __TESTCONTAINERS_TEMPORAL_PORT_7233__ = temporalContainer.getMappedPort(7233);\n\n  provide(\"__TESTCONTAINERS_TEMPORAL_IP__\", __TESTCONTAINERS_TEMPORAL_IP__);\n  provide(\"__TESTCONTAINERS_TEMPORAL_PORT_7233__\", __TESTCONTAINERS_TEMPORAL_PORT_7233__);\n\n  console.log(\n    `🚀 Temporal test environment is ready at ${__TESTCONTAINERS_TEMPORAL_IP__}:${__TESTCONTAINERS_TEMPORAL_PORT_7233__}`,\n  );\n\n  // Return teardown function\n  return async () => {\n    console.log(\"🧹 Cleaning up Temporal test environment...\");\n\n    try {\n      await temporalContainer.stop();\n      console.log(\"✅ Temporal container stopped\");\n    } catch (error) {\n      console.error(\"⚠️  Error stopping container:\", error);\n    }\n\n    try {\n      await postgresContainer.stop();\n      console.log(\"✅ PostgreSQL container stopped\");\n    } catch (error) {\n      console.error(\"⚠️  Error stopping PostgreSQL container:\", error);\n    }\n\n    try {\n      await network.stop();\n      console.log(\"✅ Network stopped\");\n    } catch (error) {\n      console.error(\"⚠️  Error stopping network:\", error);\n    }\n  };\n}\n"],"mappings":";;;;;;;AAeA,eAA8B,MAAM,EAAE,WAAwB;AAC5D,SAAQ,IAAI,2CAA2C;CAGvD,MAAM,UAAU,MAAM,IAAI,SAAS,CAAC,OAAO;AAG3C,SAAQ,IAAI,sCAAsC;CAClD,MAAM,oBAAoB,MAAM,IAAI,iBAAiB,gBAAgB,CAClE,YAAY,QAAQ,CACpB,mBAAmB,WAAW,CAC9B,iBAAiB,KAAK,CACtB,gBAAgB;EACf,aAAa;EACb,eAAe;EACf,mBAAmB;EACpB,CAAC,CACD,gBAAgB;EACf,MAAM,CAAC,aAAa,yBAAyB;EAC7C,UAAU;EACV,SAAS;EACT,aAAa;EACb,SAAS;EACV,CAAC,CACD,iBAAiB,KAAK,gBAAgB,CAAC,CACvC,OAAO;AAEV,SAAQ,IAAI,iCAAiC;AAG7C,SAAQ,IAAI,oCAAoC;CAChD,MAAM,oBAAoB,MAAM,IAAI,iBAAiB,+BAA+B,CACjF,YAAY,QAAQ,CACpB,iBAAiB,KAAK,CACtB,gBAAgB;EACf,IAAI;EACJ,SAAS;EACT,gBAAgB;EAChB,eAAe;EACf,cAAc;EACd,YAAY;EACZ,4BAA4B;EAC7B,CAAC,CACD,gBAAgB;EACf,MAAM,CAAC,aAAa,8CAA8C;EAClE,UAAU;EACV,SAAS;EACT,aAAa;EACb,SAAS;EACV,CAAC,CACD,iBAAiB,KAAK,gBAAgB,CAAC,CACvC,OAAO;AAEV,SAAQ,IAAI,+BAA+B;CAE3C,MAAM,iCAAiC,kBAAkB,SAAS;CAClE,MAAM,wCAAwC,kBAAkB,cAAc,KAAK;AAEnF,SAAQ,kCAAkC,+BAA+B;AACzE,SAAQ,yCAAyC,sCAAsC;AAEvF,SAAQ,IACN,4CAA4C,+BAA+B,GAAG,wCAC/E;AAGD,QAAO,YAAY;AACjB,UAAQ,IAAI,8CAA8C;AAE1D,MAAI;AACF,SAAM,kBAAkB,MAAM;AAC9B,WAAQ,IAAI,+BAA+B;WACpC,OAAO;AACd,WAAQ,MAAM,iCAAiC,MAAM;;AAGvD,MAAI;AACF,SAAM,kBAAkB,MAAM;AAC9B,WAAQ,IAAI,iCAAiC;WACtC,OAAO;AACd,WAAQ,MAAM,4CAA4C,MAAM;;AAGlE,MAAI;AACF,SAAM,QAAQ,MAAM;AACpB,WAAQ,IAAI,oBAAoB;WACzB,OAAO;AACd,WAAQ,MAAM,+BAA+B,MAAM"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temporal-contract/testing",
-  "version": "0.0.7",
+  "version": "0.2.0",
   "description": "Temporal testing utilities",
   "type": "module",
   "exports": {
@@ -18,22 +18,26 @@
     "dist"
   ],
   "dependencies": {
-    "@temporalio/client": "1.14.0",
-    "@temporalio/worker": "1.14.0",
-    "testcontainers": "11.10.0"
+    "@temporalio/client": "1.14.1",
+    "@temporalio/worker": "1.14.1",
+    "testcontainers": "11.11.0"
   },
   "devDependencies": {
-    "@types/node": "25.0.3",
-    "tsdown": "0.18.1",
+    "@types/node": "25.2.3",
+    "tsdown": "0.20.3",
+    "typedoc": "0.28.17",
+    "typedoc-plugin-markdown": "4.10.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.16",
-    "@temporal-contract/tsconfig": "0.0.7"
+    "vitest": "4.0.18",
+    "@temporal-contract/tsconfig": "0.2.0",
+    "@temporal-contract/typedoc": "0.1.0"
   },
   "peerDependencies": {
     "vitest": "^4"
   },
   "scripts": {
     "build": "tsdown src/global-setup.ts src/extension.ts --format esm --dts --clean",
+    "build:docs": "typedoc",
     "typecheck": "tsc --noEmit"
   }
 }