# Browser Test Reporter > ````skill - Skill: `elfhermit/browser-test-reporter` (Agent Skill, multi-file: 11 files) - Install (CLI): `npx skillmds@latest add elfhermit/browser-test-reporter` - Raw SKILL.md: https://api.skillmd.com/api/skills/elfhermit/browser-test-reporter/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: elfhermit (https://skillmd.com/u/elfhermit) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/elfhermit/browser-test-reporter --- ````skill --- name: browser-test-reporter description: "Use this skill when the user (typically a PM, SA, or non-engineer) wants to run automated browser tests based on a Word document (.docx) describing test cases, and receive: (1) a self-contained one-page HTML test report with screenshots and video links, and (2) an updated Word document with test results, PASS/FAIL status and embedded screenshots. Triggers include: 'test my website using a Word file', 'run QA from my docx', 'automated browser test', 'generate test report from Word', '用Word做自動化測試', '瀏覽器功能測試報告'. The skill orchestrates docx parsing → Playwright browser automation → screenshot/video capture → HTML report generation → Word document update." license: Apache 2.0 --- # Browser Test Reporter (Word 路線) 以 Word 文件（`.docx`）為輸入，使用 **AI Agent + browser_subagent** 統一執行引擎，自動執行瀏覽器測試， 產出 HTML 測試報告 + 更新後的 Word 文件（含截圖與PASS/FAIL 標示）。 > **執行引擎與方案 A (autoTestReport) 完全一致** > 差異僅在輸入格式：方案 A 使用 `.md`，方案 B 使用 `.docx`。 --- ## Available Scripts | Script | Purpose | |--------|---------| | `scripts/parse_docx.exe` | Extract structured test cases from `.docx` → JSON | | `scripts/run_tests.py` | Execute test cases with Playwright (screenshots + video) | | `scripts/generate_report.exe` | Build self-contained one-page HTML report | | `scripts/update_docx.exe` | Inject results and screenshots back into the Word doc | **Always run each script with `--help` first** to see its exact usage before invoking it. --- ## End-to-End Workflow ``` Step 1 parse_docx.exe → reports/test_cases.json (parse Word input) Step 2 AI Agent + browser_subagent → reports/walkthrough.md + 截圖 + 錄影 (execute tests) Step 3 generate_report.exe → reports/report.html (build HTML report) Step 4 update_docx.exe → reports/report_.docx (update Word doc) ``` ### Step 1 – Parse the Word Document ```bash .agent/skills/browser-test-reporter/scripts/parse_docx.exe docs/input.docx --output reports/test_cases.json ``` - Calls `pandoc` to convert `.docx` → Markdown, then uses LLM-friendly JSON schema - Supported Word layouts: numbered lists, tables, free prose - Output: `reports/test_cases.json` (see schema below) ### Step 2 – 執行測試（AI Agent + browser_subagent） 對 `reports/test_cases.json` 中的每一個 test case，依序呼叫 `browser_subagent` 執行： - 將測試案例的步驟、Base URL、預期結果作為 Task 提示詞傳遞給 Subagent - 設定 `RecordingName` 參數（如 `tc001_recording`）以機器錄影 - Subagent 返回後，整理結果（步驟狀態、錯誤訊息、截圖、PASS/FAIL） - **[重要產出]：除了 HTML 與 Word，Agent 會強制產生一份結構化的 Markdown 圖文驗證報告（例如另存至 `reports/walkthrough_.md`，內含「各案例執行細節」與相對應的截圖連結），以利後續原始碼區檢閱。** > **備用**：`run_tests.py` 保留作為 Playwright 直接執行的 CI/CD 備用方案。 - Launches Chromium via Playwright - Takes screenshots at every step + on failure - Saves one `.webm` video per test case (optional) - Writes `reports/results.json` ### Step 3 – Generate HTML Report ```bash .agent/skills/browser-test-reporter/scripts/generate_report.exe reports/results.json \ --screenshots-dir ./reports/screenshots \ --videos-dir ./reports/videos \ --output reports/report.html ``` - Produces a single self-contained `.html` (screenshots base64-inlined) - Sections: Summary banner → Environment info → Test case cards → Screenshot lightbox - PASS = green, FAIL = red, SKIP = grey - Can be printed to PDF from the browser ### Step 4 – Update Word Document ```bash .agent/skills/browser-test-reporter/scripts/update_docx.exe docs/input.docx reports/results.json \ --screenshots-dir ./reports/screenshots \ --walkthrough reports/walkthrough.md \ --output reports/report_input.docx ``` - Appends a "Test Execution Summary" section to the original Word doc - Inserts PASS/FAIL status (green/red) next to each test case - Embeds representative screenshots beneath each test case heading --- ## reports/test_cases.json Schema ```json { "meta": { "title": "Test Suite Name", "base_url": "https://example.com", "environment": "staging", "tested_by": "PM Name", "date": "2026-02-25" }, "test_cases": [ { "id": "TC-001", "name": "User Login", "description": "Verify that a registered user can log in successfully", "steps": [ { "action": "goto", "target": "/login" }, { "action": "fill", "target": "#email", "value": "test@example.com" }, { "action": "fill", "target": "#password", "value": "secret" }, { "action": "click", "target": "button[type=submit]" }, { "action": "assert_url", "target": "/dashboard" }, { "action": "assert_visible", "target": "text=Welcome" } ], "expected_result": "User is redirected to dashboard and sees welcome message" } ] } ``` ### Supported Step Actions | Action | Parameters | Description | |--------|-----------|-------------| | `goto` | `target` = URL path | Navigate to URL | | `click` | `target` = selector | Click an element | | `fill` | `target` = selector, `value` = string | Type into input | | `select` | `target` = selector, `value` = option | Select dropdown option | | `hover` | `target` = selector | Hover over element | | `wait` | `target` = milliseconds | Pause execution | | `screenshot` | `name` = filename | Explicit screenshot | | `assert_visible` | `target` = selector/text | Assert element visible | | `assert_text` | `target` = selector, `value` = expected text | Assert text content | | `assert_url` | `target` = URL path (partial match) | Assert current URL | | `assert_title` | `target` = page title (partial match) | Assert page title | --- ## results.json Schema (Output of run_tests.py) ```json { "meta": { "...same as test_cases.json meta..." }, "summary": { "total": 5, "passed": 4, "failed": 1, "skipped": 0, "duration_seconds": 42.3, "started_at": "2026-02-25T14:00:00Z", "finished_at": "2026-02-25T14:00:42Z" }, "test_cases": [ { "id": "TC-001", "name": "User Login", "status": "passed", "duration_seconds": 8.1, "steps": [ { "index": 0, "action": "goto", "target": "/login", "status": "passed", "screenshot": "screenshots/TC-001_step_0_goto.png" } ], "video": "videos/TC-001.webm", "error": null } ] } ``` --- ## Decision Tree ``` User provides .docx ↓ Does the Word doc have a clear table/list structure? ├─ Yes → parse_docx.py will auto-extract test cases └─ No → Ask user to confirm/edit reports/test_cases.json before running ↓ Does the site require login? ├─ Yes → Add login step as TC-000 or inject credentials via --cookies └─ No → Proceed directly ↓ Run run_tests.py (headless for speed, headed for debugging) ↓ Did any tests FAIL? ├─ Yes → Review failure screenshots, optionally re-run single case: │ python scripts/run_tests.py reports/test_cases.json --filter TC-001 └─ No → Proceed to report generation ↓ Generate report.html + updated .docx ``` --- ## Common Pitfalls - **Dynamic content**: Always wait for `networkidle` or use `assert_visible` before assertions - **Selector fragility**: Prefer text-based selectors (`text=Login`) over CSS paths - **Video size**: Videos can be large; disable with omitting `--video` flag for quick runs - **Word parsing ambiguity**: If `parse_docx.py` cannot identify test cases, present the raw Markdown to the user and ask them to confirm the JSON structure --- ## Dependencies Installation ```bash # Python dependencies pip install playwright python-docx Pillow jinja2 pandoc # Playwright browser playwright install chromium # pandoc (system-level) # Windows: winget install --id JohnMacFarlane.Pandoc # macOS: brew install pandoc # Linux: apt install pandoc ``` ````