@yule-h2o/web_auto_flow 0.0.5

package/README.md

@@ -0,0 +1,156 @@
+# H2O Auto Flow
+
+> Playwright + Stagehand AI — 端到端自动化测试框架
+
+写脚本像写普通代码，填表/点击用原生 API（零成本），找不到选择器时让 AI 接管（按需付费）。
+
+```ts
+import { definePlan, runPlan, isMain } from "h2o-auto-flow";
+
+const plan = definePlan("登录测试", async ({ page, has, click, fill, screenshot, sleep }) => {
+  await page.goto("https://example.com/login");
+  await sleep(2000);
+
+  await fill('input[type="email"]', "test@test.com");
+  await fill('input[type="password"]', "123456");
+  await click('[type="submit"]');
+  await sleep(3000);
+
+  if (await has(".dashboard")) {
+    await screenshot("登录成功");
+  }
+});
+
+if (isMain(import.meta.url)) await runPlan(plan);
+export default plan;
+```
+
+## 安装
+
+```bash
+# npm
+npm i h2o-auto-flow
+# pnpm
+pnpm add h2o-auto-flow
+```
+
+## 配置
+
+创建 `h2o.config.ts`（可选，也可以只用环境变量）：
+
+```ts
+import { defineConfig } from "h2o-auto-flow";
+
+export default defineConfig({
+  ai: {
+    apiKey: "sk-xxx",
+    model: "deepseek/deepseek-v4-flash",
+  },
+  output: {
+    dir: "./test-logs",         // 日志/截图/报告 输出目录，默认 ./logs
+  },
+  browser: {
+    headless: false,            // 默认 false
+    viewport: { width: 1280, height: 720 },
+  },
+});
+```
+
+没有配置文件时，自动从环境变量取值：`DEEPSEEK_API_KEY`、`OPENAI_API_KEY`、`AI_MODEL`。
+
+## API
+
+### 核心方法
+
+```ts
+definePlan("测试名", async ({ page, ...ctx }) => {
+  // ...
+});
+```
+
+| 方法                            | 说明                | 示例                                      |
+| ----------------------------- | ----------------- | --------------------------------------- |
+| `has(sel)` → `boolean`        | 元素是否在页面上          | `if (await has(".btn"))`                |
+| `which(selectors)` → `number` | 一组选择器哪个存在，返回索引    | `await which([".a", ".b", ".c"])`       |
+| `click(sel, nth?)`            | 点击第一个(或第 n 个)可见元素 | `await click(".btn")`                   |
+| `fill(sel, val)`              | 填充输入框             | `await fill("input", "hello")`          |
+| `screenshot(label)`           | 截图，自动编号           | `await screenshot("首页")`                |
+| `sleep(ms)`                   | 等待                | `await sleep(2000)`                     |
+| `wait(sel, timeout?)`         | 等待元素出现            | `await wait(".modal")`                  |
+| `ai(instruction)`             | AI 交互 + 异常检测      | `await ai("click the continue button")` |
+
+### 进阶
+
+| 方法                             | 说明                                                             |
+| ------------------------------ | -------------------------------------------------------------- |
+| `check(name)`                  | 链式断言：`.element().text().url().performance()`                   |
+| `network()`                    | 抓包：`net.filter("/api/").assertCall("/api/x", { status: 200 })` |
+| `task(label, fn, aiFallback?)` | 原生优先，失败切 AI 兜底                                                 |
+
+### `check()` 断言链
+
+```ts
+await check("登录页校验")
+  .element("input", { minCount: 2 })
+  .text(".title", "欢迎", { ignoreCase: true })
+  .url("/dashboard")
+  .performance("FCP", { lt: 3000 });
+```
+
+### `task()` 成本优先
+
+```ts
+// 纯原生
+await task("填表", () => page.locator("input").fill("test"));
+
+// 原生失败 → AI 兜底
+await task(
+  "选择体态",
+  () => page.locator(".body-type").first().click(),
+  "select the first body type option",
+);
+```
+
+### 抓包
+
+```ts
+const net = network();                          // 必须在 page.goto 之前
+await page.goto("https://example.com");
+
+net.filter("/api/login");
+net.assertCall("/api/login", { status: 200 });
+net.assertCall("/api/user", {
+  bodySchema: { id: "number", name: "string" },
+});
+```
+
+## 常用交互模式
+
+```ts
+// 条件点击
+if (await has(".continue-btn")) await click(".continue-btn");
+
+// 等元素出现再点击
+await wait(".modal");
+await click(".modal .confirm");
+
+// 多个选择器模糊匹配
+const idx = await which([".card-a", ".card-b", ".card-c"]);
+if (idx !== -1) await click([".card-a", ".card-b", ".card-c"][idx]);
+```
+
+## 报告
+
+每次运行生成 `logs/run-{时间戳}/`:
+
+```
+run-2026-06-18T18-30-05/
+├── chrome-profile/     # 浏览器 Profile
+├── screenshots/        # 截图（自动编号）
+├── report.json         # 结构化数据
+└── report.html         # 可视化（截图可点击放大，← → 切换）
+```
+
+## License
+
+MIT

