// tests/login.spec.ts
import { test, expect } from '@playwright/test';
import { LoginPage } from '../pages/LoginPage';

test.describe('登入功能', () => {
  test('使用有效帳號登入', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.login('user@example.com', 'password123');
    await expect(page).toHaveURL('/dashboard');
  });

  test('使用無效帳號登入顯示錯誤', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.login('invalid@example.com', 'wrong');
    await expect(loginPage.errorMessage).toBeVisible();
  });
});

// pages/LoginPage.ts
import { type Page, type Locator } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('電子郵件');
    this.passwordInput = page.getByLabel('密碼');
    this.submitButton = page.getByRole('button', { name: '登入' });
    this.errorMessage = page.getByTestId('error-message');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }
}

// services/ApiService.ts
import { type APIRequestContext } from '@playwright/test';

export class ApiService {
  private request: APIRequestContext;

  constructor(request: APIRequestContext) {
    this.request = request;
  }

  async createUser(userData: { name: string; email: string }) {
    const response = await this.request.post('/api/users', {
      data: userData,
    });
    return response.json();
  }

  async deleteUser(userId: string) {
    await this.request.delete(`/api/users/${userId}`);
  }

  async getAuthToken(email: string, password: string): Promise<string> {
    const response = await this.request.post('/api/auth/login', {
      data: { email, password },
    });
    const body = await response.json();
    return body.token;
  }
}

// fixtures/test-data.ts
import { test as base } from '@playwright/test';
import { faker } from '@faker-js/faker/locale/zh_TW';

type TestData = {
  testUser: { name: string; email: string; password: string };
};

export const test = base.extend<TestData>({
  testUser: async ({}, use) => {
    const user = {
      name: faker.person.fullName(),
      email: faker.internet.email(),
      password: faker.internet.password({ length: 12 }),
    };
    await use(user);
    // Teardown: 清理測試用戶
  },
});

// config/environments.ts
export const environments = {
  dev: {
    baseURL: 'https://dev.example.com',
    apiURL: 'https://api-dev.example.com',
    timeout: 30_000,
  },
  sit: {
    baseURL: 'https://sit.example.com',
    apiURL: 'https://api-sit.example.com',
    timeout: 45_000,
  },
  uat: {
    baseURL: 'https://uat.example.com',
    apiURL: 'https://api-uat.example.com',
    timeout: 60_000,
  },
  prod: {
    baseURL: 'https://www.example.com',
    apiURL: 'https://api.example.com',
    timeout: 30_000,
  },
} as const;

export type Environment = keyof typeof environments;

// playwright.config.ts（多環境支援）
import { defineConfig } from '@playwright/test';
import { environments, type Environment } from './config/environments';

const env: Environment = (process.env.TEST_ENV as Environment) || 'dev';
const config = environments[env];

export default defineConfig({
  testDir: './tests',
  timeout: config.timeout,
  retries: env === 'prod' ? 0 : 2,
  workers: env === 'prod' ? 1 : undefined,

  use: {
    baseURL: config.baseURL,
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },

  projects: [
    { name: 'chromium', use: { browserName: 'chromium' } },
    { name: 'firefox', use: { browserName: 'firefox' } },
    { name: 'webkit', use: { browserName: 'webkit' } },
  ],
});

# 執行 SIT 環境測試
TEST_ENV=sit npx playwright test

# 執行 UAT 環境，僅 Chromium
TEST_ENV=uat npx playwright test --project=chromium

# 方法一：互動式建立（推薦）
npm init playwright@latest

# 選擇：
# - TypeScript（推薦）
# - 測試資料夾：tests 或 e2e
# - GitHub Actions workflow：Yes
# - 安裝瀏覽器：Yes

# 安裝核心套件
npm install -D @playwright/test

# 下載瀏覽器（含系統依賴）
npx playwright install --with-deps

# 安裝 Playwright for Python
pip install playwright

# 下載瀏覽器
playwright install --with-deps

# 範例：Python 基本測試
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://playwright.dev/")
    print(page.title())
    browser.close()

<!-- pom.xml -->
<dependency>
  <groupId>com.microsoft.playwright</groupId>
  <artifactId>playwright</artifactId>
  <version>1.59.0</version>
</dependency>

// 範例：Java 基本測試
import com.microsoft.playwright.*;

public class PlaywrightExample {
    public static void main(String[] args) {
        try (Playwright playwright = Playwright.create()) {
            Browser browser = playwright.chromium().launch();
            Page page = browser.newPage();
            page.navigate("https://playwright.dev/");
            System.out.println(page.title());
        }
    }
}

playwright-e2e/
├── .github/
│   └── workflows/
│       └── playwright.yml          # CI/CD Pipeline
├── config/
│   ├── environments.ts             # 環境配置
│   └── test-constants.ts           # 測試常數
├── fixtures/
│   ├── auth.setup.ts               # 認證 Setup
│   └── test-data.ts                # 測試資料 Fixtures
├── pages/
│   ├── BasePage.ts                 # Page Object 基底類別
│   ├── LoginPage.ts                # 登入頁
│   ├── DashboardPage.ts            # 儀表板頁
│   └── components/
│       ├── HeaderComponent.ts      # 共用 Header
│       └── SidebarComponent.ts     # 共用 Sidebar
├── services/
│   ├── ApiService.ts               # API 服務
│   └── AuthService.ts              # 認證服務
├── tests/
│   ├── auth/
│   │   ├── login.spec.ts
│   │   └── logout.spec.ts
│   ├── dashboard/
│   │   └── dashboard.spec.ts
│   ├── api/
│   │   └── user-api.spec.ts
│   └── visual/
│       └── homepage-visual.spec.ts
├── utils/
│   ├── helpers.ts                  # 輔助函式
│   └── logger.ts                   # 日誌工具
├── test-results/                   # 測試結果（.gitignore）
├── playwright-report/              # HTML 報告（.gitignore）
├── .env.dev                        # DEV 環境變數
├── .env.sit                        # SIT 環境變數
├── .env.uat                        # UAT 環境變數
├── .gitignore
├── package.json
├── playwright.config.ts            # Playwright 配置
└── tsconfig.json

