@actiondock/testing 2.0.11 → 2.2.0

package/dist/process.d.ts

@@ -0,0 +1,117 @@
+import type { ProcessExecutor } from "@actiondock/core";
+import type { 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 MockProcessExecutorOptions {
+    /** 未命中任何模拟规则时是否回退到真实子进程执行（默认 false，未命中即抛错） */
+    fallbackToReal?: boolean;
+}
+/**
+ * 模拟进程执行器实现。
+ * 遵循 ProcessExecutor 接口契约，支持预设命令响应、跟踪调用历史并模拟超时与取消场景。
+ *
+ * 默认不回退真实子进程执行：未命中任何模拟规则时抛出明确错误，避免测试中的拼写失误穿透到真实系统命令。
+ * 如确需真实回退（例如集成本地 CLI），可显式传入 fallbackToReal: true。
+ */
+export declare class MockProcessExecutor implements ProcessExecutor {
+    private mocks;
+    calls: ProcessCall[];
+    defaultPid: number;
+    private readonly fallbackToReal;
+    constructor(options?: MockProcessExecutorOptions);
+    /**
+     * 注册模拟命令匹配与返回结果。
+     *
+     * @param matcher 匹配器（命令字符串、正则表达式或判断函数）
+     * @param handlerOrResult 预设执行结果或动态处理函数
+     */
+    register(matcher: CommandMatcher, handlerOrResult: MockProcessHandler | MockProcessResultOptions): this;
+    /**
+     * 执行外部命令并返回模拟结果。
+     *
+     * @param command 执行命令
+     * @param args 参数列表
+     * @param options 执行选项
+     */
+    exec(command: string, args?: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
+    spawn(command: string, args?: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
+    /**
+     * 获取指定命令的历史调用记录。
+     *
+     * @param command 可选命令筛选
+     */
+    getCalls(command?: string): ProcessCall[];
+    /**
+     * 获取最近一次命令调用记录。
+     */
+    getLastCall(): ProcessCall | undefined;
+    /**
+     * 检查指定命令是否被调用过。
+     *
+     * @param command 目标命令
+     */
+    hasCalled(command: string): boolean;
+    /**
+     * 清空历史调用记录。
+     */
+    clearHistory(): void;
+    /**
+     * 重置所有注册规则与历史记录。
+     */
+    reset(): void;
+    /**
+     * 渲染已注册匹配器列表，辅助定位拼写失误。
+     */
+    private describeMatchers;
+    private findMock;
+    private waitDelay;
+}

package/dist/process.js

@@ -0,0 +1,280 @@
+import { execCli } from "./cli.js";
+/**
+ * 模拟进程执行器实现。
+ * 遵循 ProcessExecutor 接口契约，支持预设命令响应、跟踪调用历史并模拟超时与取消场景。
+ *
+ * 默认不回退真实子进程执行：未命中任何模拟规则时抛出明确错误，避免测试中的拼写失误穿透到真实系统命令。
+ * 如确需真实回退（例如集成本地 CLI），可显式传入 fallbackToReal: true。
+ */
+export class MockProcessExecutor {
+    mocks = [];
+    calls = [];
+    defaultPid = 10001;
+    fallbackToReal;
+    constructor(options = {}) {
+        this.fallbackToReal = options.fallbackToReal ?? false;
+    }
+    /**
+     * 注册模拟命令匹配与返回结果。
+     *
+     * @param matcher 匹配器（命令字符串、正则表达式或判断函数）
+     * @param handlerOrResult 预设执行结果或动态处理函数
+     */
+    register(matcher, handlerOrResult) {
+        this.mocks.push({ matcher, handler: handlerOrResult });
+        return this;
+    }
+    /**
+     * 执行外部命令并返回模拟结果。
+     *
+     * @param command 执行命令
+     * @param args 参数列表
+     * @param options 执行选项
+     */
+    async exec(command, args = [], options = {}) {
+        const startTime = Date.now();
+        this.calls.push({
+            command,
+            args: [...args],
+            options: { ...options },
+            timestamp: startTime,
+        });
+        // 检查调用前是否已中断
+        if (options.signal?.aborted) {
+            const res = {
+                ok: false,
+                exitCode: -1,
+                signal: "SIGTERM",
+                stdout: "",
+                stderr: "Command aborted before execution by signal",
+                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);
+        const fullCommandLine = [command, ...args].join(" ").trim();
+        let resolved;
+        if (!matchedMock) {
+            if (!this.fallbackToReal) {
+                throw new Error(`MockProcessExecutor: 未命中任何模拟规则，且未开启 fallbackToReal，拒绝执行真实命令: ${fullCommandLine}\n已注册匹配器列表:\n${this.describeMatchers()}`);
+            }
+            try {
+                const cliRes = await execCli(command, args, {
+                    cwd: options.cwd,
+                    env: options.env,
+                    signal: options.signal,
+                    timeout: options.timeoutMs,
+                    input: options.input,
+                    encoding: options.encoding,
+                });
+                resolved = {
+                    ok: cliRes.ok,
+                    exitCode: cliRes.exitCode,
+                    stdout: cliRes.stdout,
+                    stderr: cliRes.stderr,
+                    raw: cliRes.raw,
+                    timedOut: cliRes.timedOut,
+                    durationMs: cliRes.durationMs,
+                };
+            }
+            catch (err) {
+                resolved = {
+                    ok: false,
+                    exitCode: -1,
+                    stdout: "",
+                    stderr: err?.message || String(err),
+                    raw: new Uint8Array(),
+                    durationMs: Date.now() - startTime,
+                };
+            }
+        }
+        else if (typeof matchedMock.handler === "function") {
+            resolved = await matchedMock.handler(command, args, options);
+        }
+        else {
+            resolved = matchedMock.handler;
+        }
+        // 模拟延时控制
+        const maybeMock = resolved;
+        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 = {
+            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;
+    }
+    async spawn(command, args = [], options = {}) {
+        return this.exec(command, args, options);
+    }
+    /**
+     * 获取指定命令的历史调用记录。
+     *
+     * @param command 可选命令筛选
+     */
+    getCalls(command) {
+        if (!command) {
+            return [...this.calls];
+        }
+        return this.calls.filter((c) => c.command === command);
+    }
+    /**
+     * 获取最近一次命令调用记录。
+     */
+    getLastCall() {
+        return this.calls[this.calls.length - 1];
+    }
+    /**
+     * 检查指定命令是否被调用过。
+     *
+     * @param command 目标命令
+     */
+    hasCalled(command) {
+        return this.calls.some((c) => c.command === command);
+    }
+    /**
+     * 清空历史调用记录。
+     */
+    clearHistory() {
+        this.calls = [];
+    }
+    /**
+     * 重置所有注册规则与历史记录。
+     */
+    reset() {
+        this.mocks = [];
+        this.calls = [];
+    }
+    /**
+     * 渲染已注册匹配器列表，辅助定位拼写失误。
+     */
+    describeMatchers() {
+        if (this.mocks.length === 0) {
+            return "（无任何已注册匹配器）";
+        }
+        return this.mocks
+            .map((m) => {
+            const desc = typeof m.matcher === "string"
+                ? `"${m.matcher}"`
+                : m.matcher instanceof RegExp
+                    ? `/${m.matcher.source}/${m.matcher.flags}`
+                    : "[Function]";
+            return `- ${desc}`;
+        })
+            .join("\n");
+    }
+    findMock(command, args, options) {
+        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) {
+                    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;
+    }
+    async waitDelay(delayMs, options) {
+        return new Promise((resolve) => {
+            let timer;
+            let onAbort;
+            const cleanup = () => {
+                if (timer) {
+                    clearTimeout(timer);
+                    timer = undefined;
+                }
+                if (options.signal && onAbort) {
+                    options.signal.removeEventListener("abort", onAbort);
+                    onAbort = undefined;
+                }
+            };
+            if (options.signal) {
+                if (options.signal.aborted) {
+                    resolve();
+                    return;
+                }
+                onAbort = () => {
+                    cleanup();
+                    resolve();
+                };
+                options.signal.addEventListener("abort", onAbort, { once: true });
+            }
+            timer = setTimeout(() => {
+                cleanup();
+                resolve();
+            }, delayMs);
+        });
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,208 @@
+import { ActionRunner, type ExecutionService, type ExecutionStartOptions, InMemoryEventSink, type ProjectConfig, type RuntimePlatform } from "@actiondock/core";
+import type { Clock } from "@actiondock/core";
+import type { ActionDefinition, Config, ExecutionEvent, ExecutionResult, Logger, StateStore } from "@actiondock/sdk";
+import { FakeClock } from "./clock.js";
+import { MockProcessExecutor } from "./process.js";
+import { MemoryStorage } from "./storage.js";
+/**
+ * 基于内存 Map 的只读/可写配置实现，专供单元测试使用。
+ */
+export declare class MemoryConfig implements Config {
+    private store;
+    constructor(initial?: Record<string, unknown>);
+    get<T = unknown>(key: string): T | undefined;
+    get<T = unknown>(key: string, defaultValue: T): T;
+    has(key: string): boolean;
+    /**
+     * 在测试期间动态更新或插入配置值。
+     * @param key 配置键名
+     * @param value 配置值
+     */
+    set(key: string, value: unknown): void;
+    /**
+     * 删除指定配置项。
+     * @param key 配置键名
+     */
+    delete(key: string): boolean;
+    /**
+     * 列出所有已存储配置项。
+     */
+    list(): Record<string, unknown>;
+}
+/**
+ * 内存状态条目结构体，包含数据值与可选的过期时间戳。
+ */
+export interface MemoryStateEntry {
+    value: unknown;
+    expiresAt?: number;
+}
+import { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment } from "@actiondock/sdk";
+export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment };
+/**
+ * 基于内存 Map 的状态存储实现，支持命名空间隔离与 TTL 自动失效，专供单元测试使用。
+ */
+export declare class MemoryStateStore implements StateStore {
+    private store;
+    private namespace;
+    private clock;
+    constructor(store?: Map<string, any>, namespace?: string, clock?: Clock);
+    /** 获取注入时钟的当前时间戳（毫秒），TTL 过期判定单一事实入口 */
+    private nowMs;
+    private qualify;
+    private extractEntry;
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(prefix?: string): Promise<number>;
+    keys(prefix?: string): Promise<string[]>;
+    scope(namespace: string): StateStore;
+}
+/**
+ * 内存日志记录器实现，将所有日志记录在数组中以便在测试断言中检索。
+ */
+export declare class MemoryLogger implements Logger {
+    logs: Array<{
+        level: string;
+        message: string;
+        data?: unknown;
+    }>;
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+import { ActionRuntimeError } from "@actiondock/sdk";
+export { ActionRuntimeError };
+/**
+ * 带有写入和调试能力的配置接口。
+ */
+export interface TestConfig extends Config {
+    /** 写入配置键值 */
+    set(key: string, value: unknown): void;
+    /** 删除指定配置键 */
+    delete(key: string): boolean;
+    /** 列出所有已存储配置项 */
+    list(): Record<string, unknown>;
+}
+/**
+ * 测试配置管理器实现。
+ */
+export declare class TestConfigStore implements TestConfig {
+    private runtimeConfig;
+    private storage;
+    constructor(storage: MemoryStorage, projectConfig?: ProjectConfig, overrides?: Record<string, unknown>);
+    get<T = unknown>(key: string): T | undefined;
+    get<T = unknown>(key: string, defaultValue: T): T;
+    has(key: string): boolean;
+    set(key: string, value: unknown): void;
+    delete(key: string): boolean;
+    list(): Record<string, unknown>;
+}
+/**
+ * 测试事件接收器实现。
+ * 记录执行期间产生的所有事件并支持历史检索。
+ */
+export declare class TestEventSink extends InMemoryEventSink {
+    private allEvents;
+    private sequenceCounter;
+    /** 获取下一个单调自增序号 */
+    nextSequence(): number;
+    emit(event: ExecutionEvent): void;
+    /**
+     * 检索历史事件列表。
+     *
+     * @param runId 可选运行标识筛选
+     */
+    getEvents(runId?: string): ExecutionEvent[];
+    /**
+     * 清理所有捕获的事件记录。
+     */
+    clearAll(): void;
+}
+/**
+ * 测试运行时初始化选项。
+ */
+export interface TestRuntimeOptions {
+    /** 绑定的 Package 标识 */
+    packageId?: string;
+    /** 初始注入的配置键值映射 */
+    config?: Record<string, unknown>;
+    /** 运行级别临时配置覆写字典 */
+    configOverrides?: Record<string, unknown>;
+    /** 初始注入的状态键值映射 */
+    state?: Record<string, unknown>;
+    /** 可选注入的模拟时钟实例 */
+    clock?: FakeClock;
+    /** 可选注入的模拟进程执行器 */
+    process?: MockProcessExecutor;
+    /** 可选注入的日志记录器（默认使用 MemoryLogger） */
+    logger?: Logger;
+    /** 可选注入的底层存储实例 */
+    storage?: MemoryStorage;
+    /** 项目静态配置元数据 */
+    projectConfig?: ProjectConfig;
+    /** 预注册的 Action 动作列表 */
+    actions?: Array<{
+        id: string;
+        action: ActionDefinition;
+    } | (ActionDefinition & {
+        id: string;
+    })> | Record<string, ActionDefinition> | Map<string, ActionDefinition>;
+    /** 可选注入的标准运行时平台实例 */
+    platform?: RuntimePlatform;
+}
+/**
+ * 测试运行时接口。
+ */
+export interface TestRuntime {
+    /** 调试配置接口 */
+    config: TestConfig;
+    /** 调试状态持久化接口 */
+    state: StateStore;
+    /** 调试模拟时钟接口 */
+    clock: FakeClock;
+    /** 调试模拟进程执行接口 */
+    process: MockProcessExecutor;
+    /** 调试执行事件捕获接口 */
+    events: TestEventSink;
+    /** 调试日志记录捕获接口 */
+    logger: MemoryLogger;
+    /** 底层存储引擎 */
+    storage: MemoryStorage;
+    /** 统一执行服务 */
+    executionService: ExecutionService;
+    /** 核心执行器引擎（向后兼容保留） */
+    runner: ActionRunner;
+    /** 注册 Action 动作定义 */
+    registerAction(id: string, action: ActionDefinition): void;
+    registerAction(action: ({
+        id: string;
+        action?: ActionDefinition;
+    } & Partial<ActionDefinition>) | ActionDefinition): void;
+    /** 获取已注册的 Action 动作定义 */
+    getAction(id: string): ActionDefinition | undefined;
+    /** 列出已注册的所有 Action 动作定义 */
+    listActions(): ActionDefinition[];
+    /**
+     * 执行 Action 并直接返回业务结果数据，失败时抛出 ActionRuntimeError 规范化异常。
+     *
+     * @param action Action 动作定义或已注册标识
+     * @param input 输入参数数据
+     */
+    run<I = unknown, O = unknown>(action: ActionDefinition<I, O> | string, input?: I): Promise<O>;
+    /**
+     * 执行 Action 并返回完整的 ExecutionResult 信封结构。
+     *
+     * @param action Action 动作定义或已注册标识
+     * @param input 输入参数数据
+     * @param options 可选执行控制参数
+     */
+    execute<I = unknown, O = unknown>(action: ActionDefinition<I, O> | string, input?: I, options?: ExecutionStartOptions): Promise<ExecutionResult<O>>;
+}
+/**
+ * 创建全功能测试运行时实例。
+ * 基于统一 ExecutionService 协调执行全生命周期，并暴露配置、状态、时钟、进程与事件等调试接口。
+ *
+ * @param options 测试运行时选项
+ */
+export declare function createTestRuntime(options?: TestRuntimeOptions): TestRuntime;