Playwright 安裝配置文件詳解

Playwright 安裝&配置文件詳解

環境準備

Node.js 14.0+（推薦 LTS 版本）
npm（推薦使用最新版）
支持 Windows、macOS、Linux

一步到位的官方推薦安裝方式

1. 進入你的項目目錄

# Windows
cd 路徑\到\你的項目
# macOS/Linux
cd /path/to/your/project

2. 初始化 Playwright 項目

npm init playwright@latest

操作提示：
在出現選項時，請用鍵盤的上下方向鍵選擇你想要的內容，然后按**回車（Enter）**鍵確認。

執行后會進入交互式引導，每個選項說明如下：

選項1：Do you want to use TypeScript or JavaScript?

TypeScript：推薦（如果你的項目文件是 .ts 結尾，選這個）
JavaScript：如果你只用 .js 文件可以選這個

選項2：Where to put your end-to-end tests?

輸入測試用例目錄名，建議用 tests 或 e2e（如果已有同名目錄會復用）

選項3：Add a GitHub Actions workflow? (y/N)

y：生成 GitHub Actions 工作流文件，方便 CI 自動化
n：不生成（本地開發可選 n）

選項4：Install Playwright browsers? (Y/n)

Y：自動下載 Chromium、Firefox、Webkit 三大主流瀏覽器（推薦）
n：跳過，后續可手動 npx playwright install

3. 運行初始化命令后的效果

Playwright 會自動：

初始化 npm 項目（如無 package.json 會自動創建）
安裝 Playwright 及相關依賴
下載主流瀏覽器
生成測試配置和示例代碼

生成的目錄結構示例

playwright/
├── playwright.config.ts           # Playwright 測試配置文件
├── package.json                   # 項目依賴與腳本
├── package-lock.json              # 依賴鎖定
├── node_modules/                  # 依賴包
├── tests/                         # 主測試目錄
│   └── example.spec.ts            # 官方示例測試
├── tests-examples/                # 額外官方示例
│   └── demo-todo-app.spec.ts      # TodoMVC 端到端測試
├── .gitignore                     # 忽略文件
└── README.md                      # 項目說明

詳細文件與目錄說明

playwright.config.ts

Playwright 的主配置文件。
作用：配置測試目錄、并發、重試、報告、支持的瀏覽器（Chromium/Firefox/Webkit）等。

詳細配置說明：

import { defineConfig, devices } from '@playwright/test';export default defineConfig({// 測試目錄配置testDir: './tests',                    // 測試文件目錄testMatch: '**/*.spec.ts',             // 測試文件匹配模式timeout: 30000,                        // 單個測試超時時間（毫秒）// 全局設置globalTimeout: 600000,                 // 所有測試總超時時間expect: {timeout: 5000,                       // expect 斷言超時時間toHaveScreenshot: { maxDiffPixels: 100 }, // 截圖對比配置},// 并發配置workers: process.env.CI ? 1 : undefined, // CI 環境單進程，本地多進程fullyParallel: true,                   // 是否完全并行運行測試// 重試配置retries: process.env.CI ? 2 : 0,       // CI 環境失敗重試 2 次// 報告配置reporter: [['html'],                            // HTML 報告['list']                             // 命令行報告],// 瀏覽器配置use: {// 基礎配置baseURL: 'http://localhost:3000',    // 基礎 URLtrace: 'on-first-retry',             // 失敗時記錄追蹤screenshot: 'only-on-failure',       // 失敗時截圖// 瀏覽器配置viewport: { width: 1280, height: 720 }, // 視窗大小ignoreHTTPSErrors: true,             // 忽略 HTTPS 錯誤video: 'on-first-retry',             // 失敗時錄制視頻// 上下文配置locale: 'zh-CN',                     // 瀏覽器語言timezoneId: 'Asia/Shanghai',         // 時區geolocation: { longitude: 116.3, latitude: 39.9 }, // 地理位置permissions: ['geolocation'],        // 權限設置},// 多瀏覽器配置projects: [{name: 'chromium',use: { ...devices['Desktop Chrome'] },},{name: 'firefox',use: { ...devices['Desktop Firefox'] },},{name: 'webkit',use: { ...devices['Desktop Safari'] },},// 移動設備配置{name: 'Mobile Chrome',use: { ...devices['Pixel 5'] },},{name: 'Mobile Safari',use: { ...devices['iPhone 12'] },},],// 輸出配置outputDir: 'test-results/',            // 測試結果輸出目錄// 其他配置preserveOutput: 'always',              // 保留輸出文件forbidOnly: !!process.env.CI,          // CI 環境禁止 .onlyquiet: false,                          // 是否靜默輸出
});

