Playwright 測試Skills 最佳實踐
整理版優先睇
本文總結 Playwright 測試嘅最佳實踐，包括 8 條黃金法則、從零落地步驟同高頻踩坑對照，幫你 CI/CD 又快又穩。
呢篇文章係由一位有豐富自動化測試經驗嘅作者分享，佢見到好多開發者喺用 Playwright 做 E2E 測試時，成日遇到 CI 又慢又紅、本地復現唔到、選擇器脆皮等問題。作者認為呢啲問題多數唔係 Playwright 本身有問題，而係開發者冇守住「可維護、可重試、少等待」呢幾條基本線。
整體結論係：只要跟住 8 條黃金法則，再配合從零落地嘅步驟，同避開高頻踩坑位，就可以令 CI/CD 又快又穩。文章分為四大部分：第一係 8 條黃金法則，每條都對應真實案例；第二係從零安裝到寫第一條用例嘅步驟；第三係常見踩坑對照；第四係 Playwright 其他用途。
作者特別強調，選擇器要用用戶視角（如 getByRole），斷言要用自帶重試（如 toHaveText），等待要用條件滿足（如 toBeVisible），而唔係硬等。佢仲提醒，測試隔離、baseURL 配置、重試 + trace 呢啲做法係 CI 穩定嘅關鍵。
- 選擇器要用用戶視角定位，避免同 class 綁死，用 getByRole、getByText 等。
- 用條件等待取代固定秒數，expect 自帶重試令斷言更穩。
- 測試隔離係 CI 並行嘅基礎，每個用例要獨立可跑，唔好共享狀態。
- 配置 baseURL 同 retries+trace，令切換環境同排障更簡單。
- 從零落地只需幾步：安裝 Playwright、裝瀏覽器驅動、寫第一條用例，配合 Skill 可以加速。
8 條黃金法則，條條對應真實案例
選擇器：別跟 class 綁在一起
問題長啥樣：CSS、XPath 死死綁喺 DOM 細節上，前端一改版，你連夜改用例。為啥會咁：選擇器同實現耦合，結構一變就失效。
點搞：用「用戶視角」定位，改版耐扛啲。推薦用 getByRole()、getByText()、getByLabel()，盡量唔好用 locator('#id') 或者 locator('.class')。
硬等待：pipeline 嘅減速帶
問題長啥樣：page.waitForTimeout(3000)——等短咗偶發掛，等長咗全組陪你等。點搞：用「條件滿足」替代固定秒數，交給 Playwright 自動重試。推薦 expect(locator).toBeVisible()、toBeEnabled()、page.waitForURL()，盡量唔好用 page.waitForTimeout()。
測試隔離：CI 會亂序、會並行。唔好共享 page/context 以外嘅「可變全局狀態」，用 test.extend() 或 fixture 共享「點樣創建」，而唔係共享「同一個實例」。標準係：任意一條單獨跑都要過，唔依賴先後順序。
baseURL：換環境唔好改代碼
寫死 page.goto('https://xxx.com/login') 會搞死自己。喺 playwright.config.ts 配好 use.baseURL，用例入面只寫 page.goto('/login')。換環境？改配置或者環境變量就得。
重試 + trace：線上要體面，排障要留痕
CI 設定 retries: process.env.CI ? 2 : 0，本地用 retries: 0。trace 設為 'on-first-retry'，淨係喺首次重試時抓，唔拖慢平時 pipeline。
Fixture 優先：全局變量係並行時嘅雷
模塊頂層嘅 page、登錄態會令用例耦合，一並行就互相踩。用 test.extend() 封裝「已登錄嘅 page」或者「帶 baseURL 嘅 context」，千祈唔好喺文件頂層掛可變 page/context。
單一職責 + mock 邊界
每個用例只驗證一種核心行為，多個 expect 可以，但主線要清晰。只 mock 外部依賴（第三方 API、支付、郵件），唔好 mock 自家業務代碼呃自己。
從零落地：安裝 → 配置 → 第一條用例
大概 5 至 10 分鐘，你可以跑通一條「能入 CI」嘅用例。下面命令建議直接複製，唔好去搜三年前嘅博客。
第一步：項目與依賴。前提係 Node.js 16+，太低會怪報錯。執行：
mkdir mytest && cd mytest
npm init -y
# 安裝
npm install -D @playwright/test
# 首次安裝瀏覽器驅動（關鍵！否則會報錯）
npx playwright install
# Windows 系統額外安裝依賴（可選）
npx playwright install-deps第二步：瀏覽器驅動只裝 npm 包唔等於裝好瀏覽器。CI 鏡像入面都係一樣。新手省事就全裝，想省時間只裝 Chromium：npx playwright install chromium。驗證是否 OK 可以用 npx playwright test。
第三步：用 Skill 加速寫用例。你可以直接叫 Playwright Skill 根據頁面或者需求生成測試腳本，喺 Chrome 入面跑通，再睇 HTML 報告。同 8 條法則唔衝突：生成完再按法則收一遍選擇器、斷言同等待，CI 先穩。
在谷歌瀏覽器執行測試用例，最後查看測試報告
高頻踩坑對照，改完會多謝我
斷言：expect(await page.locator('.title').textContent()).toBe('歡迎')——無重試
正確做法：await expect(page.locator('.title')).toHaveText('歡迎')——自帶重試。
等待：await page.waitForTimeout(2000) 再點
正確做法：await expect(locator).toBeVisible() 再操作。
瀏覽器 / 設備：移動端用 test.use({ ...devices['iPhone 14'] })；多瀏覽器喺 projects 加 Firefox、WebKit。
除咗 E2E，Playwright 仲可以做 API 測試（request 上下文直接打接口）、視覺迴歸（expect(page).toHaveScreenshot()）、跨端測試（Chromium / Firefox / WebKit + 移動端模擬）。能力越大，越要記得：穩定來自規範，快來自少等、可並行。
每當我出自動化、CI相關嘅內容，後台總有人留言同一件事。
唔係用例寫錯，係成條 pipeline 又慢又紅。
改個前端 class，E2E 就死一片；CI 間中失敗，但本地點都重現唔到；仲有人一開波就 waitForTimeout(3000)，跑得慢仲覺得自己好穩。
講句或者有啲直白嘅話：
多數唔係 Playwright 唔掂，係你冇守住「可維護、可重試、少等待」呢幾條線。
抽十幾分鐘，跟住下面「黃金法則 → 點樣落地 → 踩坑」行一次，你嘅 CI/CD 真係有機會又快又穩。
一、Playwright 黃金法則：8 條，條條對應真實案例
1. 選擇器：唔好同 class 綁埋一齊
問題係點樣：
CSS、XPath 死綁喺 DOM 細節上面，前端一改版，你就要漏夜改 test case。
點解會咁：
選擇器同實現耦合，結構一變就失效。
咋整：
用「用戶視角」定位，改版就耐用啲。
- 推薦：getByRole()、getByText()、getByLabel()
- 盡量唔好：locator('#id')、locator('.class')（除非真係冇辦法）
2. 硬等：pipeline 嘅減速帶
問題係點樣：page.waitForTimeout(3000)——等短咗間中死，等長咗成組人陪你等。
咋整：
用「條件滿足」取代固定秒數，交俾 Playwright 自動重試。
- 推薦：expect(locator).toBeVisible()、toBeEnabled()、page.waitForURL()
- 可以唔用就唔用：page.waitForTimeout()
3. Web-first 斷言：頁面慢少少，唔好即刻判死刑
問題係點樣：expect(await locator.textContent()).toBe('xxx') 只判一次，網絡震一震你就誤報。
咋整：
用內置重試嘅斷言。
- 推薦：expect(locator).toHaveText('xxx')、toBeVisible()
- 別： 先 await 取值再 expect
4. 測試隔離：CI 係會亂次序、會並行㗎
問題係點樣：
用例共享狀態、依賴執行順序，本地串行全部綠，CI 單跑一條就死。
咋整：
- 唔好共享 page/context 以外嘅「可變全局狀態」
- 用 test.extend() 或者 fixture 共享「點樣建立」，唔好共享「同一個實例」
- 標準： 任意一條單獨跑都可以過，唔依賴先後次序
5. baseURL：轉環境唔好改 code
問題係點樣：
寫死 page.goto('https://xxx.com/login')，本地、預發、CI 轉環境就要改 code 改到嘔。
咋整：playwright.config.ts 裏配好 use.baseURL，用例裏面只寫 page.goto('/login')。
轉環境？改 config 或環境變量就得。
6. 重試 + trace：線上要體面，排障要留痕
問題係點樣：
CI 間中紅，成輪重跑心累；冇 trace，對住 log 估到天光。
咋整：
- CI：retries: process.env.CI ? 2 : 0（線上寬容啲）
- 本地：retries: 0（改 test case 要快）
- trace：trace: 'on-first-retry'——淨係喺第一次重試時收集，唔拖慢平時 pipeline
7. Fixture 優先：全局變量係並行時嘅地雷
問題係點樣：
模塊最頂層嘅 page、登入狀態，用例耦合，一並行就互相踩。
咋整：test.extend() 封裝「已登入嘅 page」「帶 baseURL 嘅 context」。
千祈唔好喺文件最頂層掛可變 page/context。
8. 單一職責 + mock 邊界
- 每個用例只驗證一種核心行為（多個 expect 可以，但主線要清晰）
- 只 mock 外部依賴（第三方 API、支付、郵件），唔好 mock 自己業務 code 呃自己
二、由零落地：安裝 → 配置 → 第一條用例
大概 5～10 分鐘，你可以跑通一條「可以入 CI」嘅用例。
下面指令建議你直接複製，唔好去揾嗰啲三年前嘅 blog，坑唔同。
第一步：項目與依賴
前提：Node.js 16+（太低會出各種奇怪 error）。
mkdir mytest && cd mytest
npm init -y
# 安裝
npm install -D @playwright/test
# 首次安裝瀏覽器驅動（關鍵！否則會報錯）
npx playwright install
# Windows 系統額外安裝依賴（可選）
npx playwright install-deps
安裝瀏覽器驅動咁就可以喺 trae 入面用 playwright-skill 喇
第二步：瀏覽器驅動
只裝 npm 包 不等於 裝好瀏覽器。CI 鏡像入面都係咁。
# 新手省事：全裝
npx playwright install
# 想省時間：只裝 Chromium
npx playwright install chromium
Windows 如果缺少系統依賴，可以按官方文檔執行 npx playwright install-deps（視情況）。
驗證係咪 OK：
npx playwright test第三步：用 Skill 加速寫用例
你可以直接俾 Playwright Skill 根據頁面或需求生成測試腳本，喺 Chrome 入面跑通，再睇 HTML 報告——同「8 條法則」唔衝突：生成完之後再按法則收一次選擇器、斷言同等待，CI 先至穩。
喺 Google Chrome 執行測試用例
最後睇測試報告
三、高頻踩坑：對住改，改完會多謝我
3.1 斷言
- expect(await page.locator('.title').textContent()).toBe('歡迎') —— 冇重試
- await expect(page.locator('.title')).toHaveText('歡迎') —— 內置重試
3.2 等待
- await page.waitForTimeout(2000) 再點
- await expect(locator).toBeVisible() 再操作
3.3 瀏覽器 / 裝置
- 手機端：test.use({ ...devices['iPhone 14'] })
- 多瀏覽器：喺 projects 入面加 Firefox、WebKit
3.4 「裝完 package 就走」——CI 入面最常見炒車
現象： 報錯揾唔到 chromium / firefox / webkit 可執行檔案。
原因： 只 npm install ，冇拉瀏覽器 binary。
辦法： Pipeline 入面顯式執行 npx playwright install chromium（或全量 install + 按需 install-deps）。
呢條同「Skill 好唔好用」無關，係 Playwright 嘅硬門檻。
四、Playwright 仲可以做啲乜（唔好淨係當點點點工具）
除咗 E2E，你仲可以：
- API 測試：request 上下文中直接打 API，同頁面流程組合
- 視覺回歸：expect(page).toHaveScreenshot()
- 跨端： Chromium / Firefox / WebKit + 手機模擬
能力越大，越要記住：穩定嚟自規範，快嚟自少等、可並行。
最後講幾句
我寫呢篇，係因為自己都經歷過「CI 通過率低、全部人等重跑」嗰種兩眼一黑。
Playwright 本身好打得，快同穩都係可以配置出嚟嘅。
選擇器好似用戶咁諗，斷言好似有耐性咁等，環境好似配置咁切。
微信交流羣：
只要我發自動化、CI 相關的內容，後台總有人留言同一件事。
不是用例寫錯了，是整條 pipeline 又慢又紅。
改個前端 class，E2E 掛一片；CI 上偶發失敗，本地卻死活復現不了；還有人一上來就 waitForTimeout(3000)，跑得慢還覺得自己很穩。
說句可能有點直白的話：
多半不是 Playwright 不行，是你沒守住「可維護、可重試、少等待」這幾條線。
抽十幾分鍾，按下面「黃金法則 → 怎麼落地 → 踩坑」走一遍，你的 CI/CD 真的有機會又快又穩。
一、Playwright 黃金法則：8 條，條條對應真實案例
1. 選擇器：別跟 class 綁在一起
問題長啥樣：
CSS、XPath 死死綁在 DOM 細節上，前端一改版，你連夜改用例。
為啥會這樣：
選擇器跟實現耦合，結構一變就失效。
咋整：
用「用戶視角」定位，改版耐扛一點。
- 推薦：getByRole()、getByText()、getByLabel()
- 儘量別：locator('#id')、locator('.class')（除非真沒轍）
2. 硬等待：pipeline 的減速帶
問題長啥樣：page.waitForTimeout(3000)——等短了偶發掛，等長了全組陪你等。
咋整：
用「條件滿足」替代固定秒數，交給 Playwright 自動重試。
- 推薦：expect(locator).toBeVisible()、toBeEnabled()、page.waitForURL()
- 能不用就不用：page.waitForTimeout()
3. Web-first 斷言：頁面慢一點，別立刻判死刑
問題長啥樣：expect(await locator.textContent()).toBe('xxx') 只判一次，網絡抖一下你就誤報。
咋整：
用自帶重試的斷言。
- 推薦：expect(locator).toHaveText('xxx')、toBeVisible()
- 別： 先 await 取值再 expect
4. 測試隔離：CI 可是會亂序、會並行的
問題長啥樣：
用例共享狀態、依賴執行順序，本地串行全綠，CI 單跑一條就掛。
咋整：
- 不共享 page/context 以外的「可變全局狀態」
- 用 test.extend() 或 fixture 共享「怎麼創建」，別共享「同一個實例」
- 標準： 任意一條單獨跑都能過，不依賴先後順序
5. baseURL：換環境別改代碼
問題長啥樣：
寫死 page.goto('https://xxx.com/login')，本地、預發、CI 切環境就改代碼改到吐。
咋整：playwright.config.ts 裏配好 use.baseURL，用例裏只寫 page.goto('/login')。
換環境？改配置或環境變量就行。
6. 重試 + trace：線上要體面，排障要留痕
問題長啥樣：
CI 偶發紅，整輪重跑心累；沒有 trace，對着日誌猜到天亮。
咋整：
- CI：retries: process.env.CI ? 2 : 0（線上寬容一點）
- 本地：retries: 0（改用例要快）
- trace：trace: 'on-first-retry'——只在首次重試時抓，不拖慢平時 pipeline
7. Fixture 優先：全局變量是並行時的雷
問題長啥樣：
模塊頂層的 page、登錄態，用例耦合，一併行就互相踩。
咋整：test.extend() 封裝「已登錄的 page」「帶 baseURL 的 context」。
千萬不要在文件頂層掛可變 page/context。
8. 單一職責 + mock 邊界
- 每個用例只驗證一種核心行為（多個 expect 可以，但主線要清晰）
- 只 mock 外部依賴（第三方 API、支付、郵件），別 mock 自家業務代碼糊弄自己
二、從零落地：安裝 → 配置 → 第一條用例
大概 5～10 分鐘，你能跑通一條「能進 CI」的用例。
下面命令建議你直接複製，別去搜那種三年前的博客，坑不一樣。
第一步：項目與依賴
前提：Node.js 16+（低了會各種怪報錯）。
mkdir mytest && cd mytest
npm init -y
# 安裝
npm install -D @playwright/test
# 首次安裝瀏覽器驅動（關鍵！否則會報錯）
npx playwright install
# Windows 系統額外安裝依賴（可選）
npx playwright install-deps安裝瀏覽器驅動這樣就可以在trae中使用playwright-skill了
第二步：瀏覽器驅動
只裝 npm 包 不等於 裝好瀏覽器。CI 鏡像裏也一樣。
# 新手省事：全裝
npx playwright install
# 想省時間：只裝 Chromium
npx playwright install chromiumWindows 若缺系統依賴，可按官方文檔執行 npx playwright install-deps（視情況）。
驗證是否 OK：
npx playwright test第三步：用 Skill 加速寫用例
你可以直接讓 Playwright Skill 根據頁面或需求生成測試腳本，在 Chrome 裏跑通，再看 HTML 報告——和「8 條法則」不衝突：生成完再按法則收一遍選擇器、斷言和等待，CI 才穩。
在谷歌瀏覽器執行測試用例
最後查看測試報告
三、高頻踩坑：對照改，改完會感謝我
3.1 斷言
- expect(await page.locator('.title').textContent()).toBe('歡迎') —— 無重試
- await expect(page.locator('.title')).toHaveText('歡迎') —— 自帶重試
3.2 等待
- await page.waitForTimeout(2000) 再點
- await expect(locator).toBeVisible() 再操作
3.3 瀏覽器 / 設備
- 移動端：test.use({ ...devices['iPhone 14'] })
- 多瀏覽器：在 projects 里加 Firefox、WebKit
3.4 「裝完包就跑」——CI 裏最常見翻車
現象： 報錯找不到 chromium / firefox / webkit 可執行文件。
原因： 只 npm install 了，沒拉瀏覽器二進制。
辦法： Pipeline 裏顯式執行 npx playwright install chromium（或全量 install + 按需 install-deps）。
這條和「Skill 好不好用」無關，是 Playwright 的硬門檻。
四、Playwright 還能幹啥（別隻當點點點工具）
除了 E2E，你還可以：
- API 測試：request 上下文直接打接口，和頁面流組合
- 視覺迴歸：expect(page).toHaveScreenshot()
- 跨端： Chromium / Firefox / WebKit + 移動端模擬
能力越大，越要記得：穩定來自規範，快來自少等、可並行。
寫在最後
我寫這篇，是因為自己也經歷過「CI 通過率低、全員等重跑」那種兩眼一黑。
Playwright 本身很能打，快和穩都是可以配出來的。
選擇器像用戶一樣想，斷言像有耐心一樣等，環境像配置一樣切。
微信交流羣：