// .vscode/settings.json
{
  "playwright.reuseBrowser": true,
  "playwright.showTrace": true,
  "testing.defaultGutterClickAction": "debug",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

// .vscode/mcp.json（VS Code MCP 設定）
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

# Claude Code 整合
claude mcp add playwright npx @playwright/mcp@latest

# 全域安裝 CLI
npm install -g @playwright/cli@latest

# 安裝 Skills（增強 Agent 整合）
playwright-cli install --skills

# 開啟監控面板（Dashboard）
playwright-cli show

# 開啟指定 URL
playwright-cli open https://example.com --headed

# 對頁面進行輸入操作
playwright-cli type "搜尋關鍵字"
playwright-cli press Enter

# 截圖
playwright-cli screenshot

# 取得頁面快照（Accessibility Tree）
playwright-cli snapshot

# 依據你的開發工具產生 Agent 定義檔
# Visual Studio Code
npx playwright init-agents --loop=vscode

# Claude Code
npx playwright init-agents --loop=claude

# OpenCode
npx playwright init-agents --loop=opencode

// tests/example.spec.ts
import { test, expect } from '@playwright/test';

test('驗證首頁標題', async ({ page }) => {
  // 導航至目標頁面
  await page.goto('https://playwright.dev/');
  
  // 驗證標題包含 "Playwright"
  await expect(page).toHaveTitle(/Playwright/);
});

test('點擊快速開始連結', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  
  // 使用語意化 Locator
  await page.getByRole('link', { name: 'Get started' }).click();
  
  // 驗證導航成功
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

# 執行所有測試（Headless 模式）
npx playwright test

# 顯示瀏覽器視窗（Headed 模式）
npx playwright test --headed

# 僅執行 Chromium
npx playwright test --project=chromium

# 執行單一檔案
npx playwright test tests/example.spec.ts

# UI 模式（互動式偵錯）
npx playwright test --ui

test('新 Locator API 示範', async ({ page }) => {
  await page.goto('/form');

  // 描述 Locator 用途，讓測試報告更清楚
  const submitBtn = page.getByRole('button', { name: '送出' });
  submitBtn.describe('主要送出按鈕');
  console.log(submitBtn.description()); // '主要送出按鈕'

  // 將任意 Locator 轉換為最佳實踐格式
  const normalized = await page.locator('.submit-btn').normalize();
  // 可能回傳: page.getByRole('button', { name: '送出' })

  // 擷取頁面 Aria Snapshot（適合 AI Agent 理解頁面結構）
  const snapshot = await page.ariaSnapshot();
  console.log(snapshot);

  // 互動式選取 Locator（開發偵錯用）
  // const locator = await page.pickLocator();
});

```typescript
// 最佳 Locator 範例
test('Locator 策略示範', async ({ page }) => {
  await page.goto('/form');

  // ✅ 推薦：語意化 Locator
  await page.getByRole('textbox', { name: '使用者名稱' }).fill('admin');
  await page.getByRole('textbox', { name: '密碼' }).fill('pass123');
  await page.getByRole('button', { name: '登入' }).click();

  // ✅ 推薦：data-testid
  await expect(page.getByTestId('welcome-message')).toContainText('歡迎');

  // ❌ 避免：脆弱的 CSS Selector
  // await page.locator('#root > div:nth-child(3) > button').click();
});

// Auto-wait 自動處理，無需手動等待
test('Auto-wait 範例', async ({ page }) => {
  await page.goto('/dynamic-page');

  // Playwright 自動等待按鈕出現並可點擊
  await page.getByRole('button', { name: '載入更多' }).click();

  // 自動等待文字出現
  await expect(page.getByText('載入完成')).toBeVisible();

  // ❌ 避免：不要使用固定等待
  // await page.waitForTimeout(3000);
});

test('Web-First Assertions 範例', async ({ page }) => {
  await page.goto('/dashboard');

  // 頁面驗證
  await expect(page).toHaveTitle('儀表板');
  await expect(page).toHaveURL(/\/dashboard/);

  // 元素驗證
  await expect(page.getByTestId('user-name')).toHaveText('王小明');
  await expect(page.getByRole('button', { name: '送出' })).toBeEnabled();
  await expect(page.getByTestId('loading')).toBeHidden();

  // 數量驗證
  await expect(page.getByRole('listitem')).toHaveCount(5);

  // CSS 驗證
  await expect(page.getByTestId('alert')).toHaveClass(/alert-success/);

  // 屬性驗證
  await expect(page.getByRole('link', { name: '首頁' })).toHaveAttribute('href', '/');
});

// playwright.config.ts
export default defineConfig({
  use: {
    headless: true,  // CI 預設 headless
    // headless: false, // 開發時切換
  },
});

# 命令列控制
npx playwright test --headed    # 顯示瀏覽器
npx playwright test --ui        # UI 模式
npx playwright test             # Headless（預設）

# 開啟 Codegen
npx playwright codegen https://example.com

# 指定輸出檔案
npx playwright codegen --output tests/recorded.spec.ts https://example.com

# 模擬行動裝置
npx playwright codegen --device="iPhone 15" https://example.com

# 指定瀏覽器
npx playwright codegen --browser=firefox https://example.com

# 啟動 Inspector（逐步偵錯）
npx playwright test --debug

# 在程式碼中插入斷點
await page.pause();  // 暫停執行，開啟 Inspector

// playwright.config.ts
export default defineConfig({
  use: {
    // 'on'：總是錄製
    // 'off'：不錄製
    // 'on-first-retry'：第一次重試時錄製（推薦）
    // 'retain-on-failure'：失敗時保留
    // 'retain-on-failure-and-retries'：記錄每次執行，失敗時保留所有 Trace（v1.59+，適合除錯 Flaky Test）
    trace: 'on-first-retry',
  },
});

# 查看 Trace 檔案
npx playwright show-trace trace.zip

# 或在測試後開啟報告（包含 Trace）
npx playwright show-report

test('Mock API 回應', async ({ page }) => {
  // 攔截 API 並回傳 Mock 資料
  await page.route('**/api/users', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify([
        { id: 1, name: '王小明', email: 'wang@example.com' },
        { id: 2, name: '李大華', email: 'lee@example.com' },
      ]),
    });
  });

  await page.goto('/users');
  await expect(page.getByText('王小明')).toBeVisible();
});

test('模擬網路錯誤', async ({ page }) => {
  // 模擬 500 Server Error
  await page.route('**/api/users', (route) =>
    route.fulfill({ status: 500, body: 'Internal Server Error' })
  );

  await page.goto('/users');
  await expect(page.getByText('載入失敗')).toBeVisible();
});

test('攔截並修改請求', async ({ page }) => {
  // 攔截請求，修改 Header
  await page.route('**/api/**', async (route) => {
    const headers = {
      ...route.request().headers(),
      'X-Test-Header': 'playwright-test',
    };
    await route.continue({ headers });
  });

  await page.goto('/dashboard');
});

test('阻擋圖片載入（加速測試）', async ({ page }) => {
  await page.route('**/*.{png,jpg,jpeg,gif,svg}', (route) => route.abort());
  await page.goto('/heavy-page');
});

test('多分頁操作', async ({ page, context }) => {
  await page.goto('/');

  // 監聽新分頁
  const [newPage] = await Promise.all([
    context.waitForEvent('page'),
    page.getByRole('link', { name: '在新視窗開啟' }).click(),
  ]);

  // 操作新分頁
  await newPage.waitForLoadState();
  await expect(newPage).toHaveTitle(/新頁面/);
  await newPage.close();
});

test('iframe 操作', async ({ page }) => {
  await page.goto('/page-with-iframe');

  // 取得 iframe
  const frame = page.frameLocator('#payment-iframe');

  // 在 iframe 內操作
  await frame.getByLabel('卡號').fill('4111111111111111');
  await frame.getByLabel('到期月/年').fill('12/28');
  await frame.getByRole('button', { name: '付款' }).click();
});

test('檔案上傳', async ({ page }) => {
  await page.goto('/upload');

  // 單一檔案上傳
  await page.getByLabel('選擇檔案').setInputFiles('test-data/report.pdf');

  // 多檔案上傳
  await page.getByLabel('選擇檔案').setInputFiles([
    'test-data/doc1.pdf',
    'test-data/doc2.pdf',
  ]);

  await page.getByRole('button', { name: '上傳' }).click();
  await expect(page.getByText('上傳成功')).toBeVisible();
});

test('檔案下載', async ({ page }) => {
  await page.goto('/download');

  // 等待下載事件
  const [download] = await Promise.all([
    page.waitForEvent('download'),
    page.getByRole('link', { name: '下載報表' }).click(),
  ]);

  // 儲存至指定路徑
  await download.saveAs('downloads/' + download.suggestedFilename());
  
  // 驗證檔案名稱
  expect(download.suggestedFilename()).toBe('monthly-report.xlsx');
});

test('首頁視覺回歸', async ({ page }) => {
  await page.goto('/');

  // 全頁截圖比對
  await expect(page).toHaveScreenshot('homepage.png', {
    maxDiffPixelRatio: 0.01,  // 允許 1% 差異
    fullPage: true,
  });
});

test('元件視覺測試', async ({ page }) => {
  await page.goto('/components');

  // 特定元素截圖比對
  const card = page.getByTestId('product-card');
  await expect(card).toHaveScreenshot('product-card.png');
});

test('PDF 產生', async ({ page }) => {
  await page.goto('/report');
  await page.pdf({
    path: 'output/report.pdf',
    format: 'A4',
    printBackground: true,
    margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' },
  });
});

// fixtures/auth.setup.ts
import { test as setup } from '@playwright/test';

const authFile = 'playwright/.auth/user.json';

setup('登入並儲存認證狀態', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('帳號').fill('admin@example.com');
  await page.getByLabel('密碼').fill('Admin123!');
  await page.getByRole('button', { name: '登入' }).click();

  // 等待登入完成
  await page.waitForURL('/dashboard');

  // 儲存認證狀態
  await page.context().storageState({ path: authFile });
});

// playwright.config.ts
export default defineConfig({
  projects: [
    // Setup project：執行登入
    { name: 'setup', testMatch: /.*\.setup\.ts/ },

    // 測試專案：重用認證狀態
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },
  ],
});

test('Screencast 錄影範例', async ({ page }) => {
  // 開始錄影
  await page.screencast.start({ path: 'video.webm' });

  await page.goto('/dashboard');
  await page.getByRole('button', { name: '新增' }).click();
  // ... 執行操作

  // 停止錄影
  await page.screencast.stop();
});

test('Screencast 動作標註', async ({ page }) => {
  // 啟用動作標註：自動標示互動元素並顯示動作標題
  await page.screencast.showActions({ position: 'top-right' });

  // 也可在配置檔中啟用
  // playwright.config.ts:
  // use: {
  //   video: {
  //     mode: 'on',
  //     show: {
  //       actions: { position: 'top-left' },
  //       test: { position: 'top-right' },
  //     },
  //   },
  // },
});

test('Screencast 章節與覆蓋層', async ({ page }) => {
  await page.screencast.start({ path: 'receipt.webm' });
  await page.screencast.showActions({ position: 'top-right' });

  // 顯示章節標題
  await page.screencast.showChapter('驗證結帳流程', {
    description: '新增優惠券支援 - Ticket #1234',
    duration: 1000,
  });

  // 執行驗證步驟
  await page.locator('#coupon').fill('SAVE20');
  await page.locator('#apply-coupon').click();
  await expect(page.locator('.discount')).toContainText('20%');

  // 顯示自訂 HTML 覆蓋層
  await page.screencast.showOverlay('<div style="color: red">錄製中</div>');

  await page.screencast.showChapter('完成', {
    description: '優惠券已套用，折扣已反映在總金額',
  });

  await page.screencast.stop();
});

test('即時幀擷取', async ({ page }) => {
  await page.screencast.start({
    onFrame: ({ data }) => sendToVisionModel(data),
    size: { width: 800, height: 600 },
  });

  // 執行操作，每一幀都會透過 onFrame 回呼傳送
  await page.goto('/dashboard');

  await page.screencast.stop();
});

import { chromium } from 'playwright';

// 啟動並綁定瀏覽器
const browser = await chromium.launch();
const { endpoint } = await browser.bind('my-session', {
  workspaceDir: '/my/project',
});

// 其他客戶端可透過以下方式連接：
// 1. playwright-cli:
//    playwright-cli attach my-session
//    playwright-cli -s my-session snapshot

// 2. @playwright/mcp:
//    @playwright/mcp --endpoint=my-session

// 3. Playwright API（支援多客戶端同時連接）:
//    const browser = await chromium.connect(endpoint);

// 也可透過 WebSocket 綁定
const { endpoint: wsEndpoint } = await browser.bind('ws-session', {
  host: 'localhost',
  port: 0,  // 自動分配 Port
});
// wsEndpoint 為 ws:// URL

// 停止接受新連接
await browser.unbind();

# 開啟 Dashboard
playwright-cli show

# playwright-cli 自動綁定所有瀏覽器
# 也可用環境變數讓 @playwright/test 的瀏覽器出現在 Dashboard：
PLAYWRIGHT_DASHBOARD=1 npx playwright test

# 啟動 CLI 除錯
$ npx playwright test --debug=cli
### Debugging Instructions
- Run "playwright-cli attach tw-87b59e" to attach to this test

# 在另一個終端機附加
$ playwright-cli attach tw-87b59e
### Session `tw-87b59e` created, attached to `tw-87b59e`.

# 逐步執行
$ playwright-cli --session tw-87b59e step-over
### Page
- Page URL: https://playwright.dev/
- Page Title: Fast and reliable end-to-end testing for modern web apps | Playwright

# 開啟 Trace
$ npx playwright trace open test-results/example-has-title-chromium/trace.zip

# 列出所有動作
$ npx playwright trace actions --grep="expect"
     # Time       Action                                          Duration
  ──── ─────────  ────────────────────────────────────────────── ────────
    9. 0:00.859  Expect "toHaveTitle"                                5.1s  ✗

# 查看特定動作詳情
$ npx playwright trace action 9
  Expect "toHaveTitle"
  Error: expect(page).toHaveTitle(expected) failed
    Expected pattern: /Wrong Title/
    Received string:  "Fast and reliable end-to-end testing for modern web apps | Playwright"

# 查看 DOM 快照
$ npx playwright trace snapshot 9 --name after

# 關閉 Trace
$ npx playwright trace close

test('await using 自動清理範例', async ({ context }) => {
  await using page = await context.newPage();

  {
    // Route 和 InitScript 在區塊結束時自動移除
    await using route = await page.route('**/*', route => route.continue());
    await using script = await page.addInitScript('console.log("init")');
    await page.goto('https://playwright.dev');
  }
  // 此處 route 和 init script 已自動被移除
});

// pages/BasePage.ts
import { type Page, type Locator, expect } from '@playwright/test';

export abstract class BasePage {
  readonly page: Page;
  readonly header: Locator;
  readonly footer: Locator;
  readonly loadingSpinner: Locator;

  constructor(page: Page) {
    this.page = page;
    this.header = page.locator('header');
    this.footer = page.locator('footer');
    this.loadingSpinner = page.getByTestId('loading-spinner');
  }

  async waitForPageLoad() {
    await this.loadingSpinner.waitFor({ state: 'hidden' });
  }

  async navigateTo(path: string) {
    await this.page.goto(path);
    await this.waitForPageLoad();
  }

  async getCurrentURL(): Promise<string> {
    return this.page.url();
  }

  async takeScreenshot(name: string) {
    await this.page.screenshot({ path: `screenshots/${name}.png`, fullPage: true });
  }
}

// pages/TransactionPage.ts（銀行系統範例）
import { type Page, type Locator, expect } from '@playwright/test';
import { BasePage } from './BasePage';

export class TransactionPage extends BasePage {
  readonly accountSelect: Locator;
  readonly amountInput: Locator;
  readonly memoInput: Locator;
  readonly submitButton: Locator;
  readonly confirmDialog: Locator;
  readonly successMessage: Locator;
  readonly transactionTable: Locator;

  constructor(page: Page) {
    super(page);
    this.accountSelect = page.getByLabel('轉出帳號');
    this.amountInput = page.getByLabel('轉帳金額');
    this.memoInput = page.getByLabel('備註');
    this.submitButton = page.getByRole('button', { name: '確認轉帳' });
    this.confirmDialog = page.getByRole('dialog');
    this.successMessage = page.getByTestId('success-message');
    this.transactionTable = page.getByRole('table');
  }

  async goto() {
    await this.navigateTo('/transaction/transfer');
  }

  async transfer(account: string, amount: string, memo?: string) {
    await this.accountSelect.selectOption(account);
    await this.amountInput.fill(amount);
    if (memo) {
      await this.memoInput.fill(memo);
    }
    await this.submitButton.click();
  }

  async confirmTransfer() {
    await this.confirmDialog.getByRole('button', { name: '確認' }).click();
  }

  async verifySuccess(expectedMessage: string) {
    await expect(this.successMessage).toContainText(expectedMessage);
  }

  async getTransactionCount(): Promise<number> {
    return this.transactionTable.getByRole('row').count() - 1; // 排除 header
  }
}

# 重複執行測試，找出 Flaky Test
npx playwright test --repeat-each=10

# 重試失敗測試
npx playwright test --retries=2

// ✅ 推薦命名格式
test.describe('交易功能', () => {
  test('應該在輸入有效金額時成功轉帳', async ({ page }) => {});
  test('應該在餘額不足時顯示錯誤訊息', async ({ page }) => {});
  test('應該在超過每日限額時阻擋交易', async ({ page }) => {});
});

// ✅ 英文命名（國際團隊）
test.describe('Transaction Feature', () => {
  test('should transfer successfully with valid amount', async ({ page }) => {});
  test('should show error when balance is insufficient', async ({ page }) => {});
  test('should block transaction when daily limit exceeded', async ({ page }) => {});
});

// fixtures/index.ts
import { test as base } from '@playwright/test';
import { LoginPage } from '../pages/LoginPage';
import { DashboardPage } from '../pages/DashboardPage';
import { ApiService } from '../services/ApiService';

type MyFixtures = {
  loginPage: LoginPage;
  dashboardPage: DashboardPage;
  apiService: ApiService;
};

export const test = base.extend<MyFixtures>({
  loginPage: async ({ page }, use) => {
    await use(new LoginPage(page));
  },
  dashboardPage: async ({ page }, use) => {
    await use(new DashboardPage(page));
  },
  apiService: async ({ request }, use) => {
    await use(new ApiService(request));
  },
});

export { expect } from '@playwright/test';

// tests/dashboard.spec.ts（使用自訂 Fixtures）
import { test, expect } from '../fixtures';

test('儀表板顯示正確資訊', async ({ dashboardPage }) => {
  await dashboardPage.goto();
  await expect(dashboardPage.welcomeMessage).toBeVisible();
});

# .github/workflows/playwright.yml
name: Playwright Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1/4, 2/4, 3/4, 4/4]  # 平行分片

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright Browsers
        run: npx playwright install --with-deps

      - name: Run Playwright tests
        run: npx playwright test --shard=${{ matrix.shard }}
        env:
          TEST_ENV: sit

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report-${{ matrix.shard }}
          path: playwright-report/
          retention-days: 30

      - name: Upload blob report
        uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: blob-report-${{ strategy.job-index }}
          path: blob-report/
          retention-days: 1

  merge-reports:
    if: ${{ !cancelled() }}
    needs: [test]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci

      - name: Download blob reports
        uses: actions/download-artifact@v4
        with:
          path: all-blob-reports
          pattern: blob-report-*
          merge-multiple: true

      - name: Merge reports
        run: npx playwright merge-reports --reporter html ./all-blob-reports

      - name: Upload merged report
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report-merged
          path: playwright-report/
          retention-days: 30

# .gitlab-ci.yml
stages:
  - test
  - report

playwright-tests:
  stage: test
  image: mcr.microsoft.com/playwright:v1.59.0-noble
  parallel: 4
  script:
    - npm ci
    - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL
  artifacts:
    when: always
    paths:
      - playwright-report/
      - test-results/
    expire_in: 7 days
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'

// Jenkinsfile
pipeline {
    agent {
        docker {
            image 'mcr.microsoft.com/playwright:v1.59.0-noble'
        }
    }

    environment {
        TEST_ENV = 'sit'
        CI = 'true'
    }

    stages {
        stage('Install') {
            steps {
                sh 'npm ci'
            }
        }

        stage('Test') {
            steps {
                sh 'npx playwright test'
            }
        }
    }

    post {
        always {
            publishHTML(target: [
                allowMissing: true,
                alwaysLinkToLastBuild: true,
                keepAll: true,
                reportDir: 'playwright-report',
                reportFiles: 'index.html',
                reportName: 'Playwright Report'
            ])

            archiveArtifacts artifacts: 'test-results/**', allowEmptyArchive: true
        }
        failure {
            // 發送 Teams / Email 通知
            office365ConnectorSend(
                status: 'FAILURE',
                webhookUrl: "${TEAMS_WEBHOOK_URL}",
                message: "Playwright 測試失敗：${BUILD_URL}"
            )
        }
    }
}

// playwright.config.ts
export default defineConfig({
  reporter: [
    ['html', { open: 'never', outputFolder: 'playwright-report' }],
    ['json', { outputFile: 'test-results/results.json' }],
    ['junit', { outputFile: 'test-results/junit.xml' }],
  ],
});

# 安裝 Allure Reporter
npm install -D allure-playwright

// playwright.config.ts
export default defineConfig({
  reporter: [
    ['allure-playwright', { outputFolder: 'allure-results' }],
    ['html'],
  ],
});

# 產生 Allure 報告
npx allure generate allure-results -o allure-report --clean
npx allure open allure-report

// utils/notify.ts
export async function sendTeamsNotification(webhookUrl: string, results: {
  total: number;
  passed: number;
  failed: number;
  reportUrl: string;
}) {
  const card = {
    '@type': 'MessageCard',
    summary: 'Playwright 測試結果',
    themeColor: results.failed > 0 ? 'FF0000' : '00FF00',
    title: `Playwright 測試 ${results.failed > 0 ? '❌ 失敗' : '✅ 通過'}`,
    sections: [{
      facts: [
        { name: '總數', value: results.total.toString() },
        { name: '通過', value: results.passed.toString() },
        { name: '失敗', value: results.failed.toString() },
      ],
    }],
    potentialAction: [{
      '@type': 'OpenUri',
      name: '查看報告',
      targets: [{ os: 'default', uri: results.reportUrl }],
    }],
  };

  await fetch(webhookUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(card),
  });
}

# Dockerfile.playwright
FROM mcr.microsoft.com/playwright:v1.59.0-noble

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .

CMD ["npx", "playwright", "test"]

# docker-compose.yml
services:
  playwright:
    build:
      context: .
      dockerfile: Dockerfile.playwright
    environment:
      - TEST_ENV=sit
      - CI=true
    volumes:
      - ./playwright-report:/app/playwright-report
      - ./test-results:/app/test-results

# 使用 Docker 執行測試
docker compose run --rm playwright

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  webServer: {
    command: 'npm run start',
    wait: {
      stdout: '/Listening on port (?<my_server_port>\\d+)/',
    },
  },
});

// 測試中可透過環境變數取得擷取的 Port
import { test, expect } from '@playwright/test';

test.use({ baseURL: `http://localhost:${process.env.MY_SERVER_PORT ?? 3000}` });

test('首頁載入', async ({ page }) => {
  await page.goto('/');
});

// playwright.config.ts
export default defineConfig({
  tag: '@nightly',  // 所有測試自動附加此標籤
});

// playwright.config.ts
export default defineConfig({
  reporter: [
    // HTML 報告
    ['html', {
      open: 'never',         // CI 中不自動開啟
      outputFolder: 'playwright-report',
      host: '0.0.0.0',      // 允許遠端存取
      port: 9323,
    }],
    // JSON 結構化資料
    ['json', { outputFile: 'test-results/results.json' }],
    // JUnit XML（CI 整合）
    ['junit', { outputFile: 'test-results/junit.xml' }],
    // 行列表（終端機輸出）
    ['list'],
  ],
});

# 手動開啟 HTML 報告
npx playwright show-report

# 指定報告路徑
npx playwright show-report ./playwright-report

# 指定 Port
npx playwright show-report --port 9323

// 在程式碼中手動建立 Trace
test('交易流程追蹤', async ({ page, context }) => {
  // 開始追蹤
  await context.tracing.start({
    screenshots: true,
    snapshots: true,
    sources: true,
  });

  // 執行測試步驟
  await page.goto('/transaction');
  await page.getByLabel('金額').fill('50000');
  await page.getByRole('button', { name: '轉帳' }).click();

  // 停止追蹤並儲存
  await context.tracing.stop({ path: 'traces/transaction-trace.zip' });
});

// reporters/CustomReporter.ts
import type {
  FullConfig, FullResult, Reporter, Suite, TestCase, TestResult
} from '@playwright/test/reporter';

class CustomReporter implements Reporter {
  private startTime: number = 0;
  private results: { passed: number; failed: number; skipped: number } = {
    passed: 0, failed: 0, skipped: 0,
  };

  onBegin(config: FullConfig, suite: Suite) {
    this.startTime = Date.now();
    console.log(`🚀 開始執行 ${suite.allTests().length} 個測試`);
  }

  onTestEnd(test: TestCase, result: TestResult) {
    const status = result.status;
    if (status === 'passed') this.results.passed++;
    else if (status === 'failed') this.results.failed++;
    else if (status === 'skipped') this.results.skipped++;

    const duration = (result.duration / 1000).toFixed(2);
    const icon = status === 'passed' ? '✅' : status === 'failed' ? '❌' : '⏭️';
    console.log(`${icon} [${duration}s] ${test.title}`);
  }

  async onEnd(result: FullResult) {
    const duration = ((Date.now() - this.startTime) / 1000).toFixed(2);
    console.log('\n📊 測試結果摘要：');
    console.log(`   通過：${this.results.passed}`);
    console.log(`   失敗：${this.results.failed}`);
    console.log(`   跳過：${this.results.skipped}`);
    console.log(`   耗時：${duration}s`);
    console.log(`   狀態：${result.status}`);
  }
}

export default CustomReporter;

// playwright.config.ts
export default defineConfig({
  reporter: [
    ['./reporters/CustomReporter.ts'],
    ['html'],
  ],
});

// reporters/PrometheusReporter.ts
import type { Reporter, FullResult, TestCase, TestResult } from '@playwright/test/reporter';

class PrometheusReporter implements Reporter {
  private metrics: string[] = [];

  onTestEnd(test: TestCase, result: TestResult) {
    const labels = `suite="${test.parent.title}",test="${test.title}",browser="${test.parent.project()?.name || 'unknown'}"`;
    
    // 測試持續時間
    this.metrics.push(
      `playwright_test_duration_seconds{${labels}} ${result.duration / 1000}`
    );
    
    // 測試結果
    this.metrics.push(
      `playwright_test_status{${labels},status="${result.status}"} 1`
    );
  }

  async onEnd(result: FullResult) {
    // 推送至 Prometheus Pushgateway
    const metricsBody = this.metrics.join('\n');
    
    try {
      await fetch('http://pushgateway:9091/metrics/job/playwright', {
        method: 'POST',
        body: metricsBody,
      });
      console.log('📊 指標已推送至 Prometheus');
    } catch (error) {
      console.error('推送指標失敗:', error);
    }
  }
}

export default PrometheusReporter;

# 測試通過率
sum(playwright_test_status{status="passed"}) / sum(playwright_test_status) * 100

# 平均測試時間
avg(playwright_test_duration_seconds) by (suite)

# 失敗測試數量趨勢
sum(rate(playwright_test_status{status="failed"}[24h])) by (suite)

// utils/cleanup.ts
import { type APIRequestContext } from '@playwright/test';

export class TestDataCleaner {
  private request: APIRequestContext;
  private createdResources: { type: string; id: string }[] = [];

  constructor(request: APIRequestContext) {
    this.request = request;
  }

  track(type: string, id: string) {
    this.createdResources.push({ type, id });
  }

  async cleanAll() {
    for (const resource of this.createdResources.reverse()) {
      try {
        await this.request.delete(`/api/${resource.type}/${resource.id}`);
        console.log(`🗑️ 清理 ${resource.type}/${resource.id}`);
      } catch (error) {
        console.warn(`⚠️ 清理失敗 ${resource.type}/${resource.id}:`, error);
      }
    }
    this.createdResources = [];
  }
}

// 使用範例
import { test } from '@playwright/test';
import { TestDataCleaner } from '../utils/cleanup';

test('建立並清理測試資料', async ({ request }) => {
  const cleaner = new TestDataCleaner(request);

  try {
    // 建立測試資料
    const response = await request.post('/api/users', {
      data: { name: 'Test User', email: 'test@example.com' },
    });
    const user = await response.json();
    cleaner.track('users', user.id);

    // 執行測試 ...
  } finally {
    // 確保清理
    await cleaner.cleanAll();
  }
});

# .github/workflows/scheduled-tests.yml
name: Scheduled Playwright Tests

on:
  schedule:
    # 每日凌晨 2 點（UTC+8 = UTC 18:00 前一天）
    - cron: '0 18 * * *'
    # 每週一上午 9 點
    - cron: '0 1 * * 1'
  workflow_dispatch:  # 手動觸發

jobs:
  nightly-regression:
    if: github.event.schedule == '0 18 * * *' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps
      - name: Run Full Regression
        run: npx playwright test --grep @regression
        env:
          TEST_ENV: sit

  weekly-visual:
    if: github.event.schedule == '0 1 * * 1'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps
      - name: Run Visual Tests
        run: npx playwright test --grep @visual
        env:
          TEST_ENV: uat

// playwright.config.ts
export default defineConfig({
  // 完全平行（預設）
  fullyParallel: true,

  // Worker 數量（CI 中可設定固定值）
  workers: process.env.CI ? 4 : undefined,

  // 分片執行（CI 跨機器分散）
  // 由 CLI 指定：--shard=1/4
});

# 本地平行執行
npx playwright test --workers=4

# CI 分片執行（4 台機器）
npx playwright test --shard=1/4  # Machine 1
npx playwright test --shard=2/4  # Machine 2
npx playwright test --shard=3/4  # Machine 3
npx playwright test --shard=4/4  # Machine 4

// playwright.config.ts（效能最佳化設定）
export default defineConfig({
  use: {
    // 只在失敗時錄影，減少 I/O
    video: 'retain-on-failure',
    
    // 只在第一次重試時追蹤
    trace: 'on-first-retry',
    
    // 只在失敗時截圖
    screenshot: 'only-on-failure',
    
    // 關閉 JavaScript（純靜態頁面測試）
    // javaScriptEnabled: false,
    
    // 限制視口大小
    viewport: { width: 1280, height: 720 },
    
    // 阻擋不必要的資源
    // 在 globalSetup 中設定
  },
  
  // 依瀏覽器設定不同 timeout
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
      timeout: 30_000,
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
      timeout: 45_000,  // Firefox 稍慢
    },
  ],
});

