miaoda-game-devkit 0.4.0 → 0.6.0

package/README.md

@@ -7,20 +7,31 @@
 - React 游戏的生产/手动时钟、Strict Mode 安全 Controller ownership、JSDOM
   Vitest 配置和自动收集运行错误的 Testing Library setup，分别从 `miaoda-game-devkit/react`、
   `miaoda-game-devkit/react/testing` 和 `miaoda-game-devkit/react/vitest-config` 导入；
-- React 的 `playthroughTest` 与项目级 reporter 自动验证独立的 entry/primary DOM
-  输入、有界推进、结果断言及至少两次有序 checkpoint 签到；聚焦运行只提示未检查，
+- React 的 `playthroughTest` 与项目级 reporter 自动验证连续的 enter/milestone/finish
+  玩法阶段、真实 DOM 输入或确定性推进、有界结果、结果断言和阶段状态变化；聚焦运行只提示未检查，
   完整运行缺少有效流程时失败；
 
-`playthroughTest` 的主流程回调从参数接收 `user`、`performInput`、`checkpoint`、
-`stepUntil` 和绑定当前测试的 `expect`。按 entry 输入、`checkpoint("entered")`、primary 输入、
-有界等待、使用回调提供的 `expect` 断言权威结果、
-`checkpoint("progress")` 或 `checkpoint("terminal")` 的顺序记录最低证据。每条流程至少需要
-这两次 checkpoint；checkpoint 只负责签到，不携带或验证状态。大型游戏仍只保留一条最短关键流程；
-分支、关卡规则和恢复清理由专门测试覆盖。不要再次调用 `userEvent.setup()`。
+`playthroughTest` 的主流程回调只需要编排 `enter`、至少三个唯一命名的 `milestone` 和
+`finish`。`enter` 必须声明真实输入 `act`；后续阶段声明 `act` 或确定性 `step`。每个阶段还要
+提供初始为 false 的有界 `until`，以及使用 test-bound `expect` 的 `assert`。DevKit 在验证阶段
+前后 DOM 或权威 `observe` 状态确实变化后自动提交阶段证据。每个 `milestone` 使用非空且
+唯一的领域名称，表示一段独立的玩法进展。`finish.kind` 对有限结果使用 `terminal`，对无尽或
+沙盒游戏的有意义进展使用 `progress`。大型游戏保留一条最短关键流程；分支、关卡规则和恢复
+清理由专门测试覆盖。不要再次调用 `userEvent.setup()`。
+Playthrough 测试始终以非并发任务运行，且只统计当前阶段 `act` 执行窗口内的输入事件，避免
+同一 JSDOM 中其他测试或后台事件污染玩法证据。
 时间、帧或自定义 scheduler 流程必须显式传入确定性 `step`；精确物理时间、暂停恢复
 或调度清理测试可使用 `ManualGameClock`。Canvas/Controller 流程在 `playthroughTest` 上声明一次
 `observe`，返回 JSON 可序列化的权威 Telemetry 状态；框架自动比较流程状态并复用为超时诊断。
 
+失败的 production playthrough 会额外输出一条有界 `TRACE:`：记录已完成 milestone、当前阶段、
+阶段前后可观测状态与推进步数。通过流程不输出 TRACE，避免增加
+常规 CI 噪声。显式启用 Vitest retry 时，每次尝试会重置证据，最终报告只展示最后一次尝试的
+CAUSE 与 TRACE；repeat 同样为每轮建立新证据。测试超时或取消会中止后续有界推进，并通过
+Vitest 的 test-local failure hook 在 worker 最终同步前保留活动阶段；若测试主体已完成、随后由
+`afterEach` 或运行时错误判失败，reporter 仍会从 task metadata 恢复这条流程证据。状态优先来自 `observe`，没有 Telemetry 时才使用有界 DOM
+摘要；不要把 TRACE 当作新的断言或第二份业务状态。
+
 Vitest 的 fake timers（包括 `vi.advanceTimersToNextFrame()`）适合在 devkit 自身的
 专门 scheduler 合约中使用，但不在所有 production playthrough 中全局启用；React
 Testing Library 的 `asyncWrapper` 和 user-event 内部 timer 会因此互相影响。使用自定义
