成員 1 · 迴圈的執行端

讓我們把 QA 簡單化。

AI 測試大師 · MK QA MASTER

mk-qa-master 是一個 MCP server，讓 AI client 幫你跑 Web（pytest / Jest / Cypress / Go）、手機（Maestro · iOS + Android · 含 BlueStacks）跟 API 測試（你 pytest / Jest / Cypress / Go test 裡用 httpx / supertest / cy.request 寫的 API 測試一樣吃）——從 URL 或當下手機畫面寫下一輪 TC，每跑完一次當你的「資料驅動 QA 優化顧問」。

GitHub → PyPI 看完整文件
驅動以下任一測試 framework
pytest + Playwright Jest Cypress go test Maestro · iOS + Android
範圍

這「不」是什麼

mk-qa-master 站在 AI client 跟測試 framework 之間。它不是 framework、不是 LLM、不是 CI runner、不是 source-code 分析器、也不是 SaaS UI。

測試 framework
→ 你帶 pytest / Jest / Cypress / Go test / Maestro 進來——qa-master 負責驅動它們
LLM
→ 推理交給你的 AI client（Claude / Cursor / Codex / Gemini）。qa-master 只 expose tool
CI runner
→ 本地跑 + 產 JUnit XML / HTML 報告。把 JUnit 接進 GitHub Actions / Jenkins / GitLab 是你的事
原始碼分析器
→ 分析的是 live DOM（Web）/ view hierarchy（手機），不是你 repo 的 source code
SaaS 儀表板
→ MCP-native，住在 AI client 裡。HTML 報告就是一個自包含 .html 檔
功能

三件事。一個 server。Web + 手機。

按你會用到的頻率排。

▶

跨框架跑測試 · Web 跟手機

用 QA_RUNNER 環境變數切 framework：Web 走 pytest / Jest / Cypress / Go，手機走 maestro（iOS Simulator、Android Emulator、實體機、BlueStacks 都吃）。內建 auto-retry、JUnit XML、截圖、Playwright trace.zip / Maestro recordings。

✎

從 URL 或當下畫面寫測試

analyze_url 偵測 DOM、analyze_screen 抓手機畫面 hierarchy。兩者都拆出 form / cta / nav / tab-bar 模塊與真實 selector，再由 generate_test 產生可直接跑的 pytest 或 Maestro YAML — 不是 # TODO 占位符。

⚡

你的 QA 優化顧問

每次 run 自動快照並寫一份新的 optimization-plan.md。flaky / broken / slow_regression 排序，每條都附證據——不是憑感覺。Web 跟手機共用同一條迴圈。

流程

一個會自我修正的迴圈

每次 run 餵 optimizer、optimizer 指出最弱環節、下次 run 優先攻那一環。沒有這個迴圈、AI 只是個更快的 monkey tester。

分析
analyze_url / analyze_screen
Web 偵測 DOM、手機抓 hierarchy → form / cta / nav 模塊 + 真實 selector。
產生
generate_test / auto_generate_tests
對抓到的模塊產可直接跑的 pytest .py 或 Maestro .yaml——不是 # TODO 占位符。
執行
run_tests / run_failed
驅動原生 runner，產 JUnit XML、截圖、trace.zip / Maestro 錄影。
回報
get_test_report / get_failure_details
outcome 字串 + error signature + history 快照。下一步餵給顧問。
顧問
get_optimization_plan
三個視角（套件 / MCP / AI）→ 排序好的下次 run 行動清單。迴圈在這裡閉合。
↻ 下次 run 優先攻最弱的那條
領域知識的三層架構

不只看 DOM、更要懂業務

光看 DOM 的 analyzer 只能產「空欄位送出應出錯」這種泛例——就是換包裝的 monkey testing。所以我們疊了三層真 QA 知識。

內建
ISTQB 七大原則、等價分割、邊界值、決策表、狀態轉換、測試金字塔、Shift-Left、Mobile checklist、QA metrics。全部內建在 server。
你的檔案
把 qa-knowledge.md 放進專案根目錄：業務規則、歷史 Bug、標準斷言文字、user journey、技術約束。init_qa_knowledge 一鍵起手範本。
Per-test inline
把領域知識 slice 透過 business_context 帶進 generate_test，自動印成 # Business context: 註解區塊在 test 函式裡，reviewer 不用切到別的 wiki 就看得到「為什麼測這個」。
優化顧問

從三個視角看你的工作

