@actiondock/testing 2.0.11 → 2.2.0

package/README.md

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

package/dist/cli.d.ts

@@ -0,0 +1,35 @@
+import { findExecutable } from "@actiondock/core";
+export { findExecutable };
+/**
+ * CLI 执行选项配置。
+ */
+export interface ExecCliOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+    timeout?: number;
+    input?: string | Uint8Array;
+    encoding?: string;
+    throwOnError?: boolean;
+}
+/**
+ * CLI 执行结果结构体。
+ */
+export interface ExecCliResult {
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    raw: Uint8Array;
+    timedOut?: boolean;
+    durationMs: number;
+}
+/**
+ * 执行外部 CLI 命令并收集输出。
+ * 基于异步 spawn 与 Promise 化封装（与 runtime-node 执行器风格对齐），保留既有的输出收集与退出码语义。
+ *
+ * @param command 执行命令
+ * @param args 参数列表
+ * @param options 执行选项
+ */
+export declare function execCli(command: string, args?: string[], options?: ExecCliOptions): Promise<ExecCliResult>;

package/dist/cli.js

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { findExecutable } from "@actiondock/core";
+export { findExecutable };
+/**
+ * 执行外部 CLI 命令并收集输出。
+ * 基于异步 spawn 与 Promise 化封装（与 runtime-node 执行器风格对齐），保留既有的输出收集与退出码语义。
+ *
+ * @param command 执行命令
+ * @param args 参数列表
+ * @param options 执行选项
+ */
+export async function execCli(command, args = [], options = {}) {
+    const startTime = performance.now();
+    if (options.signal?.aborted) {
+        const errRes = {
+            ok: false,
+            exitCode: -1,
+            stdout: "",
+            stderr: "Command aborted before execution by signal",
+            raw: new Uint8Array(0),
+            durationMs: 0,
+        };
+        if (options.throwOnError) {
+            throw new Error(errRes.stderr);
+        }
+        return errRes;
+    }
+    const hasPathSep = command.includes("/") || command.includes("\\");
+    const binPath = hasPathSep ? (existsSync(command) ? command : null) : findExecutable(command);
+    if (!binPath) {
+        const errRes = {
+            ok: false,
+            exitCode: -1,
+            stdout: "",
+            stderr: `Command '${command}' not found in PATH.`,
+            raw: new Uint8Array(0),
+            durationMs: Math.round(performance.now() - startTime),
+        };
+        if (options.throwOnError) {
+            throw new Error(errRes.stderr);
+        }
+        return errRes;
+    }
+    let stdinInput;
+    if (options.input !== undefined) {
+        if (typeof options.input === "string") {
+            stdinInput = Buffer.from(options.input);
+        }
+        else if (options.input instanceof Uint8Array) {
+            stdinInput = Buffer.from(options.input);
+        }
+    }
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(binPath, args, {
+                cwd: options.cwd || process.cwd(),
+                env: options.env ? { ...process.env, ...options.env } : process.env,
+                stdio: [stdinInput ? "pipe" : "ignore", "pipe", "pipe"],
+            });
+        }
+        catch (err) {
+            const errRes = {
+                ok: false,
+                exitCode: -1,
+                stdout: "",
+                stderr: err?.message || String(err),
+                raw: new Uint8Array(0),
+                durationMs: Math.round(performance.now() - startTime),
+            };
+            if (options.throwOnError) {
+                reject(err);
+                return;
+            }
+            resolve(errRes);
+            return;
+        }
+        let settled = false;
+        let timedOut = false;
+        let spawnError;
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let timeoutTimer;
+        if (options.timeout && options.timeout > 0) {
+            timeoutTimer = setTimeout(() => {
+                timedOut = true;
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch {
+                    // 忽略已退出状态
+                }
+            }, options.timeout);
+        }
+        const cleanup = () => {
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+        };
+        const finalize = (exitCodeFromClose) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            const durationMs = Math.round(performance.now() - startTime);
+            const decoder = new TextDecoder(options.encoding || "utf-8");
+            const rawStdout = stdoutChunks.length > 0 ? new Uint8Array(Buffer.concat(stdoutChunks)) : new Uint8Array(0);
+            const rawStderr = stderrChunks.length > 0 ? new Uint8Array(Buffer.concat(stderrChunks)) : new Uint8Array(0);
+            const stdout = rawStdout.length > 0 ? decoder.decode(rawStdout).trim() : "";
+            let stderr = rawStderr.length > 0 ? decoder.decode(rawStderr).trim() : "";
+            if (timedOut && !stderr) {
+                stderr = `Command '${command}' timed out after ${options.timeout}ms`;
+            }
+            const exitCode = timedOut ? -1 : (exitCodeFromClose ?? (spawnError ? -1 : 0));
+            const ok = !timedOut && exitCode === 0;
+            const result = {
+                ok,
+                exitCode,
+                stdout,
+                stderr,
+                raw: rawStdout,
+                timedOut: timedOut || undefined,
+                durationMs,
+            };
+            if (options.throwOnError && !ok) {
+                reject(new Error(stderr || `Command '${command}' failed with exit code ${exitCode}`));
+                return;
+            }
+            resolve(result);
+        };
+        child.stdout?.on("data", (chunk) => {
+            stdoutChunks.push(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderrChunks.push(chunk);
+        });
+        child.on("error", (err) => {
+            spawnError = err;
+            finalize(child.exitCode);
+        });
+        child.on("close", (code) => {
+            finalize(code);
+        });
+        if (stdinInput && child.stdin) {
+            child.stdin.on("error", () => {
+                // 目标进程提前退出时忽略管道写入错误
+            });
+            child.stdin.end(stdinInput);
+        }
+    });
+}