@@ -85,8 +96,9 @@ Phaser 4 模板对应使用 `miaoda-phaser-game-lint`。命令类型不通过依
 开发工具包自行维护并精确固定 Vitest 等工具版本，从自身依赖中解析可执行文件，使用方不需要重复声明
 Biome、Oxlint 或 tsgo。仓库中保留稳定的命令入口，因此 `dist/` 尚未生成时，pnpm
 也能正确建立命令链接；工作区开发状态下由 Nx 在模板检查前构建开发工具包，发布包则
-直接携带运行时 `dist/`。打包消费者契约会验证固定 Vitest 版本以及 reporter 的通过、聚焦和
-缺失流程行为。开发工具包内部的 `*.test.*` 与构建后的 `*.contract.mjs` 都不会
+直接携带运行时 `dist/`。打包消费者契约会验证固定 Vitest 版本以及 reporter 的通过、聚焦、
+缺失流程、retry 失败诊断和 hook 失败诊断行为。开发工具包内部的 `*.test.*` 与构建后的
+`*.contract.mjs` 都不会
 进入 npm 包；这些契约只由 devkit 自己的测试目标执行。
 
 monorepo 中的模板可以放置只包含 `extends: ["miaoda-game-devkit/biome"]` 的薄配置，

package/dist/react/testing.d.mts

@@ -33,112 +33,97 @@ interface StepUntilOptions {
      * The value is sampled only when the bound is exhausted.
      */
     diagnostics?: () => unknown;
+    /** 测试超时或运行取消时停止继续推进，通常由 playthroughTest 自动传入。 */
+    signal?: AbortSignal;
 }
 
+type ReactPlaythroughStageKind = "entered" | "milestone" | "progress" | "terminal";
+/** 一段已完成玩法留下的可序列化证据。 */
+interface ReactPlaythroughStageEvidence {
+    name: string;
+    kind: ReactPlaythroughStageKind;
+    domInputEvents: number;
+    advancedSteps: number;
+    assertions: number;
+    stateChanged: boolean;
+    before: string;
+    after: string;
+}
 /** 单条 React 主流程测试留下的可序列化运行期证据。 */
 interface ReactPlaythroughEvidence {
-    /** 捕获阶段观察到的键盘、指针或触摸类 DOM 输入总数。 */
     domInputEvents: number;
-    /** 由 performInput 明确标记的入口输入次数。 */
-    entryInputs: number;
-    /** 由 performInput 明确标记的核心玩法输入次数。 */
-    primaryInputs: number;
-    /** 在步数上限内成功满足条件的 stepUntil 次数。 */
-    boundedRuns: number;
-    /** 最后一次 stepUntil 成功后新增的 Vitest 断言数。 */
-    assertionsAfterOutcome: number;
-    /** 已记录的 checkpoint 类型，供 reporter 给出精确提示。 */
-    checkpoints: ReactPlaythroughCheckpointKind[];
-    /** helper 是否已经完成全部证据校验。 */
+    stages: ReactPlaythroughStageEvidence[];
     verified: boolean;
 }
 /** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
 interface ReactPlaythroughMetadata {
-    /** metadata 结构版本，用于拒绝无法识别的旧数据。 */
-    version: 3;
-    /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
+    version: 4;
     waiverReason?: string;
-    /** 测试执行期间持续更新的客观证据。 */
+    trace?: string;
     evidence: ReactPlaythroughEvidence;
 }
