@kkeve/suite 0.0.13 → 0.0.15

package/dist/commands/run.js

@@ -230,7 +230,10 @@ async function run(options) {
     console.log(chalk_1.default.blue(`  ▶ Round ${round} — Executing Playwright tests...\n`));
     await ensurePlaywrightBrowsers();
     if (!env.KEVE_CDP_ENDPOINT && !env.KEVE_CDP_WS_ENDPOINT) {
-        env.KEVE_CDP_ENDPOINT = 'http://127.0.0.1:9222';
+        // 不再盲目设置 KEVE_CDP_ENDPOINT fallback — 如果 browserSetup() 未成功启动 Chrome，
+        // 这个 fallback 会让 isCdpMode() 返回 true → getCdpBrowser() 去连一个不存在的 CDP → throw
+        // 现在由 getCdpBrowser() 内部处理 graceful fallback 到非 CDP 模式
+        console.log(chalk_1.default.gray('  Note: No CDP endpoint configured — Playwright will launch its own browser'));
     }
     const exitCode = await new Promise((resolve) => {
         const child = (0, node_child_process_1.spawn)('npx', pwArgs, {

package/dist/core/generateReport/reportData.js

@@ -73,9 +73,12 @@ function resolveOptions(opts) {
 //   2. ktest 原始的 TCDPQA100195 / TCDPQA100189 等：「大写字母+数字」连续无分隔
 //      （ktest 命名规则：TC=TestCase DPQA=数据平台QA 100195=序列号）
 function parseCaseIdFromTitle(title) {
-    const colonMatch = title.match(/^([A-Z]+(?:-[A-Z]+)*-\d+|[A-Z]+\d+):/);
-    const bracketMatch = title.match(/\[([A-Z]+(?:-[A-Z]+)*-\d+|[A-Z]+\d+)\]/);
-    const spaceMatch = title.match(/^([A-Z]+(?:-[A-Z]+)*-\d+|[A-Z]+\d+)\s/);
+    // Case ID patterns: "SKILL_SHARE-01:", "AG-01:", "ABC123:", "[REG-02]"
+    // Supports: underscores (SKILL_SHARE), hyphens (REG-01), pure alphanumeric (ABC123)
+    const caseIdPattern = '[A-Z][A-Z0-9]*(?:[_-][A-Z0-9]+)*-\\d+|[A-Z]+\\d+';
+    const colonMatch = title.match(new RegExp(`^(${caseIdPattern}):`));
+    const bracketMatch = title.match(new RegExp(`\\[(${caseIdPattern})\\]`));
+    const spaceMatch = title.match(new RegExp(`^(${caseIdPattern})\\s`));
     return colonMatch?.[1] || bracketMatch?.[1] || spaceMatch?.[1] || null;
 }
 /**

package/dist/core/global-setup.d.ts

@@ -1,6 +1,6 @@
 declare global {
     var __keve_cdp_browser: import('@playwright/test').Browser | undefined;
 }
-export declare function getCdpBrowser(): Promise<import('@playwright/test').Browser>;
+export declare function getCdpBrowser(): Promise<import('@playwright/test').Browser | null>;
 export declare function isCdpMode(): boolean;
 export default function (): Promise<void>;

package/dist/core/global-setup.js

@@ -50,21 +50,30 @@ async function getCdpBrowser() {
     if (!wsUrl && process.env.KEVE_CDP_ENDPOINT) {
         const httpUrl = process.env.KEVE_CDP_ENDPOINT.replace(/\/$/, '');
         try {
-            const resp = await fetch(`${httpUrl}/json/version`);
+            const resp = await fetch(`${httpUrl}/json/version`, { signal: AbortSignal.timeout(5000) });
             const data = await resp.json();
             wsUrl = data.webSocketDebuggerUrl;
             console.log(`[keve CDP] Resolved WS endpoint: ${wsUrl}`);
         }
         catch (e) {
-            throw new Error(`Failed to resolve CDP WebSocket URL from ${httpUrl}: ${e.message}`);
+            console.warn(`[keve CDP] Failed to resolve CDP WebSocket URL from ${httpUrl}: ${e.message} — falling back to non-CDP mode`);
+            return null;
         }
     }
-    if (!wsUrl)
-        throw new Error('No CDP endpoint configured');
-    const browser = await chromium.connectOverCDP(wsUrl, { timeout: 15000 });
-    console.log(`[keve CDP] Connected via ${wsUrl}`);
-    globalThis.__keve_cdp_browser = browser;
-    return browser;
+    if (!wsUrl) {
+        console.warn(`[keve CDP] No CDP endpoint configured — falling back to non-CDP mode`);
+        return null;
+    }
+    try {
+        const browser = await chromium.connectOverCDP(wsUrl, { timeout: 15000 });
+        console.log(`[keve CDP] Connected via ${wsUrl}`);
+        globalThis.__keve_cdp_browser = browser;
+        return browser;
+    }
+    catch (connectErr) {
+        console.warn(`[keve CDP] connectOverCDP failed: ${connectErr.message} — falling back to non-CDP mode`);
+        return null;
+    }
 }
 function isCdpMode() {
     return !!process.env.KEVE_CDP_WS_ENDPOINT || !!process.env.KEVE_CDP_ENDPOINT;
@@ -76,8 +85,9 @@ async function default_1() {
     if (cdpEndpoint) {
         console.log(`[keve global-setup] CDP endpoint detected: ${cdpEndpoint}`);
         // CDP 模式：在 global-setup 中提前连接一次，缓存 Browser 对象
-        try {
-            const browser = await getCdpBrowser();
+        // getCdpBrowser() 失败时返回 null 并清除 CDP 环境变量 → 后续 fixture 自动 fallback
+        const browser = await getCdpBrowser();
+        if (browser) {
             const contexts = browser.contexts();
             const pages = contexts.length > 0 ? contexts[0].pages() : [];
             console.log(`[keve global-setup] CDP connected. contexts=${contexts.length}, pages=${pages.length}`);
@@ -85,8 +95,8 @@ async function default_1() {
                 console.log(`[keve global-setup] Existing tabs: ${pages.map(p => p.url()).join(', ')}`);
             }
         }
-        catch (e) {
-            console.warn(`[keve global-setup] CDP connection failed: ${e.message}`);
+        else {
+            console.warn(`[keve global-setup] CDP connection failed — tests will use non-CDP fallback (chromium.launch)`);
         }
         if (!fs.existsSync(storageStatePath)) {
             const authDir = path.dirname(storageStatePath);

package/dist/core/keve-test.js

@@ -104,8 +104,17 @@ exports.test = test_1.test.extend({
     browser: async ({}, use, testInfo) => {
         if ((0, global_setup_1.isCdpMode)()) {
             const browser = await (0, global_setup_1.getCdpBrowser)(); // 复用全局共享的 CDP browser
-            await use(browser);
-            // CDP 模式下不关闭浏览器（共享连接，关闭会影响后续用例）
+            if (browser) {
+                await use(browser);
+                // CDP 模式下不关闭浏览器（共享连接，关闭会影响后续用例）
+            }
+            else {
+                // CDP 不可达 → graceful fallback 到独立启动浏览器
+                console.log(`[keve-test] CDP unavailable, falling back to chromium.launch()`);
+                const fallback = await test_1.chromium.launch(testInfo.project?.use?.launchOptions || {});
+                await use(fallback);
+                await fallback.close();
+            }
         }
         else {
             const browser = await test_1.chromium.launch(testInfo.project?.use?.launchOptions || {});
@@ -114,7 +123,8 @@ exports.test = test_1.test.extend({
         }
     },
     page: async ({ browser }, use) => {
-        if ((0, global_setup_1.isCdpMode)()) {
+        const isCdp = (0, global_setup_1.isCdpMode)() && browser.isConnected();
+        if (isCdp) {
             const contexts = browser.contexts();
             const cdpContext = contexts.length > 0 ? contexts[0] : await browser.newContext();
             // CDP 模式：优先复用已有 page（保留登录状态），仅在无可用 page 时新开
@@ -224,43 +234,69 @@ exports.test = test_1.test.extend({
                 };
             }
             else {
-                // ── Per-goal timeout: prevent one slow goal from exhausting the test timeout ──
-                // Default 300s per goal; total test timeout should be ≥ (goals × 300s + overhead)
-                const GOAL_TIMEOUT_MS = 300_000;
-                const goalTimeoutController = new AbortController();
-                const goalTimeout = setTimeout(() => {
-                    goalTimeoutController.abort();
-                    console.log(`[keveGoal] ⏰ "${options.step}" timed out after ${GOAL_TIMEOUT_MS}ms — stopping agent`);
-                }, GOAL_TIMEOUT_MS);
+                // ── Page liveness check: if fn killed the page, skip Agent Re-Act ──
+                // When fn error involves page/browser close, the page is dead —
+                // Agent cannot take a11y snapshots or interact. Skip immediately.
+                let pageAlive = true;
                 try {
-                    reactResult = await (0, agent_1.reactLoop)(page, options.step, options.expected, {
-                        learnedActionsHint: learnedHint,
-                        specFilePath: ctx.specFilePath,
-                        fnSource,
-                        fnResult: fnError ? { error: fnError } : { success: true },
-                        signal: goalTimeoutController.signal,
-                        goalScreenshotBefore: goalScreenshotBefore || undefined,
-                        fnAfterScreenshot: fnAfterScreenshot || undefined,
-                    });
+                    await page.url();
+                }
+                catch {
+                    pageAlive = false;
                 }
-                catch (reactErr) {
-                    reactTimedOut = true;
-                    const isGoalTimeout = goalTimeoutController.signal.aborted;
-                    const msg = isGoalTimeout
-                        ? `Goal timed out (${GOAL_TIMEOUT_MS}ms)`
-                        : (reactErr?.message || String(reactErr));
-                    console.log(`[keveGoal] reactLoop interrupted: ${msg.slice(0, 200)}`);
+                if (!pageAlive) {
+                    console.log(`[keveGoal] 🚫 "${options.step}" BLOCKED — page is dead after fn error, skipping agent Re-Act`);
                     reactResult = {
                         expectedMet: false,
-                        actions: [],
+                        actions: [{
+                                action: { tool: 'done', verdict: 'blocked', text: `Page closed after fn error: ${fnError}` },
+                                toolOutput: '',
+                                result: 'ok',
+                            }],
                         finalSnapshot: '',
                         agentScreenshots: [],
-                        conclusion: isGoalTimeout ? 'blocked' : 'fail',
+                        conclusion: 'blocked',
                     };
                 }
-                finally {
-                    clearTimeout(goalTimeout);
-                }
+                else {
+                    // ── Per-goal timeout: prevent one slow goal from exhausting the test timeout ──
+                    // Default 300s per goal; total test timeout should be ≥ (goals × 300s + overhead)
+                    const GOAL_TIMEOUT_MS = 300_000;
+                    const goalTimeoutController = new AbortController();
+                    const goalTimeout = setTimeout(() => {
+                        goalTimeoutController.abort();
+                        console.log(`[keveGoal] ⏰ "${options.step}" timed out after ${GOAL_TIMEOUT_MS}ms — stopping agent`);
+                    }, GOAL_TIMEOUT_MS);
+                    try {
+                        reactResult = await (0, agent_1.reactLoop)(page, options.step, options.expected, {
+                            learnedActionsHint: learnedHint,
+                            specFilePath: ctx.specFilePath,
+                            fnSource,
+                            fnResult: fnError ? { error: fnError } : { success: true },
+                            signal: goalTimeoutController.signal,
+                            goalScreenshotBefore: goalScreenshotBefore || undefined,
+                            fnAfterScreenshot: fnAfterScreenshot || undefined,
+                        });
+                    }
+                    catch (reactErr) {
+                        reactTimedOut = true;
+                        const isGoalTimeout = goalTimeoutController.signal.aborted;
+                        const msg = isGoalTimeout
+                            ? `Goal timed out (${GOAL_TIMEOUT_MS}ms)`
+                            : (reactErr?.message || String(reactErr));
+                        console.log(`[keveGoal] reactLoop interrupted: ${msg.slice(0, 200)}`);
+                        reactResult = {
+                            expectedMet: false,
+                            actions: [],
+                            finalSnapshot: '',
+                            agentScreenshots: [],
+                            conclusion: isGoalTimeout ? 'blocked' : 'fail',
+                        };
+                    }
+                    finally {
+                        clearTimeout(goalTimeout);
+                    }
+                } // end of page-alive else (agent Re-Act path)
             } // end of else (non-blocked path)
             // ── Deterministic override: fn assertion failure cannot be overridden by Agent "pass" ──
             // When fn has a hard assertion failure (Expected X, Received Y), the value mismatch
@@ -466,6 +502,16 @@ function isEnvironmentBlockedError(err) {
         || msg.includes('err_too_many_redirects')) {
         return true;
     }
+    // Page/context/browser closed — dead page, Agent cannot explore
+    // e.g. "page.waitForLoadState: Target page, context or browser has been closed"
+    // e.g. "page.ariaSnapshot: Target page, context or browser has been closed"
+    // When the CDP connection drops or the user closes the tab, any page API throws this.
+    // Agent Re-Act on a dead page is a waste of time → BLOCKED immediately.
+    if (msg.includes('target page, context or browser has been closed')
+        || msg.includes('page has been closed') || msg.includes('browser has been closed')
+        || msg.includes('context has been closed')) {
+        return true;
+    }
     return false;
 }
 /**

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

@@ -85,6 +85,19 @@ export declare class KevePageAgent {
     /** Current execute options (set at start of execute(), accessible from hooks) */
     options?: AgentOptions;
     private hooks?;
+    _dialogHandler: {
+        accept: boolean;
+        promptText?: string;
+    } | null;
+    _lastDialogInfo: {
+        type: string;
+        message: string;
+        accepted: boolean;
+    } | null;
+    _pendingFileChooser: any;
+    _consoleMessages: any[];
+    _networkRequests: any[];
+    _pageListenersSetup: boolean;
     constructor(page: Page, options?: {
         maxSteps?: number;
         customSystemPrompt?: string;
@@ -92,6 +105,9 @@ export declare class KevePageAgent {
     });
     /** Stop the current execution */
     stop(): void;
+    /** Set up page event listeners for dialog, console, network, and file chooser capture.
+     *  Called once per page; subsequent calls are no-ops. */
+    private setupPageListeners;
     /** Main Re-Act execute loop */
     execute(step: string, expected: string, options?: AgentOptions): Promise<AgentResult>;
     private pushObservation;

package/dist/page-agent/agent.js

@@ -157,6 +157,13 @@ class KevePageAgent {
     /** Current execute options (set at start of execute(), accessible from hooks) */
     options;
     hooks;
+    // Page event listener state (used by handle_dialog, console_messages, file_upload, network_requests)
+    _dialogHandler = null;
+    _lastDialogInfo = null;
+    _pendingFileChooser = null;
+    _consoleMessages = [];
+    _networkRequests = [];
+    _pageListenersSetup = false;
     constructor(page, options) {
         this.page = page;
         this.maxSteps = options?.maxSteps ?? 8;
@@ -175,12 +182,95 @@ class KevePageAgent {
     stop() {
         this.abortController.abort();
     }
+    /** Set up page event listeners for dialog, console, network, and file chooser capture.
+     *  Called once per page; subsequent calls are no-ops. */
+    setupPageListeners() {
+        if (this._pageListenersSetup)
+            return;
+        this._pageListenersSetup = true;
+        // ── Dialog handler ──
+        // Playwright auto-dismisses dialogs unless a handler is registered.
+        // Our handler auto-accepts by default, but _dialogHandler can override.
+        this.page.on('dialog', async (dialog) => {
+            const handler = this._dialogHandler;
+            const accept = handler?.accept ?? true;
+            const promptText = handler?.promptText;
+            try {
+                if (accept) {
+                    await dialog.accept(promptText || '');
+                }
+                else {
+                    await dialog.dismiss();
+                }
+            }
+            catch {
+                // Fallback: always accept to unblock the page
+                try {
+                    await dialog.accept();
+                }
+                catch { /* give up */ }
+            }
+            this._lastDialogInfo = {
+                type: dialog.type(),
+                message: dialog.message(),
+                accepted: accept,
+            };
+            this._dialogHandler = null;
+            // Notify the Agent so it knows a dialog appeared
+            this.pushObservation(`🔔 Native dialog [${dialog.type()}] appeared: "${dialog.message().slice(0, 100)}" — was ${accept ? 'accepted' : 'dismissed'}.`);
+        });
+        // ── Console messages ──
+        this.page.on('console', (msg) => {
+            this._consoleMessages.push({ level: msg.type(), text: msg.text() });
+            if (this._consoleMessages.length > 200)
+                this._consoleMessages.shift();
+        });
+        this.page.on('pageerror', (err) => {
+            this._consoleMessages.push({ level: 'error', text: `Uncaught: ${err.message}` });
+        });
+        // ── Network requests ──
+        this.page.on('request', (req) => {
+            const url = req.url();
+            const isStatic = /\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|map)(\?|$)/i.test(url);
+            this._networkRequests.push({
+                _req: req,
+                method: req.method(),
+                url,
+                isStatic,
+                status: null,
+            });
+            if (this._networkRequests.length > 100)
+                this._networkRequests.shift();
+        });
+        this.page.on('response', (res) => {
+            const req = res.request();
+            // Match by reference identity — Playwright guarantees same Request object
+            for (let i = this._networkRequests.length - 1; i >= 0; i--) {
+                if (this._networkRequests[i]._req === req) {
+                    this._networkRequests[i].status = res.status();
+                    break;
+                }
+            }
+        });
+        // ── File chooser ──
+        this.page.on('filechooser', (fileChooser) => {
+            this._pendingFileChooser = fileChooser;
+        });
+    }
     /** Main Re-Act execute loop */
     async execute(step, expected, options) {
         // Reset state
         this.events = [];
         this.abortController = new AbortController();
         this.options = options;
+        // Reset page event listener state
+        this._dialogHandler = null;
+        this._lastDialogInfo = null;
+        this._pendingFileChooser = null;
+        this._consoleMessages = [];
+        this._networkRequests = [];
+        // Set up page event listeners (idempotent — only runs once per page)
+        this.setupPageListeners();
         const hooks = options?.hooks ?? this.hooks;
         // Link external signal (e.g. per-goal timeout) to internal abort controller
         const externalSignal = options?.signal;

package/dist/page-agent/system_prompt.md

@@ -293,7 +293,7 @@ You MUST output a JSON object with the following FLAT structure every step:
   "evaluation_previous_goal": "Concise one-sentence analysis of your last action. State success, failure, or uncertain. Reference the screenshot if it confirms or contradicts the expected state.",
   "memory": "1-3 concise sentences of key observations that will help in future steps.",
   "next_goal": "State the next immediate goal and action to achieve it.",
-  "tool": "The action tool name (click, type, hover, navigate, scroll, wait, done, visual_locate, visual_assert, etc.)",
+  "tool": "The action tool name (click, type, hover, navigate, scroll, wait, wait_for, done, drag, verify_value, handle_dialog, console_messages, file_upload, network_requests, resize_viewport, visual_locate, visual_assert, select_option, fill_form, pressKey, execute_javascript, etc.)",
   "ref": "Element ref from the accessibility tree, e.g. 'f5e13' (for click/type/hover)",
   "text": "Text to type (for type) OR description for done/visual_locate/visual_assert",
   ...other tool-specific fields...

package/dist/page-agent/tools.js

@@ -499,7 +499,7 @@ exports.tools.set('navigate', tool({
             }
             url = new URL(url, base).href;
         }
-        await this.page.goto(url, { waitUntil: 'networkidle', timeout: 15000 });
+        await this.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 });
         return `✅ Navigated to ${url}`;
     },
 }));
@@ -747,6 +747,302 @@ exports.tools.set('fill_form', tool({
         return results.join('\n');
     },
 }));
+// --- drag ---
+exports.tools.set('drag', tool({
+    description: `Drag from a starting point to an ending point using real mouse events (mousedown → mousemove steps → mouseup). Use for: resizing elements via drag handles, drag-to-reorder lists, any UI requiring hold+move interaction.
+
+Two targeting modes:
+1. By ref — drags from the element's center (use for drag-to-reorder)
+2. By coordinates (startX/startY) — precise point (use for resize handles found via visual_locate)
+
+Target specification:
+- Relative: use deltaX/deltaY (e.g. deltaX=200 moves 200px right)
+- Absolute: use endX/endY (e.g. endX=800, endY=400)
+
+NOT for: scrolling (use scroll), clicking (use click), HTML5 DnD between elements.`,
+    inputSchema: zod_1.z.object({
+        ref: zod_1.z.string().optional()
+            .describe('Element ref to start dragging from. Drags from element center. Use startX/startY for resize handles.'),
+        startX: zod_1.z.number().optional()
+            .describe('X coordinate to start dragging from (viewport pixels). Use when you have precise coordinates from visual_locate.'),
+        startY: zod_1.z.number().optional()
+            .describe('Y coordinate to start dragging from (viewport pixels).'),
+        deltaX: zod_1.z.number().optional()
+            .describe('Horizontal displacement in pixels. Positive=right, negative=left. Use with ref or startX/startY.'),
+        deltaY: zod_1.z.number().optional()
+            .describe('Vertical displacement in pixels. Positive=down, negative=up.'),
+        endX: zod_1.z.number().optional()
+            .describe('Absolute X coordinate to drag to (viewport pixels). Use deltaX/deltaY for relative, endX/endY for absolute.'),
+        endY: zod_1.z.number().optional()
+            .describe('Absolute Y coordinate to drag to (viewport pixels).'),
+        steps: zod_1.z.number().min(1).max(100).default(10)
+            .describe('Number of intermediate mousemove steps. More=smoother animation. Default 10. Use 20+ for CSS resize.'),
+    }),
+    execute: async function (input) {
+        // 1. Determine start coordinates
+        let sx, sy;
+        if (input.ref) {
+            const locator = this.page.locator(`aria-ref=${input.ref}`);
+            try {
+                const box = await locator.boundingBox({ timeout: 5000 });
+                if (!box)
+                    return `❌ Cannot drag: element [ref=${input.ref}] not visible or detached`;
+                sx = box.x + box.width / 2;
+                sy = box.y + box.height / 2;
+            }
+            catch (err) {
+                return `❌ Cannot drag: element [ref=${input.ref}] error: ${err.message}`;
+            }
+        }
+        else if (input.startX !== undefined && input.startY !== undefined) {
+            sx = input.startX;
+            sy = input.startY;
+        }
+        else {
+            return `❌ Cannot drag: provide either ref or startX/startY`;
+        }
+        // 2. Determine end coordinates
+        let ex, ey;
+        if (input.endX !== undefined && input.endY !== undefined) {
+            ex = input.endX;
+            ey = input.endY;
+        }
+        else if (input.deltaX !== undefined || input.deltaY !== undefined) {
+            ex = sx + (input.deltaX || 0);
+            ey = sy + (input.deltaY || 0);
+        }
+        else {
+            return `❌ Cannot drag: provide either deltaX/deltaY or endX/endY`;
+        }
+        // 3. Execute real mouse drag with intermediate steps
+        const steps = input.steps ?? 10;
+        try {
+            await this.page.mouse.move(sx, sy);
+            await this.page.mouse.down();
+            for (let i = 1; i <= steps; i++) {
+                const progress = i / steps;
+                await this.page.mouse.move(sx + (ex - sx) * progress, sy + (ey - sy) * progress);
+                await this.page.waitForTimeout(16); // ~60fps
+            }
+            await this.page.mouse.up();
+            await this.page.waitForTimeout(300); // wait for resize/layout to settle
+            return `✅ Dragged from (${Math.round(sx)}, ${Math.round(sy)}) to (${Math.round(ex)}, ${Math.round(ey)}) in ${steps} steps (Δx=${Math.round(ex - sx)}, Δy=${Math.round(ey - sy)})`;
+        }
+        catch (err) {
+            try {
+                await this.page.mouse.up();
+            }
+            catch { /* ensure mouse released */ }
+            return `❌ Drag failed: ${err.message}`;
+        }
+    },
+}));
+// --- wait_for ---
+exports.tools.set('wait_for', tool({
+    description: `Wait for text to appear or disappear on the page, or for a specified duration. More efficient than polling with wait(time).
+
+- waitForText: wait until specific text becomes visible on the page (e.g. wait for "保存成功" toast)
+- waitForTextGone: wait until specific text disappears (e.g. wait for "加载中..." spinner to vanish)
+- seconds: simple time-based wait (max 30s)
+
+At least one parameter is required. You can combine them (e.g. wait for text + timeout).`,
+    inputSchema: zod_1.z.object({
+        waitForText: zod_1.z.string().optional()
+            .describe('Wait for this text to appear on the page (visible)'),
+        waitForTextGone: zod_1.z.string().optional()
+            .describe('Wait for this text to disappear from the page (hidden)'),
+        seconds: zod_1.z.number().min(0.1).max(30).optional()
+            .describe('Wait time in seconds (max 30)'),
+    }),
+    execute: async function (input) {
+        if (!input.waitForText && !input.waitForTextGone && !input.seconds) {
+            return `❌ wait_for: provide at least one of waitForText, waitForTextGone, or seconds`;
+        }
+        const results = [];
+        if (input.seconds) {
+            await this.page.waitForTimeout(input.seconds * 1000);
+            results.push(`waited ${input.seconds}s`);
+        }
+        if (input.waitForTextGone) {
+            const locator = this.page.getByText(input.waitForTextGone).first();
+            try {
+                await locator.waitFor({ state: 'hidden', timeout: 15000 });
+                results.push(`"${input.waitForTextGone}" disappeared`);
+            }
+            catch {
+                results.push(`⚠️ "${input.waitForTextGone}" still visible after 15s`);
+            }
+        }
+        if (input.waitForText) {
+            const locator = this.page.getByText(input.waitForText).first();
+            try {
+                await locator.waitFor({ state: 'visible', timeout: 15000 });
+                results.push(`"${input.waitForText}" appeared`);
+            }
+            catch {
+                results.push(`⚠️ "${input.waitForText}" not found after 15s`);
+            }
+        }
+        return `✅ ${results.join(', ')}`;
+    },
+}));
+// --- verify_value ---
+exports.tools.set('verify_value', tool({
+    description: `Deterministically verify a form element's current value — no LLM needed. Faster and more precise than visual_assert for value checks.
+
+- textbox/slider/combobox → checks locator.inputValue()
+- checkbox/radio → checks locator.isChecked()
+
+Returns ✅ if value matches, ❌ if mismatch. Use for precise value assertions instead of visual inspection.`,
+    inputSchema: zod_1.z.object({
+        ref: zod_1.z.string().describe('Element ref from the accessibility tree'),
+        type: zod_1.z.enum(['textbox', 'checkbox', 'radio', 'combobox', 'slider'])
+            .describe('Element type: textbox/slider/combobox → check inputValue; checkbox/radio → check isChecked'),
+        value: zod_1.z.string().describe('Expected value. For checkbox/radio: "true" or "false". For textbox: expected text. For combobox: expected selected value.'),
+    }),
+    execute: async function (input) {
+        const locator = this.page.locator(`aria-ref=${input.ref}`);
+        try {
+            if (input.type === 'checkbox' || input.type === 'radio') {
+                const checked = await locator.isChecked({ timeout: 5000 });
+                const expected = input.value === 'true';
+                if (checked === expected) {
+                    return `✅ Verify [ref=${input.ref}] ${input.type}: checked=${checked} (expected ${input.value})`;
+                }
+                return `❌ Verify [ref=${input.ref}] ${input.type}: checked=${checked} (expected ${input.value})`;
+            }
+            // textbox, slider, combobox — check inputValue
+            const actualValue = await locator.inputValue({ timeout: 5000 });
+            if (actualValue === input.value) {
+                return `✅ Verify [ref=${input.ref}] ${input.type}: value="${actualValue}" (expected "${input.value}")`;
+            }
+            // For combobox, also check textContent (custom components may not expose value via inputValue)
+            if (input.type === 'combobox') {
+                const textContent = await locator.textContent({ timeout: 2000 }).catch(() => '');
+                if (textContent?.includes(input.value)) {
+                    return `✅ Verify [ref=${input.ref}] combobox: text contains "${input.value}" (inputValue="${actualValue}")`;
+                }
+            }
+            return `❌ Verify [ref=${input.ref}] ${input.type}: value="${actualValue}" (expected "${input.value}")`;
+        }
+        catch (err) {
+            return `❌ Verify [ref=${input.ref}] failed: ${err.message}`;
+        }
+    },
+}));
+// --- handle_dialog ---
+exports.tools.set('handle_dialog', tool({
+    description: `Handle native browser dialogs (alert, confirm, prompt). Native dialogs are auto-accepted by default when they appear.
+
+Two usage modes:
+1. BEFORE a dialog-triggering action: call handle_dialog(accept=false) to override the default auto-accept behavior. Then click the button that triggers the dialog.
+2. AFTER a dialog appeared: call handle_dialog to check what dialog was captured and how it was handled.
+
+Native dialogs are auto-accepted unless you pre-set a different action. If a click triggers a dialog, it will be handled automatically based on your pre-set preference.`,
+    inputSchema: zod_1.z.object({
+        accept: zod_1.z.boolean().default(true).describe('Whether to accept (true) or dismiss (false) the next native dialog. Default true.'),
+        promptText: zod_1.z.string().optional().describe('Text to enter in prompt dialog (only when accept=true and dialog is a prompt)'),
+    }),
+    execute: async function (input) {
+        // Set handler for the NEXT dialog
+        this._dialogHandler = { accept: input.accept, promptText: input.promptText };
+        // Also report the last captured dialog (if any)
+        const last = this._lastDialogInfo;
+        if (last) {
+            return `Last dialog: [${last.type}] "${last.message.slice(0, 80)}" — was ${last.accepted ? 'accepted' : 'dismissed'}. Next dialog will be ${input.accept ? 'accepted' : 'dismissed'}.`;
+        }
+        return `Next native dialog will be ${input.accept ? 'accepted' : 'dismissed'}${input.promptText ? ` with text "${input.promptText}"` : ''}.`;
+    },
+}));
+// --- console_messages ---
+exports.tools.set('console_messages', tool({
+    description: `Get browser console log messages captured during page execution. Use to check for JavaScript errors, verify log output, or debug page issues. More reliable than visual checking for error toasts or log messages.`,
+    inputSchema: zod_1.z.object({
+        level: zod_1.z.enum(['error', 'warning', 'info', 'debug']).default('info')
+            .describe('Minimum log level. "error"=only errors, "warning"=errors+warnings, "info"=add info logs, "debug"=all. Default "info".'),
+    }),
+    execute: async function (input) {
+        const messages = this._consoleMessages || [];
+        const levelPriority = { debug: 0, info: 1, warning: 2, error: 3 };
+        const minPriority = levelPriority[input.level] ?? 1;
+        const filtered = messages.filter((m) => (levelPriority[m.level] ?? 0) >= minPriority);
+        if (filtered.length === 0) {
+            return `No console messages at level "${input.level}" or above. Total captured: ${messages.length}.`;
+        }
+        const formatted = filtered.map((m, i) => `[${i + 1}] ${m.level.toUpperCase()}: ${m.text.slice(0, 200)}`).join('\n');
+        return `Console messages (${filtered.length}/${messages.length} at level ≥ "${input.level}"):\n${formatted}`;
+    },
+}));
+// --- file_upload ---
+exports.tools.set('file_upload', tool({
+    description: `Upload one or more files via a file input element. When you click a file input button, a file chooser dialog appears. This tool uploads files to the pending file chooser.
+
+Flow: 1) Click the file input button (e.g. "上传文件", "选择文件"), 2) Call file_upload with the file paths.
+
+Paths must be absolute. The file chooser is single-use — after uploading, a new click is needed for another upload.`,
+    inputSchema: zod_1.z.object({
+        paths: zod_1.z.array(zod_1.z.string()).describe('Absolute file paths to upload'),
+    }),
+    execute: async function (input) {
+        const fileChooser = this._pendingFileChooser;
+        if (!fileChooser) {
+            return `❌ No pending file chooser. Click a file input element first to trigger a file chooser dialog.`;
+        }
+        try {
+            await fileChooser.setFiles(input.paths);
+            this._pendingFileChooser = null;
+            return `✅ Uploaded ${input.paths.length} file(s): ${input.paths.map(p => p.split('/').pop()).join(', ')}`;
+        }
+        catch (err) {
+            this._pendingFileChooser = null;
+            return `❌ File upload failed: ${err.message}`;
+        }
+    },
+}));
+// --- network_requests ---
+exports.tools.set('network_requests', tool({
+    description: `List network requests made by the page. Use to verify API calls were made, check response status codes, or debug network issues. Returns a numbered list with method, URL, and status code.
+
+Filter by URL pattern (regex) and optionally include static resources (images, fonts, scripts). By default, only API/XHR requests are shown.`,
+    inputSchema: zod_1.z.object({
+        filter: zod_1.z.string().optional()
+            .describe('Regex pattern to filter URLs (e.g. "/api/.*user")'),
+        includeStatic: zod_1.z.boolean().default(false)
+            .describe('Include static resources (images, fonts, scripts). Default false.'),
+    }),
+    execute: async function (input) {
+        const requests = this._networkRequests || [];
+        const filter = input.filter ? new RegExp(input.filter) : undefined;
+        const lines = [];
+        for (let i = 0; i < requests.length; i++) {
+            const req = requests[i];
+            if (!input.includeStatic && req.isStatic)
+                continue;
+            if (filter && !filter.test(req.url))
+                continue;
+            const status = req.status ? ` [${req.status}]` : '';
+            const method = req.method || '?';
+            lines.push(`[${i + 1}] ${method} ${req.url.slice(0, 120)}${status}`);
+        }
+        if (lines.length === 0) {
+            return `No matching network requests. Total captured: ${requests.length}.`;
+        }
+        return `Network requests (${lines.length} shown, ${requests.length} total):\n${lines.join('\n')}`;
+    },
+}));
+// --- resize_viewport ---
+exports.tools.set('resize_viewport', tool({
+    description: `Resize the browser viewport (window size). Use for responsive design testing or to trigger layout changes at specific viewport sizes. Common breakpoints: 375×667 (mobile), 768×1024 (tablet), 1280×720 (desktop), 1920×1080 (full HD).`,
+    inputSchema: zod_1.z.object({
+        width: zod_1.z.number().min(320).max(3840).describe('Viewport width in pixels'),
+        height: zod_1.z.number().min(240).max(2160).describe('Viewport height in pixels'),
+    }),
+    execute: async function (input) {
+        await this.page.setViewportSize({ width: input.width, height: input.height });
+        await this.page.waitForTimeout(300);
+        return `✅ Viewport resized to ${input.width}×${input.height}`;
+    },
+}));
 // ── verify_expected fully removed (Phase 6) ──
 // LLM now sees screenshots via multimodal prompt and self-evaluates.
 // No separate verification tool or function needed — each step's screenshot

package/doc/skills/keve-e2e-gen/references/script-generation-guide.md

@@ -51,6 +51,7 @@
 > 2. **绝不硬编码等待时间**：不使用 `waitForTimeout()`，通过 POM waitForReady 或断言等待
 > 3. **绝不硬编码环境数据**（D05）：ID/配置值从 `fixtures/test-data.ts` 导入
 > 4. **每个测试覆盖恰好一个排列**：测试体内无 if/else 分支逻辑
+> 5. **绝不使用 `waitForLoadState('networkidle')`**：BI 仪表盘等页面有 WebSocket/SSE/长轮询等持久连接，`networkidle` 永远不会 resolve 导致无限挂起。使用 `waitForLoadState('domcontentloaded')` 或 `page.goto(url, { waitUntil: 'domcontentloaded' })` 代替
 
 ### 正确模式 vs 禁止模式
 
@@ -64,6 +65,16 @@ await expect(page.locator('[data-e2e-name="智能应用列表-筛选区域"]')).
 await page.locator('.filter-area').click();
 await page.waitForTimeout(5000);
 await agentDetailPage.navigate(636, 'edit');
+
+// ❌ 禁止：waitForLoadState('networkidle') — BI 页面有持久连接会无限挂起
+await page.goto(url);
+await page.waitForLoadState('networkidle');  // ← 永远不会 resolve！
+
+// ✅ 正确：使用 domcontentloaded 替代
+await page.goto(url, { waitUntil: 'domcontentloaded' });
+// 或
+await page.goto(url);
+await page.waitForLoadState('domcontentloaded');
 ```
 
 ### fixtures/test-data.ts 结构

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkeve/suite",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "AI-powered full-stack test agent CLI - static analysis, unit test, component test, E2E test, execute, evaluate, and report",
   "license": "MIT",
   "bin": {