package/dist/clock.d.ts

@@ -0,0 +1,54 @@
+import type { Clock } from "@actiondock/core";
+/**
+ * 模拟时钟初始化选项。
+ */
+export interface FakeClockOptions {
+    /** 初始时间戳或日期对象 */
+    now?: Date | number | string;
+    /** 初始单调时间戳毫秒数 */
+    startMonotonic?: number;
+}
+/**
+ * 确定性测试模拟时钟实现。
+ * 遵循 Clock 接口契约，支持手动单调推进时间并调度计时器。
+ */
+export declare class FakeClock implements Clock {
+    private currentNow;
+    private currentMonotonic;
+    private initialRealNow;
+    private advancedMs;
+    private isFixed;
+    private nextTimerId;
+    private pendingSleeps;
+    constructor(options?: FakeClockOptions);
+    /**
+     * 获取当前模拟墙上时间。
+     */
+    now(): Date;
+    /**
+     * 获取当前模拟单调时间戳（毫秒）。
+     */
+    monotonic(): number;
+    /**
+     * 异步休眠指定毫秒。
+     * 等待通过 advance 方法推进时间至目标时刻后完成。
+     *
+     * @param ms 休眠毫秒数
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * 手动向前推进指定毫秒时间。
+     * 严格按时间戳递增顺序触发并完成所有到期的休眠计时器。
+     *
+     * @param ms 推进的毫秒数
+     */
+    advance(ms: number): Promise<void>;
+    /**
+     * 获取当前等待中的计时器数量。
+     */
+    get pendingCount(): number;
+    /**
+     * 清除并取消所有等待中的计时器。
+     */
+    clear(): void;
+}

package/dist/clock.js

