@actiondock/testing 2.0.4

package/README.md

@@ -0,0 +1,92 @@
+# @actiondock/testing
+
+ActionDock 2.0 确定性测试框架与测试运行时。
+
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green?logo=node.js)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+`@actiondock/testing` 为 ActionDock 工具与技能开发者提供确定性、无物理依赖且具备真实 Core 执行语义的单元测试框架。
+
+---
+
+## 核心组件与测试能力
+
+### FakeClock 确定性时钟
+
+解耦真实物理系统时间，彻底消除异步定时器测试中的偶发性失败与等待开销：
+
+- 模拟墙上时间 `now` 与单调递增时间戳 `monotonic`。
+- 通过 `advance(ms)` 瞬间推进模拟时间，并以严格确定的顺序依次唤醒挂起的计时器与延迟任务。
+- 支持时间倒流检测与高精度时间戳快照。
+
+### MockProcessExecutor 模拟进程执行器
+
+在沙箱中拦截并伪造所有外部系统命令与子进程调用：
+
+- **灵活规则匹配**：通过 `onCommand` 注册匹配器，支持字符串完全匹配、正则表达式匹配或自定义断言谓词函数。
+- **丰富的响应定义**：支持模拟标准输出、标准错误流、非零退出码、二进制字节流以及执行耗时。
+- **异常场景复现**：可直接模拟命令执行超时（`timedOut`）或取消信号阻断（`cancelled`）。
+- **调用历史追踪**：精确记录每次调用的完整入参、工作目录与环境变量，提供便捷的断言追踪支持。
+
+### MemoryStorage 纯内存存储
+
+基于内存 SQLite 驱动构建的无磁盘运行时存储实现：
+
+- 具备与生产环境持久化存储完全相同的配置优先级解析规则与事务边界。
+- 完整支持状态数据的命名空间隔离、前缀检索与基于存活时间的自动过期判定。
+- 完整持久化运行历史记录与结构化输入输出快照。
+
+### createTestRuntime 测试运行时工厂
+
+深度复用核心引擎 `ActionRunner` 的测试脚手架：
+
+- **真实生命周期校验**：在内存测试中同步执行输入输出 JSON Schema 校验、调用环路死锁检测与超时控制。
+- **双模态执行接口**：支持通过 `run` 直接获取业务数据（失败时抛出带有错误码的异常），或通过 `execute` 获取包含运行标识与元数据的完整信封。
+- **全要素调试访问**：测试运行时直接暴露 `config`、`state`、`clock`、`process`、`events` 与 `storage` 实例，便于在测试用例中注入先验数据并断言副作用。
+
+---
+
+## 快速使用示例
+
+```ts
+import { defineAction } from "@actiondock/sdk";
+import { createTestRuntime, FakeClock, MockProcessExecutor } from "@actiondock/testing";
+
+const gitBranchAction = defineAction({
+  id: "git.branch",
+  inputSchema: {
+    type: "object",
+    properties: {
+      remote: { type: "boolean" },
+    },
+  },
+  async run(input, ctx) {
+    const res = await ctx.process.exec("git", ["branch"]);
+    return { output: res.stdout.trim() };
+  },
+});
+
+// 初始化模拟执行器与测试运行时
+const processExecutor = new MockProcessExecutor();
+processExecutor.onCommand("git", {
+  stdout: "* main\n  feature/agent\n",
+});
+
+const runtime = createTestRuntime({
+  process: processExecutor,
+});
+
+// 执行 Action 并断言业务数据
+const result = await runtime.run(gitBranchAction, { remote: false });
+console.log(result.output);
+
+// 断言底层命令调用记录
+console.log(processExecutor.getHistory().length === 1);
+```
+
+---
+
+## 开源协议
+
+本项目采用 Apache-2.0 开源协议。

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@actiondock/testing",
+  "version": "2.0.4",
+  "description": "ActionDock Test Runtime for testing Actions with real Core execution semantics",
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@actiondock/core": "^2.0.0",
+    "@actiondock/sdk": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "keywords": ["actiondock", "testing", "agent", "actions", "mock"],
+  "author": "team4u",
+  "license": "Apache-2.0"
+}

package/src/clock.ts

