dsh-browser-verify 0.1.2 → 0.1.3

package/README.md

@@ -18,7 +18,7 @@ verification is just tool calls.
 ## Quick start
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.2
+dsh plugin --profile web add dsh-browser-verify@0.1.3
 ```
 
 1. **Install** with the command above (or see [Install](#install)).
@@ -44,7 +44,7 @@ state?"; add `browser_screenshot` when you need to see the layout, or
 
 | Tool | Purpose |
 |---|---|
-| `browser_open` | Open a URL in a fresh scenario (headless Chromium, default viewport 390×844 @2x) and report title / HTTP status / visible-text summary / console errors. Optional `waitSelector` waits for a key element before returning, and optional inline `mocks` intercept APIs **before** the first navigation — for pages that boot against mocked data. |
+| `browser_open` | Open a URL in a fresh scenario (headless Chromium, default viewport 390×844 @2x) and report title / HTTP status / visible-text summary / console errors. Without `waitSelector` it waits for the page to render-settle (two identical consecutive visible-text samples, capped at ~3s) before snapshotting, so it never returns the boot/skeleton frame; loading-state noise (`加载中...` etc.) is filtered out of the summary. Optional `waitSelector` waits for a key element before returning, and optional inline `mocks` intercept APIs **before** the first navigation — for pages that boot against mocked data. |
 | `browser_mock` | Register a playwright-glob route (`**/api/*.do*`) returning your JSON, then auto-reload the page to show the mocked state — the quickest way to verify empty / error / abnormal states without touching the backend. Duplicate patterns are rejected with a hint. |
 | `browser_assert` | The cheapest and most precise check: wait for a CSS selector, verify its count and contained text, return `{pass, count, actualText, elapsedMs}`. A mismatch is `pass:false` (with the diff), never a throw — so failure is a first-class result, not an error you debug. |
 | `browser_screenshot` | Capture the current page (viewport or full page) and **auto-project the image block into the model context** — the model sees the layout without any file handling. Reports dimensions, sha256, and `identicalToPrevious:true` when the shot is byte-identical to the previous one (page probably not refreshed). |
@@ -69,7 +69,7 @@ browser_screenshot
 ## Install
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.2
+dsh plugin --profile web add dsh-browser-verify@0.1.3
 ```
 
 The version is pinned on purpose: pnpm 11 holds back packages published in the
@@ -120,7 +120,7 @@ first `browser_open` fails with an actionable install hint.
 
 ## Testing status
 
-39 unit tests (fully offline — no browser needed), strict typecheck, and a
+41 unit tests (fully offline — no browser needed), strict typecheck, and a
 per-file ≥90% statement coverage gate. Verified **end-to-end in the real DSH
 web GUI** on dsh 0.1.2-alpha.4: a two-state loop (empty + normal) against a
 live uni-app H5 (hhhweb) in 6 tool calls, with screenshots auto-projected and

package/README.zh.md

@@ -12,7 +12,7 @@
 ## 快速上手
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.2
+dsh plugin --profile web add dsh-browser-verify@0.1.3
 ```
 
 1. **安装**（更多方式见 [安装](#安装)）。
@@ -36,7 +36,7 @@ browser_assert  selector=".empty-wrap" text="暂无可用缴费服务"
 
 | 工具                   | 用途                                                                                                                                                                                                                                                       |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `browser_open`       | 在全新场景中打开 URL（无头 Chromium，默认视口 390×844 @2x），返回 title / HTTP 状态 / 可见文本摘要 / console 错误。可选`waitSelector` 等待关键元素出现后再返回；可选内联 `mocks` 在**首次导航前**拦截接口——用于一启动就依赖 mock 数据的页面。 |
+| `browser_open`       | 在全新场景中打开 URL（无头 Chromium，默认视口 390×844 @2x），返回 title / HTTP 状态 / 可见文本摘要 / console 错误。不传 `waitSelector` 时默认等待页面**渲染稳定**后再采样（连续两次相同可见文本即稳定，上限约 3s），不会采到启动骨架帧；`加载中...` 等加载态文案自动过滤。可选 `waitSelector` 等待关键元素出现后再返回；可选内联 `mocks` 在**首次导航前**拦截接口——用于一启动就依赖 mock 数据的页面。 |
 | `browser_mock`       | 注册 playwright glob 路由（如`**/api/*.do*`）返回指定 JSON，并自动 reload 页面展示 mock 状态——不碰后端最快验证空态/异常态。重复 pattern 会提示报错。                                                                                                   |
 | `browser_assert`     | 最省 token 也最精确的验证：等待 CSS 选择器出现，校验数量与包含文本，返回`{pass, count, actualText, elapsedMs}`。不满足时返回 `pass:false`（附差异），**绝不抛错**——失败是一等公民的结果，而不是要调试的异常。                                  |
 | `browser_screenshot` | 截取当前页面（视口或整页），**自动以 image block 投影到模型上下文**——模型直接"看见"版式，无需任何文件处理。返回尺寸、sha256；与上一张完全一致时 `identicalToPrevious:true`（疑似页面未刷新）。                                                   |
@@ -61,7 +61,7 @@ browser_screenshot
 ## 安装
 
 ```sh
-dsh plugin --profile web add dsh-browser-verify@0.1.2
+dsh plugin --profile web add dsh-browser-verify@0.1.3
 ```
 
 版本故意钉死：pnpm 11 会暂缓 24 小时内新发布的包，裸写 `add dsh-browser-verify`（latest）会在发布当天装到上一个版本。`--profile web`
@@ -101,7 +101,7 @@ npx playwright install chromium     # 需要 playwright-core@1.62.0
 
 ## 测试状态
 
-39 个单测（完全离线，无需浏览器）、严格 typecheck、每文件 ≥90% 语句覆盖率闸门。已在 **dsh 0.1.2-alpha.4 真实 GUI 端到端验证**：对一个真实 uni-app H5（hhhweb），空态+正常态两态闭环共 6 次调用，截图自动投影，无临时目录残留、无僵尸进程。
+41 个单测（完全离线，无需浏览器）、严格 typecheck、每文件 ≥90% 语句覆盖率闸门。已在 **dsh 0.1.2-alpha.4 真实 GUI 端到端验证**：对一个真实 uni-app H5（hhhweb），空态+正常态两态闭环共 6 次调用，截图自动投影，无临时目录残留、无僵尸进程。
 
 ## 已知限制
 

package/lib/cli.js

@@ -1,4 +1,4 @@
-import { t as BrowserDriver } from "./driver-DxMldTYf.js";
+import { t as BrowserDriver } from "./driver-Dwuu4MgP.js";
 import { readFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";

package/lib/{driver-DxMldTYf.js → driver-Dwuu4MgP.js}

@@ -91,6 +91,19 @@ const MAX_VISIBLE = 8;
 const MAX_VISIBLE_LEN = 40;
 const MAX_ERRORS = 5;
 const MAX_ERROR_LEN = 120;
+/** Poll interval and cap for the default render-settled wait (no waitSelector). */
+const SETTLE_INTERVAL_MS = 250;
+const SETTLE_CAP_MS = 3e3;
+/**
+* Loading-state noise (uni-app showLoading / boot toasts) filtered out of the
+* visible summary. Anchored full-string patterns only, so business states like
+* 加载失败 / 加载更多 are never affected.
+*/
+const NOISE_TEXT_PATTERN = /^(加载中|正在加载|请稍候|loading)[.…]{0,3}$/i;
+/** True for transient loading-state text that should not pollute the summary. */
+function isNoiseText(text) {
+	return NOISE_TEXT_PATTERN.test(text);
+}
 function assertNoMockConflict(patterns, next) {
 	if (patterns.includes(next)) throw new Error(`browser-verify: 拦截 pattern 已存在: ${next}（已有: ${patterns.join(", ")}）。请先 browser_open 重开场景或用不同的 urlPattern。`);
 }