-
-/** 玩家输入在最低可玩流程中的语义阶段。 */
-type ReactPlaythroughInputKind = "entry" | "primary";
-/** 可审计流程签到；entered 是入口，progress/terminal 是有效结果。 */
-type ReactPlaythroughCheckpointKind = "entered" | "progress" | "terminal";
-/** Canvas/Controller flows declare one authoritative read; simple DOM flows omit it. */
 interface ReactPlaythroughOptions {
-    /** Stable, JSON-serializable production state sampled across the audited flow. */
+    /** Canvas/Controller flows expose one stable authoritative production read. */
     observe: () => unknown;
 }
-/** 主流程回调唯一需要学习的测试工具。 */
+interface ReactPlaythroughAssertContext {
+    expect: ExpectStatic;
+    user: UserEvent;
+    view: RenderResult;
+}
+interface ReactPlaythroughStageShared {
+    until: () => boolean;
+    assert: (context: ReactPlaythroughAssertContext) => void | Promise<void>;
+    maxSteps?: number;
+    diagnostics?: () => unknown;
+}
+type ReactPlaythroughInteractiveStage = ReactPlaythroughStageShared & {
+    act: () => void | Promise<void>;
+    step?: StepUntilOptions["step"];
+};
+type ReactPlaythroughAutonomousStage = ReactPlaythroughStageShared & {
+    act?: never;
+    step: NonNullable<StepUntilOptions["step"]>;
+};
+type ReactPlaythroughStage = ReactPlaythroughInteractiveStage | ReactPlaythroughAutonomousStage;
+/** 合法入口必须由真实生产 DOM 输入驱动，不能用自动 step 代替。 */
+type ReactPlaythroughEnterStage = ReactPlaythroughInteractiveStage;
+type ReactPlaythroughFinishStage = ReactPlaythroughStage & {
+    kind: "progress" | "terminal";
+};
+/** 游戏作者只编排进入、领域里程碑和最终结果。 */
 interface ReactPlaythroughArguments {
-    /** Testing Library 对生产游戏入口的渲染结果。 */
     view: RenderResult;
-    /** 已由 playthroughTest 创建的真实 DOM 用户输入驱动。 */
     user: UserEvent;
-    /** Vitest 绑定到当前 test 的断言 API；结果断言必须使用这个实例。 */
-    expect: ExpectStatic;
-    /**
-     * 包裹一段真实 DOM 输入并声明用途。
-     * entry 用于进入合法游戏状态，primary 用于移动、挥拍、拖拽、落子等核心操作。
-     */
-    performInput(kind: ReactPlaythroughInputKind, input: () => void | Promise<void>): Promise<void>;
-    /**
-     * 记录流程签到。先在 entry 后记录 entered，再在 primary、stepUntil 和
-     * 结果断言后记录 progress 或 terminal。
-     */
-    checkpoint(kind: ReactPlaythroughCheckpointKind): void;
-    /**
-     * 在硬性步数上限内等待权威结果。
-     * 返回后必须再断言该结果，进入中间 active/running 状态不算完成。
-     * 即时结果不需要 step；时间、帧或自定义 scheduler 流程必须传入确定性 step。
-     */
-    stepUntil(condition: () => boolean, options?: StepUntilOptions): Promise<number>;
+    enter(stage: ReactPlaythroughEnterStage): Promise<void>;
+    milestone(name: string, stage: ReactPlaythroughStage): Promise<void>;
+    finish(name: string, stage: ReactPlaythroughFinishStage): Promise<void>;
 }
-/** 使用方编写的生产玩法步骤；既支持同步游戏，也支持异步 DOM 输入。 */
 type ReactPlaythroughRun = (arguments_: ReactPlaythroughArguments) => void | Promise<void>;
