# CẤP ĐỘ 1 — Cài Đặt & Chạy Test Đầu Tiên

> **Dành cho ai?** Người **hoàn toàn chưa biết lập trình**, chưa từng dùng terminal.
> **Mục tiêu của cấp độ này:** Cài đặt xong công cụ, **chạy được test có sẵn** và **đọc hiểu kết quả** pass/fail.
> Bạn **KHÔNG cần viết một dòng code nào** ở cấp độ này.

## ✅ Bạn hoàn thành Cấp độ 1 khi:

- [ ] Gõ `node --version` thấy số phiên bản
- [ ] Mở được project trong VSCode và mở được terminal bên trong VSCode
- [ ] Chạy `npm install` và `npx playwright install` không lỗi
- [ ] Chạy 1 test có sẵn, **thấy trình duyệt tự bật lên và tự thao tác**
- [ ] Đọc được dòng tổng kết `X passed, Y failed` trong terminal
- [ ] Mở được báo cáo HTML bằng `npx playwright show-report`

Khi tick đủ 6 ô trên → chuyển sang **Cấp độ 1.5**.

---

## Phần 0 — Từ Điển Thuật Ngữ (đọc 5 phút, đỡ hoang mang cả tuần)

| Thuật ngữ | Hiểu đơn giản là |
| --- | --- |
| **Terminal** | Cửa sổ để "nói chuyện" với máy tính bằng cách gõ lệnh chữ, thay vì click chuột. Gõ lệnh → Enter → máy làm. |
| **Lệnh (command)** | Một câu chữ bạn gõ vào terminal. Ví dụ `node --version` là lệnh hỏi "Node phiên bản mấy?". |
| **Node.js** | Phần mềm nền để chạy Playwright. Giống như phải cài "đầu đọc" trước khi xem đĩa. |
| **npm / npx** | Công cụ đi kèm Node.js để tải và chạy các thư viện. Bạn không cần hiểu sâu — chỉ cần gõ đúng lệnh. |
| **Project** | Thư mục chứa toàn bộ code test của team. Nhận từ Git hoặc file nén. |
| **Test / Test case** | Một kịch bản kiểm tra tự động, ví dụ: "mở trang → điền username → click Login → kiểm tra đăng nhập thành công". |
| **Pass / Fail** | Pass ✓ = kết quả đúng như mong đợi. Fail ✗ = có gì đó sai (có thể do bug, có thể do test viết sai). |
| **Spec file** | File chứa code của test case, tên có đuôi `.spec.ts`. Cấp độ 2 bạn sẽ tự viết. |
| **Selector** | "Địa chỉ" của một nút/ô nhập trên trang web, để Playwright biết click vào đâu. Học ở Cấp độ 2. |

> **Quy ước trong tài liệu:** những dòng nằm trong ô màu xám (code block) là **lệnh để gõ vào terminal**.
> Nếu dòng bắt đầu bằng ký tự `$` thì **không gõ dấu `$`** — chỉ gõ phần sau nó.
> Dòng bắt đầu bằng `#` là chú thích, không cần gõ.

---

## Phần 1 — Cài Đặt

### 1.1 Cài Node.js