每次 run 結束、顧問讀 history/ + telemetry log，寫一份排序好的行動清單。三個視角：

測試品質

每條 test 的 outcomes 字串（PFPFP）算 flake_score，加上 error signature 比對。連 3 次失敗 + 相同 signature → 標 broken（真 bug、不是 flake）。

MCP 易用性

Tool 呼叫 telemetry 找 top tool、錯誤率、重複 args、常見鏈（A→B）。告訴你哪裡可以包 meta-tool 或加 cache。

AI 有效度

generate_test 寫的測試有沒有出現在下次 run？analyze_url 偵測的模塊有沒有對應 test 檔？採用率 vs 覆蓋缺口、全部追蹤。

Runner

7 個 runner、共用一組 tool

用 QA_RUNNER 環境變數切。七種 framework、同一個 MCP 介面——四種 Web、手機走 Maestro、API 走 Schemathesis（OpenAPI / Swagger，v0.6.0 起）或 Newman（Postman collection，v0.6.1 起）。既有的 API 測試（pytest + httpx / Jest + supertest / Cypress cy.request() / Go httptest）繼續搭原 runner、不用搬家。Pact provider 驗證在 v0.7.0 roadmap。

pytest-playwright
env: QA_RUNNER=pytest
since 0.1.0
jest
env: QA_RUNNER=jest
since 0.2.0
cypress
env: QA_RUNNER=cypress
since 0.2.0
go test
env: QA_RUNNER=go
since 0.2.0
maestro（iOS + Android + BlueStacks）
env: QA_RUNNER=maestro（+ 選用 QA_ANDROID_HOST 給 BlueStacks）
since 0.3.0
schemathesis（OpenAPI / Swagger）
env: QA_RUNNER=schemathesis + QA_OPENAPI_URL（http(s):// 或 file://）；裝 mk-qa-master[api]
since 0.6.0
newman（Postman collection）
env: QA_RUNNER=newman + QA_POSTMAN_COLLECTION（路徑）；系統前置：npm install -g newman
since 0.6.1
Tool 表

16 個 tool、分 5 個角色

按角色分組。每組是 analyze → generate → run → report → advise 迴圈的一層。README 的 prompting cookbook 有中文自然語句寫法——你很少需要自己叫 tool 名稱。

Discover — 暖機 + 掃描
  • get_runner_info — 目前用哪個 runner、有哪些可用——session 第一個叫，讓 AI 知道後面要產 Playwright .py 還是 Maestro .yaml
  • list_tests — 用 runner 原生機制列全部可執行測試——pytest --collect-only、jest --listTests、cypress glob、go -list、maestro YAML 遞迴
  • analyze_url — Web：偵測 live URL → form / nav / dialog / cta 模塊 + selectors + 頁面打過的 API endpoints + 跑版警告 + candidate TC
  • analyze_screen — 手機：dump maestro hierarchy → form / cta / tab_bar 模塊 + candidate TC，自動濾掉 iOS 狀態列 + asset 名稱噪音
Generate — 模塊變可跑測試
  • generate_test — test 骨架；帶 analyze_url/analyze_screen 的 module 進來時，產可直接跑的 Playwright .py 或 Maestro .yaml——真 selector、不是 # TODO
  • auto_generate_tests — 一鍵：analyze_url → 每個 module 產一條 test。給 URL，回 tests/ 資料夾
  • codegen — 啟動 Playwright codegen（Web）/ 提示用 maestro studio（手機）。錄基準 happy-path 用
  • init_qa_knowledge — 在 project root 起 qa-knowledge.md 範本——業務規則 / 歷史 Bug / 標準斷言 / user journey / 技術約束
  • get_qa_context — 讀 qa-knowledge.md（內建 ISTQB fallback）。把相關段落帶進 generate_test.business_context 寫有業務知識的測試
Run — 執行測試套件
  • run_tests — 用 active runner 跑；產 report.json + JUnit XML、snapshot 到 history/、自動更新 optimization-plan.md。可選 filter
  • run_failed — 只重跑上次失敗——pytest --lf、jest --onlyFailures、cypress/go 反查、maestro nodeid → .yaml。比整套快很多
Report — 看剛剛發生什麼
  • get_test_report — 摘要：passed / failed / skipped / flaky_in_run / duration。便宜——多輪操作中間反覆查狀態用
  • get_failure_details — 每條失敗的 message + screenshot + Playwright trace.zip + video 路徑 + 解析的 step 序列。「為什麼 fail」一鍵答
  • generate_html_report — 把最近一次 run 渲染成一個自包含 HTML——base64 截圖、trend sparkline、Passed 收合 / Failed 展開。可丟 Slack
  • get_test_history — 最近 N 次歸檔 run 摘要——flake / duration 退化 / pass-rate trend。要可執行建議接 get_optimization_plan
