chore(test): add shared helpers and integration scaffold

marslavish · marslavish · commit 938c003eb57e · 2026-04-27T17:54:56.000+08:00
diff --git a/package.json b/package.json
@@ -19,6 +19,7 @@
     "build": "pnpm -r run build",
     "build:dev": "pnpm -r run build:dev",
     "test": "pnpm -r run test",
+    "test:integration": "jest --config tests/integration/jest.config.js",
     "typecheck": "node ./scripts/typecheck.js",
     "test:live:ollama": "pnpm --filter @agentic-kit/ollama run test:live:smoke",
     "test:live:ollama:extended": "pnpm --filter @agentic-kit/ollama run test:live:extended",
diff --git a/packages/agent/__tests__/tsconfig.json b/packages/agent/__tests__/tsconfig.json
@@ -2,9 +2,19 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "noEmit": true,
-    "rootDir": "..",
+    "rootDir": "../../..",
+    "baseUrl": "../../..",
+    "paths": {
+      "@test/*": ["tools/test/*"],
+      "agentic-kit": ["packages/agentic-kit/src"],
+      "@agentic-kit/agent": ["packages/agent/src"]
+    },
     "types": ["jest", "node"]
   },
-  "include": ["./**/*.ts", "../src/**/*.ts"],
+  "include": [
+    "./**/*.ts",
+    "../src/**/*.ts",
+    "../../../tools/test/**/*.ts"
+  ],
   "exclude": ["../dist", "../node_modules"]
 }
diff --git a/packages/agent/jest.config.js b/packages/agent/jest.config.js
@@ -17,6 +17,7 @@ module.exports = {
   modulePathIgnorePatterns: ['dist/*'],
   moduleNameMapper: {
     '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^@test/(.*)$': '<rootDir>/../../tools/test/$1',
     '^agentic-kit$': '<rootDir>/../agentic-kit/src',
     '^@agentic-kit/(.*)$': '<rootDir>/../$1/src',
   },
diff --git a/packages/agentic-kit/__tests__/tsconfig.json b/packages/agentic-kit/__tests__/tsconfig.json
@@ -2,9 +2,19 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "noEmit": true,
-    "rootDir": "..",
+    "rootDir": "../../..",
+    "baseUrl": "../../..",
+    "paths": {
+      "@test/*": ["tools/test/*"],
+      "agentic-kit": ["packages/agentic-kit/src"],
+      "@agentic-kit/agent": ["packages/agent/src"]
+    },
     "types": ["jest", "node"]
   },
-  "include": ["./**/*.ts", "../src/**/*.ts"],
+  "include": [
+    "./**/*.ts",
+    "../src/**/*.ts",
+    "../../../tools/test/**/*.ts"
+  ],
   "exclude": ["../dist", "../node_modules"]
 }
diff --git a/packages/agentic-kit/jest.config.js b/packages/agentic-kit/jest.config.js
@@ -17,6 +17,8 @@ module.exports = {
   modulePathIgnorePatterns: ['dist/*'],
   moduleNameMapper: {
     '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^@test/(.*)$': '<rootDir>/../../tools/test/$1',
+    '^agentic-kit$': '<rootDir>/src',
     '^@agentic-kit/(.*)$': '<rootDir>/../$1/src',
   },
   setupFilesAfterEnv: ['<rootDir>/jest.setup.js']
diff --git a/packages/anthropic/__tests__/tsconfig.json b/packages/anthropic/__tests__/tsconfig.json
@@ -2,9 +2,19 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "noEmit": true,
-    "rootDir": "..",
+    "rootDir": "../../..",
+    "baseUrl": "../../..",
+    "paths": {
+      "@test/*": ["tools/test/*"],
+      "agentic-kit": ["packages/agentic-kit/src"],
+      "@agentic-kit/agent": ["packages/agent/src"]
+    },
     "types": ["jest", "node"]
   },
-  "include": ["./**/*.ts", "../src/**/*.ts"],
+  "include": [
+    "./**/*.ts",
+    "../src/**/*.ts",
+    "../../../tools/test/**/*.ts"
+  ],
   "exclude": ["../dist", "../node_modules"]
 }