配置項詳解：
1. 測試目錄配置
  - testDir: 指定測試文件所在目錄
  - testMatch: 指定測試文件匹配模式
  - timeout: 單個測試用例超時時間
2. 全局設置
  - globalTimeout: 所有測試的總超時時間
  - expect: 斷言相關配置
    - timeout: 斷言等待超時時間
    - toHaveScreenshot: 截圖對比配置
3. 并發配置
  - workers: 并行運行的測試進程數
  - fullyParallel: 是否允許完全并行運行
4. 重試配置
  - retries: 測試失敗時的重試次數
  - 建議在 CI 環境設置重試，本地開發可不設置
5. 報告配置
  - reporter: 測試報告格式
  - 支持多種報告格式：html、list、dot、json 等
  - 可同時使用多個報告器
6. 瀏覽器配置
  - use: 全局瀏覽器配置
    - baseURL: 基礎 URL，所有測試都會基于此 URL
    - trace: 追蹤記錄配置
    - screenshot: 截圖配置
    - viewport: 視窗大小
    - video: 視頻錄制配置
    - locale: 瀏覽器語言
    - timezoneId: 時區設置
    - geolocation: 地理位置模擬
    - permissions: 瀏覽器權限設置
7. 多瀏覽器配置
  - projects: 定義多個測試項目
  - 每個項目可以配置不同的瀏覽器和設備
  - 支持桌面端和移動端設備
  - 可以使用預定義的設備配置
8. 輸出配置
  - outputDir: 測試結果輸出目錄
  - preserveOutput: 輸出文件保留策略
9. 其他配置
  - forbidOnly: 是否禁止使用 .only
  - quiet: 是否靜默輸出
  - use: 全局使用配置
最佳實踐建議：
1. 根據項目需求選擇合適的配置項
2. CI 環境和本地開發環境使用不同配置
3. 合理設置超時時間和重試次數
4. 使用多瀏覽器配置確保跨瀏覽器兼容性
5. 配置適當的報告格式便于問題分析
6. 合理使用追蹤、截圖和視頻錄制功能

package.json
- Node.js 項目的依賴和腳本清單。
- 作用：記錄項目依賴（如 @playwright/test）、腳本命令、項目描述等。
- 主要內容：
  - devDependencies：Playwright 及類型依賴。
  - scripts：可自定義測試命令。
  - description、author、license 等元信息。
package-lock.json
- 依賴鎖定文件。
- 作用：確保團隊成員安裝的依賴版本一致，避免"我的能跑你的不能跑"。
node_modules/
- 依賴包目錄。
- 作用：存放所有通過 npm 安裝的依賴。
- 注意：此目錄通常不需要提交到 git。
tests/
- 主測試目錄。
- 作用：存放你的 E2E 測試用例。
- 默認包含 example.spec.ts，內容演示 Playwright 的基本用法。
- 你可以在此目錄下添加、組織自己的測試文件。
tests/example.spec.ts
- 官方自動生成的示例測試。
- 作用：幫助你快速了解 Playwright 的基本斷言、頁面操作等。
- 內容示例：
  - 訪問官網，斷言標題
  - 點擊"Get started"鏈接，斷言頁面內容
tests-examples/
- 額外官方示例目錄。
- 作用：提供更復雜的端到端測試案例，便于參考和學習。
tests-examples/demo-todo-app.spec.ts
- TodoMVC 應用的完整端到端測試。
- 作用：演示 Playwright 如何測試真實的前端應用，包括增刪查改、狀態斷言等。
- 內容較長，適合進階學習。

4. 運行你的第一個測試

npx playwright test

會自動運行 tests/ 目錄下的所有測試用例
首次運行會自動打開瀏覽器下載和測試報告

5. 常見問題與建議

TypeScript/JavaScript 選錯了怎么辦？
- 重新運行 npm init playwright@latest，或手動調整文件后綴和配置
已有測試目錄/配置怎么辦？
- 初始化時如遇同名文件，Playwright 會提示是否覆蓋，謹慎選擇
瀏覽器沒裝全？
- 可隨時運行 npx playwright install 補裝
如何自定義配置？
- 修改 playwright.config.ts

6. 參考：自動生成的示例測試內容

tests/example.spec.ts 示例：

import { test, expect } from '@playwright/test';test('has title', async ({ page }) => {await page.goto('https://playwright.dev/');await expect(page).toHaveTitle(/Playwright/);
});test('get started link', async ({ page }) => {await page.goto('https://playwright.dev/');await page.getByRole('link', { name: 'Get started' }).click();await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});