-/** 低配置主流程测试函数及其结构化豁免入口。 */
 interface ReactPlaythroughTest {
-    /** 渲染生产入口并声明一条最低可玩主流程。 */
     (element: ReactNode, run: ReactPlaythroughRun): void;
-    /** Use one authoritative observer when gameplay results live outside the DOM. */
     (element: ReactNode, options: ReactPlaythroughOptions, run: ReactPlaythroughRun): void;
-    /** 仅允许带充分理由地豁免确实没有玩家输入的项目。 */
-    skip(reason: string, element: ReactNode, run: ReactPlaythroughRun): void;
+    skip(reason: string, element: ReactNode): void;
 }
 /** reporter 从单个 Vitest TestCase 提取出的稳定审计输入。 */
 interface ReactPlaythroughAuditInput {
-    /** 包含 describe 层级的完整测试名，仅用于诊断输出。 */
     name: string;
-    /** Vitest 报告的最终执行状态。 */
     state: "passed" | "failed" | "skipped" | "pending";
-    /** 只有 playthroughTest 声明的测试才具备该字段。 */
     metadata?: ReactPlaythroughMetadata;
 }
-/** 整次 Vitest 运行的最低可玩性审计结果。 */
 interface ReactPlaythroughAuditResult {
-    /** 是否满足有效主流程或有效豁免。 */
     passed: boolean;
-    /** 是否依靠显式非交互理由通过，而非执行了主流程。 */
     waived: boolean;
-    /** 可直接指导模型补测的稳定问题列表。 */
     issues: string[];
 }
 /** React 游戏测试的最低可玩主流程入口。 */
 declare const playthroughTest: ReactPlaythroughTest;
-/**
- * 供 Vitest reporter 与确定性契约测试共用的纯审计函数。
- *
- * 它只验证客观流程证据，不能理解任意游戏的胜负语义；具体结果仍由
- * 使用方在 stepUntil 返回后通过权威状态或玩家可见结果断言。
- */
+/** 供 Vitest reporter 与确定性契约测试共用的纯审计函数。 */
 declare function auditReactPlaythroughRun(tests: ReactPlaythroughAuditInput[]): ReactPlaythroughAuditResult;
 declare module "vitest" {
     interface TaskMeta {
-        /** 供 ReactPlaythroughReporter 汇总的可序列化主流程证据。 */
         reactPlaythrough?: ReactPlaythroughMetadata;
     }
 }
 
-export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughCheckpointKind, type ReactPlaythroughEvidence, type ReactPlaythroughInputKind, type ReactPlaythroughMetadata, type ReactPlaythroughOptions, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };
+export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAssertContext, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughAutonomousStage, type ReactPlaythroughEnterStage, type ReactPlaythroughEvidence, type ReactPlaythroughFinishStage, type ReactPlaythroughInteractiveStage, type ReactPlaythroughMetadata, type ReactPlaythroughOptions, type ReactPlaythroughStage, type ReactPlaythroughStageEvidence, type ReactPlaythroughStageKind, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };

package/dist/react/testing.d.ts

@@ -33,112 +33,97 @@ interface StepUntilOptions {
      * The value is sampled only when the bound is exhausted.
      */
     diagnostics?: () => unknown;
+    /** 测试超时或运行取消时停止继续推进，通常由 playthroughTest 自动传入。 */
+    signal?: AbortSignal;
 }
 
+type ReactPlaythroughStageKind = "entered" | "milestone" | "progress" | "terminal";
+/** 一段已完成玩法留下的可序列化证据。 */
+interface ReactPlaythroughStageEvidence {
+    name: string;
+    kind: ReactPlaythroughStageKind;
+    domInputEvents: number;
+    advancedSteps: number;
+    assertions: number;
+    stateChanged: boolean;
+    before: string;
+    after: string;
+}
 /** 单条 React 主流程测试留下的可序列化运行期证据。 */
 interface ReactPlaythroughEvidence {
-    /** 捕获阶段观察到的键盘、指针或触摸类 DOM 输入总数。 */
     domInputEvents: number;
-    /** 由 performInput 明确标记的入口输入次数。 */
-    entryInputs: number;
-    /** 由 performInput 明确标记的核心玩法输入次数。 */
-    primaryInputs: number;
-    /** 在步数上限内成功满足条件的 stepUntil 次数。 */
-    boundedRuns: number;
-    /** 最后一次 stepUntil 成功后新增的 Vitest 断言数。 */
-    assertionsAfterOutcome: number;
-    /** 已记录的 checkpoint 类型，供 reporter 给出精确提示。 */
-    checkpoints: ReactPlaythroughCheckpointKind[];
-    /** helper 是否已经完成全部证据校验。 */
+    stages: ReactPlaythroughStageEvidence[];
     verified: boolean;
 }
 /** 通过 Vitest task metadata 从 worker 传递给主线程 reporter 的数据。 */
 interface ReactPlaythroughMetadata {
-    /** metadata 结构版本，用于拒绝无法识别的旧数据。 */
-    version: 3;
-    /** 静态、非交互项目跳过主流程验证时必须提供的理由。 */
+    version: 4;
     waiverReason?: string;
-    /** 测试执行期间持续更新的客观证据。 */
+    trace?: string;
     evidence: ReactPlaythroughEvidence;
 }
