@actiondock/testing 2.0.12 → 2.2.1

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

@@ -1,18 +1,78 @@
-import { ActionRunner, type ExecutionService, type ExecutionStartOptions, InMemoryEventSink, type ProjectConfig } from "@actiondock/core";
-import { type ActionDefinition, type Config, type ExecutionEvent, type ExecutionResult, type Logger, MemoryLogger, type RuntimeError, type StateStore } from "@actiondock/sdk";
-import { FakeClock } from "./clock";
-import { MockProcessExecutor } from "./process";
-import { MemoryStorage } from "./storage";
+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";
 /**
- * 规范化运行时错误异常类。
- * 当 run 方法执行失败时抛出，完整实现 RuntimeError 契约。
+ * 基于内存 Map 的只读/可写配置实现，专供单元测试使用。
  */
-export declare class ActionRuntimeError extends Error implements RuntimeError {
-    code: string;
-    details?: unknown;
-    cause?: unknown;
-    constructor(error: RuntimeError);
+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 };
 /**
  * 带有写入和调试能力的配置接口。
  */
@@ -82,7 +142,14 @@ export interface TestRuntimeOptions {
     /** 项目静态配置元数据 */
     projectConfig?: ProjectConfig;
     /** 预注册的 Action 动作列表 */
-    actions?: ActionDefinition[] | Record<string, ActionDefinition> | Map<string, ActionDefinition>;
+    actions?: Array<{
+        id: string;
+        action: ActionDefinition;
+    } | (ActionDefinition & {
+        id: string;
+    })> | Record<string, ActionDefinition> | Map<string, ActionDefinition>;
+    /** 可选注入的标准运行时平台实例 */
+    platform?: RuntimePlatform;
 }
 /**
  * 测试运行时接口。
@@ -107,7 +174,11 @@ export interface TestRuntime {
     /** 核心执行器引擎（向后兼容保留） */
     runner: ActionRunner;
     /** 注册 Action 动作定义 */
-    registerAction(action: ActionDefinition): void;
+    registerAction(id: string, action: ActionDefinition): void;
+    registerAction(action: ({
+        id: string;
+        action?: ActionDefinition;
+    } & Partial<ActionDefinition>) | ActionDefinition): void;
     /** 获取已注册的 Action 动作定义 */
     getAction(id: string): ActionDefinition | undefined;
     /** 列出已注册的所有 Action 动作定义 */