@kkeve/suite 0.0.15 → 0.0.18

package/dist/engine-cypress/shotBuffer.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * shotBuffer — 截图对比结果的 goal 级缓冲（浏览器侧）
+ *
+ * core/screenshotDiff.ts 是 Node 模块（依赖 fs），不能被打进 Cypress 的浏览器
+ * bundle。但结构必须一致：keveGoal 要把本 goal 内所有对比结果（matched /
+ * baseline_required / exceeded）写进 attachment 的 screenshotDiff 字段。
+ * 这里只做「暂存 + 取出」，真正的对比在 Node 侧经 bridge 完成。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CypressScreenshotDiffError = void 0;
+exports.beginGoalShotDiffCapture = beginGoalShotDiffCapture;
+exports.isGoalShotDiffCaptureActive = isGoalShotDiffCaptureActive;
+exports.drainGoalShotDiff = drainGoalShotDiff;
+exports.recordShotDiff = recordShotDiff;
+/** 与 Playwright 的 ScreenshotDiffError 同形：带 shotDiff 结构，keveGoal 据此短路 */
+class CypressScreenshotDiffError extends Error {
+    shotDiff;
+    constructor(result) {
+        super(result.message);
+        this.name = 'ScreenshotDiffError';
+        this.shotDiff = result;
+    }
+}
+exports.CypressScreenshotDiffError = CypressScreenshotDiffError;
+let buffer = null;
+function beginGoalShotDiffCapture() {
+    buffer = [];
+}
+function isGoalShotDiffCaptureActive() {
+    return buffer !== null;
+}
+function drainGoalShotDiff() {
+    const out = buffer || [];
+    buffer = null;
+    return out;
+}
+function recordShotDiff(result) {
+    if (buffer)
+        buffer.push(result);
+}

package/dist/engine-cypress/state.d.ts

@@ -0,0 +1,56 @@
+/**
+ * state — Cypress spec 内的「当前用例」执行状态（浏览器侧）
+ *
+ * Cypress 没有 Playwright 那样的 fixture 作用域，装饰器宿主、keveGoal、
+ * 报告收集三者需要共享同一份状态。这里用模块级单例承载，
+ * 由 host.ts 在 beforeEach 里重置、在测试体收口时读取。
+ *
+ * 约束：零依赖（会被打进 Cypress 浏览器 bundle）。
+ */
+/** 与 Playwright 附件同形的内存附件（body 为 JSON 字符串） */
+export interface CyAttachment {
+    name: string;
+    contentType: string;
+    body: string;
+}
+export interface CyTestState {
+    /** 用例完整标题（`${id}: ${description}`），报告匹配的规范键 */
+    title: string;
+    /** spec 文件路径（仅展示用） */
+    file: string;
+    /** 当前用例的附件集合（keveGoalResult 等） */
+    attachments: CyAttachment[];
+    /** 当前用例的执行日志（对齐 Playwright 侧 test-results.json 的 stdout 字段） */
+    logs: string[];
+    /** 应用侧未捕获异常（由 Cypress uncaught:exception 事件收集） */
+    uncaughtErrors: string[];
+    /** keveGoal 在当前用例内的序号 */
+    goalOrder: number;
+    /** 是否被 skip（前置条件不满足 → blocked，不是 fail） */
+    skipReason: string;
+}
+export declare function beginTestState(title: string, file?: string): CyTestState;
+export declare function getTestState(): CyTestState | null;
+/** 取当前状态；不在用例内时抛出可诊断的错误 */
+export declare function requireTestState(): CyTestState;
+export declare function endTestState(): CyTestState | null;
+export declare function addAttachment(att: CyAttachment): void;
+/** 记录应用侧未捕获异常（Cypress uncaught:exception 事件） */
+export declare function addUncaughtError(message: string): void;
+/**
+ * 记录一行执行日志。
+ *
+ * Cypress spec 跑在浏览器里，console.log 不会进入 Node 侧进程输出，
+ * 因此 Playwright 那份 stdout 轨迹在 Cypress 下会缺失。这里显式收集，
+ * 由 reporter 随结果一起送回 Node，保证两端报告同构。
+ */
+export declare function addLog(line: string): void;
+export declare function nextGoalOrder(): number;
+/**
+ * 把 JSON 文本编码成 base64。
+ *
+ * 必须这么做：Playwright 的 JSON reporter 会把 attachment 的 Buffer body 序列化成
+ * base64 字符串，reportData.ts 也是无条件按 base64 解码。Cypress 侧直接写明文 JSON
+ * 会导致报告里的 keveGoalResult 解析不出来（截图与步骤全丢）。
+ */
+export declare function encodeAttachmentBody(json: string): string;