-
-/** 玩家输入在最低可玩流程中的语义阶段。 */
-type ReactPlaythroughInputKind = "entry" | "primary";
-/** 可审计流程签到；entered 是入口，progress/terminal 是有效结果。 */
-type ReactPlaythroughCheckpointKind = "entered" | "progress" | "terminal";
-/** Canvas/Controller flows declare one authoritative read; simple DOM flows omit it. */
 interface ReactPlaythroughOptions {
-    /** Stable, JSON-serializable production state sampled across the audited flow. */
+    /** Canvas/Controller flows expose one stable authoritative production read. */
     observe: () => unknown;
 }
-/** 主流程回调唯一需要学习的测试工具。 */
+interface ReactPlaythroughAssertContext {
+    expect: ExpectStatic;
+    user: UserEvent;
+    view: RenderResult;
+}
+interface ReactPlaythroughStageShared {
+    until: () => boolean;
+    assert: (context: ReactPlaythroughAssertContext) => void | Promise<void>;
+    maxSteps?: number;
+    diagnostics?: () => unknown;
+}
+type ReactPlaythroughInteractiveStage = ReactPlaythroughStageShared & {
+    act: () => void | Promise<void>;
+    step?: StepUntilOptions["step"];
+};
+type ReactPlaythroughAutonomousStage = ReactPlaythroughStageShared & {
+    act?: never;
+    step: NonNullable<StepUntilOptions["step"]>;
+};
+type ReactPlaythroughStage = ReactPlaythroughInteractiveStage | ReactPlaythroughAutonomousStage;
+/** 合法入口必须由真实生产 DOM 输入驱动，不能用自动 step 代替。 */
+type ReactPlaythroughEnterStage = ReactPlaythroughInteractiveStage;
+type ReactPlaythroughFinishStage = ReactPlaythroughStage & {
+    kind: "progress" | "terminal";
+};
+/** 游戏作者只编排进入、领域里程碑和最终结果。 */
 interface ReactPlaythroughArguments {
-    /** Testing Library 对生产游戏入口的渲染结果。 */
     view: RenderResult;
-    /** 已由 playthroughTest 创建的真实 DOM 用户输入驱动。 */
     user: UserEvent;
-    /** Vitest 绑定到当前 test 的断言 API；结果断言必须使用这个实例。 */
-    expect: ExpectStatic;
-    /**
-     * 包裹一段真实 DOM 输入并声明用途。
-     * entry 用于进入合法游戏状态，primary 用于移动、挥拍、拖拽、落子等核心操作。
-     */
-    performInput(kind: ReactPlaythroughInputKind, input: () => void | Promise<void>): Promise<void>;
-    /**
-     * 记录流程签到。先在 entry 后记录 entered，再在 primary、stepUntil 和
-     * 结果断言后记录 progress 或 terminal。
-     */
-    checkpoint(kind: ReactPlaythroughCheckpointKind): void;
-    /**
-     * 在硬性步数上限内等待权威结果。
-     * 返回后必须再断言该结果，进入中间 active/running 状态不算完成。
-     * 即时结果不需要 step；时间、帧或自定义 scheduler 流程必须传入确定性 step。
-     */
-    stepUntil(condition: () => boolean, options?: StepUntilOptions): Promise<number>;
+    enter(stage: ReactPlaythroughEnterStage): Promise<void>;
+    milestone(name: string, stage: ReactPlaythroughStage): Promise<void>;
+    finish(name: string, stage: ReactPlaythroughFinishStage): Promise<void>;
 }