diff --git a/packages/anthropic/jest.config.js b/packages/anthropic/jest.config.js
@@ -15,5 +15,11 @@ module.exports = {
   testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$',
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
   modulePathIgnorePatterns: ['dist/*'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^@test/(.*)$': '<rootDir>/../../tools/test/$1',
+    '^agentic-kit$': '<rootDir>/../agentic-kit/src',
+    '^@agentic-kit/(.*)$': '<rootDir>/../$1/src',
+  },
   setupFilesAfterEnv: ['<rootDir>/jest.setup.js']
 };
diff --git a/packages/ollama/__tests__/tsconfig.json b/packages/ollama/__tests__/tsconfig.json
@@ -2,9 +2,19 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "noEmit": true,
-    "rootDir": "..",
+    "rootDir": "../../..",
+    "baseUrl": "../../..",
+    "paths": {
+      "@test/*": ["tools/test/*"],
+      "agentic-kit": ["packages/agentic-kit/src"],
+      "@agentic-kit/agent": ["packages/agent/src"]
+    },
     "types": ["jest", "node"]
   },
-  "include": ["./**/*.ts", "../src/**/*.ts"],
+  "include": [
+    "./**/*.ts",
+    "../src/**/*.ts",
+    "../../../tools/test/**/*.ts"
+  ],
   "exclude": ["../dist", "../node_modules"]
 }
diff --git a/packages/ollama/jest.config.js b/packages/ollama/jest.config.js
@@ -16,5 +16,11 @@ module.exports = {
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
   modulePathIgnorePatterns: ['dist/*'],
   testPathIgnorePatterns: process.env.OLLAMA_LIVE_READY === '1' ? [] : ['\\.live\\.test\\.ts$'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^@test/(.*)$': '<rootDir>/../../tools/test/$1',
+    '^agentic-kit$': '<rootDir>/../agentic-kit/src',
+    '^@agentic-kit/(.*)$': '<rootDir>/../$1/src',
+  },
   setupFilesAfterEnv: ['<rootDir>/jest.setup.js']
 };
diff --git a/packages/openai/__tests__/tsconfig.json b/packages/openai/__tests__/tsconfig.json
@@ -2,9 +2,19 @@
   "extends": "../tsconfig.json",
   "compilerOptions": {
     "noEmit": true,
-    "rootDir": "..",
+    "rootDir": "../../..",
+    "baseUrl": "../../..",
+    "paths": {
+      "@test/*": ["tools/test/*"],
+      "agentic-kit": ["packages/agentic-kit/src"],
+      "@agentic-kit/agent": ["packages/agent/src"]
+    },
     "types": ["jest", "node"]
   },
-  "include": ["./**/*.ts", "../src/**/*.ts"],
+  "include": [
+    "./**/*.ts",
+    "../src/**/*.ts",
+    "../../../tools/test/**/*.ts"
+  ],
   "exclude": ["../dist", "../node_modules"]
 }
diff --git a/packages/openai/jest.config.js b/packages/openai/jest.config.js
@@ -15,5 +15,11 @@ module.exports = {
   testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$',
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
   modulePathIgnorePatterns: ['dist/*'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^@test/(.*)$': '<rootDir>/../../tools/test/$1',
+    '^agentic-kit$': '<rootDir>/../agentic-kit/src',
+    '^@agentic-kit/(.*)$': '<rootDir>/../$1/src',
+  },
   setupFilesAfterEnv: ['<rootDir>/jest.setup.js']
 };
