run_tests
Execute the test suite under the active QA runner and produce a structured report. Supports filter to narrow test scope and auto-refreshes optimization plan.
Instructions
Execute the test suite under the active QA_RUNNER and produce a structured report. The single most-called tool — invoke whenever a user says 「跑/run/test/check/驗證/執行」, after generate_test (verify new test), or after a fix (confirm bug gone).
Behavior:
Invokes the runner's native CLI under QA_PROJECT_ROOT — pytest with --screenshot=on / --tracing=on / --video=retain-on-failure, or
npx jest --json,npx cypress run --reporter json,go test -json,maestro test --format junitOptional
filternarrows the scope: pytest -k expr, jest -t pattern, cypress --spec glob, go -run regex, maestro flow-name substringWrites report.json (pytest-json-report shape, runner-agnostic) + JUnit XML
Snapshots the run into history/ and auto-triggers optimizer.write_plan() → optimization-plan.md is refreshed
Maestro: auto-retries flows that failed on first attempt (MAESTRO_RETRY=true), surfaces flaky_in_run count Returns: {exit_code, raw_exit_code, stdout_tail, stderr_tail, retry_enabled, flaky_in_run, ...}
When to use:
After writing a new test → verify it actually passes
Smoke before a release
Whenever the user prompt contains a run/test verb
When NOT to use:
Inspecting last results without re-running → use get_test_report (cheaper)
Re-running only failed cases → use run_failed (way faster)
Enumerating which tests exist → use list_tests
Edge cases:
No tests match
filter→ exit_code != 0 with 「no tests ran」 in stderr_tailQA_TIMEOUT_SECONDS exceeded → exit_code 124 +
[TIMEOUT…]tag in stderr_tailfilterstarting with-or containing..→ blocked by security guardrail, returns {error: …}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | 選填，測試名稱關鍵字。pytest 走 -k 表達式（支援 and/or/not）、Jest 走 -t、Cypress 走 --spec '**/*<filter>*'、Go 走 -run regex、Maestro 在 flow 檔名作子字串比對。 | |
| headed | No | 選填，僅對 pytest-playwright 有效。True 時瀏覽器有 UI 模式跑（適合 debug、看 flake 視覺現象）；預設 headless 跑、CI / 大量套件用這個。 | |
| browser | No | 選填，僅對 pytest-playwright 有效，指定 Playwright 啟用的 browser engine。需事先 `playwright install <browser>` 過。 | chromium |