-/** 使用方编写的生产玩法步骤；既支持同步游戏，也支持异步 DOM 输入。 */
 type ReactPlaythroughRun = (arguments_: ReactPlaythroughArguments) => void | Promise<void>;
-/** 低配置主流程测试函数及其结构化豁免入口。 */
 interface ReactPlaythroughTest {
-    /** 渲染生产入口并声明一条最低可玩主流程。 */
     (element: ReactNode, run: ReactPlaythroughRun): void;
-    /** Use one authoritative observer when gameplay results live outside the DOM. */
     (element: ReactNode, options: ReactPlaythroughOptions, run: ReactPlaythroughRun): void;
-    /** 仅允许带充分理由地豁免确实没有玩家输入的项目。 */
-    skip(reason: string, element: ReactNode, run: ReactPlaythroughRun): void;
+    skip(reason: string, element: ReactNode): void;
 }
 /** reporter 从单个 Vitest TestCase 提取出的稳定审计输入。 */
 interface ReactPlaythroughAuditInput {
-    /** 包含 describe 层级的完整测试名，仅用于诊断输出。 */
     name: string;
-    /** Vitest 报告的最终执行状态。 */
     state: "passed" | "failed" | "skipped" | "pending";
-    /** 只有 playthroughTest 声明的测试才具备该字段。 */
     metadata?: ReactPlaythroughMetadata;
 }
-/** 整次 Vitest 运行的最低可玩性审计结果。 */
 interface ReactPlaythroughAuditResult {
-    /** 是否满足有效主流程或有效豁免。 */
     passed: boolean;
-    /** 是否依靠显式非交互理由通过，而非执行了主流程。 */
     waived: boolean;
-    /** 可直接指导模型补测的稳定问题列表。 */
     issues: string[];
 }
 /** React 游戏测试的最低可玩主流程入口。 */
 declare const playthroughTest: ReactPlaythroughTest;
-/**
- * 供 Vitest reporter 与确定性契约测试共用的纯审计函数。
- *
- * 它只验证客观流程证据，不能理解任意游戏的胜负语义；具体结果仍由
- * 使用方在 stepUntil 返回后通过权威状态或玩家可见结果断言。
- */
+/** 供 Vitest reporter 与确定性契约测试共用的纯审计函数。 */
 declare function auditReactPlaythroughRun(tests: ReactPlaythroughAuditInput[]): ReactPlaythroughAuditResult;
 declare module "vitest" {
     interface TaskMeta {
-        /** 供 ReactPlaythroughReporter 汇总的可序列化主流程证据。 */
         reactPlaythrough?: ReactPlaythroughMetadata;
     }
 }
 
-export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughCheckpointKind, type ReactPlaythroughEvidence, type ReactPlaythroughInputKind, type ReactPlaythroughMetadata, type ReactPlaythroughOptions, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };
+export { ManualGameClock, type ReactPlaythroughArguments, type ReactPlaythroughAssertContext, type ReactPlaythroughAuditInput, type ReactPlaythroughAuditResult, type ReactPlaythroughAutonomousStage, type ReactPlaythroughEnterStage, type ReactPlaythroughEvidence, type ReactPlaythroughFinishStage, type ReactPlaythroughInteractiveStage, type ReactPlaythroughMetadata, type ReactPlaythroughOptions, type ReactPlaythroughStage, type ReactPlaythroughStageEvidence, type ReactPlaythroughStageKind, type ReactPlaythroughTest, type StepUntilOptions, auditReactPlaythroughRun, playthroughTest };