scoutqa-test

ScoutQA 測試技能

使用 scoutqa CLI 對網頁應用程式執行 AI 驅動的探索性測試。

將 ScoutQA 視為一個智慧測試夥伴，能夠自主探索、發現問題並驗證功能。將測試委派給多個並行的 ScoutQA 執行，以最大化測試涵蓋率，同時節省時間。

何時使用此技能

在兩種情況下使用此技能：

1. 使用者要求測試 - 當使用者明確要求測試網站或驗證功能時
2. 主動驗證 - 在實作網頁功能後，自動執行測試以驗證實作是否正確

主動使用範例：

• 實作登入表單後 → 測試驗證流程
• 加入表單驗證後 → 驗證驗證規則和錯誤處理
• 建立結帳流程後 → 測試端到端購買流程
• 修復錯誤後 → 驗證修復是否有效且未破壞其他功能

最佳實踐：當你完成實作一個網頁功能後，主動在背景啟動 ScoutQA 測試來驗證功能，同時繼續處理其他任務。

執行測試

測試工作流程

複製此檢查清單並追蹤進度：

測試進度：

• [ ] 撰寫具體的測試提示，包含明確的期望
• [ ] 在背景執行 scoutqa 指令
• [ ] 告知使用者執行 ID 和瀏覽器 URL
• [ ] 提取並分析結果

步驟 1：撰寫具體的測試提示

請參閱下方「撰寫有效提示」章節的指引。

步驟 2：執行 scoutqa 指令

重要：使用 Bash 工具的 timeout 參數（5000ms = 5 秒）來擷取執行細節：

呼叫 Bash 工具時，設定 timeout: 5000 作為參數：

• 這是 Claude Code 中 Bash 工具的內建 timeout 參數（非 Unix 的 timeout 指令）
• 5 秒後，Bash 工具會回傳控制權，並附帶一個任務 ID，而程序會繼續在背景執行
• 這與 Unix 的 timeout 不同，後者會終止程序——這裡的程序會持續執行
• 前 5 秒會從 ScoutQA 的輸出中擷取執行 ID 和瀏覽器 URL
• 測試會繼續在 ScoutQA 的基礎設施上遠端執行，並以背景任務方式運作

scoutqa --url "https://example.com" --prompt "你的測試指示"

在前幾秒內，指令會輸出：

• 執行 ID（例如 019b831d-xxx）
• 瀏覽器 URL（例如 https://app.scoutqa.ai/t/019b831d-xxx）
• 顯示測試進度的初始工具呼叫

在 5 秒超時後，Bash 工具會回傳一個任務 ID，而指令會繼續在背景執行。你可以在測試執行期間處理其他任務。超時僅用於擷取初始輸出（執行 ID 和瀏覽器 URL）——測試會繼續在本地端以背景任務執行，同時也在 ScoutQA 的基礎設施上遠端執行。

步驟 3：告知使用者執行 ID 和瀏覽器 URL

在 Bash 工具回傳任務 ID（已在前 5 秒擷取執行細節）後，告知使用者：

• ScoutQA 執行 ID 和瀏覽器 URL，以便他們在瀏覽器中監控進度
• 背景任務 ID，以便他們稍後檢查本地指令輸出

測試會繼續在背景執行，同時你繼續處理其他工作。

步驟 4：提取並分析結果

請參閱下方「呈現結果」章節以了解完整格式。

指令選項

• --url（必要）：要測試的網站 URL（支援 localhost / 127.0.0.1）
• --prompt（必要）：自然語言的測試指示
• --project-id（選用）：關聯到一個專案以便追蹤
• -v, --verbose（選用）：顯示所有工具呼叫，包括內部呼叫

本地測試支援

ScoutQA 支援自主測試 localhost 和 127.0.0.1 URL——無需手動設定。

# 在開發應用程式時，無縫測試本地執行的應用程式
scoutqa --url "http://localhost:3000" --prompt "測試註冊表單"

何時使用各指令

開始新測試？ → 使用 scoutqa --url --prompt
驗證已知問題？ → 使用 scoutqa issue-verify --issue-id <id>
從執行中尋找問題 ID？ → 使用 scoutqa list-issues --execution-id <id>
代理需要更多上下文？ → 使用 scoutqa send-message（請參閱「追蹤卡住的執行」）

撰寫有效提示