# Step 1：更新 Playwright
npm install -D @playwright/test@latest

# Step 2：更新瀏覽器
npx playwright install --with-deps

# Step 3：檢查版本
npx playwright --version

# Step 4：執行測試驗證
npx playwright test

# Step 5：更新視覺快照（如有變更）
npx playwright test --update-snapshots

// 版本固定策略（package.json）
{
  "devDependencies": {
    // ✅ 推薦：固定 Minor 版本
    "@playwright/test": "~1.59.0",
    
    // ❌ 避免：自動升級 Major
    // "@playwright/test": "^1.59.0"
  }
}

# 查看已安裝的瀏覽器
npx playwright install --list

# 安裝特定瀏覽器
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

# 清理舊版瀏覽器
npx playwright install --clean

# 回滾至特定版本
npm install -D @playwright/test@1.58.0

# 重新安裝對應瀏覽器
npx playwright install --with-deps

# 驗證回滾
npx playwright test

// ✅ 正確做法：使用環境變數
test('登入系統', async ({ page }) => {
  const username = process.env.TEST_USER!;
  const password = process.env.TEST_PASSWORD!;
  
  await page.goto('/login');
  await page.getByLabel('帳號').fill(username);
  await page.getByLabel('密碼').fill(password);
  await page.getByRole('button', { name: '登入' }).click();
});