Advisor — 自我強化教練
  • get_optimization_plan — 三層排序好的行動清單：套件品質（flake / broken / slow_regression）+ MCP 使用（top tool、重複 args、錯誤率）+ AI 效益（generate_test 採用率、覆蓋缺口）。每次 run 自動寫 optimization-plan.md
工作流程

四個 prompt 涵蓋 ~90% 的真實用法

一句話給 AI client，工具自動串。

1.

"測 https://your-site/login——分析頁面、對每個模塊寫測試、跑、再告訴我要修什麼。"

analyze_url → generate_test (×N modules) → run_tests → get_failure_details → get_optimization_plan
2.

"我剛加了三個新功能頁——analyzer 找到什麼就自動產測試、跑起來。"

auto_generate_tests(url=...) → run_tests → get_test_report → get_optimization_plan
3.

"這週測試套件哪裡爛——給我排序好的行動清單，不要憑感覺。"

get_test_history(limit=30) → get_optimization_plan(history_limit=30, telemetry_limit=2000)
4.

"在 iOS Simulator 上測我 app 的條碼按鈕，順便告訴我它會不會 flaky。"

analyze_screen(app_id='com.example.app', launch_app=true) → generate_test(module=<cta>) → run_tests → get_optimization_plan
範例輸出

你實際會拿到什麼

跟 spec-master 同一套形式——markdown，可直接 paste 進 Slack / JIRA / sprint planning doc。每次 run 完自動寫。

get_optimization_plan

# Optimization Plan — 2026-05-12T14:03:40

_Based on 6 archived runs._

## Prioritized Actions

### 1. 🔴 HIGH — flaky
- **Target**: `tests/test_login.py::test_invalid_credentials`
- **Evidence**: flake_score=0.4, outcomes=PFPFP, rerun_count=1
- **Suggestion**: 加 explicit wait（wait_for_response / locator wait）
- **auto_action_hint**: `get_failure_details(test_id="test_invalid_credentials")`

### 2. 🟡 MEDIUM — coverage_gap
- **Target**: `register_form`（analyze_url 在 /register 偵測到的模塊）
- **Evidence**: analyze_url 偵測但 repo 內找不到對應 test_*.py
- **Suggestion**: `generate_test(description="...", filename="test_register_form.py")`

### 3. 🟡 MEDIUM — slow_regression
- **Target**: `tests/test_checkout.py::test_full_flow`
- **Evidence**: 最近 6 次 run，median duration 1.8× baseline
- **Suggestion**: 看 network wait 用法、固定 fixture data、考慮 parallel mark

## MCP usability
- Top tool：`run_tests` (38%) · `analyze_url` (22%) · `get_failure_details` (14%)
- 常見呼叫鏈：`analyze_url → generate_test`（出現 17 次）
- 錯誤率：2.3%（1 次 analyze_url 在慢 staging 上 timeout）

## AI 有效度
- generate_test 採用率：11 條產出有 9 條出現在下次 run（82%）
- 覆蓋缺口：1 個 analyze_url 偵測的模塊沒有對應 test 檔（`register_form`）

get_test_report + get_failure_details

# Test Report — pytest-playwright

- total: 23
- passed: 19
- failed: 3
- flaky_in_run: 1   ← auto-retry 救回
- skipped: 0
- duration: 31.4s

## Failures
1. `tests/test_login.py::test_invalid_credentials`
   - message: `AssertionError: 預期錯誤訊息未顯示`
   - screenshot: `test-results/.../test-failed-1.png`
   - trace:      `test-results/.../trace.zip`
   - video:      `test-results/.../video.webm`

2. `tests/test_coupon.py::test_idempotency`
   - message: `Timeout 等 /api/coupon (5000ms)`
   - last step: `Page.waitForResponse('/api/coupon')`

加進 MCP client config

重啟 client，然後就用你平常跟 AI 對話的方式講就好。

{
  "mcpServers": {
    "mk-qa-master": {
      "command": "uvx",
      "args": ["mk-qa-master"],
      "env": {
        "QA_RUNNER": "pytest",
        "QA_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}
看完整文件 → 姐妹專案 → mk-spec-master