@outfitter/testing 0.2.4 → 0.3.0

package/dist/index.js

@@ -1,405 +1,7 @@
-// src/fixtures.ts
-var cachedRequire;
-function getNodeRequire() {
-  if (cachedRequire !== undefined) {
-    if (cachedRequire === null) {
-      throw new Error("Node.js built-ins are unavailable in this runtime.");
-    }
-    return cachedRequire;
-  }
-  const metaRequire = import.meta.require;
-  if (typeof metaRequire === "function") {
-    cachedRequire = metaRequire;
-    return metaRequire;
-  }
-  const globalRequire = globalThis.require;
-  if (typeof globalRequire === "function") {
-    cachedRequire = globalRequire;
-    return globalRequire;
-  }
-  cachedRequire = null;
-  throw new Error("Node.js built-ins are unavailable in this runtime.");
-}
-function getNodeFs() {
-  return getNodeRequire()("node:fs");
-}
-function getNodeFsPromises() {
-  return getNodeRequire()("node:fs/promises");
-}
-function getNodeOs() {
-  return getNodeRequire()("node:os");
-}
-function getNodePath() {
-  return getNodeRequire()("node:path");
-}
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function deepMerge(target, source) {
-  const result = { ...target };
-  for (const key of Object.keys(source)) {
-    const sourceValue = source[key];
-    const targetValue = target[key];
-    if (sourceValue === undefined) {
-      continue;
-    }
-    if (isPlainObject(sourceValue) && isPlainObject(targetValue)) {
-      result[key] = deepMerge(targetValue, sourceValue);
-    } else {
-      result[key] = sourceValue;
-    }
-  }
-  return result;
-}
-function deepClone(obj) {
-  if (obj === null || typeof obj !== "object") {
-    return obj;
-  }
-  if (Array.isArray(obj)) {
-    return obj.map((item) => deepClone(item));
-  }
-  const cloned = {};
-  for (const key of Object.keys(obj)) {
-    cloned[key] = deepClone(obj[key]);
-  }
-  return cloned;
-}
-function createFixture(defaults) {
-  return (overrides) => {
-    const cloned = deepClone(defaults);
-    if (overrides === undefined) {
-      return cloned;
-    }
-    return deepMerge(cloned, overrides);
-  };
-}
-function generateTempDirPath() {
-  const { tmpdir } = getNodeOs();
-  const { join } = getNodePath();
-  const timestamp = Date.now();
-  const random = Math.random().toString(36).slice(2, 10);
-  return join(tmpdir(), `outfitter-test-${timestamp}-${random}`);
-}
-async function withTempDir(fn) {
-  const { mkdir, rm } = getNodeFsPromises();
-  const dir = generateTempDirPath();
-  await mkdir(dir, { recursive: true });
-  try {
-    return await fn(dir);
-  } finally {
-    await rm(dir, { recursive: true, force: true }).catch(() => {});
-  }
-}
-async function withEnv(vars, fn) {
-  const originalValues = new Map;
-  for (const key of Object.keys(vars)) {
-    originalValues.set(key, process.env[key]);
-  }
-  for (const [key, value] of Object.entries(vars)) {
-    process.env[key] = value;
-  }
-  try {
-    return await fn();
-  } finally {
-    for (const [key, originalValue] of originalValues) {
-      if (originalValue === undefined) {
-        delete process.env[key];
-      } else {
-        process.env[key] = originalValue;
-      }
-    }
-  }
-}
-function loadFixture(name, options) {
-  const { readFileSync } = getNodeFs();
-  const { extname, join } = getNodePath();
-  const baseDir = options?.fixturesDir ?? join(process.cwd(), "__fixtures__");
-  const filePath = join(baseDir, name);
-  const content = readFileSync(filePath, "utf-8");
-  if (extname(filePath) === ".json") {
-    return JSON.parse(content);
-  }
-  return content;
-}
-// src/cli-harness.ts
-function createCliHarness(command) {
-  return {
-    async run(args) {
-      const child = Bun.spawn([command, ...args], {
-        stdin: "pipe",
-        stdout: "pipe",
-        stderr: "pipe"
-      });
-      child.stdin?.end();
-      const stdoutPromise = child.stdout ? new Response(child.stdout).text() : Promise.resolve("");
-      const stderrPromise = child.stderr ? new Response(child.stderr).text() : Promise.resolve("");
-      const exitCodePromise = child.exited;
-      const [stdout, stderr, exitCode] = await Promise.all([
-        stdoutPromise,
-        stderrPromise,
-        exitCodePromise
-      ]);
-      return {
-        stdout,
-        stderr,
-        exitCode: typeof exitCode === "number" ? exitCode : 1
-      };
-    }
-  };
-}
-// src/cli-helpers.ts
-class ExitError extends Error {
-  code;
-  constructor(code) {
-    super(`Process exited with code ${code}`);
-    this.code = code;
-  }
-}
-async function captureCLI(fn) {
-  const stdoutChunks = [];
-  const stderrChunks = [];
-  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
-  const originalStderrWrite = process.stderr.write.bind(process.stderr);
-  const originalExit = process.exit.bind(process);
-  const originalConsoleLog = console.log;
-  const originalConsoleError = console.error;
-  process.stdout.write = (chunk, _encoding, cb) => {
-    stdoutChunks.push(typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk);
-    if (typeof cb === "function")
-      cb();
-    return true;
-  };
-  process.stderr.write = (chunk, _encoding, cb) => {
-    stderrChunks.push(typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk);
-    if (typeof cb === "function")
-      cb();
-    return true;
-  };
-  console.log = (...args) => {
-    const line = `${args.map(String).join(" ")}
-`;
-    stdoutChunks.push(new TextEncoder().encode(line));
-  };
-  console.error = (...args) => {
-    const line = `${args.map(String).join(" ")}
-`;
-    stderrChunks.push(new TextEncoder().encode(line));
-  };
-  process.exit = (code) => {
-    throw new ExitError(code ?? 0);
-  };
-  let exitCode = 0;
-  try {
-    await fn();
-  } catch (error) {
-    if (error instanceof ExitError) {
-      exitCode = error.code;
-    } else {
-      exitCode = 1;
-    }
-  } finally {
-    process.stdout.write = originalStdoutWrite;
-    process.stderr.write = originalStderrWrite;
-    process.exit = originalExit;
-    console.log = originalConsoleLog;
-    console.error = originalConsoleError;
-  }
-  const decoder = new TextDecoder("utf-8");
-  return {
-    stdout: decoder.decode(concatChunks(stdoutChunks)),
-    stderr: decoder.decode(concatChunks(stderrChunks)),
-    exitCode
-  };
-}
-function mockStdin(input) {
-  const originalStdin = process.stdin;
-  const encoded = new TextEncoder().encode(input);
-  const mockStream = {
-    async* [Symbol.asyncIterator]() {
-      yield encoded;
-    },
-    fd: 0,
-    isTTY: false
-  };
-  process.stdin = mockStream;
-  return {
-    restore: () => {
-      process.stdin = originalStdin;
-    }
-  };
-}
-function concatChunks(chunks) {
-  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const chunk of chunks) {
-    result.set(chunk, offset);
-    offset += chunk.length;
-  }
-  return result;
-}
-// src/mcp-harness.ts
-import {
-  createMcpServer
-} from "@outfitter/mcp";
-function createMcpHarness(server, options = {}) {
-  return {
-    callTool(name, input) {
-      return server.invokeTool(name, input);
-    },
-    listTools() {
-      return server.getTools();
-    },
-    searchTools(query) {
-      const normalized = query.trim().toLowerCase();
-      const tools = server.getTools();
-      if (normalized.length === 0) {
-        return tools;
-      }
-      return tools.filter((tool) => {
-        const nameMatch = tool.name.toLowerCase().includes(normalized);
-        const descriptionMatch = tool.description.toLowerCase().includes(normalized);
-        return nameMatch || descriptionMatch;
-      });
-    },
-    loadFixture(name) {
-      return loadFixture(name, options.fixturesDir ? { fixturesDir: options.fixturesDir } : undefined);
-    },
-    reset() {}
-  };
-}
-function createMCPTestHarness(options) {
-  const server = createMcpServer({
-    name: options.name ?? "mcp-test",
-    version: options.version ?? "0.0.0"
-  });
-  for (const tool of options.tools) {
-    server.registerTool(tool);
-  }
-  return createMcpHarness(server, {
-    ...options.fixturesDir !== undefined ? { fixturesDir: options.fixturesDir } : {}
-  });
-}
-// src/mock-factories.ts
-import {
-  generateRequestId
-} from "@outfitter/contracts";
-function createTestLogger(context = {}) {
-  return createTestLoggerWithContext(context, []);
-}
-function createTestLoggerWithContext(context, logs) {
-  const write = (level, message, data) => {
-    const merged = { ...context, ...data ?? {} };
-    const entry = {
-      level,
-      message
-    };
-    if (Object.keys(merged).length > 0) {
-      entry.data = merged;
-    }
-    logs.push(entry);
-  };
-  return {
-    logs,
-    clear() {
-      logs.length = 0;
-    },
-    trace: (message, metadata) => {
-      write("trace", message, metadata);
-    },
-    debug: (message, metadata) => {
-      write("debug", message, metadata);
-    },
-    info: (message, metadata) => {
-      write("info", message, metadata);
-    },
-    warn: (message, metadata) => {
-      write("warn", message, metadata);
-    },
-    error: (message, metadata) => {
-      write("error", message, metadata);
-    },
-    fatal: (message, metadata) => {
-      write("fatal", message, metadata);
-    },
-    child(childContext) {
-      return createTestLoggerWithContext({ ...context, ...childContext }, logs);
-    }
-  };
-}
-function createTestConfig(schema, values) {
-  const parsed = schema.safeParse(values);
-  let data;
-  if (parsed.success) {
-    data = parsed.data;
-  } else {
-    const maybePartial = schema.partial;
-    if (typeof maybePartial !== "function") {
-      throw parsed.error;
-    }
-    const partialSchema = maybePartial.call(schema);
-    const partialParsed = partialSchema.safeParse(values);
-    if (!partialParsed.success) {
-      throw partialParsed.error;
-    }
-    data = partialParsed.data;
-  }
-  return {
-    get(key) {
-      return getPath(data, key);
-    },
-    getRequired(key) {
-      const value = getPath(data, key);
-      if (value === undefined) {
-        throw new Error(`Missing required config value: ${key}`);
-      }
-      return value;
-    }
-  };
-}
-function createTestContext(overrides = {}) {
-  const logger = overrides.logger ?? createTestLogger();
-  const requestId = overrides.requestId ?? generateRequestId();
-  const context = {
-    requestId,
-    logger,
-    cwd: overrides.cwd ?? process.cwd(),
-    env: overrides.env ?? { ...process.env }
-  };
-  if (overrides.config !== undefined) {
-    context.config = overrides.config;
-  }
-  if (overrides.signal !== undefined) {
-    context.signal = overrides.signal;
-  }
-  if (overrides.workspaceRoot !== undefined) {
-    context.workspaceRoot = overrides.workspaceRoot;
-  }
-  return context;
-}
-function getPath(obj, key) {
-  const parts = key.split(".").filter((part) => part.length > 0);
-  let current = obj;
-  for (const part of parts) {
-    if (current === null || typeof current !== "object") {
-      return;
-    }
-    current = current[part];
-  }
-  return current;
-}
-export {
-  withTempDir,
-  withEnv,
-  mockStdin,
-  loadFixture,
-  createTestLogger,
-  createTestContext,
-  createTestConfig,
-  createMCPTestHarness as createMcpTestHarness,
-  createMcpHarness,
-  createMCPTestHarness,
-  createFixture,
-  createCliHarness,
-  captureCLI
-};
+export { createFixture, loadFixture, withEnv, withTempDir } from "./fixtures.js";
+export { createCliHarness } from "./cli-harness.js";
+export { captureCLI, mockStdin } from "./cli-helpers.js";
+export { createMCPTestHarness, createMcpHarness, createMcpTestHarness } from "./mcp-harness.js";
+export { getTestContext, testCommand } from "./test-command.js";
+export { testTool } from "./test-tool.js";
+export { createTestConfig, createTestContext, createTestLogger } from "./mock-factories.js";