// ❌ 錯誤做法：硬編碼敏感資料
// await page.getByLabel('帳號').fill('admin@bank.com');
// await page.getByLabel('密碼').fill('RealPassword123!');

# .env.sit（加入 .gitignore）
TEST_USER=test_user_sit
TEST_PASSWORD=encrypted_password_here
TEST_API_KEY=sit_api_key_here

// fixtures/roles.ts
import { test as base } from '@playwright/test';

type RoleFixture = {
  adminPage: import('@playwright/test').Page;
  userPage: import('@playwright/test').Page;
  viewerPage: import('@playwright/test').Page;
};

export const test = base.extend<RoleFixture>({
  adminPage: async ({ browser }, use) => {
    const context = await browser.newContext({
      storageState: 'playwright/.auth/admin.json',
    });
    const page = await context.newPage();
    await use(page);
    await context.close();
  },

  userPage: async ({ browser }, use) => {
    const context = await browser.newContext({
      storageState: 'playwright/.auth/user.json',
    });
    const page = await context.newPage();
    await use(page);
    await context.close();
  },

  viewerPage: async ({ browser }, use) => {
    const context = await browser.newContext({
      storageState: 'playwright/.auth/viewer.json',
    });
    const page = await context.newPage();
    await use(page);
    await context.close();
  },
});