package/dist/engine-cypress/state.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * state — Cypress spec 内的「当前用例」执行状态（浏览器侧）
+ *
+ * Cypress 没有 Playwright 那样的 fixture 作用域，装饰器宿主、keveGoal、
+ * 报告收集三者需要共享同一份状态。这里用模块级单例承载，
+ * 由 host.ts 在 beforeEach 里重置、在测试体收口时读取。
+ *
+ * 约束：零依赖（会被打进 Cypress 浏览器 bundle）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.beginTestState = beginTestState;
+exports.getTestState = getTestState;
+exports.requireTestState = requireTestState;
+exports.endTestState = endTestState;
+exports.addAttachment = addAttachment;
+exports.addUncaughtError = addUncaughtError;
+exports.addLog = addLog;
+exports.nextGoalOrder = nextGoalOrder;
+exports.encodeAttachmentBody = encodeAttachmentBody;
+let current = null;
+function beginTestState(title, file = '') {
+    current = { title, file, attachments: [], logs: [], uncaughtErrors: [], goalOrder: 0, skipReason: '' };
+    return current;
+}
+function getTestState() {
+    return current;
+}
+/** 取当前状态；不在用例内时抛出可诊断的错误 */
+function requireTestState() {
+    if (!current) {
+        throw new Error('[keve] 当前不在用例执行上下文中：keveGoal 必须在 @keveScene 方法体内调用');
+    }
+    return current;
+}
+function endTestState() {
+    const out = current;
+    current = null;
+    return out;
+}
+function addAttachment(att) {
+    requireTestState().attachments.push(att);
+}
+/** 记录应用侧未捕获异常（Cypress uncaught:exception 事件） */
+function addUncaughtError(message) {
+    const state = getTestState();
+    if (!state)
+        return;
+    state.uncaughtErrors.push(message);
+}
+/**
+ * 记录一行执行日志。
+ *
+ * Cypress spec 跑在浏览器里，console.log 不会进入 Node 侧进程输出，
+ * 因此 Playwright 那份 stdout 轨迹在 Cypress 下会缺失。这里显式收集，
+ * 由 reporter 随结果一起送回 Node，保证两端报告同构。
+ */
+function addLog(line) {
+    const state = getTestState();
+    if (!state)
+        return;
+    state.logs.push(line.endsWith('\n') ? line : `${line}\n`);
+}
+function nextGoalOrder() {
+    const state = requireTestState();
+    return state.goalOrder++;
+}
+/**
+ * 把 JSON 文本编码成 base64。
+ *
+ * 必须这么做：Playwright 的 JSON reporter 会把 attachment 的 Buffer body 序列化成
+ * base64 字符串，reportData.ts 也是无条件按 base64 解码。Cypress 侧直接写明文 JSON
+ * 会导致报告里的 keveGoalResult 解析不出来（截图与步骤全丢）。
+ */
+function encodeAttachmentBody(json) {
+    const bytes = new TextEncoder().encode(json);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += 1)
+        binary += String.fromCharCode(bytes[i]);
+    return btoa(binary);
+}

package/dist/engine-playwright/engineAdapter.d.ts