專注於要探索和驗證的內容，而非指示性的步驟。ScoutQA 會自主決定如何測試。

範例：使用者註冊流程

scoutqa --url "https://example.com" --prompt "
探索使用者註冊流程。測試表單驗證的邊界情況，
驗證錯誤處理，並檢查無障礙合規性。
"

範例：電子商務結帳

scoutqa --url "https://shop.example.com" --prompt "
測試結帳流程。驗證價格計算、購物車持久性、
付款選項和行動裝置響應式設計。
"

範例：執行並行測試以獲得全面涵蓋率

在單一訊息中多次呼叫 Bash 工具來啟動多個並行測試，每次呼叫都將 Bash 工具的 timeout 參數設為 5000（毫秒）：

# 測試 1：驗證與安全性
scoutqa --url "https://app.example.com" --prompt "
探索驗證機制：登入/登出、會話處理、密碼重設、
以及安全性邊界情況。
"

# 測試 2：核心功能（並行執行）
scoutqa --url "https://app.example.com" --prompt "
測試儀表板與主要使用者工作流程。驗證資料載入、
CRUD 操作和搜尋功能。
"

# 測試 3：無障礙（並行執行）
scoutqa --url "https://app.example.com" --prompt "
執行無障礙稽核：WCAG 合規性、鍵盤導航、
螢幕閱讀器支援、色彩對比。
"

實作方式：發送一條包含三次 Bash 工具呼叫的訊息。每次呼叫 Bash 工具時，將 timeout 參數設為 5000 毫秒。5 秒後，每次 Bash 呼叫會回傳一個任務 ID，而程序會繼續在背景執行。這會從每個測試的初始輸出中擷取執行 ID 和瀏覽器 URL，然後三個測試會繼續並行執行（同時在本地端背景任務和 ScoutQA 的基礎設施上遠端執行）。

關鍵指引：

• 描述要測試什麼，而非如何測試（ScoutQA 會找出步驟）
• 專注於目標、邊界情況和關注點
• 針對不同測試領域執行多個並行執行
• 信任 ScoutQA 能自主探索並發現問題
• 呼叫 scoutqa 指令時，務必將 Bash 工具的 timeout 參數設為 5000 毫秒（這會在 5 秒後回傳控制權，同時程序繼續在背景執行）
• 對於並行測試，在單一訊息中多次呼叫 Bash 工具
• 記住：Bash 工具超時 ≠ Unix timeout 指令（Bash 超時會讓程序在背景繼續執行，Unix timeout 則會終止它）

常見測試場景

部署後冒煙測試：

scoutqa --url "$URL" --prompt "
冒煙測試：驗證部署後關鍵功能是否正常運作。
檢查首頁、導航、登入/登出以及主要使用者流程。
"

無障礙稽核：

scoutqa --url "$URL" --prompt "
稽核無障礙：WCAG 2.1 AA 合規性、鍵盤導航、
螢幕閱讀器支援、色彩對比和語意化 HTML。
"

電子商務測試：

scoutqa --url "$URL" --prompt "
探索電子商務功能：產品搜尋/篩選、
購物車操作、結帳流程和價格計算。
"

SaaS 應用程式：

scoutqa --url "$URL" --prompt "
測試 SaaS 應用程式：驗證、儀表板、CRUD 操作、
權限和資料完整性。
"

表單驗證：

scoutqa --url "$URL" --prompt "
測試表單驗證：邊界情況、錯誤處理、必填欄位、
格式驗證和成功提交。
"

行動裝置響應式設計：

scoutqa --url "$URL" --prompt "
檢查行動裝置體驗：響應式佈局、導航、
觸控互動和視口行為。
"

驗證已知問題：

# 首先，從先前的執行中尋找問題 ID
scoutqa list-issues --execution-id <executionId>

# 然後驗證問題（會自動建立新的驗證執行）
scoutqa issue-verify --issue-id <issueId>

issue-verify 指令會：

1. 為該問題建立一個驗證執行
2. 顯示執行 ID 和瀏覽器 URL
3. 即時串流代理的驗證進度
4. 顯示完成摘要，並附上結果連結

功能驗證（實作後）：

scoutqa --url "$URL" --prompt "
驗證新的[功能名稱]是否正常運作。測試核心功能、
邊界情況、錯誤處理以及與現有功能的整合。
"

範例：編寫功能後主動測試

