# Playwright Automation — sun-ecm ## Tổng quan Dự án test tự động Playwright cho hệ thống ECM (sun-ecm). - Test files: `sun-ecm/tests/uc/` - Helpers & fixtures: `sun-ecm/src/` - Tài liệu kỹ thuật dùng chung: `sun-ecm/tests/README.md` --- ## Tài liệu theo màn hình **Mỗi màn hình có 1 file tài liệu kỹ thuật riêng** trong `sun-ecm/src/screen-instructions/`. Trước khi viết hoặc sửa test cho màn hình nào, đọc file tương ứng — file đó là nguồn sự thật duy nhất về URL, fields, buttons, selectors và patterns của màn đó. | Màn hình | UC liên quan | File tài liệu | Skill | | --------------------------------- | ------------ | -------------------------------------------------------------- | ------------------ | | Kho tài liệu (`/managed-records`) | UC29, UC77… | `sun-ecm/src/screen-instructions/KHO_TAI_LIEU.md` | `/kho-tai-lieu` | | Ngăn (`/settings/compartments`) | UC9 | `sun-ecm/src/screen-instructions/TANG.md` | — | ### Project `sun-ecm-update` (bản build mới của app) | Màn hình | File tài liệu | Skill | | --------------------------------- | -------------------------------------------------------------------- | ------------------ | | Kho tài liệu (`/managed-records`) | `sun-ecm-update/src/screen-instructions/KHO-TAI-LIEU.md` (+ các file MD con `KHO-TAI-LIEU.*.md`) | `/kho-tai-lieu-v2` | > ⚠️ `sun-ecm` và `sun-ecm-update` là **2 bản app khác nhau** — testId/hành vi đã đổi nhiều. > Đừng dùng lẫn tài liệu giữa 2 project. > Khi người dùng đề cập tên màn hình, mã UC, hoặc URL → tra bảng trên, đọc file tài liệu tương ứng **trước khi** thực hiện bất kỳ thao tác nào. --- ## Quy ước đặt tên & cấu trúc test **Chia theo mục số của testcase, KHÔNG chia theo thư mục UC** (1 mục có thể thuộc nhiều UC, và 1 UC rải ra nhiều mục → tầng `uc/` gây rối). Cấu trúc: - Spec file: `tests//..spec.ts` — vd `tests/1.4.1/1.4.1.153.spec.ts` - Tên test: `"UC - - " + ACCOUNT.` (mã UC vẫn ghi trong **tên test** và trong khối comment đầu file, không ghi vào đường dẫn) - Fixture: `librarian` (ecm01) + `admin` (ecm09) là mặc định; thêm fixture khác khi cần vai phụ - **Tiền điều kiện chung + danh sách case của 1 mục: `tests//.md`** — xem mục "Phạm vi file `.md`" bên dưới. **Đọc file này trước khi viết case của mục đó; thêm case mới thì cập nhật lại danh sách case.** Nếu mục chưa có file → tạo (mẫu: `sun-ecm-update/tests/1.4.2/1.4.2.md`). - Data file: `tests//.default.data.ts` - Dựng dữ liệu tiền điều kiện dùng chung cho nhiều case của 1 mục: `tests//.setup.ts` - Thao tác (chuỗi bước) dùng chung cho nhiều case của 1 mục: `tests//.steps.ts` (thao tác thuần màn hình thì vẫn để ở `screen-instructions/.functions.ts`) --- ## Phạm vi file `.md` — 🚨 CHỈ TIỀN ĐIỀU KIỆN CHUNG, KHÔNG GHI LOGIC `tests//.md` là tài liệu **dùng chung cho cả bộ case của 1 mục**, nên chỉ chứa những gì **mọi case trong mục đều dùng**: | ✅ Được ghi vào `.md` | ❌ Không ghi vào — thuộc về đâu | | --------------------------------------------------------- | -------------------------------------------------------------------------------- | | Nguyên văn tiền điều kiện QA + cách đọc nó | Thao tác / Mong muốn của 1 case → comment đầu file `..spec.ts` | | Bảng "vai → cách script dựng dữ liệu" | Cách assert, kỳ vọng, tiêu chí fail → spec của case đó | | Cấu trúc dữ liệu mà `.setup.ts` tạo ra | Giả định khi viết case, điểm cần QA/DEV chốt của 1 case → spec của case đó | | Ràng buộc bắt buộc khi **dựng dữ liệu** (vd phải Hoạt động) | Bảng/mô tả hàm dùng chung → **JSDoc ngay tại hàm** (`.steps.ts`, `*.functions.ts`) | | Danh sách case: mã, nội dung testcase, file, trạng thái chạy | Mô tả cách làm của từng case trong bảng danh sách case | **Nguyên tắc chung: không mô tả logic vào file `.md` nào cả** — logic nằm cạnh code của chính nó (comment đầu spec cho logic của case, JSDoc cho logic của hàm). File `.md` chỉ dùng cho **tiền điều kiện chung** và **mô tả màn hình** (mục dưới). Lý do: logic viết trong `.md` bị trùng lặp với spec, phình file và nhanh lạc hậu khi sửa case. > ⚠️ `sun-ecm-update/tests/1.4.1/1.4.1.md` và `1.4.6.md` viết trước quy ước này nên **còn lẫn logic** > (bảng hàm steps, ghi chú từng case) — đừng lấy làm mẫu; mẫu đúng là `1.4.2.md`. --- ## Đọc tiền điều kiện của testcase QA Testcase QA gửi sang gồm **Tiền điều kiện → Thao tác → Mong muốn**. Quy ước xử lý: 1. **Tiền điều kiện là điều đã cho, không phải điều cần nghi ngờ.** QA ghi "vai X được phân quyền Y" thì mặc định X **thực hiện được** toàn bộ phần Thao tác để tới bước Mong muốn. Viết thẳng case theo mô tả; **không** tự đổi kỳ vọng thành "vai này chắc bị chặn". Nếu chạy thật mà bị chặn → đó là **kết quả test**, để QA/DEV kết luận. 2. **Quyền cấp lớn bao trùm cấp nhỏ**: có quyền trên **BHS** thì cũng có quyền đó trên **TM/TL** bên trong nó. Ngược lại thì không. 3. Việc **dựng dữ liệu** cho tiền điều kiện là của script (tạo BHS, cấp quyền, chuyển trạng thái…) — thường do `librarian`/`admin` dựng, rồi vai cần kiểm tra mới thao tác. 4. Chỗ nào tài liệu màn hình chưa có testId/selector → hỏi lại hoặc khảo sát bằng `/khao-sat-man-hinh`, **không bịa**. Nhưng chỉ hỏi về **selector/hành vi màn hình**, không hỏi lại những gì tiền điều kiện đã khẳng định. --- ## Phạm vi nội dung file mô tả màn hình - File `screen-instructions/.md` mô tả **đúng những gì nhìn thấy trên màn hình**: field, nút, testId, cấu trúc modal/bảng, thông báo, luồng thao tác. Viết sao cho người đọc hình dung được màn hình **mà không cần mở MCP**. - **Logic ẩn/hiện theo vai, chặn truy cập, điều kiện quyền** → để **file riêng** (vd `KHO-TAI-LIEU.PHAN-QUYEN-THEO-VAI.md`), không nhồi vào file mô tả gốc. Hành vi ẩn/hiện đúng hay sai là việc của **test case**, không phải của tài liệu. --- ## Thêm màn hình mới 1. Tạo `sun-ecm/src/screen-instructions/.md` 2. Tạo `.claude/commands/.md` (skill tương ứng) 3. Thêm 1 dòng vào bảng "Tài liệu theo màn hình" ở trên