diff --git a/tests/integration/README.md b/tests/integration/README.md
@@ -0,0 +1,14 @@
+# Integration tests
+
+Workspace-level lane that runs in-process integration tests against the kit's
+HTTP boundary. Brings up `http.createServer`, exercises real serialization
+and `fetch`, with mocked providers.
+
+Empty in Phase 0 — scaffolding only. First tests land with Phase 1.3 (run
+serialization helpers) and 1.1 (pause/resume). Run with:
+
+```sh
+pnpm test:integration
+```
+
+`passWithNoTests` is set, so the script is safe to run while empty.
diff --git a/tests/integration/jest.config.js b/tests/integration/jest.config.js
@@ -0,0 +1,24 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  rootDir: '.',
+  passWithNoTests: true,
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        babelConfig: false,
+        tsconfig: '<rootDir>/tsconfig.json',
+      },
+    ],
+  },
+  testRegex: '\\.test\\.(jsx?|tsx?)$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^@test/(.*)$': '<rootDir>/../../tools/test/$1',
+    '^agentic-kit$': '<rootDir>/../../packages/agentic-kit/src',
+    '^@agentic-kit/(.*)$': '<rootDir>/../../packages/$1/src',
+  },
+};
diff --git a/tests/integration/tsconfig.json b/tests/integration/tsconfig.json
@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "../..",
+    "baseUrl": "../..",
+    "paths": {
+      "@test/*": ["tools/test/*"],
+      "agentic-kit": ["packages/agentic-kit/src"],
+      "@agentic-kit/agent": ["packages/agent/src"],
+      "@agentic-kit/anthropic": ["packages/anthropic/src"],
+      "@agentic-kit/openai": ["packages/openai/src"],
+      "@agentic-kit/ollama": ["packages/ollama/src"]
+    },
+    "types": ["jest", "node"]
+  },
+  "include": ["./**/*.ts", "../../tools/test/**/*.ts"]
+}
diff --git a/tools/test/README.md b/tools/test/README.md
@@ -0,0 +1,24 @@
+# Shared test helpers
+
+Repo-internal helpers for unit tests. Imported via the `@test/*` tsconfig path
+alias (see each package's `__tests__/tsconfig.json` and `jest.config.js`).
+Not a workspace package, not published.
+
+## Helpers
+
+- `makeFakeModel(overrides?)` — `ModelDescriptor` with sane defaults.
+- `makeFakeAssistantMessage(overrides?)` — `AssistantMessage` with zero usage and stop reason.
+- `createScriptedProvider({ responses })` — `ProviderAdapter` that emits a derived event sequence per `AssistantMessage` in `responses` on successive `stream()` calls. `stopReason` of `error` or `aborted` produces an `error` terminal event; otherwise `done`.
+- `createScriptedSSEResponse(events)` — `Response` whose body serializes each `AgentEvent` as one SSE frame (`data: <json>\n\n`).
+- `parseSSEStream(stream)` — async iterable that parses `AgentEvent` SSE frames from a `ReadableStream<Uint8Array>`. Handles split chunks, multi-line `data:`, comment lines, event-type framing, trailing newlines, and mid-event abort (incomplete trailing event is dropped, per SSE spec).
+
+## Deferred
+
+`runRunStoreContractTests(makeStore)` lands with Phase 1.2 alongside the
+`RunStore` interface. Adding it now would be dead scaffolding.
+
+## Adding a helper
+
+Promote a helper to `tools/test/` only when a third package needs the same
+idiom. Duplication of a 30-line scripted helper across two packages is fine;
+duplicating across three is the trigger for promotion.
diff --git a/tools/test/fixtures.ts b/tools/test/fixtures.ts
@@ -0,0 +1,40 @@
+import type { AssistantMessage, ModelDescriptor, Usage } from 'agentic-kit';
+
+const ZERO_USAGE: Usage = {
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+
+export function makeFakeModel(overrides: Partial<ModelDescriptor> = {}): ModelDescriptor {
+  return {
+    id: 'demo',
+    name: 'Demo',
+    api: 'fake-api',
+    provider: 'fake',
+    baseUrl: 'http://fake.local',
+    input: ['text'],
+    reasoning: false,
+    tools: true,
+    ...overrides,
+  };
+}
+
+export function makeFakeAssistantMessage(
+  overrides: Partial<AssistantMessage> = {}
+): AssistantMessage {
+  return {
+    role: 'assistant',
+    api: 'fake-api',
+    provider: 'fake',
+    model: 'demo',
+    usage: { ...ZERO_USAGE, cost: { ...ZERO_USAGE.cost } },
+    stopReason: 'stop',
+    timestamp: Date.now(),
+    content: [{ type: 'text', text: '' }],
+    ...overrides,
+  };
+}
diff --git a/tools/test/index.ts b/tools/test/index.ts
@@ -0,0 +1,3 @@
+export { makeFakeAssistantMessage, makeFakeModel } from './fixtures';
+export { createScriptedProvider, type ScriptedProviderOptions } from './scripted-provider';
+export { createScriptedSSEResponse, parseSSEStream } from './scripted-sse';
diff --git a/tools/test/scripted-provider.ts b/tools/test/scripted-provider.ts
diff --git a/tools/test/scripted-sse.ts b/tools/test/scripted-sse.ts