在實作使用者註冊表單後，自動驗證其是否正常運作：

scoutqa --url "http://localhost:3000/register" --prompt "
測試新實作的使用者註冊表單。驗證：
- 表單驗證（電子郵件格式、密碼強度、必填欄位）
- 錯誤訊息正確顯示
- 成功註冊流程
- 邊界情況（重複電子郵件、特殊字元等）
"

這能在實作仍在上下文中時立即發現問題。

列出問題

使用 scoutqa list-issues 瀏覽先前執行中發現的問題。這有助於尋找問題 ID 以搭配 issue-verify 使用。

scoutqa list-issues --execution-id <executionId>

選項：

• --execution-id（必要）：執行 ID（來自 /t/<executionId> URL 或 CLI 輸出）

範例輸出：

顯示 3 個問題：

🔴 019c-abc1
   登入按鈕在行動裝置上無回應
   嚴重性：嚴重 | 類別：可用性 | 狀態：開啟

🟠 019c-abc2
   電子郵件欄位缺少表單驗證
   嚴重性：高 | 類別：功能 | 狀態：開啟

🟡 019c-abc3
   頁尾連結色彩對比不足
   嚴重性：中 | 類別：無障礙 | 狀態：已解決

呈現結果

立即呈現（啟動測試後）

在執行 scoutqa 指令後，立即向使用者呈現執行細節：

**ScoutQA 測試已啟動**

執行 ID：`019b831d-xxx`
即時檢視：https://app.scoutqa.ai/t/019b831d-xxx

測試正在遠端執行。你可以在瀏覽器中透過上方連結查看即時進度，同時我會繼續處理其他任務。

最終結果（完成後）

當執行完成時，使用此格式呈現發現：

**ScoutQA 測試結果**

執行 ID：`ex_abc123`

**發現的問題：**

[高] 無障礙：Logo 圖片缺少替代文字

- 影響：螢幕閱讀器無法描述 Logo
- 位置：頁首導航

[中] 可用性：提交按鈕在行動裝置視口中不可見

- 影響：使用者在行動裝置上無法完成表單
- 位置：聯絡表單，頁面底部

[低] 功能：搜尋有效查詢時未傳回結果

- 影響：搜尋功能看似故障
- 位置：主要搜尋列

**摘要：** 在無障礙、可用性和功能類別中共發現 3 個問題。請在上方 URL 查看包含螢幕截圖的完整互動式報告。

務必包含：

• 執行 ID（例如 ex_abc123）以供參考
• 發現的問題，包含嚴重性、類別（無障礙、可用性、功能）、影響和位置

追蹤卡住的執行

如果遠端代理卡住或需要釐清，使用 send-message 繼續：

# 範例：代理卡在登入，使用者提供憑證
scoutqa send-message --execution-id ex_abc123 --prompt "
使用這些測試憑證：使用者名稱：testuser@example.com，密碼：TestPass123
"

# 範例：代理詢問接下來要測試哪個流程
scoutqa send-message --execution-id ex_abc123 --prompt "
接下來專注於結帳流程，跳過願望清單功能
"

檢查測試結果

ScoutQA 測試會在 ScoutQA 的基礎設施上遠端執行。在啟動測試並使用短超時來擷取執行 ID 後：

1. 測試會繼續遠端執行（非本地端背景）
2. 你可以立即繼續其他工作
3. 稍後若要檢查結果，請造訪測試啟動時提供的瀏覽器 URL
4. 或者，使用 scoutqa get-execution --execution-id <id> 透過 CLI 取得結果

最佳實踐：啟動測試時，將 Bash 工具的 timeout 參數設為 5000 毫秒。5 秒後，Bash 工具會回傳控制權，並附帶任務 ID 和執行細節（執行 ID 和瀏覽器 URL），同時測試會繼續在背景執行。然後你可以繼續其他工作，並在需要時在 ScoutQA 網站或透過 CLI 檢查結果。

疑難排解

問題	解決方案
command not found: scoutqa	安裝 CLI：npm i -g @scoutqa/cli@latest
驗證過期 / 未授權	執行 scoutqa auth login
測試卡住或需要輸入	使用 scoutqa send-message --execution-id
檢查測試結果	造訪瀏覽器 URL 或 scoutqa get-execution --execution-id
需要問題 ID 進行驗證	執行 scoutqa list-issues --execution-id <id>