// tests/rbac/admin-access.spec.ts
import { test, expect } from '../../fixtures/roles';

test('管理員可以存取系統設定', async ({ adminPage }) => {
  await adminPage.goto('/settings');
  await expect(adminPage.getByRole('heading', { name: '系統設定' })).toBeVisible();
});

test('一般用戶無法存取系統設定', async ({ userPage }) => {
  await userPage.goto('/settings');
  await expect(userPage.getByText('權限不足')).toBeVisible();
});

// utils/audit-logger.ts
import * as fs from 'fs';
import * as path from 'path';

export class AuditLogger {
  private logFile: string;

  constructor() {
    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
    this.logFile = path.join('audit-logs', `test-audit-${timestamp}.log`);
    fs.mkdirSync('audit-logs', { recursive: true });
  }

  log(action: string, details: Record<string, string>) {
    const entry = {
      timestamp: new Date().toISOString(),
      action,
      ...details,
    };
    fs.appendFileSync(this.logFile, JSON.stringify(entry) + '\n');
  }
}

// 使用範例
test('稽核 - 交易操作', async ({ page }) => {
  const audit = new AuditLogger();

  audit.log('TEST_START', { test: '交易轉帳', env: process.env.TEST_ENV! });

  await page.goto('/transaction');
  audit.log('NAVIGATE', { url: '/transaction' });

  await page.getByLabel('金額').fill('50000');
  audit.log('INPUT', { field: '金額', value: '50000' });

  await page.getByRole('button', { name: '送出' }).click();
  audit.log('SUBMIT', { action: '轉帳送出' });

  audit.log('TEST_END', { status: 'passed' });
});

