@actiondock/testing 2.0.11 → 2.0.12

package/dist/clock.d.ts

@@ -0,0 +1,51 @@
+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 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/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 将 @actiondock/testing 注册为 @actiondock/sdk 中 createTestRuntime 的全局生产级实现。
+ */
+export declare function registerTestingAsSdkProvider(): void;
+export * from "./clock";
+export * from "./process";
+export * from "./storage";
+export * from "./runtime";

package/dist/index.js

@@ -0,0 +1,486 @@
+// packages/testing/src/index.ts
+import { registerTestRuntimeProvider } from "@actiondock/sdk";
+
+// packages/testing/src/runtime.ts
+import {
+  DefaultExecutionService,
+  InMemoryEventSink,
+  RuntimeConfig,
+  RuntimeStateStore
+} from "@actiondock/core";
+import {
+  MemoryLogger
+} from "@actiondock/sdk";
+
+// packages/testing/src/clock.ts
+class FakeClock {
+  currentNow;
+  currentMonotonic;
+  nextTimerId = 1;
+  pendingSleeps = [];
+  constructor(options = {}) {
+    if (options.now !== undefined) {
+      this.currentNow = new Date(options.now).getTime();
+    } else {
+      this.currentNow = Date.now();
+    }
+    this.currentMonotonic = options.startMonotonic ?? 0;
+  }
+  now() {
+    return new Date(this.currentNow);
+  }
+  monotonic() {
+    return this.currentMonotonic;
+  }
+  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);
+    });
+  }
+  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;
+    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"));
+    }
+  }
+}
+
+// packages/testing/src/process.ts
+class MockProcessExecutor {
+  mocks = [];
+  calls = [];
+  detachedCalls = [];
+  defaultPid = 10001;
+  register(matcher, handlerOrResult) {
+    this.mocks.push({ matcher, handler: handlerOrResult });
+    return this;
+  }
+  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: 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;
+    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;
+    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 spawnDetached(options) {
+    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 = {
+        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
+    };
+  }
+  getCalls(command) {
+    if (!command) {
+      return [...this.calls];
+    }
+    return this.calls.filter((c) => c.command === command);
+  }
+  getLastCall() {
+    return this.calls[this.calls.length - 1];
+  }
+  hasCalled(command) {
+    return this.calls.some((c) => c.command === command);
+  }
+  clearHistory() {
+    this.calls = [];
+    this.detachedCalls = [];
+  }
+  reset() {
+    this.mocks = [];
+    this.calls = [];
+    this.detachedCalls = [];
+  }
+  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 || 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;
+  }
+  async waitDelay(delayMs, options) {
+    return new Promise((resolve) => {
+      let timer;
+      const cleanup = () => {
+        if (timer)
+          clearTimeout(timer);
+      };
+      if (options.signal) {
+        options.signal.addEventListener("abort", () => {
+          cleanup();
+          resolve();
+        }, { once: true });
+      }
+      timer = setTimeout(() => {
+        cleanup();
+        resolve();
+      }, delayMs);
+    });
+  }
+}
+
+// packages/testing/src/storage.ts
+import {
+  SqliteRuntimeStorage
+} from "@actiondock/core";
+
+class MemoryStorage extends SqliteRuntimeStorage {
+  constructor(options = {}) {
+    super({
+      packageId: options.packageId || "test-pkg",
+      dbPath: ":memory:",
+      driver: options.driver,
+      clock: options.clock
+    });
+  }
+}
+
+// packages/testing/src/runtime.ts
+class ActionRuntimeError extends Error {
+  code;
+  details;
+  cause;
+  constructor(error) {
+    super(error.message);
+    this.name = "ActionRuntimeError";
+    this.code = error.code;
+    this.details = error.details;
+    this.cause = error.cause;
+    Object.setPrototypeOf(this, ActionRuntimeError.prototype);
+  }
+}
+
+class TestConfigStore {
+  runtimeConfig;
+  storage;
+  constructor(storage, projectConfig, overrides) {
+    this.storage = storage;
+    this.runtimeConfig = new RuntimeConfig(storage, overrides, projectConfig, undefined);
+  }
+  get(key, defaultValue) {
+    return this.runtimeConfig.get(key, defaultValue);
+  }
+  has(key) {
+    return this.runtimeConfig.has(key);
+  }
+  set(key, value) {
+    this.storage.setConfig(key, value);
+  }
+  delete(key) {
+    return this.storage.deleteConfig(key);
+  }
+  list() {
+    return this.storage.listConfig();
+  }
+}
+
+class TestEventSink extends InMemoryEventSink {
+  allEvents = [];
+  sequenceCounter = 0;
+  nextSequence() {
+    return this.sequenceCounter++;
+  }
+  emit(event) {
+    this.allEvents.push(event);
+    super.emit(event);
+  }
+  getEvents(runId) {
+    if (runId) {
+      return this.allEvents.filter((e) => e.runId === runId);
+    }
+    return [...this.allEvents];
+  }
+  clearAll() {
+    this.allEvents = [];
+    this.sequenceCounter = 0;
+  }
+}
+function createTestRuntime(options = {}) {
+  const packageId = options.packageId || "test-pkg";
+  const clock = options.clock ?? new FakeClock;
+  const process = options.process ?? new MockProcessExecutor;
+  const storage = options.storage ?? new MemoryStorage({
+    packageId,
+    clock
+  });
+  if (options.config) {
+    for (const [key, val] of Object.entries(options.config)) {
+      storage.setConfig(key, val);
+    }
+  }
+  if (options.state) {
+    for (const [key, val] of Object.entries(options.state)) {
+      storage.setState("", key, val);
+    }
+  }
+  const events = new TestEventSink;
+  const memoryLogger = options.logger instanceof MemoryLogger ? options.logger : new MemoryLogger;
+  const actionsMap = new Map;
+  if (options.actions) {
+    if (Array.isArray(options.actions)) {
+      for (const act of options.actions) {
+        actionsMap.set(act.id, act);
+      }
+    } else if (options.actions instanceof Map) {
+      for (const [k, v] of options.actions) {
+        actionsMap.set(k, v);
+      }
+    } else if (typeof options.actions === "object") {
+      for (const [k, v] of Object.entries(options.actions)) {
+        actionsMap.set(k, v);
+      }
+    }
+  }
+  const executionService = new DefaultExecutionService({
+    packageId,
+    storage,
+    projectConfig: options.projectConfig,
+    configOverrides: options.configOverrides,
+    actions: actionsMap,
+    process,
+    clock,
+    logger: memoryLogger,
+    eventSink: events
+  });
+  const testConfig = new TestConfigStore(storage, options.projectConfig, options.configOverrides);
+  const testState = new RuntimeStateStore(storage);
+  const registerAction = (action) => {
+    executionService.registerAction(action);
+  };
+  const getAction = (id) => {
+    return executionService.getAction(id);
+  };
+  const listActions = () => {
+    return executionService.listActions();
+  };
+  const execute = async (action, input = {}, execOptions = {}) => {
+    if (typeof action !== "string") {
+      executionService.registerAction(action);
+    }
+    const actionRef = typeof action === "string" ? action : action.id;
+    const ticket = await executionService.start(actionRef, input, {
+      signal: execOptions.signal,
+      timeoutMs: execOptions.timeoutMs,
+      config: execOptions.configOverrides,
+      parentRunId: execOptions.parentRunId,
+      rootRunId: execOptions.rootRunId,
+      maxCallDepth: execOptions.maxCallDepth,
+      logger: execOptions.logger,
+      progress: execOptions.progress,
+      process: execOptions.process || process
+    });
+    const result = await ticket.result;
+    return result;
+  };
+  const run = async (action, input = {}) => {
+    const result = await execute(action, input);
+    if (!result.ok) {
+      throw new ActionRuntimeError(result.error);
+    }
+    return result.data;
+  };
+  return {
+    config: testConfig,
+    state: testState,
+    clock,
+    process,
+    events,
+    logger: memoryLogger,
+    storage,
+    executionService,
+    runner: executionService.runner,
+    registerAction,
+    getAction,
+    listActions,
+    run,
+    execute
+  };
+}
+
+// packages/testing/src/index.ts
+function registerTestingAsSdkProvider() {
+  registerTestRuntimeProvider(createTestRuntime);
+}
+export {
+  ActionRuntimeError,
+  FakeClock,
+  MemoryStorage,
+  MockProcessExecutor,
+  TestConfigStore,
+  TestEventSink,
+  createTestRuntime,
+  registerTestingAsSdkProvider
+};