package/dist/core/ai-engine/AITest.d.ts

@@ -0,0 +1,27 @@
+import type { PageLike, AIAssertionResult, AIResult, AIEngineOptions, QualityOptions, AnomalyOptions } from "./types";
+import { LLMClient } from "./llm-client";
+export declare class AITest {
+    readonly name: string;
+    private tasks;
+    private stagehand;
+    private llm;
+    private options;
+    constructor(name: string, options: AIEngineOptions);
+    /** 自然语言交互：AI 自动找元素并操作（填充/点击/选择等） */
+    act(instruction: string): this;
+    /** 结构化提取：从页面元素提取数据并校验 Schema */
+    extract(selector: string, schema: Record<string, string>, instruction?: string): this;
+    /** 情感断言：判断文本情感是否符合预期 */
+    assertSentiment(selector: string, expected: "positive" | "negative" | "neutral", criteria?: string): this;
+    /** 内容质量断言：检查长度、关键词、语气、禁用词等 */
+    assertQuality(selector: string, opts: QualityOptions): this;
+    /** 异常检测：检查页面是否处于错误/空白/加载失败等非预期状态 */
+    detectAnomaly(opts?: AnomalyOptions): this;
+    /** 自定义断言 */
+    assertCustom(label: string, fn: (page: PageLike, llm: LLMClient, stagehand: any) => Promise<Omit<AIAssertionResult, "type">>): this;
+    run(page: PageLike): Promise<AIResult>;
+}
+/**
+ * 快捷工厂函数
+ */
+export declare function ai(name: string, options: AIEngineOptions): AITest;

package/dist/core/ai-engine/assertions/anomaly.d.ts

@@ -0,0 +1,6 @@
+import type { PageLike, AnomalyOptions, AIAssertionResult } from "../types";
+import type { LLMClient } from "../llm-client";
+/**
+ * 全局异常检测 — 检查页面是否处于错误/空白/加载失败等非预期状态
+ */
+export declare function assertAnomaly(page: PageLike, llm: LLMClient, options?: AnomalyOptions): Promise<AIAssertionResult>;

package/dist/core/ai-engine/assertions/extraction.d.ts

@@ -0,0 +1,6 @@
+import type { PageLike, ExtractionOptions, AIAssertionResult } from "../types";
+import type { LLMClient } from "../llm-client";
+/**
+ * 从页面元素中提取结构化数据，并校验是否符合 Schema
+ */
+export declare function assertExtraction(page: PageLike, llm: LLMClient, selector: string, options: ExtractionOptions): Promise<AIAssertionResult>;

package/dist/core/ai-engine/assertions/quality.d.ts

@@ -0,0 +1,6 @@
+import type { PageLike, QualityOptions, AIAssertionResult } from "../types";
+import type { LLMClient } from "../llm-client";
+/**
+ * 断言页面内容质量（长度、关键词、语气、禁用词）
+ */
+export declare function assertQuality(page: PageLike, llm: LLMClient, selector: string, options: QualityOptions): Promise<AIAssertionResult>;