1. Truy cập [https://nodejs.org](https://nodejs.org)
2. Tải bản **LTS** (Long Term Support) — nút bên trái
3. Chạy file cài đặt (`.pkg` trên Mac, `.msi` trên Windows), nhấn **Next** → **Finish**, giữ nguyên mọi lựa chọn mặc định
4. Kiểm tra:
   - **Mac:** nhấn ⌘ + Space → gõ "Terminal" → Enter
   - **Windows:** nhấn Windows + R → gõ `cmd` → Enter
   - Gõ lệnh sau rồi Enter:
     ```
     node --version
     ```
   - Thấy số phiên bản dạng `v20.11.0` → thành công ✓

> **Nếu Windows báo `'node' is not recognized...`:** đóng cửa sổ cmd, mở lại rồi thử lại.
> Vẫn không được → khởi động lại máy (Node cần "đăng ký" với hệ thống sau khi cài).

### 1.2 Cài VSCode

**VSCode** (Visual Studio Code) là chương trình để mở và soạn thảo code — giống Word nhưng dành cho code.

1. Truy cập [https://code.visualstudio.com](https://code.visualstudio.com)
2. Tải về và cài đặt theo hướng dẫn trên màn hình
3. Mở VSCode — bạn thấy thanh biểu tượng bên trái (Activity Bar) và vùng soạn thảo ở giữa

### 1.3 Cài Extension "Playwright Test for VSCode"

Extension = tiện ích cài thêm vào VSCode. Cái này giúp bạn **chạy test bằng nút bấm**, không cần gõ lệnh.

1. Trong VSCode, nhấn **Ctrl+Shift+X** (Windows) hoặc **⌘+Shift+X** (Mac)
2. Gõ tìm: `Playwright Test for VSCode`
3. Chọn extension có biểu tượng 2 mặt nạ xanh–đỏ, nhà xuất bản **Microsoft**
4. Nhấn **Install**

### 1.4 Mở Project trong VSCode

Project nhận từ Git hoặc file nén (giải nén vào thư mục quen thuộc trước), sau đó:

1. Mở VSCode
2. Menu **File** → **Open Folder…**
3. Chọn thư mục project, nhấn **Open**
4. Nếu VSCode hỏi "Do you trust the authors?" → chọn **Yes, I trust the authors**

Cây thư mục hiện bên trái (Explorer) — đây là "nhà" của project.

### 1.5 Mở Terminal ngay trong VSCode

Từ giờ trở đi, mọi lệnh đều gõ trong terminal **bên trong VSCode** (tiện hơn mở riêng):

- Menu **Terminal** → **New Terminal** (hoặc phím **Ctrl+`** — dấu huyền, bên trái phím số 1)
- Panel terminal xuất hiện phía dưới, **tự động trỏ sẵn vào thư mục project** ✓

### 1.6 Cài thư viện của project

Gõ lệnh này **một lần duy nhất** cho mỗi project:

```bash
npm install
```

Đợi vài phút — terminal tự tải về hàng trăm thư viện. Xong khi thấy dòng `added X packages`.

### 1.7 Cài trình duyệt cho Playwright

Playwright dùng trình duyệt **riêng** của nó (không đụng đến Chrome bạn đang dùng):

```bash
npx playwright install
```

Lần đầu mất 5–10 phút tùy mạng. Chỉ cần làm 1 lần trên mỗi máy.

### 1.8 ⚠️ Nếu cài đặt gặp lỗi — tra bảng này trước khi hỏi

| Hiện tượng | Nguyên nhân thường gặp | Cách xử lý |
| --- | --- | --- |
| `'node' is not recognized` / `command not found: node` | Chưa cài Node, hoặc chưa khởi động lại terminal sau khi cài | Đóng mở lại terminal; vẫn lỗi thì khởi động lại máy; vẫn lỗi thì cài lại Node |
| `npm install` chạy rất lâu rồi báo lỗi mạng (`ETIMEDOUT`, `ECONNRESET`) | Mạng công ty chặn / có proxy | Thử mạng khác (phát wifi điện thoại) để xác nhận; nếu đúng do mạng công ty → hỏi IT về cấu hình proxy cho npm |
| `npx playwright install` treo hoặc lỗi tải browser | Tương tự — firewall chặn tải file lớn | Thử mạng khác; hoặc hỏi người đã cài được trong team |
| Windows PowerShell báo `running scripts is disabled` | Windows chặn chạy script | Dùng **Command Prompt** (cmd) thay vì PowerShell: trong terminal VSCode, click mũi tên cạnh dấu `+` → chọn **Command Prompt** |
| Trên Linux: browser bật lên rồi lỗi thiếu thư viện hệ thống | Thiếu dependencies | Chạy `npx playwright install-deps` |
| `EACCES: permission denied` | Thiếu quyền ghi file | Mac/Linux: đừng dùng `sudo` với npm; kiểm tra thư mục project có thuộc quyền của bạn không |

**Nguyên tắc chung khi gặp lỗi:** copy nguyên văn dòng lỗi (dòng đầu tiên màu đỏ) và tìm Google hoặc hỏi Claude/ChatGPT kèm nguyên văn đó. Đừng gõ lại bằng trí nhớ — dễ sai chính tả.

### 1.9 Cấu hình tài khoản (chỉ cho project nội bộ)

> **Bỏ qua bước này** nếu bạn đang học với trang demo saucedemo.com. Quay lại khi vào project thật (Cấp độ 3 hướng dẫn chi tiết).

Tóm tắt: project nội bộ cần file `.env` (chứa URL môi trường) và `account.json` (chứa tài khoản test). Chi tiết trong tài liệu Cấp độ 3, mục "Cấu hình môi trường".

---

## Phần 2 — Chạy Test Có Sẵn

Đây là khoảnh khắc quan trọng nhất của Cấp độ 1: **nhìn máy tính tự test thay bạn**.

### 2.1 Cách 1 — Chạy bằng VSCode Extension (khuyến nghị khi mới học)

1. Click **biểu tượng ống nghiệm** (🧪) ở thanh bên trái — mục **Testing**
2. Cây test hiện ra — mở rộng để thấy từng file, từng test case
3. **Tick vào ô "Show browser"** ở panel Playwright (phía dưới) — để thấy trình duyệt khi chạy
4. Nhấn nút **▶** cạnh tên một test bất kỳ
5. Trình duyệt bật lên, tự điền, tự click — bạn chỉ việc xem
6. Kết quả: ✓ xanh = pass, ✗ đỏ = fail. Click vào test fail để xem chi tiết lỗi

### 2.2 Cách 2 — Chạy bằng lệnh trong terminal

```bash
# Chạy tất cả test trong project
npx playwright test

# Chạy 1 thư mục hoặc 1 file cụ thể
npx playwright test tests/saucedemo/
npx playwright test tests/saucedemo/login.spec.ts

# Thêm --headed để MỞ trình duyệt cho bạn xem (mặc định chạy ẩn)
npx playwright test tests/saucedemo/ --headed

# Chạy tuần tự từng test một (dễ theo dõi khi mới học)
npx playwright test tests/saucedemo/ --headed --workers=1

# Chạy 1 test theo tên (lọc bằng -g)
npx playwright test -g "đăng nhập thành công" --headed
```

> **`--headed` là gì?** Mặc định Playwright chạy trình duyệt "ẩn" (headless) cho nhanh.
> Thêm `--headed` để hiện trình duyệt lên — khi học nên luôn dùng để thấy điều gì đang xảy ra.

### 2.3 Đọc kết quả trong terminal

Khi chạy xong, terminal hiện tổng kết:

```
Running 7 tests using 1 worker

  ✓  1 Login — Đăng nhập thành công (2.1s)
  ✓  2 Login — Đăng nhập thất bại khi sai mật khẩu (1.8s)
  ✗  3 Login — Đăng nhập thất bại khi để trống username (0.9s)

  6 passed, 1 failed (12.3s)
```

Khi có test fail, Playwright in thêm lý do:

```
Error: expect(locator).toContainText(expected)

Expected string: "Username is required"
Received string: ""

  → tests/saucedemo/login.spec.ts:58
```

**Cách đọc — theo đúng thứ tự 3 dòng:**

1. **Expected** = test mong đợi điều gì → "chữ *Username is required* phải xuất hiện"
2. **Received** = thực tế nhận được gì → "chuỗi rỗng, tức không có chữ nào"
3. **Dòng cuối** = lỗi xảy ra ở file nào, dòng bao nhiêu → `login.spec.ts` dòng 58

Chỉ cần đọc đúng 3 dòng này là biết 80% chuyện gì xảy ra. **Đừng sợ chữ đỏ** — fail là chuyện bình thường hằng ngày của tester automation.

### 2.4 Mở báo cáo HTML

Sau mỗi lần chạy, Playwright tự tạo báo cáo đẹp:

```bash
npx playwright show-report
```

Trình duyệt mở trang báo cáo, bạn có thể:

- Xem danh sách test pass/fail/skip
- Click vào test fail → xem **ảnh chụp màn hình** tại thời điểm lỗi
- Lọc theo trạng thái
- Gửi cả thư mục `playwright-report/` cho đồng nghiệp xem

### 2.5 Trace Viewer — "tua lại video" của test fail

**Trace** = bản ghi từng bước test đã làm, xem lại được như tua video.

1. Mở HTML report (`npx playwright show-report`)
2. Click vào test bị fail
3. Kéo xuống phần **Traces** → click vào trace
4. Trace Viewer mở ra:
   - Click từng bước để xem màn hình tại thời điểm đó
   - Thấy chính xác bước nào fail

> **Mẹo:** nếu đồng nghiệp gửi bạn 1 file trace (`.zip`), bạn có thể mở tại
> [https://trace.playwright.dev](https://trace.playwright.dev) mà không cần cài gì cả.

### 2.6 UI Mode — chế độ tương tác (trực quan nhất)

```bash
npx playwright test --ui
```

Một cửa sổ mở ra cho phép: chạy từng test bằng click, xem trình duyệt live, xem timeline từng thao tác. Đây là "sân chơi" tốt nhất khi mới học — hãy thử nghịch 10 phút.

---

## Tổng kết Cấp độ 1

Bạn vừa làm được điều mà nhiều người nghĩ là "chỉ dev mới làm được": cài môi trường, chạy test tự động, đọc kết quả. Quay lại checklist đầu tài liệu, tick đủ 6 ô.

**Tiếp theo:** mở tài liệu **Cấp độ 1.5 — Codegen: Nhìn Thao Tác Của Bạn Biến Thành Code**. Ở đó bạn sẽ dùng công cụ ghi thao tác để thấy mỗi click, mỗi lần gõ phím đều biến thành 1 dòng code — bước đệm nhẹ nhàng trước khi tự viết ở Cấp độ 2.

---

_Phiên bản 2.0 — tách từ tài liệu gốc, bổ sung từ điển thuật ngữ và bảng lỗi cài đặt._