@@ -110,7 +123,7 @@ function summarizeVisibleText(texts) {
 	const out = [];
 	for (const raw of texts) {
 		const trimmed = raw.trim();
-		if (trimmed === "") continue;
+		if (trimmed === "" || isNoiseText(trimmed)) continue;
 		const reduced = trimmed.length > MAX_VISIBLE_LEN ? trimmed.slice(0, MAX_VISIBLE_LEN) : trimmed;
 		if (seen.has(reduced)) continue;
 		seen.add(reduced);
@@ -159,6 +172,7 @@ var Scenario = class {
 			timeout
 		});
 		if (opts.waitSelector !== void 0) await this.page.waitForSelector(opts.waitSelector, { timeout });
+		else await this.waitUntilRendered(timeout);
 		const texts = await this.page.evaluate(VISIBLE_TEXT_SCRIPT);
 		return {
 			title: await this.page.title(),
@@ -169,6 +183,26 @@ var Scenario = class {
 			elapsedMs: Date.now() - started
 		};
 	}
+	/**
+	* Default settle wait: two consecutive identical non-empty visible-text
+	* samples (250ms apart) mean the render stopped changing. Bounded by
+	* min(timeoutMs, 3s) — pages that never settle (polling/animations) fall
+	* through to the current snapshot instead of burning the whole budget.
+	*/
+	async waitUntilRendered(timeoutMs) {
+		const cap = Math.min(timeoutMs, SETTLE_CAP_MS);
+		const deadline = Date.now() + cap;
+		let prev = null;
+		for (;;) {
+			const sig = (await this.page.evaluate(VISIBLE_TEXT_SCRIPT)).join("\0");
+			if (sig !== "") {
+				if (prev !== null && sig === prev) return;
+				prev = sig;
+			}
+			if (Date.now() >= deadline) return;
+			await new Promise((resolve) => setTimeout(resolve, SETTLE_INTERVAL_MS));
+		}
+	}
 	async addMock(rule) {
 		assertNoMockConflict([...this.mocks.keys()], rule.urlPattern);
 		const status = rule.status ?? 200;

package/lib/index.js

@@ -1,4 +1,4 @@
-import { t as BrowserDriver } from "./driver-DxMldTYf.js";
+import { t as BrowserDriver } from "./driver-Dwuu4MgP.js";
 import { exec } from "node:child_process";
 import { readdir, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -111,7 +111,7 @@ function registerBrowserTools(ctx) {
 	});
 	ctx.tools.register(defineTool({
 		name: "browser_open",
-		description: "在无头浏览器中打开一个页面并返回页面状态（标题/状态码/可见文本摘要/console 错误）用于验证前端页面；可选 waitSelector 等待关键元素出现，默认视口 390×844 @2x（移动端形态）。可传 mocks 在打开时拦截接口（用于启动即依赖接口数据的页面）。验证顺序：先 browser_assert 做 DOM 断言，确需看版式再 browser_screenshot。",
+		description: "在无头浏览器中打开一个页面并返回页面状态（标题/状态码/可见文本摘要/console 错误）用于验证前端页面；可选 waitSelector 等待关键元素出现（不传时自动等待页面渲染稳定后返回，加载态文案如「加载中...」自动过滤），默认视口 390×844 @2x（移动端形态）。可传 mocks 在打开时拦截接口（用于启动即依赖接口数据的页面）。验证顺序：先 browser_assert 做 DOM 断言，确需看版式再 browser_screenshot。",
 		parameters: {
 			url: {
 				type: "string",
@@ -165,7 +165,7 @@ function registerBrowserTools(ctx) {
 			},
 			waitSelector: {
 				type: "string",
-				description: "可选：等待该选择器出现后再返回（优先于固定等待）"
+				description: "可选：等待该选择器出现后再返回；不传则自动等待页面渲染稳定后返回（最多数秒）"
 			},
 			timeoutMs: {
 				type: "number",

package/lib/types/browser/scenario.d.ts

@@ -23,6 +23,8 @@ export interface AssertResult {
     actualText: string | null;
     elapsedMs: number;
 }
+/** True for transient loading-state text that should not pollute the summary. */
+export declare function isNoiseText(text: string): boolean;
 export declare function assertNoMockConflict(patterns: string[], next: string): void;
 export declare function normalizeCountSpec(count: number | {
     min: number;
@@ -48,6 +50,13 @@ export declare class Scenario {
         waitSelector?: string;
         timeoutMs?: number;
     }): Promise<OpenResult>;
+    /**
+     * Default settle wait: two consecutive identical non-empty visible-text
+     * samples (250ms apart) mean the render stopped changing. Bounded by
+     * min(timeoutMs, 3s) — pages that never settle (polling/animations) fall
+     * through to the current snapshot instead of burning the whole budget.
+     */
+    private waitUntilRendered;
     addMock(rule: {
         urlPattern: string;
         json: unknown;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-browser-verify",
   "description": "Read-only browser verification tools for the DeepSeek Harness web GUI: browser_open / browser_mock / browser_assert / browser_screenshot — verify a page (H5/desktop) in ≤4 tool calls with mock interception, DOM assertions, and screenshots that auto-project into the model context.",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "packageManager": "pnpm@11.7.0",
   "engines": {

package/src/browser/scenario.ts

@@ -34,6 +34,20 @@ const MAX_VISIBLE_LEN = 40
 const MAX_ERRORS = 5
 const MAX_ERROR_LEN = 120
 const MAX_DIFF_LEN = 120
+/** Poll interval and cap for the default render-settled wait (no waitSelector). */
+const SETTLE_INTERVAL_MS = 250
+const SETTLE_CAP_MS = 3000
+/**
+ * Loading-state noise (uni-app showLoading / boot toasts) filtered out of the
+ * visible summary. Anchored full-string patterns only, so business states like
+ * 加载失败 / 加载更多 are never affected.
+ */
+const NOISE_TEXT_PATTERN = /^(加载中|正在加载|请稍候|loading)[.…]{0,3}$/i
+
+/** True for transient loading-state text that should not pollute the summary. */
+export function isNoiseText(text: string): boolean {
+  return NOISE_TEXT_PATTERN.test(text)
+}
 
 export function assertNoMockConflict(patterns: string[], next: string): void {
   if (patterns.includes(next)) {
@@ -52,7 +66,7 @@ export function summarizeVisibleText(texts: string[]): string[] {
   const out: string[] = []
   for (const raw of texts) {
     const trimmed = raw.trim()
-    if (trimmed === '') continue
+    if (trimmed === '' || isNoiseText(trimmed)) continue
     const reduced = trimmed.length > MAX_VISIBLE_LEN ? trimmed.slice(0, MAX_VISIBLE_LEN) : trimmed
     if (seen.has(reduced)) continue
     seen.add(reduced)
@@ -106,6 +120,11 @@ export class Scenario {
     const response = await this.page.goto(opts.url, { waitUntil: 'domcontentloaded', timeout })
     if (opts.waitSelector !== undefined) {
       await this.page.waitForSelector(opts.waitSelector, { timeout })
+    } else {
+      // No explicit selector: wait for the page to render-settle instead of
+      // snapshotting the boot frame (SPAs like uni-app show skeleton/loading
+      // right after domcontentloaded — a 500ms snapshot reads empty).
+      await this.waitUntilRendered(timeout)
     }
     const texts = await this.page.evaluate(VISIBLE_TEXT_SCRIPT) as string[]
     return {
@@ -118,6 +137,27 @@ export class Scenario {
     }
   }
 
+  /**
+   * Default settle wait: two consecutive identical non-empty visible-text
+   * samples (250ms apart) mean the render stopped changing. Bounded by
+   * min(timeoutMs, 3s) — pages that never settle (polling/animations) fall
+   * through to the current snapshot instead of burning the whole budget.
+   */
+  private async waitUntilRendered(timeoutMs: number): Promise<void> {
+    const cap = Math.min(timeoutMs, SETTLE_CAP_MS)
+    const deadline = Date.now() + cap
+    let prev: string | null = null
+    for (;;) {
+      const sig = (await this.page.evaluate(VISIBLE_TEXT_SCRIPT) as string[]).join('\u0000')
+      if (sig !== '') {
+        if (prev !== null && sig === prev) return
+        prev = sig
+      }
+      if (Date.now() >= deadline) return
+      await new Promise(resolve => setTimeout(resolve, SETTLE_INTERVAL_MS))
+    }
+  }
+
   async addMock(rule: { urlPattern: string; json: unknown; status?: number; reload?: boolean; timeoutMs?: number }): Promise<string[]> {
     assertNoMockConflict([...this.mocks.keys()], rule.urlPattern)
     const status = rule.status ?? 200

package/src/tools/index.ts

@@ -24,7 +24,7 @@ export function registerBrowserTools(ctx: Context): void {
 
   ctx.tools.register(defineTool({
     name: 'browser_open',
-    description: '在无头浏览器中打开一个页面并返回页面状态（标题/状态码/可见文本摘要/console 错误）用于验证前端页面；可选 waitSelector 等待关键元素出现，默认视口 390×844 @2x（移动端形态）。可传 mocks 在打开时拦截接口（用于启动即依赖接口数据的页面）。验证顺序：先 browser_assert 做 DOM 断言，确需看版式再 browser_screenshot。',
+    description: '在无头浏览器中打开一个页面并返回页面状态（标题/状态码/可见文本摘要/console 错误）用于验证前端页面；可选 waitSelector 等待关键元素出现（不传时自动等待页面渲染稳定后返回，加载态文案如「加载中...」自动过滤），默认视口 390×844 @2x（移动端形态）。可传 mocks 在打开时拦截接口（用于启动即依赖接口数据的页面）。验证顺序：先 browser_assert 做 DOM 断言，确需看版式再 browser_screenshot。',
     parameters: {
       url: { type: 'string', required: true, description: '页面地址，如 http://localhost:5173/hweb/pages/...' },
       viewport: {
@@ -50,7 +50,7 @@ export function registerBrowserTools(ctx: Context): void {
         },
         description: '可选：页面启动前注册的接口拦截（glob urlPattern + json，如 [{urlPattern: "**/api/*.do*", json: {...}}]）',
       },
-      waitSelector: { type: 'string', description: '可选：等待该选择器出现后再返回（优先于固定等待）' },
+      waitSelector: { type: 'string', description: '可选：等待该选择器出现后再返回；不传则自动等待页面渲染稳定后返回（最多数秒）' },
       timeoutMs: { type: 'number', description: `加载超时，默认 ${envTimeoutMs()}ms` },
     },
     output: {