package/dist/core/ai-engine/assertions/sentiment.d.ts

@@ -0,0 +1,6 @@
+import type { PageLike, SentimentOptions, AIAssertionResult } from "../types";
+import type { LLMClient } from "../llm-client";
+/**
+ * 断言页面元素的文本情感倾向
+ */
+export declare function assertSentiment(page: PageLike, llm: LLMClient, selector: string, options: SentimentOptions): Promise<AIAssertionResult>;

package/dist/core/ai-engine/llm-client.d.ts

@@ -0,0 +1,24 @@
+import type { LLMConfig, ChatMessage, ChatResponse } from "./types";
+/**
+ * 简易 OpenAI 兼容 LLM 客户端
+ *
+ * 支持 DeepSeek、OpenAI、及任何 OpenAI 兼容 API。
+ * 自动从模型名推断 endpoint 和 API Key。
+ */
+export declare class LLMClient {
+    private config;
+    private totalTokens;
+    constructor(config: LLMConfig);
+    /** 获取累计 token 消耗 */
+    getTotalTokens(): number;
+    /** 发送 Chat Completion 请求 */
+    chat(messages: ChatMessage[]): Promise<ChatResponse>;
+    /** 单轮对话快捷方法 */
+    complete(systemPrompt: string, userMessage: string): Promise<ChatResponse>;
+    /** 判断类快捷方法 — 返回布尔值 */
+    judge(systemPrompt: string, userMessage: string, expectedAnswer?: string): Promise<{
+        passed: boolean;
+        reason: string;
+        raw: string;
+    }>;
+}

package/dist/core/ai-engine/prompts.d.ts

@@ -0,0 +1,3 @@
+export declare const SENTIMENT_PROMPT = "You are a sentiment analyzer for UI testing. Given a piece of UI text, classify its emotional tone.\n\nCategories:\n- positive: encouraging, friendly, warm, optimistic, praising, welcoming\n- negative: angry, frustrated, blaming, cold, dismissive, alarming\n- neutral: factual, informational, neutral instructions\n\nReply with ONLY one word: \"positive\", \"negative\", or \"neutral\". Then a brief reason.";
+export declare const EXTRACTION_PROMPT = "You are a data extraction tool for UI testing. Extract structured information from the given HTML or text content.\n\nRules:\n- Return ONLY valid JSON, no markdown, no explanation\n- Use the exact field names provided in the schema\n- If a field cannot be found, use null\n- For numbers, return the numeric value (not strings)";
+export declare const ANOMALY_PROMPT = "You are an anomaly detector for UI testing. Analyze the given page content and determine if the page is in an error or unexpected state.\n\nAnomalies to detect:\n- Blank/white page with no meaningful content\n- Error messages (e.g., \"500 Internal Server Error\", \"Something went wrong\", \"Page not found\")\n- Loading failures (e.g., infinite spinner, \"Loading...\" stuck forever)\n- Broken elements (e.g., missing images, unstyled content)\n- Unexpected redirects to error pages\n\nReply with ONLY \"YES\" if an anomaly is detected, or \"NO\" if the page looks normal.\nThen a brief reason.";

package/dist/core/ai-engine/types.d.ts

