@actiondock/testing 2.0.11 → 2.2.0

package/dist/runtime.js

@@ -0,0 +1,426 @@
+import { DefaultExecutionService, InMemoryEventSink, RuntimeConfig, RuntimeStateStore, SystemClock, normalizeActionCollection, } from "@actiondock/core";
+import { FakeClock } from "./clock.js";
+import { MockProcessExecutor } from "./process.js";
+import { MemoryStorage } from "./storage.js";
+/**
+ * 基于内存 Map 的只读/可写配置实现，专供单元测试使用。
+ */
+export class MemoryConfig {
+    store;
+    constructor(initial = {}) {
+        this.store = new Map(Object.entries(initial));
+    }
+    get(key, defaultValue) {
+        if (this.store.has(key)) {
+            return this.store.get(key);
+        }
+        return defaultValue;
+    }
+    has(key) {
+        return this.store.has(key);
+    }
+    /**
+     * 在测试期间动态更新或插入配置值。
+     * @param key 配置键名
+     * @param value 配置值
+     */
+    set(key, value) {
+        this.store.set(key, value);
+    }
+    /**
+     * 删除指定配置项。
+     * @param key 配置键名
+     */
+    delete(key) {
+        return this.store.delete(key);
+    }
+    /**
+     * 列出所有已存储配置项。
+     */
+    list() {
+        return Object.fromEntries(this.store.entries());
+    }
+}
+// 状态键编解码能力单一事实源位于 @actiondock/sdk，此处 re-export 维持既有导入路径兼容并供本模块内部复用
+import { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment, } from "@actiondock/sdk";
+export { decodeStateKey, encodeStateKey, escapeStateSegment, unescapeStateSegment };
+/**
+ * 基于内存 Map 的状态存储实现，支持命名空间隔离与 TTL 自动失效，专供单元测试使用。
+ */
+export class MemoryStateStore {
+    store;
+    namespace;
+    clock;
+    constructor(store, namespace = "", clock) {
+        this.store = store || new Map();
+        this.namespace = namespace;
+        this.clock = clock ?? new SystemClock();
+    }
+    /** 获取注入时钟的当前时间戳（毫秒），TTL 过期判定单一事实入口 */
+    nowMs() {
+        return this.clock.now().getTime();
+    }
+    qualify(key) {
+        return encodeStateKey(this.namespace, key);
+    }
+    extractEntry(raw) {
+        if (raw !== null &&
+            typeof raw === "object" &&
+            ("__actiondock_entry__" in raw ||
+                "expiresAt" in raw)) {
+            return raw;
+        }
+        return { value: raw };
+    }
+    async get(key) {
+        const qKey = this.qualify(key);
+        const raw = this.store.get(qKey);
+        if (raw === undefined)
+            return undefined;
+        const entry = this.extractEntry(raw);
+        if (entry.expiresAt !== undefined && entry.expiresAt <= this.nowMs()) {
+            this.store.delete(qKey);
+            return undefined;
+        }
+        return (entry.value !== undefined ? structuredClone(entry.value) : undefined);
+    }
+    async set(key, value, ttl) {
+        const qKey = this.qualify(key);
+        const expiresAt = typeof ttl === "number" && ttl > 0 ? this.nowMs() + ttl * 1000 : undefined;
+        const entry = {
+            value: structuredClone(value),
+            expiresAt,
+        };
+        entry.__actiondock_entry__ = true;
+        this.store.set(qKey, entry);
+    }
+    async delete(key) {
+        const qKey = this.qualify(key);
+        return this.store.delete(qKey);
+    }
+    async clear(prefix = "") {
+        const keysToDelete = await this.keys(prefix);
+        let count = 0;
+        for (const k of keysToDelete) {
+            if (this.store.delete(this.qualify(k))) {
+                count++;
+            }
+        }
+        return count;
+    }
+    async keys(prefix = "") {
+        const now = this.nowMs();
+        const result = [];
+        for (const [k, raw] of this.store.entries()) {
+            let decoded;
+            try {
+                decoded = decodeStateKey(k);
+            }
+            catch {
+                continue;
+            }
+            if (decoded.namespace === this.namespace) {
+                if (prefix && !decoded.key.startsWith(prefix)) {
+                    continue;
+                }
+                const entry = this.extractEntry(raw);
+                if (entry.expiresAt !== undefined && entry.expiresAt <= now) {
+                    this.store.delete(k);
+                    continue;
+                }
+                result.push(decoded.key);
+            }
+        }
+        return result;
+    }
+    scope(namespace) {
+        const nextNs = this.namespace
+            ? `${this.namespace}:${namespace}`
+            : namespace;
+        return new MemoryStateStore(this.store, nextNs, this.clock);
+    }
+}
+/**
+ * 内存日志记录器实现，将所有日志记录在数组中以便在测试断言中检索。
+ */
+export class MemoryLogger {
+    logs = [];
+    debug(message, data) {
+        this.logs.push({ level: "debug", message, data });
+    }
+    info(message, data) {
+        this.logs.push({ level: "info", message, data });
+    }
+    warn(message, data) {
+        this.logs.push({ level: "warn", message, data });
+    }
+    error(message, data) {
+        this.logs.push({ level: "error", message, data });
+    }
+}
+// 规范化运行时错误类单一事实源位于 @actiondock/sdk，此处 re-export 维持既有导入路径兼容并供本模块内部复用
+import { ActionRuntimeError } from "@actiondock/sdk";
+export { ActionRuntimeError };
+/**
+ * 测试配置管理器实现。
+ */
+export 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) {
+        const res = this.storage.deleteConfig(key);
+        return typeof res === "boolean" ? res : true;
+    }
+    list() {
+        return this.storage.listConfig();
+    }
+}
+/**
+ * 测试事件接收器实现。
+ * 记录执行期间产生的所有事件并支持历史检索。
+ */
+export class TestEventSink extends InMemoryEventSink {
+    allEvents = [];
+    sequenceCounter = 0;
+    /** 获取下一个单调自增序号 */
+    nextSequence() {
+        return this.sequenceCounter++;
+    }
+    emit(event) {
+        this.allEvents.push(event);
+        super.emit(event);
+    }
+    /**
+     * 检索历史事件列表。
+     *
+     * @param runId 可选运行标识筛选
+     */
+    getEvents(runId) {
+        if (runId) {
+            return this.allEvents.filter((e) => e.runId === runId);
+        }
+        return [...this.allEvents];
+    }
+    /**
+     * 清理所有捕获的事件记录。
+     */
+    clearAll() {
+        this.allEvents = [];
+        this.sequenceCounter = 0;
+    }
+}
+const anonymousTestActions = new WeakMap();
+let anonymousTestActionCounter = 0;
+/** 测试运行时内部持有的匿名 Action 下一次可用序号 */
+function nextAnonymousTestActionId() {
+    anonymousTestActionCounter++;
+    return `test-action-${anonymousTestActionCounter}`;
+}
+/**
+ * 将任意形态的 actions 输入归一化为统一映射表。
+ *
+ * 直接复用 core 的 normalizeActionCollection 作为归一化单一事实源，
+ * 避免在 testing 包内重新实现三形态分支造成逻辑拷贝；
+ * 此处无需 actionSpecs 产物，仅取 actionsMap，并额外为不含包前缀的标识补充限定别名。
+ *
+ * @param rawActions 三形态之一的 Action 集合输入
+ * @param packageId 当前 Package 标识，用于补充限定别名
+ */
+function normalizeTestActions(rawActions, packageId) {
+    const { actionsMap } = normalizeActionCollection(rawActions);
+    for (const [id, act] of [...actionsMap]) {
+        if (!id.includes("/")) {
+            actionsMap.set(`${packageId}/${id}`, act);
+        }
+    }
+    return actionsMap;
+}
+/**
+ * 测试运行时 Action 注册表。
+ * 统一持有本地 actionsMap 与 executionService 双份注册状态，收敛注册、检索与列举入口。
+ */
+class TestActionRegistry {
+    actionsMap;
+    executionService;
+    packageId;
+    constructor(actionsMap, executionService, packageId) {
+        this.actionsMap = actionsMap;
+        this.executionService = executionService;
+        this.packageId = packageId;
+    }
+    /** 双签名注册：字符串标识与定义，或携带 id 的定义对象 */
+    register(idOrAction, maybeAction) {
+        if (typeof idOrAction === "string") {
+            if (!maybeAction) {
+                throw new Error(`registerAction(id, action) 调用缺少 action 定义：id=${idOrAction}`);
+            }
+            this.executionService.registerAction(idOrAction, maybeAction);
+            this.actionsMap.set(idOrAction, maybeAction);
+            if (!idOrAction.includes("/")) {
+                this.actionsMap.set(`${this.packageId}/${idOrAction}`, maybeAction);
+            }
+            return;
+        }
+        const actObj = idOrAction;
+        const id = actObj.id;
+        const act = actObj.action ?? (typeof actObj.run === "function" ? idOrAction : undefined);
+        if (id && act) {
+            this.actionsMap.set(id, act);
+            if (!id.includes("/")) {
+                this.actionsMap.set(`${this.packageId}/${id}`, act);
+            }
+        }
+        this.executionService.registerAction(idOrAction);
+    }
+    /** 按标识检索已注册定义 */
+    get(id) {
+        return this.executionService.getAction(id);
+    }
+    /** 列出已注册的全部定义 */
+    list() {
+        return this.executionService.listActions();
+    }
+}
+/**
+ * 解析 execute 入参的 Action 引用。
+ *
+ * 字符串直接作为引用；对象则依次尝试自身 id、注册表反查、匿名 WeakMap 映射，
+ * 并在首次出现时完成注册。全程不修改调用方传入的对象。
+ *
+ * @param action Action 定义或已注册标识
+ * @param registry 测试运行时 Action 注册表
+ * @returns 可用于 executionService 启动执行的引用标识
+ */
+function resolveActionRef(action, registry) {
+    if (typeof action === "string") {
+        return action;
+    }
+    const candidateId = action.id;
+    if (candidateId) {
+        registry.executionService.registerAction(candidateId, action);
+        registry.actionsMap.set(candidateId, action);
+        return candidateId;
+    }
+    // 反查注册表：同一对象已注册时复用既有标识
+    for (const [registeredId, registeredAct] of registry.actionsMap) {
+        if (registeredAct === action) {
+            return registeredId;
+        }
+    }
+    // 匿名对象首次出现：仅记录 WeakMap 映射，不写入调用方对象
+    let anonId = anonymousTestActions.get(action);
+    if (!anonId) {
+        anonId = nextAnonymousTestActionId();
+        anonymousTestActions.set(action, anonId);
+    }
+    registry.executionService.registerAction(anonId, action);
+    registry.actionsMap.set(anonId, action);
+    return anonId;
+}
+/**
+ * 创建全功能测试运行时实例。
+ * 基于统一 ExecutionService 协调执行全生命周期，并暴露配置、状态、时钟、进程与事件等调试接口。
+ *
+ * @param options 测试运行时选项
+ */
+export function createTestRuntime(options = {}) {
+    const packageId = options.packageId || "my-pkg";
+    const clock = options.clock ??
+        (options.platform?.clock instanceof FakeClock ? options.platform.clock : new FakeClock());
+    const process = options.process ??
+        (options.platform?.process instanceof MockProcessExecutor
+            ? options.platform.process
+            : new MockProcessExecutor());
+    const storage = options.storage ??
+        (options.platform?.storage
+            ? options.platform.storage.createStorage(packageId)
+            : 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 = normalizeTestActions(options.actions, packageId);
+    const executionService = new DefaultExecutionService({
+        packageId,
+        storage,
+        projectConfig: options.projectConfig,
+        configOverrides: options.configOverrides,
+        actions: actionsMap,
+        process,
+        clock,
+        logger: memoryLogger,
+        eventSink: events,
+        platform: options.platform,
+    });
+    const registry = new TestActionRegistry(actionsMap, executionService, packageId);
+    const testConfig = new TestConfigStore(storage, options.projectConfig, options.configOverrides);
+    const testState = new RuntimeStateStore(storage);
+    const registerAction = (idOrAction, maybeAction) => {
+        registry.register(idOrAction, maybeAction);
+    };
+    const execute = async (action, input = {}, execOptions = {}) => {
+        const actionRef = resolveActionRef(action, registry);
+        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: (id) => registry.get(id),
+        listActions: () => registry.list(),
+        run,
+        execute,
+    };
+}

package/dist/storage.d.ts

@@ -0,0 +1,20 @@
+import { type Clock, SqliteRuntimeStorage, type SqliteDriver } from "@actiondock/core";
+/**
+ * 内存运行时存储初始化选项。
+ */
+export interface MemoryStorageOptions {
+    /** 绑定的 Package 标识，默认为 test-pkg */
+    packageId?: string;
+    /** 可选注入的时间提供器，便于与模拟时钟联动 */
+    clock?: Clock;
+    /** 可选显式注入的底层 SQLite 驱动 */
+    driver?: SqliteDriver;
+}
+/**
+ * 统一内存运行时存储实现。
+ * 基于 SqliteRuntimeStorage 构建，默认使用 :memory: 内存数据库并对接虚拟时钟，
+ * 确保与生产环境具备完全相同的配置优先级、状态过期契约与运行终态行为。
+ */
+export declare class MemoryStorage extends SqliteRuntimeStorage {
+    constructor(options?: MemoryStorageOptions);
+}

package/dist/storage.js

@@ -0,0 +1,16 @@
+import { SqliteRuntimeStorage, } from "@actiondock/core";
+/**
+ * 统一内存运行时存储实现。
+ * 基于 SqliteRuntimeStorage 构建，默认使用 :memory: 内存数据库并对接虚拟时钟，
+ * 确保与生产环境具备完全相同的配置优先级、状态过期契约与运行终态行为。
+ */
+export class MemoryStorage extends SqliteRuntimeStorage {
+    constructor(options = {}) {
+        super({
+            packageId: options.packageId || "test-pkg",
+            dbPath: ":memory:",
+            driver: options.driver,
+            clock: options.clock,
+        });
+    }
+}

package/package.json

@@ -1,37 +1,38 @@
 {
   "name": "@actiondock/testing",
-  "version": "2.0.11",
+  "version": "2.2.0",
   "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",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./src/index.ts",
-      "types": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "files": [
-    "src",
+    "dist",
     "README.md"
   ],
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=24.12.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "test": "bun test"
+    "build": "node ../../scripts/build.ts",
+    "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/core": "^2.0.11",
-    "@actiondock/sdk": "^2.0.11"
+    "@actiondock/core": "^2.2.0",
+    "@actiondock/sdk": "^2.2.0"
   },
   "devDependencies": {
-    "@types/bun": "latest",
     "typescript": "^5.7.0"
   },
   "keywords": [

package/src/clock.ts

@@ -1,136 +0,0 @@
-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

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