README - Playwright TypeScript boilerplate

README.md

🎭 Project Name — Playwright Test Automation

End-to-end testing framework built with Playwright and TypeScript.

---

📑 Table of Contents

• Features
• Prerequisites
• Getting Started
• Project Structure
• Running Tests
• Configuration
• Reporting
• CI/CD
• Contributing
• License
• Tiếng Việt

---

✨ Features

• Cross-browser testing — Chromium, Firefox, WebKit
• Parallel execution — fast feedback with worker-based parallelism
• Auto-waiting — no flaky selectors, Playwright handles element readiness
• Page Object Model (POM) — clean, maintainable test architecture
• HTML & Allure reports — rich test reporting out of the box
• CI/CD ready — GitHub Actions workflow included
• Environment management — .env based configuration

---

📋 Prerequisites

Tool	Version
Node.js	>= 18
npm / yarn / pnpm	latest
Git	latest

---

🚀 Getting Started

# Clone the repository
git clone https://github.com/<your-org>/<your-repo>.git
cd <your-repo>

# Install dependencies
npm install

# Install Playwright browsers
npx playwright install --with-deps

# Run all tests
npx playwright test

Environment Variables

Copy the example env file and update values as needed:

cp .env.example .env

Variable	Description	Default
BASE_URL	Application base URL	http://localhost:3000
ENV	Target environment (dev / staging / prod)	dev
HEADLESS	Run browsers in headless mode	true

---

📁 Project Structure

├── .github/
│   └── workflows/
│       └── playwright.yml        # CI/CD pipeline
├── src/
│   ├── fixtures/                 # Custom test fixtures
│   ├── pages/                    # Page Object Models
│   │   ├── base.page.ts
│   │   ├── login.page.ts
│   │   └── home.page.ts
│   ├── helpers/                  # Utility & helper functions
│   │   └── api.helper.ts
│   └── data/                     # Test data (JSON, CSV, etc.)
│       └── users.json
├── tests/
│   ├── auth/
│   │   └── login.spec.ts
│   ├── dashboard/
│   │   └── dashboard.spec.ts
│   └── e2e/
│       └── checkout.spec.ts
├── .env.example
├── .gitignore
├── playwright.config.ts          # Playwright configuration
├── tsconfig.json
├── package.json
└── README.md

---

🧪 Running Tests

# Run all tests
npx playwright test

# Run in headed mode (see the browser)
npx playwright test --headed

# Run a specific test file
npx playwright test tests/auth/login.spec.ts

# Run tests matching a grep pattern
npx playwright test --grep "login"

# Run on a specific browser
npx playwright test --project=chromium

# Run in debug mode
npx playwright test --debug

# Run with UI mode
npx playwright test --ui

---

⚙️ Configuration

Key settings in playwright.config.ts:

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  timeout: 30_000,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [['html'], ['list']],
  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

---

📊 Reporting

# Open the HTML report after a test run
npx playwright show-report

Reports are generated in the playwright-report/ directory by default.

---

🔄 CI/CD

A GitHub Actions workflow is included at .github/workflows/playwright.yml:

name: Playwright Tests

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m "feat: add my feature"
4. Push to the branch: git push origin feature/my-feature
5. Open a Pull Request

Please follow Conventional Commits for commit messages.

---

📄 License

This project is licensed under the MIT License.

---

---

🇻🇳 Tiếng Việt

🎭 Tên Dự Án — Tự Động Hóa Kiểm Thử với Playwright

Framework kiểm thử end-to-end được xây dựng bằng Playwright và TypeScript.

---

✨ Tính Năng

• Kiểm thử đa trình duyệt — Chromium, Firefox, WebKit
• Chạy song song — phản hồi nhanh nhờ cơ chế worker
• Tự động chờ (auto-wait) — không còn test flaky, Playwright tự xử lý trạng thái element
• Page Object Model (POM) — kiến trúc test sạch, dễ bảo trì
• Báo cáo HTML & Allure — báo cáo test trực quan
• Sẵn sàng CI/CD — đã bao gồm workflow GitHub Actions
• Quản lý môi trường — cấu hình qua file .env

---

📋 Yêu Cầu Hệ Thống

Công cụ	Phiên bản
Node.js	>= 18
npm / yarn / pnpm	mới nhất
Git	mới nhất

---

🚀 Bắt Đầu

# Clone repository
git clone https://github.com/<your-org>/<your-repo>.git
cd <your-repo>

# Cài đặt dependencies
npm install

# Cài đặt trình duyệt Playwright
npx playwright install --with-deps

# Chạy toàn bộ test
npx playwright test

Biến Môi Trường

Sao chép file env mẫu và cập nhật giá trị:

cp .env.example .env

Biến	Mô tả	Mặc định
BASE_URL	URL gốc của ứng dụng	http://localhost:3000
ENV	Môi trường (dev / staging / prod)	dev
HEADLESS	Chạy trình duyệt ở chế độ headless	true

---

📁 Cấu Trúc Dự Án

├── .github/workflows/            # Pipeline CI/CD
├── src/
│   ├── fixtures/                 # Fixture tùy chỉnh
│   ├── pages/                    # Page Object Models
│   ├── helpers/                  # Hàm tiện ích
│   └── data/                     # Dữ liệu test (JSON, CSV, v.v.)
├── tests/                        # Thư mục chứa test
├── playwright.config.ts          # Cấu hình Playwright
├── tsconfig.json
├── package.json
└── README.md

---

🧪 Chạy Test

# Chạy toàn bộ test
npx playwright test

# Chạy có giao diện trình duyệt
npx playwright test --headed

# Chạy file test cụ thể
npx playwright test tests/auth/login.spec.ts

# Lọc test theo tên
npx playwright test --grep "login"

# Chạy trên trình duyệt cụ thể
npx playwright test --project=chromium

# Chạy chế độ debug
npx playwright test --debug

# Chạy chế độ UI
npx playwright test --ui

---

📊 Báo Cáo

# Mở báo cáo HTML sau khi chạy test
npx playwright show-report

---

🤝 Đóng Góp

1. Fork repository
2. Tạo nhánh tính năng: git checkout -b feature/tinh-nang-moi
3. Commit thay đổi: git commit -m "feat: thêm tính năng mới"
4. Push lên nhánh: git push origin feature/tinh-nang-moi
5. Tạo Pull Request

Vui lòng tuân theo Conventional Commits cho commit message.

---

📄 Giấy Phép

Dự án được phân phối theo Giấy phép MIT.