@@ -0,0 +1,102 @@
+import type { PageLike } from "../../core/rule-engine/types";
+export type { PageLike };
+export interface LLMConfig {
+    /** 模型标识，如 "deepseek/deepseek-v4-flash" 或 "openai/gpt-4o-mini" */
+    model: string;
+    /** API Base URL，默认 DeepSeek: https://api.deepseek.com/v1 */
+    baseURL?: string;
+    /** API Key */
+    apiKey?: string;
+    /** 温度 0-2，默认 0.1（测试场景需要确定性） */
+    temperature?: number;
+    /** 最大输出 token */
+    maxTokens?: number;
+    /** 请求超时 (ms) */
+    timeout?: number;
+}
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export interface ChatResponse {
+    content: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+export interface SentimentOptions {
+    /** 期望情感: positive / negative / neutral */
+    expected: "positive" | "negative" | "neutral";
+    /** 自定义判断标准 */
+    criteria?: string;
+    /** 超时 (ms) */
+    timeout?: number;
+}
+export interface ExtractionOptions {
+    /** JSON Schema 约束输出格式 */
+    schema: Record<string, string>;
+    /** 提取指令 */
+    instruction?: string;
+    timeout?: number;
+}
+export interface QualityOptions {
+    /** 最低文本长度 */
+    minLength?: number;
+    /** 必须包含关键词 */
+    containsKeywords?: string[];
+    /** 期望语气 */
+    tone?: "professional" | "friendly" | "casual" | "urgent";
+    /** 不允许包含的词 */
+    forbiddenWords?: string[];
+    /** 是否检查拼写/语法 */
+    checkGrammar?: boolean;
+    timeout?: number;
+}
+export interface AnomalyOptions {
+    /** 是否检查空白页 */
+    checkBlank?: boolean;
+    /** 是否检查错误消息 */
+    checkError?: boolean;
+    /** 是否检查加载失败 */
+    checkLoading?: boolean;
+    timeout?: number;
+}
+export type AIAssertionType = "act" | "extract" | "sentiment" | "quality" | "anomaly" | "custom";
+export interface AIAssertionTask {
+    type: AIAssertionType;
+    name: string;
+    execute: (page: PageLike, stagehand: any) => Promise<AIAssertionResult>;
+}
+export interface AIAssertionResult {
+    passed: boolean;
+    type: AIAssertionType;
+    name: string;
+    message: string;
+    duration: number;
+    details?: string;
+    /** LLM 原始响应 */
+    rawResponse?: string;
+    /** 失败截图 base64 */
+    screenshot?: string;
+}
+export interface AIResult {
+    name: string;
+    assertions: AIAssertionResult[];
+    hasFailure: boolean;
+    passRate: number;
+    totalDuration: number;
+    /** 估算的 token 消耗 */
+    estimatedTokens: number;
+}
+export interface AIEngineOptions {
+    /** Stagehand 实例（用于 act/extract） */
+    stagehand: any;
+    /** LLM 客户端配置（用于 sentiment/quality/anomaly） */
+    llm?: LLMConfig;
+    /** 失败时截图 */
+    screenshotOnFailure?: boolean;
+    /** 首个断言失败即停 */
+    bailOnFailure?: boolean;
+}

package/dist/core/rule-engine/RuleTest.d.ts

@@ -0,0 +1,36 @@
+import type { PageLike, AssertionResult, RuleResult, RuleEngineOptions, ElementAssertionOptions, TextAssertionOptions, AttributeAssertionOptions, NavigationAssertionOptions, NetworkAssertionOptions, PerformanceAssertionOptions, AccessibilityAssertionOptions } from "./types";
+import type { PerfMetric } from "./assertions/performance";
+export declare class RuleTest {
+    readonly name: string;
+    private tasks;
+    private options;
+    constructor(name: string, options?: RuleEngineOptions);
+    /** 断言元素存在性/可见性/可编辑性/数量 */
+    assertElement(selector: string, opts?: ElementAssertionOptions): this;
+    /** 断言元素文本内容 */
+    assertText(selector: string, expected: string | RegExp, opts?: TextAssertionOptions): this;
+    /** 断言元素 HTML 属性值 */
+    assertAttribute(selector: string, attribute: string, expected: string | RegExp, opts?: AttributeAssertionOptions): this;
+    /** 断言当前页面 URL */
+    assertUrl(expected: string | RegExp, opts?: NavigationAssertionOptions): this;
+    /** 断言页面 <title> */
+    assertTitle(expected: string | RegExp, opts?: NavigationAssertionOptions): this;
+    /** 断言页面 <meta> 标签 */
+    assertMeta(metaName: string, expected: string | RegExp, opts?: NavigationAssertionOptions): this;
+    /** 断言 HTTP 状态码（可附加响应体/响应头校验） */
+    assertStatusCode(urlOrPattern: string | RegExp, expectedStatus: number, opts?: NetworkAssertionOptions): this;
+    /** 断言 Web 性能指标 */
+    assertPerformance(metric: PerfMetric, opts?: PerformanceAssertionOptions, customValue?: number): this;
+    /** 断言可访问性（alt / label / role / 对比度） */
+    assertAccessibility(selector: string, opts?: AccessibilityAssertionOptions): this;
+    /** 自定义断言：传入任意异步校验函数 */
+    assertCustom(label: string, fn: (page: PageLike) => Promise<Omit<AssertionResult, "type">>): this;
+    /**
+     * 运行全部断言，返回结果
+     */
+    run(page: PageLike): Promise<RuleResult>;
+}
+/**
+ * 快捷工厂函数
+ */
+export declare function rule(name: string, options?: RuleEngineOptions): RuleTest;

package/dist/core/rule-engine/assertions/accessibility.d.ts

@@ -0,0 +1,9 @@
+import type { PageLike, AccessibilityAssertionOptions, AssertionResult } from "../types";
+/**
+ * 断言元素的可访问性：
+ * - 图片是否有 alt 文本
+ * - 表单控件是否有关联 label
+ * - ARIA role 是否正确
+ * - 颜色对比度（基础检查）
+ */
+export declare function assertAccessibility(page: PageLike, selector: string, options?: AccessibilityAssertionOptions): Promise<AssertionResult>;

package/dist/core/rule-engine/assertions/content.d.ts

@@ -0,0 +1,9 @@
+import type { PageLike, TextAssertionOptions, AttributeAssertionOptions, AssertionResult } from "../types";
+/**
+ * 断言元素的文本内容
+ */
+export declare function assertText(page: PageLike, selector: string, expected: string | RegExp, options?: TextAssertionOptions): Promise<AssertionResult>;
+/**
+ * 断言元素的 HTML 属性值
+ */
+export declare function assertAttribute(page: PageLike, selector: string, attribute: string, expected: string | RegExp, _options?: AttributeAssertionOptions): Promise<AssertionResult>;

package/dist/core/rule-engine/assertions/element.d.ts

@@ -0,0 +1,2 @@
+import type { PageLike, ElementAssertionOptions, AssertionResult } from "../types";
+export declare function assertElement(page: PageLike, selector: string, options?: ElementAssertionOptions): Promise<AssertionResult>;

package/dist/core/rule-engine/assertions/navigation.d.ts

@@ -0,0 +1,13 @@
+import type { PageLike, NavigationAssertionOptions, AssertionResult } from "../types";
+/**
+ * 断⾔当前页面 URL
+ */
+export declare function assertUrl(page: PageLike, expected: string | RegExp, options?: NavigationAssertionOptions): Promise<AssertionResult>;
+/**
+ * 断言页面标题
+ */
+export declare function assertTitle(page: PageLike, expected: string | RegExp, _options?: NavigationAssertionOptions): Promise<AssertionResult>;
+/**
+ * 断言页面 <meta> 标签内容
+ */
+export declare function assertMeta(page: PageLike, metaName: string, expected: string | RegExp, _options?: NavigationAssertionOptions): Promise<AssertionResult>;

package/dist/core/rule-engine/assertions/network.d.ts

@@ -0,0 +1,9 @@
+import type { PageLike, NetworkAssertionOptions, AssertionResult } from "../types";
+/**
+ * 断言某个请求的 HTTP 状态码
+ *
+ * 支持两种模式：
+ * 1. 等待模式：传入 url 字符串，拦截匹配的请求并验证
+ * 2. 被动模式：若已通过其他方式捕获 response，可直接传入验证
+ */
+export declare function assertStatusCode(page: PageLike, urlOrPattern: string | RegExp, expectedStatus: number, options?: NetworkAssertionOptions): Promise<AssertionResult>;

package/dist/core/rule-engine/assertions/performance.d.ts

@@ -0,0 +1,11 @@
+import type { PageLike, PerformanceAssertionOptions, AssertionResult } from "../types";
+/**
+ * Web Vitals 指标名称
+ */
+export type PerfMetric = "FCP" | "LCP" | "TTI" | "CLS" | "TBT" | "FID" | "load" | "dns" | "tls" | "ttfb" | "dom" | "custom";
+/**
+ * 从页面提取 Web Vitals 指标（基于 Performance API）
+ */
+export declare function assertPerformance(page: PageLike, metric: PerfMetric, options?: PerformanceAssertionOptions, 
+/** 自定义指标时传入具体数值 */
+customValue?: number): Promise<AssertionResult>;

package/dist/core/rule-engine/selectors.d.ts

@@ -0,0 +1,17 @@
+import type { PageLike, LocatorLike } from "./types";
+/**
+ * 标准化选择器：对常见简写做展开，确保跨浏览器兼容。
+ * - `#id` 保持不变
+ * - `.class` 保持不变
+ * - `tag` 保持不变
+ * - 含空格的复合选择器保持不变
+ */
+export declare function normalizeSelector(selector: string): string;
+/**
+ * 生成描述性的选择器标签（用于报告）
+ */
+export declare function selectorLabel(selector: string): string;
+/**
+ * 安全获取 locator，捕获 Playwright 语法错误
+ */
+export declare function safeLocator(page: PageLike, selector: string): LocatorLike;

package/dist/core/rule-engine/types.d.ts

@@ -0,0 +1,208 @@
+/** 最小化 FrameLocator 接口，用于操作 iframe 内部元素 */
+export interface FrameLocatorLike {
+    locator(selector: string): LocatorLike;
+    frameLocator(selector: string): FrameLocatorLike;
+}
+/** 最小化 Page 接口，兼容 Playwright / Stagehand 的 page 对象 */
+export interface PageLike {
+    url(): string;
+    title(): Promise<string>;
+    locator(selector: string): LocatorLike;
+    frameLocator(selector: string): FrameLocatorLike;
+    waitForURL(url: string | RegExp, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    waitForTimeout(ms: number): Promise<void>;
+    waitForResponse(urlOrPredicate: string | RegExp | ((response: ResponseLike) => boolean), options?: {
+        timeout?: number;
+    }): Promise<ResponseLike>;
+    goto(url: string, options?: {
+        waitUntil?: string;
+        timeout?: number;
+    }): Promise<ResponseLike | null>;
+    evaluate<T>(fn: string | ((...args: any[]) => T), arg?: any): Promise<T>;
+    screenshot(options?: {
+        path?: string;
+        fullPage?: boolean;
+    }): Promise<Buffer>;
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    keyboard: {
+        press(key: string): Promise<void>;
+        type(text: string, options?: {
+            delay?: number;
+        }): Promise<void>;
+    };
+    mouse: {
+        click(x: number, y: number): Promise<void>;
+    };
+}
+export interface LocatorLike {
+    count(): Promise<number>;
+    first(): LocatorLike;
+    nth(index: number): LocatorLike;
+    isVisible(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    isHidden(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    isEnabled(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    isDisabled(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    isEditable(options?: {
+        timeout?: number;
+    }): Promise<boolean>;
+    textContent(options?: {
+        timeout?: number;
+    }): Promise<string | null>;
+    innerText(options?: {
+        timeout?: number;
+    }): Promise<string>;
+    getAttribute(name: string, options?: {
+        timeout?: number;
+    }): Promise<string | null>;
+    inputValue(options?: {
+        timeout?: number;
+    }): Promise<string>;
+    click(options?: {
+        timeout?: number;
+    }): Promise<void>;
+    fill(value: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    waitFor(options?: {
+        state?: "visible" | "hidden" | "attached" | "detached";
+        timeout?: number;
+    }): Promise<void>;
+    evaluate<T>(fn: (el: any) => T): Promise<T>;
+    screenshot(options?: {
+        path?: string;
+    }): Promise<Buffer>;
+}
+export interface ResponseLike {
+    url(): string;
+    status(): number;
+    headers(): Record<string, string>;
+    json<T = any>(): Promise<T>;
+    text(): Promise<string>;
+}
+export interface ElementAssertionOptions {
+    /** 元素必须可见 */
+    visible?: boolean;
+    /** 元素必须隐藏 */
+    hidden?: boolean;
+    /** 元素必须可编辑（input/textarea 等） */
+    editable?: boolean;
+    /** 元素必须启用 */
+    enabled?: boolean;
+    /** 元素必须禁用 */
+    disabled?: boolean;
+    /** 精确数量 */
+    count?: number;
+    /** 最小数量 */
+    minCount?: number;
+    /** 最大数量 */
+    maxCount?: number;
+    /** 等待超时 (ms) */
+    timeout?: number;
+}
+export interface TextAssertionOptions {
+    /** 精确匹配（默认） */
+    exact?: boolean;
+    /** 正则匹配 */
+    regex?: boolean;
+    /** 忽略大小写 */
+    ignoreCase?: boolean;
+    /** 是否使用 innerText（默认 textContent） */
+    useInnerText?: boolean;
+    /** 等待超时 (ms) */
+    timeout?: number;
+}
+export interface AttributeAssertionOptions {
+    timeout?: number;
+}
+export interface NavigationAssertionOptions {
+    /** 检查 URL 前需要执行的操作（选择器或动作描述） */
+    after?: string;
+    /** 超时 */
+    timeout?: number;
+}
+export interface NetworkAssertionOptions {
+    /** 等待响应超时 */
+    timeout?: number;
+    /** 验证响应体 JSON Schema */
+    schema?: Record<string, any>;
+    /** 验证响应头 */
+    headers?: Record<string, string>;
+    /** 验证响应体包含文本 */
+    contains?: string;
+}
+export interface PerformanceAssertionOptions {
+    /** 小于 (ms) */
+    lt?: number;
+    /** 小于等于 (ms) */
+    lte?: number;
+    /** 大于 (ms) */
+    gt?: number;
+    /** 大于等于 (ms) */
+    gte?: number;
+    /** 介于 [min, max] */
+    between?: [number, number];
+}
+export interface AccessibilityAssertionOptions {
+    /** 必须包含 alt 文本 */
+    altText?: string | RegExp;
+    /** 必须有对应的 label */
+    hasLabel?: boolean;
+    /** 颜色对比度最低要求 (1-21, 默认 4.5) */
+    minContrast?: number;
+    /** 检查 ARIA role */
+    role?: string;
+    /** 超时 */
+    timeout?: number;
+}
+export type AssertionType = "element" | "text" | "attribute" | "navigation" | "network" | "performance" | "accessibility" | "custom";
+export interface AssertionTask {
+    type: AssertionType;
+    name: string;
+    execute: (page: PageLike) => Promise<AssertionResult>;
+}
+export interface AssertionResult {
+    passed: boolean;
+    type: AssertionType;
+    name: string;
+    message: string;
+    duration: number;
+    /** 失败时附加的上下文信息 */
+    details?: string;
+    /** 失败截图 base64 */
+    screenshot?: string;
+}
+export interface RuleResult {
+    /** 测试名称 */
+    name: string;
+    /** 全部断言结果 */
+    assertions: AssertionResult[];
+    /** 是否有失败项 */
+    hasFailure: boolean;
+    /** 通过率 0-1 */
+    passRate: number;
+    /** 总耗时 (ms) */
+    totalDuration: number;
+}
+export interface RuleEngineOptions {
+    /** 全局超时 (ms)，默认 10000 */
+    timeout?: number;
+    /** 失败时自动截图，默认 true */
+    screenshotOnFailure?: boolean;
+    /** 首个断言失败后是否继续，默认 false */
+    bailOnFailure?: boolean;
+    /** 失败重试次数，默认 0 */
+    retryCount?: number;
+}