playwright-enterprise-template/
├── .github/
│   └── workflows/
│       ├── playwright.yml              # PR 測試
│       └── scheduled-tests.yml         # 排程測試
├── .vscode/
│   ├── settings.json                   # VS Code 設定
│   ├── extensions.json                 # 推薦擴充
│   └── mcp.json                        # MCP 設定
├── config/
│   ├── environments.ts                 # 多環境配置
│   └── constants.ts                    # 測試常數
├── fixtures/
│   ├── auth.setup.ts                   # 認證 Setup
│   ├── index.ts                        # 自訂 Fixtures
│   └── test-data.ts                    # 測試資料工廠
├── pages/
│   ├── BasePage.ts                     # 基底 Page Object
│   ├── LoginPage.ts                    # 登入頁
│   ├── DashboardPage.ts               # 儀表板
│   ├── TransactionPage.ts             # 交易頁
│   └── components/
│       ├── HeaderComponent.ts          # 共用 Header
│       ├── SidebarComponent.ts         # 共用 Sidebar
│       └── DialogComponent.ts          # 共用 Dialog
├── services/
│   ├── ApiService.ts                   # API 服務
│   ├── AuthService.ts                  # 認證服務
│   └── DataService.ts                  # 資料服務
├── reporters/
│   └── CustomReporter.ts              # 自訂報告器
├── tests/
│   ├── auth/
│   │   ├── login.spec.ts               # @smoke @auth
│   │   ├── logout.spec.ts              # @smoke @auth
│   │   └── password-reset.spec.ts      # @regression @auth
│   ├── dashboard/
│   │   └── dashboard.spec.ts           # @smoke @dashboard
│   ├── transaction/
│   │   ├── transfer.spec.ts            # @regression @transaction
│   │   └── history.spec.ts             # @regression @transaction
│   ├── api/
│   │   ├── user-api.spec.ts            # @api
│   │   └── transaction-api.spec.ts     # @api
│   └── visual/
│       ├── homepage.spec.ts            # @visual
│       └── dashboard.spec.ts           # @visual
├── utils/
│   ├── helpers.ts                      # 輔助函式
│   ├── logger.ts                       # 日誌工具
│   ├── cleanup.ts                      # 資料清理
│   └── audit-logger.ts                # 稽核日誌
├── test-data/
│   ├── users.json                      # 測試用戶資料
│   └── transactions.json               # 測試交易資料
├── playwright/
│   └── .auth/                          # 認證狀態（.gitignore）
├── .env.dev                            # DEV 環境變數
├── .env.sit                            # SIT 環境變數
├── .env.uat                            # UAT 環境變數
├── .gitignore
├── Dockerfile.playwright               # Docker 設定
├── docker-compose.yml                  # Docker Compose
├── package.json
├── playwright.config.ts                # Playwright 主配置
├── tsconfig.json
└── README.md

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';
import { environments, type Environment } from './config/environments';
import dotenv from 'dotenv';

