pageqa 0.6.0 → 0.7.0

package/dist/replay.d.ts

@@ -0,0 +1,190 @@
+import { type BskOps } from "./bsk/tools.js";
+import { type Locator } from "./locator.js";
+import { type AssertionResult, type TestReport, type TokenUsage } from "./report.js";
+export declare const REPLAY_FORMAT = "pageqa-replay";
+export declare const REPLAY_VERSION = 1;
+/** 回放步骤的类型。`snapshot` 不在其中：它只服务于模型的「观察」，回放不需要。 */
+export type ReplayStepKind = "navigate" | "click" | "fill" | "upload" | "hover" | "scroll" | "wait" | "assert_text";
+/** 需要定位元素的步骤（click/hover/scroll 共用）。 */
+export interface ReplayTargetStep {
+    kind: "click" | "hover" | "scroll";
+    /** 尽力映射到的用例步骤号（1 起）；映射不到为 null。 */
+    step: number | null;
+    /** 录制时模型给出的 target（`@eN` 或 CSS）。 */
+    target: string;
+    /** 语义定位符；target 是 CSS 或快照中查不到时为 null。 */
+    locator: Locator | null;
+}
+export interface ReplayFillStep {
+    kind: "fill";
+    step: number | null;
+    target: string;
+    /** 填入值（已把运行时变量还原成占位符写法）。 */
+    value: string;
+    /** 占位符被还原时，记录录制当次真正填入的具体值，便于人工核对。 */
+    recordedValue?: string;
+    locator: Locator | null;
+}
+export interface ReplayUploadStep {
+    kind: "upload";
+    step: number | null;
+    file: string;
+    target?: string;
+    locator: Locator | null;
+}
+export interface ReplayNavigateStep {
+    kind: "navigate";
+    step: number | null;
+    url: string;
+}
+export interface ReplayWaitStep {
+    kind: "wait";
+    step: number | null;
+    ms: number;
+}
+export interface ReplayAssertStep {
+    kind: "assert_text";
+    step: number | null;
+    /** 断言期望（已把运行时变量还原成占位符写法）。 */
+    expectation: string;
+    /** 占位符被还原时，记录录制当次实际用的字面量。 */
+    recordedExpectation?: string;
+    /** 录制时该断言由 Jev 语义判断得出（字符串匹配可能误报，回放失败时会给出提示）。 */
+    semantic?: boolean;
+}
+export type ReplayStep = ReplayTargetStep | ReplayFillStep | ReplayUploadStep | ReplayNavigateStep | ReplayWaitStep | ReplayAssertStep;
+/** 一个场景的录制结果（套件模式下每个 `## 场景` 一条）。 */
+export interface ScenarioRecording {
+    name: string;
+    /** 用例原文步骤（忽略 `#`/`>` 行），用于把回放步骤映回「用例第 k 步」。 */
+    caseSteps: string[];
+    steps: ReplayStep[];
+}
+/** 回放脚本文件结构。 */
+export interface ReplayScript {
+    format: typeof REPLAY_FORMAT;
+    version: number;
+    recordedAt: string;
+    source: {
+        /** 源用例文件路径；内联文本时为 null。 */
+        path: string | null;
+        /** 源用例内容哈希，用于回放时提示「源用例已变更」。 */
+        hash: string | null;
+    };
+    scenarios: ReplayScenario[];
+}
+export interface ReplayScenario {
+    name: string;
+    caseSteps: string[];
+    steps: ReplayStep[];
+}
+/** 源用例内容哈希（sha256 前 16 位十六进制，够用且便于人眼比对）。 */
+export declare function scriptHash(text: string): string;
+/** 把录制结果组装成脚本对象（不含文件 IO，便于单测）。 */
+export declare function buildReplayScript(recordings: ScenarioRecording[], meta?: {
+    sourcePath?: string | null;
+    sourceText?: string | null;
+}): ReplayScript;
+/** 写入回放脚本文件（自动创建父目录）。 */
+export declare function writeReplayScript(path: string, script: ReplayScript): void;
+/** 读取并校验回放脚本文件；结构不合法时抛出可读错误（而不是回放中途才崩）。 */
+export declare function loadReplayScript(path: string): ReplayScript;
+/**
+ * 把脚本里**写死的录制取值**还原成占位符，返回实际发生的替换（供日志）。
+ *
+ * 为什么需要：`locator.name`（列表里点「刚创建的那条」）与 `caseSteps` 里都可能残留
+ * 录制当次的具体时间戳，回放时新时间戳对不上，这一步必然定位失败。
+ * 新录制的脚本已经不会再写死（录制时就还原了），但**旧脚本不必重跑 LLM 重录**——
+ * 脚本自己带着 `recorded*` 证据，加载时即可就地修好。
+ *
+ * 只改写已知会承载「动态名称」的字段：用例原文、定位符名、填入值、断言期望。
+ * 刻意不动 `file`（本地文件路径必须原样存在）与 `target`/`url`（可能是有意的字面量）。
+ */
+export declare function normalizePlaceholderLiterals(script: ReplayScript): string[];
+/**
+ * 检查源用例是否已变更：变更时返回提示文本（由调用方决定如何处理）。
+ * 只警告不失败——用例文案变了不代表页面行为变了，硬失败会天天误报。
+ */
+export declare function sourceDriftNotice(script: ReplayScript): string | null;
+export interface ReplayOptions {
+    session?: string;
+    /** 启用 Jev 语义断言（默认关闭，保证回放不调用任何模型）。 */
+    semantic?: boolean;
+    debug?: boolean;
+    /** 脚本路径，写进报告便于追溯。 */
+    scriptPath?: string;
+    /** 回放时刻，用于重新展开 `${...}` 占位符（同一次回放共用一个时刻）。 */
+    now?: Date;
+    /** 任一失败（含元素未找到）即停止该场景，不跑完剩余步骤。 */
+    failFast?: boolean;
+}
+export interface ReplayRunResult {
+    report: TestReport;
+    text: string;
+    json: string;
+    transcript: string;
+    usage: TokenUsage;
+}
+/**
+ * 当前页面里找不到要操作的元素。
+ *
+ * 单独区分出来，是因为它与「操作失败」不是一回事：元素不存在说明**当前页面状态下这一步不需要**
+ * ——最典型的是录制期模型顺手点的「取 消」这类补救/清理动作（提交后弹窗没关，模型点取消补一下），
+ * 回放时页面更顺利、弹窗早已关闭，那个按钮根本不存在。
+ * 这类步骤按「跳过」处理并继续，而不是让一条 65 步的长流程在第 12 步整条报废。
+ */
+export declare class LocatorMissError extends Error {
+}
+/**
+ * 场景结论：**任一断言不成立、任一失败步骤、或中途中止** → fail。
+ *
+ * 单独抽成纯函数是因为它曾经写错过一次：只统计「抛出的步骤失败」而漏掉
+ * 「断言返回不成立」，结果一条带 FAIL 断言的用例报了 PASS 与非零之外的退出码——
+ * 假通过比报错危险得多，这里用单测钉死。
+ * 跳过（元素未找到）不影响结论：页面真的退化时，后续步骤或断言会暴露出来。
+ */
+export declare function replayScenarioStatus(outcome: {
+    failed: number;
+    aborted: string | null;
+    assertions: AssertionResult[];
+}): "pass" | "fail";
+/** 单场景的步骤执行结果（纯执行结果，不含 session 生命周期与报告组装）。 */
+export interface ReplayStepOutcome {
+    trace: string[];
+    assertions: AssertionResult[];
+    outputs: string[];
+    /** 因「元素未找到」被跳过的步骤描述（不算失败，但必须让人看见）。 */
+    skipped: string[];
+    /** 已成功执行的最后一步序号。 */
+    executed: number;
+    /** 失败（不含跳过）的步骤数。 */
+    failed: number;
+    /** 中止时的步骤标签；未中止为 null。 */
+    aborted: string | null;
+}
+export interface ReplayStepOptions {
+    /** 展开 `${...}` 占位符。 */
+    expand: (text: string) => string;
+    /** 本次回放是否启用了 Jev 语义断言。 */
+    jevActive: boolean;
+    /** 任一失败即停止该场景（默认关：跑完才能给出完整健康报告）。 */
+    failFast?: boolean;
+    /** 单步重试次数（默认 3）。 */
+    attempts?: number;
+}
+/**
+ * 按顺序执行一个场景的全部步骤（不碰 session 生命周期，便于单测）。
+ *
+ * 失败语义：
+ * - **元素未找到** → 记为「跳过」并继续。这是「当前页面状态下这一步不需要」，
+ *   而非页面退化的证据；真正的退化会由后续步骤或断言暴露出来。
+ * - **其它失败**（元素找到了但操作报错、断言不成立）→ 记为失败并继续，跑完给出全貌。
+ * - **navigate 失败** → 后续步骤已无意义，直接中止。
+ * 失败一律不会被吞掉：都会变成报告里的一条 FAIL 断言 + 非零退出码。
+ */
+export declare function executeReplaySteps(ops: BskOps, scenario: ReplayScenario, opts: ReplayStepOptions): Promise<ReplayStepOutcome>;
+/**
+ * 回放整个脚本：单场景按单份报告输出；多场景逐个回放（各自独立 session/窗口）并汇总，
+ * 汇总语义与 `--suite` 一致——任一场景失败则整体失败、退出码非零。
+ */
+export declare function runReplayScript(script: ReplayScript, opts?: ReplayOptions): Promise<ReplayRunResult>;