package/dist/process.d.ts

@@ -0,0 +1,116 @@
+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;
+}
+/**
+ * 模拟进程执行器实现。
+ * 遵循 ProcessExecutor 接口契约，支持预设命令响应、跟踪调用历史并模拟超时与取消场景。
+ */
+export declare class MockProcessExecutor implements ProcessExecutor {
+    private mocks;
+    calls: ProcessCall[];
+    detachedCalls: DetachedProcessCall[];
+    defaultPid: number;
+    /**
+     * 注册模拟命令匹配与返回结果。
+     *
+     * @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>;
+    /**
+     * 启动模拟脱离父进程的后台进程。
+     *
+     * @param options 守护进程启动选项
+     */
+    spawnDetached(options: DetachedProcessOptions): Promise<DetachedProcessResult>;
+    /**
+     * 获取指定命令的历史调用记录。
+     *
+     * @param command 可选命令筛选
+     */
+    getCalls(command?: string): ProcessCall[];
+    /**
+     * 获取最近一次命令调用记录。
+     */
+    getLastCall(): ProcessCall | undefined;
+    /**
+     * 检查指定命令是否被调用过。
+     *
+     * @param command 目标命令
+     */
+    hasCalled(command: string): boolean;
+    /**
+     * 清空历史调用记录。
+     */
+    clearHistory(): void;
+    /**
+     * 重置所有注册规则与历史记录。
+     */
+    reset(): void;
+    private findMock;
+    private waitDelay;
+}