@@ -0,0 +1,78 @@
+/**
+ * engineAdapter — 引擎无关操作接口 + Playwright 实现
+ *
+ * 所有测试脚本通过 engine.* 调用操作，不直接使用 page.locator / page.click。
+ * 未来可替换为其他引擎实现（如 WebDriver）。
+ */
+import type { Page } from '@playwright/test';
+import { type ExpectScreenshotOptions, type ShotDiffResult } from '../core/judge/screenshotDiff.js';
+import type { ElementRef, ElementEntry, DefinedPage } from '../core/page-object/definePage.js';
+import type { EngineAdapter, WaitForResponseOptions, WaitForResponseResult } from '../core/page-object/engine-types.js';
+export type { EngineAdapter, WaitForResponseOptions, WaitForResponseResult } from '../core/page-object/engine-types.js';
+export { KEVE_ENV, resolvePageUrl } from '../core/page-object/engine-types.js';
+export declare class PlaywrightEngine implements EngineAdapter {
+    private page;
+    constructor(page: Page);
+    navigate(url: string): Promise<void>;
+    openPage(page: DefinedPage, overrides?: Record<string, string>): Promise<void>;
+    callScene(sceneId: string, keveGoal?: unknown): Promise<void>;
+    waitForReady(defPage: DefinedPage): Promise<void>;
+    /**
+     * 等待指定响应 —— 配置型视觉对比场景的「就绪门」。
+     *
+     * 与 waitForReady.api 的差异：不需要 DefinedPage（配置型场景没有页面对象），
+     * 并且能拿到响应体做渲染健康断言（老平台 interceptUrl 的 statuses 语义）。
+     * 默认**软等待**（超时不阻塞，与老平台 cy.wait 后继续的容错一致），required=true 时硬失败。
+     */
+    waitForResponse(urlPart: string | RegExp, opts?: WaitForResponseOptions): Promise<WaitForResponseResult>;
+    private resolve;
+    click(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    dblClick(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    forceClick(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    clear(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    drag(source: ElementRef | ElementEntry, target: ElementRef | ElementEntry): Promise<void>;
+    scroll(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    wait(ms: number): Promise<void>;
+    waitForElement(selector: string, opts?: {
+        timeout?: number;
+        visible?: boolean;
+    }): Promise<{
+        found: boolean;
+    }>;
+    refresh(): Promise<void>;
+    evaluate(expression: string): Promise<any>;
+    screenshot(name: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectScreenshot(key: string, opts?: ExpectScreenshotOptions, ...refs: (ElementRef | ElementEntry)[]): Promise<ShotDiffResult>;
+    type(text: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    hover(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    text(...refs: (ElementRef | ElementEntry)[]): Promise<string>;
+    expectVisible(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectHidden(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectText(expected: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectNotText(expected: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectTextEquals(expected: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectTextNotEquals(expected: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectCount(count: number, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectNonEmptyCount(count: number, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectExists(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectNotExists(...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectClass(className: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectNotClass(className: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectAttribute(attr: string, value: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectAttributeContains(attr: string, value: string, ...refs: (ElementRef | ElementEntry)[]): Promise<void>;
+    expectUrlContains(part: string): Promise<void>;
+    expectUrlNotContains(part: string): Promise<void>;
+    expectUrlEquals(url: string): Promise<void>;
+    expectUrlNotEquals(url: string): Promise<void>;
+    expectTitle(part: string): Promise<void>;
+    expectTitleEquals(title: string): Promise<void>;
+    rawPage(): Page;
+    ariaSnapshot(options?: {
+        mode?: string;
+    }): Promise<string>;
+    injectCookies(cookies: any[]): Promise<void>;
+}
+/**
+ * 从 Playwright page 创建 engine 实例
+ */
+export declare function createEngine(page: Page): EngineAdapter;

package/dist/engine-playwright/engineAdapter.js

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * engineAdapter — 引擎无关操作接口 + Playwright 实现
+ *
+ * 所有测试脚本通过 engine.* 调用操作，不直接使用 page.locator / page.click。
+ * 未来可替换为其他引擎实现（如 WebDriver）。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlaywrightEngine = exports.resolvePageUrl = exports.KEVE_ENV = void 0;
+exports.createEngine = createEngine;
+const test_1 = require("@playwright/test");
+const elementResolver_js_1 = require("../core/page-object/elementResolver.js");
+const screenshotDiff_js_1 = require("../core/judge/screenshotDiff.js");
+const definePage_js_1 = require("../core/page-object/definePage.js");
+const engine_types_js_1 = require("../core/page-object/engine-types.js");
+var engine_types_js_2 = require("../core/page-object/engine-types.js");
+Object.defineProperty(exports, "KEVE_ENV", { enumerable: true, get: function () { return engine_types_js_2.KEVE_ENV; } });
+Object.defineProperty(exports, "resolvePageUrl", { enumerable: true, get: function () { return engine_types_js_2.resolvePageUrl; } });
+// ─── Playwright Engine Implementation ─────────────────────────────────
+class PlaywrightEngine {
+    page;
+    constructor(page) {
+        this.page = page;
+    }
+    async navigate(url) {
+        await this.page.goto(url, { waitUntil: 'domcontentloaded' });
+    }
+    async openPage(page, overrides) {
+        await this.navigate((0, engine_types_js_1.resolvePageUrl)(page, overrides));
+    }
+    async callScene(sceneId, keveGoal) {
+        const { sceneImplMap } = await Promise.resolve().then(() => __importStar(require('../core/decorator/keve-registry.js')));
+        const fn = sceneImplMap.get(String(sceneId));
+        if (!fn) {
+            throw new Error(`callScene: 场景 '${sceneId}' 未注册（可能被排除或不存在）`);
+        }
+        await fn({ engine: this, keveGoal });
+    }
+    async waitForReady(defPage) {
+        const { waitForReady } = defPage;
+        if (!waitForReady)
+            return;
+        // 等待 API
+        if (waitForReady.api) {
+            await this.page.waitForResponse((resp) => resp.url().includes(waitForReady.api), { timeout: 15000 }).catch(() => {
+                // API 等待失败不阻塞，继续等 UI
+            });
+        }
+        // 等待 UI 元素
+        if (waitForReady.ui) {
+            const entry = defPage.elements[waitForReady.ui];
+            if (entry && !(0, definePage_js_1.isElementFactory)(entry)) {
+                const locator = (0, elementResolver_js_1.resolveElement)(this.page, entry);
+                await locator.waitFor({ state: 'visible', timeout: 10000 });
+            }
+        }
+    }
+    /**
+     * 等待指定响应 —— 配置型视觉对比场景的「就绪门」。
+     *
+     * 与 waitForReady.api 的差异：不需要 DefinedPage（配置型场景没有页面对象），
+     * 并且能拿到响应体做渲染健康断言（老平台 interceptUrl 的 statuses 语义）。
+     * 默认**软等待**（超时不阻塞，与老平台 cy.wait 后继续的容错一致），required=true 时硬失败。
+     */
+    async waitForResponse(urlPart, opts = {}) {
+        const timeout = opts.timeout ?? 15000;
+        const started = Date.now();
+        const miss = { hit: false, url: '', status: 0, body: null, elapsedMs: 0 };
+        try {
+            const resp = await this.page.waitForResponse((r) => {
+                const urlOk = typeof urlPart === 'string' ? r.url().includes(urlPart) : urlPart.test(r.url());
+                if (!urlOk)
+                    return false;
+                if (opts.method && r.request().method().toUpperCase() !== opts.method.toUpperCase())
+                    return false;
+                if (opts.status?.length && !opts.status.includes(r.status()))
+                    return false;
+                return true;
+            }, { timeout });
+            let body = null;
+            try {
+                const text = await resp.text();
+                if (text && text.length <= 2_000_000) {
+                    try {
+                        body = JSON.parse(text);
+                    }
+                    catch {
+                        body = text;
+                    }
+                }
+            }
+            catch { /* 响应体不可读（重定向/流）不影响就绪判定 */ }
+            if (opts.afterMs && opts.afterMs > 0)
+                await this.page.waitForTimeout(opts.afterMs);
+            return { hit: true, url: resp.url(), status: resp.status(), body, elapsedMs: Date.now() - started };
+        }
+        catch (err) {
+            if (opts.required) {
+                throw new Error(`waitForResponse 超时（${timeout}ms）：未等到匹配「${String(urlPart)}」的响应 —— ${err?.message || err}`);
+            }
+            console.warn(`[engine.waitForResponse] 软等待超时（${timeout}ms），继续执行：${String(urlPart)}`);
+            return { ...miss, elapsedMs: Date.now() - started };
+        }
+    }
+    resolve(refs) {
+        // 规范化：工厂函数需要已调用，这里不做工厂调用
+        const normalized = refs.map((r) => {
+            if ((0, definePage_js_1.isElementFactory)(r)) {
+                throw new Error('Factory function must be called before passing to engine. e.g. engine.click(page.elements.itemByName("时间"))');
+            }
+            return r;
+        });
+        return (0, elementResolver_js_1.resolveChain)(this.page, ...normalized);
+    }
+    async click(...refs) {
+        const locator = this.resolve(refs);
+        await locator.first().click();
+    }
+    async dblClick(...refs) {
+        const locator = this.resolve(refs);
+        await locator.first().dblclick();
+    }
+    async forceClick(...refs) {
+        const locator = this.resolve(refs);
+        await locator.first().click({ force: true });
+    }
+    async clear(...refs) {
+        const locator = this.resolve(refs);
+        await locator.first().fill('');
+    }
+    async drag(source, target) {
+        const src = this.resolve([source]).first();
+        const dst = this.resolve([target]).first();
+        await src.dragTo(dst);
+    }
+    async scroll(...refs) {
+        if (refs.length === 0) {
+            await this.page.mouse.wheel(0, 600);
+            return;
+        }
+        const locator = this.resolve(refs);
+        await locator.first().scrollIntoViewIfNeeded();
+    }
+    async wait(ms) {
+        await this.page.waitForTimeout(Math.max(0, Number(ms) || 0));
+    }
+    async waitForElement(selector, opts = {}) {
+        const timeout = opts.timeout ?? 10000;
+        const state = opts.visible === false ? 'hidden' : 'visible';
+        try {
+            await this.page.locator(selector).first().waitFor({ state, timeout });
+            return { found: true };
+        }
+        catch {
+            return { found: false };
+        }
+    }
+    async refresh() {
+        await this.page.reload({ waitUntil: 'domcontentloaded' });
+    }
+    async evaluate(expression) {
+        // 平台 WRITE_GLOBAL 的 javascript hop 是表达式形态（如 'UI自动化看板'+new Date().getTime()）
+        return await this.page.evaluate(`(() => (${expression}))()`);
+    }
+    async screenshot(name, ...refs) {
+        await this.expectScreenshot(name, {}, ...refs);
+    }
+    async expectScreenshot(key, opts = {}, ...refs) {
+        const { test: pwTest } = await Promise.resolve().then(() => __importStar(require('@playwright/test')));
+        // keveGoal 未开缓冲时（如探索/调试直调），就地开一个临时缓冲，保证结果也能入 attachment
+        const owned = !(0, screenshotDiff_js_1.isGoalShotDiffCaptureActive)();
+        if (owned)
+            (0, screenshotDiff_js_1.beginGoalShotDiffCapture)();
+        try {
+            const buf = refs.length > 0
+                ? await this.resolve(refs).first().screenshot()
+                : await this.page.screenshot({ fullPage: !!opts.fullPage });
+            // 统一走 compareWithBaseline：其内部按 key+env 判定
+            //  - 精确视口无基线、同 key 也无其它视口基线 → 建候选基线（status=baseline_required，不算通过）
+            //  - 同 key 有其它视口基线 → size_mismatch（尺寸变化不自举，杜绝掩盖变化）
+            //  - 候选基线未审核 → baseline_required（不比对不判通过）
+            //  - active 基线 → 像素比对（matched / exceeded，超阈值抛 ScreenshotDiffError）
+            const result = (0, screenshotDiff_js_1.compareWithBaseline)(key, buf, { threshold: opts.threshold, mask: opts.mask });
+            // 记录已下沉至 screenshotDiff 模块（成功路径 + 抛错路径均自动记录）
+            // 原始截图仍挂附件（证据双保险：报告附件 + test-artifacts 路径）；
+            // 测试上下文外（独立验证脚本）test.info() 会抛错 —— 对比功能不受影响，仅跳过附件
+            try {
+                await pwTest.info()?.attach(`screenshot-${key}`, { body: buf, contentType: 'image/png' });
+            }
+            catch { /* 非测试上下文：跳过附件 */ }
+            return result;
+        }
+        finally {
+            if (owned)
+                (0, screenshotDiff_js_1.drainGoalShotDiff)();
+        }
+    }
+    async type(text, ...refs) {
+        const locator = this.resolve(refs);
+        await locator.first().fill(text);
+    }
+    async hover(...refs) {
+        const locator = this.resolve(refs);
+        await locator.first().hover();
+    }
+    async text(...refs) {
+        const locator = this.resolve(refs);
+        return await locator.first().textContent() ?? '';
+    }
+    async expectVisible(...refs) {
+        const locator = this.resolve(refs);
+        await (0, test_1.expect)(locator.first()).toBeVisible();
+    }
+    async expectHidden(...refs) {
+        const locator = this.resolve(refs);
+        await (0, test_1.expect)(locator.first()).toBeHidden();
+    }
+    async expectText(expected, ...refs) {
+        const locator = this.resolve(refs);
+        await (0, test_1.expect)(locator.first()).toContainText(expected);
+    }
+    async expectNotText(expected, ...refs) {
+        const locator = this.resolve(refs);
+        await (0, test_1.expect)(locator.first()).not.toContainText(expected);
+    }
+    async expectTextEquals(expected, ...refs) {
+        const locator = this.resolve(refs);
+        await (0, test_1.expect)(locator.first()).toHaveText(expected);
+    }
+    async expectTextNotEquals(expected, ...refs) {
+        const locator = this.resolve(refs);
+        await (0, test_1.expect)(locator.first()).not.toHaveText(expected);
+    }
+    async expectCount(count, ...refs) {
+        const locator = this.resolve(refs);
+        await (0, test_1.expect)(locator).toHaveCount(count);
+    }
+    async expectNonEmptyCount(count, ...refs) {
+        const locator = this.resolve(refs);
+        // 历史语义（老平台 EXPECTED_VALUE ctype=index）：匹配到的元素里，
+        // 文本非空的有几个。空文本元素不计入 —— 直接 toHaveCount 会把占位节点也算进去。
+        await test_1.expect
+            .poll(async () => {
+            const texts = await locator.allTextContents();
+            return texts.filter((t) => String(t).trim().length > 0).length;
+        })
+            .toBe(count);
+    }
+    async expectExists(...refs) {
+        const locator = this.resolve(refs);
+        await (0, test_1.expect)(locator.first()).toBeAttached();
+    }
+    async expectNotExists(...refs) {
+        const locator = this.resolve(refs);
+        await (0, test_1.expect)(locator).toHaveCount(0);
+    }
+    async expectClass(className, ...refs) {
+        const locator = this.resolve(refs);
+        // 检查元素 class 属性包含指定 class
+        const classAttr = await locator.first().getAttribute('class') ?? '';
+        if (!classAttr.split(/\s+/).includes(className)) {
+            throw new Error(`Element does not have class '${className}'. Actual classes: '${classAttr}'`);
+        }
+    }
+    async expectNotClass(className, ...refs) {
+        const locator = this.resolve(refs);
+        const classAttr = await locator.first().getAttribute('class') ?? '';
+        if (classAttr.split(/\s+/).includes(className)) {
+            throw new Error(`Element should not have class '${className}'. Actual classes: '${classAttr}'`);
+        }
+    }
+    async expectAttribute(attr, value, ...refs) {
+        const locator = this.resolve(refs);
+        await (0, test_1.expect)(locator.first()).toHaveAttribute(attr, value);
+    }
+    async expectAttributeContains(attr, value, ...refs) {
+        const locator = this.resolve(refs);
+        const actual = await locator.first().getAttribute(attr);
+        if (actual === null || !actual.includes(value)) {
+            throw new Error(`Element attribute '${attr}' should contain '${value}'. Actual: ${JSON.stringify(actual)}`);
+        }
+    }
+    async expectUrlContains(part) {
+        await (0, test_1.expect)(this.page).toHaveURL(new RegExp(escapeRegExp(part)));
+    }
+    async expectUrlNotContains(part) {
+        const url = this.page.url();
+        if (url.includes(part)) {
+            throw new Error(`URL '${url}' should not contain '${part}'`);
+        }
+    }
+    async expectUrlEquals(url) {
+        await (0, test_1.expect)(this.page).toHaveURL(url);
+    }
+    async expectUrlNotEquals(url) {
+        const actual = this.page.url();
+        if (actual === url) {
+            throw new Error(`URL should not equal '${url}'`);
+        }
+    }
+    async expectTitle(part) {
+        await (0, test_1.expect)(this.page).toHaveTitle(new RegExp(escapeRegExp(part)));
+    }
+    async expectTitleEquals(title) {
+        await (0, test_1.expect)(this.page).toHaveTitle(title);
+    }
+    rawPage() {
+        return this.page;
+    }
+    async ariaSnapshot(options) {
+        // 使用 Playwright 的 aria snapshot (--yarn/1.49+)
+        // 回退到 page.locator('body').innerText() 作为简化快照
+        try {
+            const snapshot = await this.page.locator('body').ariaSnapshot();
+            return snapshot ?? '';
+        }
+        catch {
+            // 旧版 Playwright 回退
+            return await this.page.locator('body').innerText();
+        }
+    }
+    async injectCookies(cookies) {
+        const context = this.page.context();
+        await context.addCookies(cookies);
+    }
+}
+exports.PlaywrightEngine = PlaywrightEngine;
+// ─── Factory ──────────────────────────────────────────────────────────
+/** RegExp 元字符转义（expectUrlContains 用） */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * 从 Playwright page 创建 engine 实例
+ */
+function createEngine(page) {
+    return new PlaywrightEngine(page);
+}

package/dist/engine-playwright/global-setup.d.ts

@@ -0,0 +1,28 @@
+/**
+ * global-setup — 登录态装配（纯数据准备，不启动浏览器）
+ *
+ * 设计调整（与平台执行链路对齐）：
+ *   - 不再由测试侧启动 chromium，也不再通过 CDP 接管已开浏览器。
+ *   - 登录态由**服务端**解析（eve-backend account-resolver → SSO cookies），
+ *     执行前以环境变量下发，这里只负责把 cookie 写成 Playwright storageState。
+ *
+ * 环境变量：
+ *   KEVE_SSO_COOKIES      — JSON 字符串化的 SsoCookie[]（服务端解析结果，首选）
+ *   KEVE_STORAGE_STATE    — storageState 输出路径（默认 ./.auth/storage-state.json）
+ *   KEVE_TARGET_URL       — 目标站点 URL（用于派生 cookie domain，缺省 kuaishou.com）
+ *
+ * 兼容：KEVE_SSO_COOKIES_FILE 指向一个包含同样 JSON 的文件。
+ */
+import type { SsoCookie } from '../core/sso-cookie.js';
+/** 由 storageState 路径解析（默认 .auth/storage-state.json） */
+export declare function resolveStorageStatePath(): string;
+/** 目标站点派生 cookie domain：https://foo.kuaishou.com/x → .kuaishou.com */
+export declare function deriveCookieDomain(targetUrl?: string): string;
+/** 读取服务端下发的 cookies（环境变量优先，其次文件） */
+export declare function readInjectedCookies(): SsoCookie[];
+/**
+ * 写出 storageState（只写文件，不启动浏览器）。
+ * 返回实际写入的 cookie 数，供执行侧日志/断言使用。
+ */
+export declare function writeStorageState(storageStatePath: string): number;
+export default function (): Promise<void>;