@@ -0,0 +1,108 @@
+/**
+ * 确定性测试模拟时钟实现。
+ * 遵循 Clock 接口契约，支持手动单调推进时间并调度计时器。
+ */
+export class FakeClock {
+    currentNow;
+    currentMonotonic;
+    initialRealNow;
+    advancedMs = 0;
+    isFixed = false;
+    nextTimerId = 1;
+    pendingSleeps = [];
+    constructor(options = {}) {
+        if (options.now !== undefined) {
+            this.currentNow = new Date(options.now).getTime();
+            this.isFixed = true;
+            this.initialRealNow = this.currentNow;
+        }
+        else {
+            this.currentNow = Date.now();
+            this.initialRealNow = this.currentNow;
+        }
+        this.currentMonotonic = options.startMonotonic ?? 0;
+    }
+    /**
+     * 获取当前模拟墙上时间。
+     */
+    now() {
+        return new Date(this.currentNow);
+    }
+    /**
+     * 获取当前模拟单调时间戳（毫秒）。
+     */
+    monotonic() {
+        return this.currentMonotonic;
+    }
+    /**
+     * 异步休眠指定毫秒。
+     * 等待通过 advance 方法推进时间至目标时刻后完成。
+     *
+     * @param ms 休眠毫秒数
+     */
+    sleep(ms) {
+        if (ms <= 0) {
+            return Promise.resolve();
+        }
+        return new Promise((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) {
+        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;
+        this.advancedMs += 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() {
+        return this.pendingSleeps.length;
+    }
+    /**
+     * 清除并取消所有等待中的计时器。
+     */
+    clear() {
+        const sleeps = this.pendingSleeps;
+        this.pendingSleeps = [];
+        for (const item of sleeps) {
+            item.reject(new Error("FakeClock timer cancelled"));
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./clock.js";
+export * from "./process.js";
+export * from "./storage.js";
+export * from "./runtime.js";
+export * from "./platform.js";
+export * from "./cli.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./clock.js";
+export * from "./process.js";
+export * from "./storage.js";
+export * from "./runtime.js";
+export * from "./platform.js";
+export * from "./cli.js";

package/dist/platform.d.ts

@@ -0,0 +1,48 @@
+import { type EventSink, type FileSystem, type ModuleLoader, type RuntimePlatform, type RuntimeStorage, type StorageFactory } from "@actiondock/core";
+import { FakeClock } from "./clock.js";
+import { MockProcessExecutor } from "./process.js";
+/**
+ * 测试平台构建配置选项。
+ */
+export interface TestPlatformOptions {
+    /** 可选注入的确定性虚拟时钟 */
+    clock?: FakeClock;
+    /** 可选注入的统一存储实例（若指定则所有 Package 存储均回退至该实例） */
+    storage?: RuntimeStorage;
+    /** 可选注入的跨 Package 全局存储实例 */
+    globalStorage?: RuntimeStorage;
+    /** 可选注入的模拟进程执行器 */
+    process?: MockProcessExecutor;
+    /** 可选注入的执行事件接收器 */
+    eventSink?: EventSink;
+    /** 可选注入的文件系统抽象驱动 */
+    files?: FileSystem;
+    /** 可选注入的源码模块加载器 */
+    modules?: ModuleLoader;
+}
+/**
+ * 测试运行时平台接口契约。
+ * 完整实现 RuntimePlatform，并显式暴露测试组件类型。
+ */
+export interface TestPlatform extends RuntimePlatform {
+    readonly name: "test";
+    readonly clock: FakeClock;
+    readonly files: FileSystem;
+    readonly modules: ModuleLoader;
+    readonly process: MockProcessExecutor;
+    readonly storage: StorageFactory;
+    readonly eventSink: EventSink;
+}
+/**
+ * 创建纯内存确定性测试平台实例。
+ * 组装测试核心组件：
+ * - FakeClock 确定性虚拟时钟
+ * - MockProcessExecutor 模拟进程执行器
+ * - MemoryStorage 纯内存数据库存储
+ * - TestEventSink 确定性事件接收器
+ * - DefaultModuleLoader 动态模块加载器
+ * - NodeFileSystem 文件系统
+ *
+ * @param options 测试平台配置选项
+ */
+export declare function createTestPlatform(options?: TestPlatformOptions): TestPlatform;

package/dist/platform.js

@@ -0,0 +1,61 @@
+import { DefaultModuleLoader, NodeFileSystem, } from "@actiondock/core";
+import { FakeClock } from "./clock.js";
+import { MockProcessExecutor } from "./process.js";
+import { TestEventSink } from "./runtime.js";
+import { MemoryStorage } from "./storage.js";
+/**
+ * 创建纯内存确定性测试平台实例。
+ * 组装测试核心组件：
+ * - FakeClock 确定性虚拟时钟
+ * - MockProcessExecutor 模拟进程执行器
+ * - MemoryStorage 纯内存数据库存储
+ * - TestEventSink 确定性事件接收器
+ * - DefaultModuleLoader 动态模块加载器
+ * - NodeFileSystem 文件系统
+ *
+ * @param options 测试平台配置选项
+ */
+export function createTestPlatform(options = {}) {
+    const clock = options.clock ?? new FakeClock();
+    const process = options.process ?? new MockProcessExecutor();
+    const eventSink = options.eventSink ?? new TestEventSink();
+    const files = options.files ?? new NodeFileSystem();
+    const modules = options.modules ?? new DefaultModuleLoader();
+    const packageStorages = new Map();
+    let globalStorageInstance = options.globalStorage;
+    const storageFactory = {
+        createStorage(packageId, _opts) {
+            if (options.storage) {
+                return options.storage;
+            }
+            let existing = packageStorages.get(packageId);
+            if (!existing) {
+                existing = new MemoryStorage({
+                    packageId,
+                    clock,
+                });
+                packageStorages.set(packageId, existing);
+            }
+            return existing;
+        },
+        createGlobalStorage(_opts) {
+            if (globalStorageInstance) {
+                return globalStorageInstance;
+            }
+            globalStorageInstance = new MemoryStorage({
+                packageId: "__global__",
+                clock,
+            });
+            return globalStorageInstance;
+        },
+    };
+    return {
+        name: "test",
+        clock,
+        files,
+        modules,
+        process,
+        storage: storageFactory,
+        eventSink,
+    };
+}