@@ -0,0 +1,136 @@
+import type { Clock } from "@actiondock/core";
+
+/**
+ * 待触发的计划计时器项。
+ */
+interface ScheduledSleep {
+  id: number;
+  targetMonotonic: number;
+  targetNow: number;
+  resolve: () => void;
+  reject: (err: unknown) => void;
+}
+
+/**
+ * 模拟时钟初始化选项。
+ */
+export interface FakeClockOptions {
+  /** 初始时间戳或日期对象 */
+  now?: Date | number | string;
+  /** 初始单调时间戳毫秒数 */
+  startMonotonic?: number;
+}
+
+/**
+ * 确定性测试模拟时钟实现。
+ * 遵循 Clock 接口契约，支持手动单调推进时间并调度计时器。
+ */
+export class FakeClock implements Clock {
+  private currentNow: number;
+  private currentMonotonic: number;
+  private nextTimerId = 1;
+  private pendingSleeps: ScheduledSleep[] = [];
+
+  constructor(options: FakeClockOptions = {}) {
+    if (options.now !== undefined) {
+      this.currentNow = new Date(options.now).getTime();
+    } else {
+      this.currentNow = Date.now();
+    }
+    this.currentMonotonic = options.startMonotonic ?? 0;
+  }
+
+  /**
+   * 获取当前模拟墙上时间。
+   */
+  now(): Date {
+    return new Date(this.currentNow);
+  }
+
+  /**
+   * 获取当前模拟单调时间戳（毫秒）。
+   */
+  monotonic(): number {
+    return this.currentMonotonic;
+  }
+
+  /**
+   * 异步休眠指定毫秒。
+   * 等待通过 advance 方法推进时间至目标时刻后完成。
+   *
+   * @param ms 休眠毫秒数
+   */
+  sleep(ms: number): Promise<void> {
+    if (ms <= 0) {
+      return Promise.resolve();
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      const targetMonotonic = this.currentMonotonic + ms;
+      const targetNow = this.currentNow + ms;
+      this.pendingSleeps.push({
+        id: this.nextTimerId++,
+        targetMonotonic,
+        targetNow,
+        resolve,
+        reject,
+      });
+      this.pendingSleeps.sort((a, b) => a.targetMonotonic - b.targetMonotonic);
+    });
+  }
+
+  /**
+   * 手动向前推进指定毫秒时间。
+   * 严格按时间戳递增顺序触发并完成所有到期的休眠计时器。
+   *
+   * @param ms 推进的毫秒数
+   */
+  async advance(ms: number): Promise<void> {
+    if (ms < 0) {
+      throw new Error("Cannot advance clock by negative time");
+    }
+    if (ms === 0) {
+      await Promise.resolve();
+      return;
+    }
+
+    const destinationMonotonic = this.currentMonotonic + ms;
+    const destinationNow = this.currentNow + ms;
+
+    while (this.pendingSleeps.length > 0) {
+      const nextSleep = this.pendingSleeps[0];
+      if (nextSleep.targetMonotonic > destinationMonotonic) {
+        break;
+      }
+
+      this.pendingSleeps.shift();
+      this.currentMonotonic = nextSleep.targetMonotonic;
+      this.currentNow = nextSleep.targetNow;
+      nextSleep.resolve();
+
+      await Promise.resolve();
+    }
+
+    this.currentMonotonic = destinationMonotonic;
+    this.currentNow = destinationNow;
+    await Promise.resolve();
+  }
+
+  /**
+   * 获取当前等待中的计时器数量。
+   */
+  get pendingCount(): number {
+    return this.pendingSleeps.length;
+  }
+
+  /**
+   * 清除并取消所有等待中的计时器。
+   */
+  clear(): void {
+    const sleeps = this.pendingSleeps;
+    this.pendingSleeps = [];
+    for (const item of sleeps) {
+      item.reject(new Error("FakeClock timer cancelled"));
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./clock";
+export * from "./process";
+export * from "./storage";
+export * from "./runtime";

package/src/process.ts

@@ -0,0 +1,394 @@
+import type { ProcessExecutor } from "@actiondock/core";
+import type {
+  DetachedProcessOptions,
+  DetachedProcessResult,
+  ProcessExecOptions,
+  ProcessResult,
+  RuntimeError,
+} from "@actiondock/sdk";
+
+/**
+ * 模拟命令匹配器。
+ */
+export type CommandMatcher =
+  | string
+  | RegExp
+  | ((command: string, args: string[], options: ProcessExecOptions) => boolean);
+
+/**
+ * 模拟进程执行结果选项。
+ */
+export interface MockProcessResultOptions {
+  /** 命令是否执行成功 */
+  ok?: boolean;
+  /** 退出状态码 */
+  exitCode?: number | null;
+  /** 终止信号名称 */
+  signal?: string;
+  /** 标准输出内容 */
+  stdout?: string;
+  /** 标准错误内容 */
+  stderr?: string;
+  /** 原始字节数组输出 */
+  raw?: Uint8Array;
+  /** 是否标记为超时 */
+  timedOut?: boolean;
+  /** 是否标记为已取消 */
+  cancelled?: boolean;
+  /** 执行耗时毫秒数 */
+  durationMs?: number;
+  /** 运行时结构化错误 */
+  error?: RuntimeError;
+  /** 模拟执行延迟毫秒数 */
+  delayMs?: number;
+}
+
+/**
+ * 模拟进程处理器函数。
+ */
+export type MockProcessHandler = (
+  command: string,
+  args: string[],
+  options: ProcessExecOptions
+) =>
+  | MockProcessResultOptions
+  | ProcessResult
+  | Promise<MockProcessResultOptions | ProcessResult>;
+
+/**
+ * 已记录的命令调用历史条目。
+ */
+export interface ProcessCall {
+  /** 执行命令名称 */
+  command: string;
+  /** 执行参数列表 */
+  args: string[];
+  /** 执行选项配置 */
+  options: ProcessExecOptions;
+  /** 调用发生时的时间戳 */
+  timestamp: number;
+}
+
+/**
+ * 已记录的后台守护进程调用历史条目。
+ */
+export interface DetachedProcessCall {
+  /** 启动参数选项 */
+  options: DetachedProcessOptions;
+  /** 调用发生时的时间戳 */
+  timestamp: number;
+}
+
+interface RegisteredMock {
+  matcher: CommandMatcher;
+  handler: MockProcessHandler | MockProcessResultOptions;
+}
+
+/**
+ * 模拟进程执行器实现。
+ * 遵循 ProcessExecutor 接口契约，支持预设命令响应、跟踪调用历史并模拟超时与取消场景。
+ */
+export class MockProcessExecutor implements ProcessExecutor {
+  private mocks: RegisteredMock[] = [];
+  public calls: ProcessCall[] = [];
+  public detachedCalls: DetachedProcessCall[] = [];
+  public defaultPid = 10001;
+
+  /**
+   * 注册模拟命令匹配与返回结果。
+   *
+   * @param matcher 匹配器（命令字符串、正则表达式或判断函数）
+   * @param handlerOrResult 预设执行结果或动态处理函数
+   */
+  register(
+    matcher: CommandMatcher,
+    handlerOrResult: MockProcessHandler | MockProcessResultOptions
+  ): this {
+    this.mocks.push({ matcher, handler: handlerOrResult });
+    return this;
+  }
+
+  /**
+   * 执行外部命令并返回模拟结果。
+   *
+   * @param command 执行命令
+   * @param args 参数列表
+   * @param options 执行选项
+   */
+  async exec(
+    command: string,
+    args: string[] = [],
+    options: ProcessExecOptions = {}
+  ): Promise<ProcessResult> {
+    const startTime = Date.now();
+    this.calls.push({
+      command,
+      args: [...args],
+      options: { ...options },
+      timestamp: startTime,
+    });
+
+    // 检查调用前是否已中断
+    if (options.signal?.aborted) {
+      const res: ProcessResult = {
+        ok: false,
+        exitCode: null,
+        signal: "SIGTERM",
+        stdout: "",
+        stderr: "Process was cancelled by AbortSignal",
+        raw: new Uint8Array(),
+        timedOut: false,
+        cancelled: true,
+        durationMs: 0,
+        error: {
+          code: "PROCESS_CANCELLED",
+          message: "Process was cancelled by AbortSignal",
+        },
+      };
+      if (options.throwOnError) {
+        throw new Error(res.stderr);
+      }
+      return res;
+    }
+
+    const matchedMock = this.findMock(command, args, options);
+    let resolved: MockProcessResultOptions | ProcessResult;
+
+    if (!matchedMock) {
+      resolved = {
+        ok: true,
+        exitCode: 0,
+        stdout: "",
+        stderr: "",
+      };
+    } else if (typeof matchedMock.handler === "function") {
+      resolved = await matchedMock.handler(command, args, options);
+    } else {
+      resolved = matchedMock.handler;
+    }
+
+    // 模拟延时控制
+    const maybeMock = resolved as MockProcessResultOptions;
+    if (typeof maybeMock.delayMs === "number" && maybeMock.delayMs > 0) {
+      await this.waitDelay(maybeMock.delayMs, options);
+    }
+
+    // 组装标准化结果
+    const timedOut = Boolean(resolved.timedOut);
+    const cancelled = Boolean(resolved.cancelled || options.signal?.aborted);
+    const stdout = resolved.stdout ?? "";
+    const stderr = resolved.stderr ?? (timedOut ? "Process timed out" : cancelled ? "Process cancelled" : "");
+    const raw = resolved.raw ?? new TextEncoder().encode(stdout);
+    const exitCode =
+      resolved.exitCode !== undefined
+        ? resolved.exitCode
+        : timedOut || cancelled
+        ? null
+        : resolved.ok === false
+        ? 1
+        : 0;
+    const ok =
+      resolved.ok !== undefined
+        ? resolved.ok
+        : exitCode === 0 && !timedOut && !cancelled && !resolved.error;
+    const durationMs = resolved.durationMs ?? Date.now() - startTime;
+
+    let error = resolved.error;
+    if (!error) {
+      if (timedOut) {
+        error = {
+          code: "PROCESS_TIMEOUT",
+          message: `Process exceeded timeout of ${options.timeoutMs ?? durationMs}ms`,
+        };
+      } else if (cancelled) {
+        error = {
+          code: "PROCESS_CANCELLED",
+          message: "Process was cancelled by AbortSignal",
+        };
+      } else if (!ok) {
+        error = {
+          code: "PROCESS_FAILED",
+          message: stderr || `Process exited with code ${exitCode}`,
+        };
+      }
+    }
+
+    const finalResult: ProcessResult = {
+      ok,
+      exitCode,
+      signal: resolved.signal,
+      stdout,
+      stderr,
+      raw,
+      timedOut,
+      cancelled,
+      durationMs,
+      error,
+    };
+
+    if (!ok && options.throwOnError) {
+      throw new Error(stderr || `Process exited with code ${exitCode}`);
+    }
+
+    return finalResult;
+  }
+
+  /**
+   * 启动模拟脱离父进程的后台进程。
+   *
+   * @param options 守护进程启动选项
+   */
+  async spawnDetached(
+    options: DetachedProcessOptions
+  ): Promise<DetachedProcessResult> {
+    const startTime = Date.now();
+    this.detachedCalls.push({
+      options: { ...options },
+      timestamp: startTime,
+    });
+
+    if (options.signal?.aborted) {
+      return {
+        ok: false,
+        ready: false,
+        durationMs: 0,
+        error: {
+          code: "PROCESS_CANCELLED",
+          message: "Process was cancelled by AbortSignal",
+        },
+      };
+    }
+
+    if (options.probe) {
+      const fakeResult: ProcessResult = {
+        ok: true,
+        exitCode: 0,
+        stdout: "ready",
+        stderr: "",
+        raw: new TextEncoder().encode("ready"),
+        timedOut: false,
+        cancelled: false,
+        durationMs: 0,
+      };
+      const isReady = await options.probe(fakeResult);
+      return {
+        ok: isReady,
+        pid: this.defaultPid++,
+        ready: isReady,
+        durationMs: Date.now() - startTime,
+      };
+    }
+
+    return {
+      ok: true,
+      pid: this.defaultPid++,
+      ready: true,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * 获取指定命令的历史调用记录。
+   *
+   * @param command 可选命令筛选
+   */
+  getCalls(command?: string): ProcessCall[] {
+    if (!command) {
+      return [...this.calls];
+    }
+    return this.calls.filter((c) => c.command === command);
+  }
+
+  /**
+   * 获取最近一次命令调用记录。
+   */
+  getLastCall(): ProcessCall | undefined {
+    return this.calls[this.calls.length - 1];
+  }
+
+  /**
+   * 检查指定命令是否被调用过。
+   *
+   * @param command 目标命令
+   */
+  hasCalled(command: string): boolean {
+    return this.calls.some((c) => c.command === command);
+  }
+
+  /**
+   * 清空历史调用记录。
+   */
+  clearHistory(): void {
+    this.calls = [];
+    this.detachedCalls = [];
+  }
+
+  /**
+   * 重置所有注册规则与历史记录。
+   */
+  reset(): void {
+    this.mocks = [];
+    this.calls = [];
+    this.detachedCalls = [];
+  }
+
+  private findMock(
+    command: string,
+    args: string[],
+    options: ProcessExecOptions
+  ): RegisteredMock | undefined {
+    const fullCommandLine = [command, ...args].join(" ").trim();
+
+    // 逆序查找，优先匹配最新注册的规则
+    for (let i = this.mocks.length - 1; i >= 0; i--) {
+      const mock = this.mocks[i];
+      if (typeof mock.matcher === "string") {
+        if (
+          mock.matcher === command ||
+          mock.matcher === fullCommandLine ||
+          fullCommandLine.startsWith(mock.matcher)
+        ) {
+          return mock;
+        }
+      } else if (mock.matcher instanceof RegExp) {
+        if (mock.matcher.test(fullCommandLine) || mock.matcher.test(command)) {
+          return mock;
+        }
+      } else if (typeof mock.matcher === "function") {
+        if (mock.matcher(command, args, options)) {
+          return mock;
+        }
+      }
+    }
+    return undefined;
+  }
+
+  private async waitDelay(
+    delayMs: number,
+    options: ProcessExecOptions
+  ): Promise<void> {
+    return new Promise<void>((resolve) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+
+      const cleanup = () => {
+        if (timer) clearTimeout(timer);
+      };
+
+      if (options.signal) {
+        options.signal.addEventListener(
+          "abort",
+          () => {
+            cleanup();
+            resolve();
+          },
+          { once: true }
+        );
+      }
+
+      timer = setTimeout(() => {
+        cleanup();
+        resolve();
+      }, delayMs);
+    });
+  }
+}