// 載入環境變數
const env: Environment = (process.env.TEST_ENV as Environment) || 'dev';
dotenv.config({ path: `.env.${env}` });

const config = environments[env];

export default defineConfig({
  // 測試目錄
  testDir: './tests',

  // 完全平行執行
  fullyParallel: true,

  // CI 模式：禁止 test.only
  forbidOnly: !!process.env.CI,

  // 重試次數
  retries: process.env.CI ? 2 : 0,

  // Worker 數量
  workers: process.env.CI ? 4 : undefined,

  // 全域逾時
  timeout: config.timeout,

  // Expect 逾時
  expect: {
    timeout: 10_000,
    toHaveScreenshot: {
      maxDiffPixelRatio: 0.01,
    },
  },

  // Reporter 設定
  reporter: process.env.CI
    ? [
        ['html', { open: 'never' }],
        ['junit', { outputFile: 'test-results/junit.xml' }],
        ['json', { outputFile: 'test-results/results.json' }],
        ['./reporters/CustomReporter.ts'],
      ]
    : [
        ['html', { open: 'on-failure' }],
        ['list'],
      ],

  // 全域設定
  use: {
    baseURL: config.baseURL,
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    locale: 'zh-TW',
    timezoneId: 'Asia/Taipei',

    // Action 逾時
    actionTimeout: 15_000,
    navigationTimeout: 30_000,

    // HTTP 認證（如需要）
    // httpCredentials: { username: '', password: '' },

    // 忽略 HTTPS 錯誤（僅測試環境）
    ignoreHTTPSErrors: env !== 'prod',
  },

  // 專案設定
  projects: [
    // Setup
    {
      name: 'setup',
      testMatch: /.*\.setup\.ts/,
    },

    // Desktop Browsers
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },
    {
      name: 'firefox',
      use: {
        ...devices['Desktop Firefox'],
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },
    {
      name: 'webkit',
      use: {
        ...devices['Desktop Safari'],
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },

    // Mobile
    {
      name: 'mobile-chrome',
      use: {
        ...devices['Pixel 7'],
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },
    {
      name: 'mobile-safari',
      use: {
        ...devices['iPhone 15'],
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },
  ],

  // 測試前啟動本地服務（開發時）
  // webServer: {
  //   command: 'npm run dev',
  //   url: 'http://localhost:3000',
  //   reuseExistingServer: !process.env.CI,
  //   // v1.57+ 新增 wait 選項：等待 stdout 輸出匹配特定正則表達式
  //   // wait: {
  //   //   stdout: '/Listening on port (?<my_server_port>\\d+)/',
  //   // },
  // },
});

{
  "name": "playwright-enterprise-template",
  "version": "1.0.0",
  "description": "企業級 Playwright E2E 測試專案",
  "scripts": {
    "test": "playwright test",
    "test:headed": "playwright test --headed",
    "test:ui": "playwright test --ui",
    "test:debug": "playwright test --debug",
    "test:chromium": "playwright test --project=chromium",
    "test:smoke": "playwright test --grep @smoke",
    "test:regression": "playwright test --grep @regression",
    "test:visual": "playwright test --grep @visual",
    "test:api": "playwright test --grep @api",
    "test:dev": "TEST_ENV=dev playwright test",
    "test:sit": "TEST_ENV=sit playwright test",
    "test:uat": "TEST_ENV=uat playwright test",
    "report": "playwright show-report",
    "codegen": "playwright codegen",
    "trace": "playwright show-trace",
    "install:browsers": "playwright install --with-deps",
    "update:snapshots": "playwright test --update-snapshots",
    "lint": "eslint tests/ pages/ services/ fixtures/ utils/"
  },
  "devDependencies": {
    "@playwright/test": "~1.59.0",
    "@faker-js/faker": "^9.0.0",
    "dotenv": "^16.0.0",
    "eslint": "^9.0.0",
    "allure-playwright": "^3.0.0"
  }
}

# Playwright
/test-results/
/playwright-report/
/blob-report/
/playwright/.auth/
/screenshots/
/downloads/
/traces/
/audit-logs/

# Allure
/allure-results/
/allure-report/

# Environment
.env.*
!.env.example

# Node
node_modules/

// tests/auth/login.spec.ts
import { test, expect } from '../../fixtures';

// 使用 Tag 分類測試
test('應該成功登入 @smoke @auth', async ({ loginPage }) => {
  await loginPage.goto();
  await loginPage.login('user@example.com', 'password');
  await expect(loginPage.page).toHaveURL('/dashboard');
});

test('密碼錯誤應顯示錯誤 @regression @auth', async ({ loginPage }) => {
  await loginPage.goto();
  await loginPage.login('user@example.com', 'wrong');
  await expect(loginPage.errorMessage).toBeVisible();
});

test('帳號鎖定後無法登入 @regression @auth @security', async ({ loginPage }) => {
  // 多次錯誤登入
  for (let i = 0; i < 5; i++) {
    await loginPage.goto();
    await loginPage.login('locked@example.com', 'wrong');
  }
  await expect(loginPage.page.getByText('帳號已鎖定')).toBeVisible();
});

# 按 Tag 執行
npx playwright test --grep @smoke           # Smoke Test
npx playwright test --grep @regression      # 回歸測試
npx playwright test --grep @security        # 安全相關
npx playwright test --grep-invert @visual   # 排除視覺測試
npx playwright test --grep "@smoke|@api"    # Smoke + API