webapp-testing

網頁應用程式測試

此技能可透過 Playwright 自動化，對本地網頁應用程式進行全面的測試與除錯。

應盡可能使用 Playwright MCP Server 來執行工作。若 MCP Server 無法使用，您可以在已安裝 Playwright 的本地 Node.js 環境中執行程式碼。

何時使用此技能

當您需要以下操作時，請使用此技能：

• 在真實瀏覽器中測試前端功能
• 驗證 UI 行為與互動
• 除錯網頁應用程式問題
• 為文件或除錯擷取螢幕截圖
• 檢查瀏覽器主控台日誌
• 驗證表單提交與使用者流程
• 檢查不同視窗尺寸下的響應式設計

先決條件

• 系統已安裝 Node.js
• 本地運行的網頁應用程式（或可存取的 URL）
• Playwright 會在需要時自動安裝

核心功能

1. 瀏覽器自動化

• 導航至 URL
• 點擊按鈕與連結
• 填寫表單欄位
• 選擇下拉選單
• 處理對話框與警示

2. 驗證

• 斷言元素存在
• 驗證文字內容
• 檢查元素可見性
• 驗證 URL
• 測試響應式行為

3. 除錯

• 擷取螢幕截圖
• 檢視主控台日誌
• 檢查網路請求
• 除錯失敗的測試

使用範例

範例 1：基本導航測試

// 導航至頁面並驗證標題
await page.goto("http://localhost:3000");
const title = await page.title();
console.log("頁面標題：", title);

範例 2：表單互動

// 填寫並提交表單
await page.fill("#username", "testuser");
await page.fill("#password", "password123");
await page.click('button[type="submit"]');
await page.waitForURL("**/dashboard");

範例 3：擷取螢幕截圖

// 為除錯擷取螢幕截圖
await page.screenshot({ path: "debug.png", fullPage: true });

使用指南

1. 務必確認應用程式正在執行 - 在執行測試前，檢查本地伺服器是否可存取
2. 使用明確等待 - 在互動前，等待元素或導航完成
3. 失敗時擷取螢幕截圖 - 拍攝螢幕截圖以協助除錯問題
4. 清理資源 - 完成後務必關閉瀏覽器
5. 妥善處理逾時 - 為較慢的操作設定合理的逾時時間
6. 逐步測試 - 從簡單的互動開始，再進行複雜流程
7. 明智使用選擇器 - 優先使用 data-testid 或基於角色的選擇器，而非 CSS 類別

常見模式

模式：等待元素

await page.waitForSelector("#element-id", { state: "visible" });

模式：檢查元素是否存在

const exists = (await page.locator("#element-id").count()) > 0;

模式：取得主控台日誌

page.on("console", (msg) => console.log("瀏覽器日誌：", msg.text()));

模式：處理錯誤

try {
  await page.click("#button");
} catch (error) {
  await page.screenshot({ path: "error.png" });
  throw error;
}

限制

• 需要 Node.js 環境
• 無法測試原生行動應用程式（請改用 React Native Testing Library）
• 可能對複雜的驗證流程有問題
• 某些現代框架可能需要特定設定

輔助函式

test-helper.js 中提供了一些輔助函式，可簡化常見任務，例如等待元素、擷取螢幕截圖及處理錯誤。您可以在測試中匯入並使用這些函式，以提高可讀性與可維護性。