@actiondock/testing 2.0.11 → 2.0.12

package/dist/runtime.d.ts

@@ -0,0 +1,137 @@
+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";
+/**
+ * 规范化运行时错误异常类。
+ * 当 run 方法执行失败时抛出，完整实现 RuntimeError 契约。
+ */
+export declare class ActionRuntimeError extends Error implements RuntimeError {
+    code: string;
+    details?: unknown;
+    cause?: unknown;
+    constructor(error: RuntimeError);
+}
+/**
+ * 带有写入和调试能力的配置接口。
+ */
+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?: ActionDefinition[] | Record<string, ActionDefinition> | Map<string, ActionDefinition>;
+}
+/**
+ * 测试运行时接口。
+ */
+export interface TestRuntime {
+    /** 调试配置接口 */
+    config: TestConfig;
+    /** 调试状态持久化接口 */
+    state: StateStore;
+    /** 调试模拟时钟接口 */
+    clock: FakeClock;
+    /** 调试模拟进程执行接口 */
+    process: MockProcessExecutor;
+    /** 调试执行事件捕获接口 */
+    events: TestEventSink;
+    /** 调试日志记录捕获接口 */
+    logger: MemoryLogger;
+    /** 底层存储引擎 */
+    storage: MemoryStorage;
+    /** 统一执行服务 */
+    executionService: ExecutionService;
+    /** 核心执行器引擎（向后兼容保留） */
+    runner: ActionRunner;
+    /** 注册 Action 动作定义 */
+    registerAction(action: 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;

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/package.json

@@ -1,37 +1,38 @@
 {
   "name": "@actiondock/testing",
-  "version": "2.0.11",
+  "version": "2.0.12",
   "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": ">=22.13.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
+    "build": "bun run ../../scripts/build.ts",
     "test": "bun test"
   },
   "dependencies": {
-    "@actiondock/core": "^2.0.11",
-    "@actiondock/sdk": "^2.0.11"
+    "@actiondock/core": "^2.0.12",
+    "@actiondock/sdk": "^2.0.12"
   },
   "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";