package/dist/mcp-harness.d.ts

@@ -1,2 +1,2 @@
-import { McpHarness, McpHarnessOptions, McpTestHarnessOptions, McpToolResponse, createMCPTestHarness, createMcpHarness } from "./shared/@outfitter/testing-5gdrv3f5.js";
+import { McpHarness, McpHarnessOptions, McpTestHarnessOptions, McpToolResponse, createMCPTestHarness, createMcpHarness } from "./shared/@outfitter/testing-jc0ppq2z.js";
 export { createMCPTestHarness as createMcpTestHarness, createMcpHarness, createMCPTestHarness, McpToolResponse, McpTestHarnessOptions, McpHarnessOptions, McpHarness };

package/dist/mcp-harness.js

@@ -1,9 +1,51 @@
 // @bun
 import {
-  createMCPTestHarness,
-  createMcpHarness
-} from "./shared/@outfitter/testing-05hzzr8n.js";
-import"./shared/@outfitter/testing-1wd76sr8.js";
+  loadFixture
+} from "./shared/@outfitter/testing-1wd76sr8.js";
+
+// packages/testing/src/mcp-harness.ts
+import {
+  createMcpServer
+} from "@outfitter/mcp";
+function createMcpHarness(server, options = {}) {
+  return {
+    callTool(name, input) {
+      return server.invokeTool(name, input);
+    },
+    listTools() {
+      return server.getTools();
+    },
+    listResources() {
+      return server.getResources();
+    },
+    searchTools(query) {
+      const normalized = query.trim().toLowerCase();
+      const tools = server.getTools();
+      if (normalized.length === 0) {
+        return tools;
+      }
+      return tools.filter((tool) => {
+        const nameMatch = tool.name.toLowerCase().includes(normalized);
+        const descriptionMatch = tool.description.toLowerCase().includes(normalized);
+        return nameMatch || descriptionMatch;
+      });
+    },
+    loadFixture(name) {
+      return loadFixture(name, options.fixturesDir ? { fixturesDir: options.fixturesDir } : undefined);
+    },
+    reset() {}
+  };
+}
+function createMCPTestHarness(options) {
+  const server = createMcpServer({
+    name: options.name ?? "mcp-test",
+    version: options.version ?? "0.0.0"
+  });
+  for (const tool of options.tools) {
+    server.registerTool(tool);
+  }
+  return createMcpHarness(server, options.fixturesDir !== undefined ? { fixturesDir: options.fixturesDir } : {});
+}
 export {
   createMCPTestHarness as createMcpTestHarness,
   createMcpHarness,

package/dist/mock-factories.js

@@ -3,7 +3,7 @@ import {
   createTestConfig,
   createTestContext,
   createTestLogger
-} from "./shared/@outfitter/testing-kdwa417a.js";
+} from "./shared/@outfitter/testing-xcd5p1gm.js";
 export {
   createTestLogger,
   createTestContext,

package/dist/shared/@outfitter/testing-136ebq11.d.ts

@@ -0,0 +1,123 @@
+import { HandlerContext, MCPHint, OutfitterError, Result, ValidationError } from "@outfitter/contracts";
+import { ToolDefinition } from "@outfitter/mcp";
+/**
+* Options for testTool().
+*/
+interface TestToolOptions {
+	/**
+	* Custom working directory for the handler context.
+	* @deprecated Use `context.cwd` instead.
+	*/
+	readonly cwd?: string;
+	/**
+	* Custom environment variables for the handler context.
+	* @deprecated Use `context.env` instead.
+	*/
+	readonly env?: Readonly<Record<string, string | undefined>>;
+	/**
+	* Custom request ID for the handler context.
+	* @deprecated Use `context.requestId` instead.
+	*/
+	readonly requestId?: string;
+	/**
+	* Full HandlerContext overrides.
+	*
+	* When provided, these values are merged with the default test context.
+	* Takes priority over the individual `cwd`, `env`, and `requestId` options.
+	*
+	* @example
+	* ```typescript
+	* await testTool(tool, input, {
+	*   context: {
+	*     requestId: "test-req-001",
+	*     cwd: "/test/dir",
+	*     logger: createTestLogger(),
+	*   },
+	* });
+	* ```
+	*/
+	readonly context?: Partial<HandlerContext>;
+	/**
+	* Hint generation function for asserting on hints.
+	*
+	* When provided, called with the handler's success result and the result
+	* is attached to the returned `TestToolResult.hints` for assertion.
+	* Returns `MCPHint[]` for MCP tool testing.
+	*
+	* @example
+	* ```typescript
+	* const result = await testTool(tool, input, {
+	*   hints: (result) => [{
+	*     description: "View details",
+	*     tool: "get-details",
+	*     input: { id: result.id },
+	*   }],
+	* });
+	* expect(result.hints).toHaveLength(1);
+	* ```
+	*/
+	readonly hints?: (result: unknown) => MCPHint[];
+}
+/**
+* Enhanced result from testTool() with optional hints.
+*
+* Extends the base `Result` with a `hints` field that contains
+* generated hints when a `hints` function was provided in options.
+*/
+type TestToolResult<
+	TOutput,
+	TError extends OutfitterError
+> = Result<TOutput, TError | InstanceType<typeof ValidationError>> & {
+	/**
+	* Generated hints from the `hints` option function.
+	*
+	* Present when `hints` option is provided and the handler succeeds.
+	* Undefined when no hints option was given or when hints array is empty.
+	*/
+	readonly hints?: MCPHint[] | undefined;
+};
+/**
+* Execute an MCP tool definition with given input.
+*
+* Validates input against the tool's Zod schema. If validation fails,
+* returns an `Err<ValidationError>` without invoking the handler.
+* If validation succeeds, invokes the handler exactly once with a
+* test `HandlerContext` and returns the handler's `Result`.
+*
+* ### v0.5 Enhancements
+*
+* - **`context`**: Full `HandlerContext` overrides (not just cwd/env/requestId).
+*   Takes priority over individual options.
+* - **`hints`**: Hint generation function for asserting on hints.
+*   When provided, the function is called with the handler's success result
+*   and the generated hints are attached to `result.hints`.
+*
+* @param tool - An MCP tool definition with inputSchema and handler
+* @param input - Raw input to validate and pass to the handler
+* @param options - Optional context overrides and hint function
+* @returns The handler's Result with optional hints, or Err<ValidationError> on schema failure
+*
+* @example
+* ```typescript
+* // Basic usage (backward compatible)
+* const result = await testTool(myTool, { a: 2, b: 3 });
+* expect(result.unwrap().sum).toBe(5);
+*
+* // With full context injection
+* const result = await testTool(myTool, input, {
+*   context: { requestId: "test-001", logger: testLogger },
+* });
+*
+* // With hints assertion
+* const result = await testTool(myTool, input, {
+*   hints: (r) => [{ description: "Next step", tool: "other" }],
+* });
+* expect(result.hints).toHaveLength(1);
+* ```
+*/
+declare function testTool<
+	TInput,
+	TOutput,
+	TError extends OutfitterError
+>(tool: ToolDefinition<TInput, TOutput, TError>, input: unknown, options?: TestToolOptions): Promise<TestToolResult<TOutput, TError>>;
+export { TestToolOptions, TestToolResult, testTool };

package/dist/shared/@outfitter/{testing-5gdrv3f5.d.ts → testing-jc0ppq2z.d.ts}

@@ -1,5 +1,5 @@
 import { OutfitterError, Result } from "@outfitter/contracts";
-import { McpError, McpServer, SerializedTool, ToolDefinition } from "@outfitter/mcp";
+import { McpError, McpServer, ResourceDefinition, SerializedTool, ToolDefinition } from "@outfitter/mcp";
 /**
 * MCP tool response content.
 * Matches the MCP protocol shape used in the spec.
@@ -18,9 +18,12 @@ interface McpToolResponse {
 interface McpHarness {
 	/**
 	* Call a tool by name with input parameters.
-	* Returns the MCP-formatted response.
+	* Returns the raw handler output (not MCP-wrapped content).
+	*
+	* Callers who know the handler's return shape can pass a type parameter
+	* to avoid manual narrowing: `harness.callTool<MyOutput>("tool", input)`.
 	*/
-	callTool(name: string, input: Record<string, unknown>): Promise<Result<McpToolResponse, InstanceType<typeof McpError>>>;
+	callTool<T = unknown>(name: string, input: Record<string, unknown>): Promise<Result<T, InstanceType<typeof McpError>>>;
 	/**
 	* List all registered tools with schemas.
 	*/
@@ -34,6 +37,10 @@ interface McpHarness {
 	*/
 	reset(): void;
 	/**
+	* List all registered resources.
+	*/
+	listResources(): ResourceDefinition[];
+	/**
 	* Search tools by name or description (case-insensitive).
 	*/
 	searchTools(query: string): SerializedTool[];