@kkeve/suite 0.0.13 → 0.0.17

package/dist/engine-cypress/agent-page.d.ts

@@ -0,0 +1,159 @@
+/**
+ * agent-page — Cypress 侧的 AgentPage 实现（CDP + 页内 agentDom）
+ *
+ * 与 Playwright 侧的 `page-agent/playwright-page.ts` 一一对应：同一个 Re-Act
+ * 循环吃同一份 `AgentPage` 契约，差异只在这层：
+ *   - DOM 读写全部经 CDP 在 AUT isolated world 内求值（绝不碰 runner 顶层页）
+ *   - 键盘/鼠标走 CDP Input 域，坐标需叠加 AUT iframe 在 runner 里的偏移
+ *   - 截图统一裁剪到 AUT iframe，元素截图在此基础上再按 boundingBox 裁一次
+ *
+ * 本模块零 Node 依赖，也不得 import '@playwright/test'（连类型都不需要）。
+ */
+import type { AgentBoundingBox, AgentKeyboard, AgentLocator, AgentMouse, AgentPage, AgentScreenshot } from '../page-agent/page-like.js';
+import { type Cdp } from './cdp.js';
+import { type PagePerformanceMetrics, type RawConsoleRecord, type RawNetworkRecord } from '../page-agent/diagnostics.js';
+/** 主世界诊断采集写入 DOM 的快照形态 */
+interface CypressDiagnosticsSnapshot {
+    browser?: RawConsoleRecord[];
+    network?: RawNetworkRecord[];
+    page?: PagePerformanceMetrics;
+}
+/**
+ * 合并多个 frame 的主世界诊断快照。
+ *
+ * 业务页面（如 kwaibi）可能把主要内容放在同源/跨域 iframe 内；单个 frame
+ * 的 dataset 只包含自己上下文里发生的 console/网络/性能事件，不能只看 AUT
+ * 顶层 frame。计数类网络/console 记录直接拼接，页面性能只有 longtask 是
+ * 可累加阻塞量，其余指标取各 frame 的最大值。
+ */
+export declare function mergeFrameDiagnostics(snaps: Array<CypressDiagnosticsSnapshot | undefined>): CypressDiagnosticsSnapshot | undefined;
+/** locator 链的一跳：与 agentDom.resolve() 的 op 结构一一对应 */
+type LocOp = {
+    t: 'css';
+    selector: string;
+} | {
+    t: 'ariaRef';
+    ref: string;
+} | {
+    t: 'text';
+    text: string;
+    exact: boolean;
+} | {
+    t: 'role';
+    role: string;
+    name?: string;
+    exact: boolean;
+} | {
+    t: 'filterHasText';
+    text: string;
+} | {
+    t: 'filterVisible';
+};
+export declare class CyAgentLocator implements AgentLocator {
+    private readonly page;
+    private readonly ops;
+    /** null = 集合本身（count/allInnerTexts 用全部）；数字 = 选中项，-1 = last */
+    private readonly index;
+    constructor(page: CyAgentPage, ops: LocOp[], 
+    /** null = 集合本身（count/allInnerTexts 用全部）；数字 = 选中项，-1 = last */
+    index?: number | null);
+    private extend;
+    private withIndex;
+    /** 集合语义的索引：null（未约束）在执行动作时按 Playwright 的「首个匹配」处理 */
+    private pickIndex;
+    private resolveExpr;
+    click(options?: any): Promise<void>;
+    dblclick(options?: any): Promise<void>;
+    fill(value: string, options?: any): Promise<void>;
+    hover(options?: any): Promise<void>;
+    pressSequentially(text: string, _options?: any): Promise<void>;
+    focus(): Promise<void>;
+    evaluate(fn: any, arg?: any): Promise<any>;
+    textContent(_options?: any): Promise<string | null>;
+    innerText(_options?: any): Promise<string>;
+    inputValue(_options?: any): Promise<string>;
+    isChecked(_options?: any): Promise<boolean>;
+    setChecked(checked: boolean, _options?: any): Promise<void>;
+    selectOption(values: any, _options?: any): Promise<any>;
+    waitFor(options?: any): Promise<void>;
+    boundingBox(_options?: any): Promise<AgentBoundingBox | null>;
+    getAttribute(name: string, _options?: any): Promise<string | null>;
+    count(): Promise<number>;
+    allInnerTexts(): Promise<string[]>;
+    isVisible(_options?: any): Promise<boolean>;
+    screenshot(_options?: any): Promise<AgentScreenshot>;
+    first(): AgentLocator;
+    last(): AgentLocator;
+    nth(index: number): AgentLocator;
+    filter(options?: any): AgentLocator;
+    locator(selector: string): AgentLocator;
+    /** 仅调试用：暴露定位链 */
+    toOps(): LocOp[];
+    /** 供 page.evaluate 之外的诊断使用 */
+    resolveHandleExpr(): string;
+}
+export declare class CyAgentPage implements AgentPage {
+    readonly cdp: Cdp;
+    private dialogHandler;
+    private dialogPreference;
+    private readonly listeners;
+    constructor(cdp: Cdp);
+    private ensureAgent;
+    /**
+     * 调用页内 `window.__keveAgent` 的某个方法。
+     *
+     * 刻意不走 `Runtime.callFunctionOn`：isolated world 里每次求值都是独立表达式，
+     * 用 JSON 组装调用最简单，且 agentDom 的入参全是可序列化的 ops/字面量。
+     */
+    callAgent<T = any>(method: string, args: any[], _options?: any): Promise<T>;
+    locator(selector: string): AgentLocator;
+    getByText(text: string, options?: any): AgentLocator;
+    getByRole(role: string, options?: any): AgentLocator;
+    ariaSnapshot(_options?: {
+        mode?: string;
+    }): Promise<string>;
+    url(): Promise<string>;
+    title(): Promise<string>;
+    goto(url: string, _options?: any): Promise<void>;
+    reload(_options?: any): Promise<void>;
+    evaluate(fn: any): Promise<any>;
+    /**
+     * 读取主世界诊断快照。
+     *
+     * Cypress 的 CDP 通道没有 domain event 订阅，主世界里的 console/网络采集
+     * 结果通过 `documentElement.dataset` 暴露给 isolated world —— 两个世界共享
+     * DOM，但不共享 JS 全局，这是唯一的稳定只读通道。
+     */
+    readDiagnosticsSnapshot(): Promise<CypressDiagnosticsSnapshot | undefined>;
+    screenshot(_options?: any): Promise<AgentScreenshot>;
+    viewportSize(): Promise<{
+        width: number;
+        height: number;
+    } | null>;
+    /** 调整 AUT iframe 尺寸（只改 runner 里的 iframe 盒子，不触碰被测页 DOM） */
+    setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    waitForTimeout(ms: number): Promise<void>;
+    /**
+     * Cypress 下拿不到 Playwright 的页面事件流（Cypress.automation 只暴露命令，
+     * 不暴露 CDP 事件订阅）。这里保留注册表，让 agent 的 setupPageListeners 不炸；
+     * dialog 由 `setDialogPreference` + 原生 dialog 自动处理兜底。
+     */
+    on(event: string, handler: (...args: any[]) => any): void;
+    /** 供未来事件桥接使用；当前仅保证接口存在 */
+    emit(event: string, ...args: any[]): void;
+    setDialogPreference(accept: boolean, promptText?: string): void;
+    private dispatchKey;
+    private parseKeyCombo;
+    private topLevelPoint;
+    readonly keyboard: AgentKeyboard;
+    /** 最近一次鼠标坐标（AUT 视口坐标），供 down/up 复用 */
+    private lastMouse;
+    readonly mouse: AgentMouse;
+    private createMouse;
+    dispose(): void;
+}
+export declare function createCyAgentPage(cdp: Cdp): CyAgentPage;
+export {};