前言¶
智能體在開發 Web 應用後，往往會給出“任務完成”的反饋。然而，代碼層面的自檢可能通過，但頁面實際表現（交互、樣式、視覺）可能存在問題。單元測試難以覆蓋視覺迴歸或真實用戶交互場景。
dsh-verify 是一個爲智能體構建的 Web 應用提供質量門控的工具。它提供真實瀏覽器的驗收測試能力，支持 CLI、MCP 服務器和 GitHub Action 三種運行方式，確保應用在真實瀏覽器環境中表現符合預期。
插件簡介¶
dsh-verify 是一個基於 Playwright 的質量檢查插件，旨在解決智能體自測與真實用戶體驗之間的鴻溝。它維護者爲 263311487-ux，採用 MIT 許可證。
插件核心價值在於將“瀏覽器”作爲獨立的裁決者。它不依賴 LLM 的主觀判斷，而是通過執行真實的點擊、輸入、樣式檢查和截圖對比，返回確定的 PASS 或 FAIL 結果。
核心能力¶
基於已覈實的事實，該插件包含以下核心功能：
- 真實瀏覽器驗收測試：基於 Playwright 引擎，執行人類在瀏覽器中的常規操作（點擊、填表、檢查樣式）。
- MCP 服務器支持：可與 Claude Code、Cursor、Copilot 等工具集成，允許智能體在會話中調用瀏覽器驗證。
- GitHub Action 集成：支持在 CI 流程中運行，每次 Push 都可觸發真實瀏覽器檢查。
- AI 起草檢查清單：提供
gen命令，允許 AI 根據頁面 URL 和 Prompt 生成測試規範並自動執行。 - 視覺迴歸：支持截圖對比和差異檢測，用於捕獲視覺漂移。
- 多瀏覽器支持：支持 Chromium、Firefox、WebKit。
- JSON 規範化測試：測試邏輯以 JSON 格式編寫，便於複用和版本控制。
安裝與啓用¶
使用前需安裝 Node.js 環境及 Playwright 瀏覽器。
- 全局安裝插件
npm install -g dsh-verify
- 安裝 Playwright 瀏覽器
首次使用需下載 Chromium 瀏覽器：
npx playwright install chromium
使用方式¶
插件提供 CLI、MCP 和 GitHub Action 三種主要使用方式。
CLI 命令行¶
在命令行中運行測試規範文件或 glob 匹配：
npx dsh-verify --spec 'specs/*.json'
MCP 服務器集成¶
將 MCP 服務器添加到 Claude Code 或 Cursor 中，以便智能體調用：
claude mcp add dsh-verify -- npx -y -p dsh-verify dsh-verify-mcp
GitHub Action 集成¶
在 CI 配置文件中使用官方 Action：
- uses: 263311487-ux/dsh-verify/.github/actions/dsh-verify@main
with:
spec: demo/fixed.json # 指定規範文件或 glob
# url: https://staging.example.com # 可選：覆蓋規範中的 base
注意事項¶
- 運行環境：插件依賴
@modelcontextprotocol-sdk、playwright和pngjs。 - Node.js 版本：需要 Node.js 版本大於等於 18。
- 權限與安全：插件以當前 dsh 進程的權限運行，安裝前請檢查源碼與許可證。
- 瀏覽器依賴：每次首次使用或更新 Playwright 版本後，可能需要重新執行
npx playwright install。
總結¶
dsh-verify 作爲一個獨立的瀏覽器驗收工具，通過 JSON 規範與真實瀏覽器執行解耦，爲 Agent 構建的應用提供了可靠的迴歸測試能力。無論是 CI 流水線中的自動化檢查，還是開發過程中的交互驗證，它都能提供客觀的通過/失敗反饋。
