Định dạng Bandum
Trang này tả quy ước của Bandum trên GitHub hoặc GitLab và định dạng các file kiểm thử nghiệm thu trong repo. Cách dùng cả bộ này trong quy trình nằm ở Kiểm thử và nghiệm thu.
Quy ước trên GitHub và GitLab
| Khái niệm | Trên nền tảng |
|---|---|
| Task | Issue, mã GH-<số>. GitLab cũng dùng tiền tố GH- với số issue trong project |
| Sprint | Milestone |
| Người phụ trách | Assignee |
| Trạng thái | Label status: …. Chưa có label là Todo, issue đã đóng là Done |
| Duyệt, trả lại | Review của PR (GitLab là MR): Approve hoặc Request changes |
Label
Bảng dưới liệt kê label Bandum dùng. Trạng thái do Bandum tự gắn, bạn chỉ phải gắn type và level.
| Label | Giá trị | Ý nghĩa |
|---|---|---|
status: in progress | Đang làm | |
status: review | Chờ kiểm thử nghiệm thu | |
status: approved | Đã duyệt, chờ merge | |
status: rejected | Bị trả lại | |
level: S, level: M, level: L | Một trong ba | Cỡ việc |
type: feature, type: bug, type: debt, type: risk | Đúng một | Loại việc, dùng cho báo cáo Flow. Thiếu label thì tính là unknown |
severity: high, severity: medium, severity: low | Tùy chọn | Mức độ, nằm trên issue do ph bandum bug tạo |
source: agent | Tùy chọn | Issue do agent báo |
Task đi từ Todo sang In progress, rồi Review. Nếu người kiểm thử duyệt thì task sang Approved rồi Done. Nếu trả lại thì task sang Rejected và quay về In progress để sửa.
Vuốt ngang để xem hết sơ đồ.
Task mức L có thư mục spec riêng, còn task mức S và M dùng thư mục chung như phần dưới.
Vị trí file
docs/features/GH-12-dang-nhap/ mức L: cạnh spec.md
docs/acceptance/GH-12/ mức S, M
testcases.md
acceptance.md
evidence/ ảnh chụp, log nhỏ
.bandum.json gốc repoMuốn biết vị trí chính xác thì chạy ph bandum paths GH-12 --json. ph bandum start dựng sẵn khung testcases.md đúng chỗ.
Marker phiên bản
<!-- bandum-format: 1 -->Marker nằm trong 10 dòng đầu của file, trước tiêu đề ## đầu tiên, thường ngay dưới tiêu đề #. Cả testcases.md lẫn acceptance.md đều có marker, và file thiếu marker được coi là v1.
Marker sai dạng là lỗi. Version cao hơn bản đọc hỗ trợ cũng là lỗi, kèm yêu cầu nâng cấp Phillip hoặc Bandum.
testcases.md
# Test cases GH-12
<!-- bandum-format: 1 -->
## TC-1 (AC-1.1, AC-1.2) Đăng nhập đúng mật khẩu
Steps:
1. Mở /login
2. Nhập tài khoản mẫu
Expected: vào trang chủMỗi testcase là một tiêu đề cấp 2 trên đúng một dòng, theo mẫu ## TC-<số> (<mã AC>, …) <tên>. Mã AC có dạng AC-<số>.<số>, nhiều mã thì cách nhau bằng dấu phẩy. Phần thân gồm mọi dòng cho đến tiêu đề # hoặc ## kế tiếp, đó là hướng dẫn cho người kiểm thử.
Mã TC không được trùng nhau trong một file. Mỗi TC gắn ít nhất một AC, và mỗi AC của task có ít nhất một TC.
AC lấy từ spec.md (mức L, tiêu đề #### AC-1.1 …) hoặc từ mô tả issue (dòng bắt đầu bằng AC-1.1, có thể đứng sau - , - [ ] hoặc **). Khối code không tính.
acceptance.md
# Acceptance testing GH-12
<!-- bandum-format: 1 -->
## Run 1 · 2026-10-26 13:46 · @tester · commit a61bca8a5312 · Sent back
| TC | AC | Result | Note |
| --- | --- | --- | --- |
| TC-1 | AC-1.1 | ✅ Pass | |
| TC-3 | AC-1.3 | ❌ Fail | Không bị khóa |
General note: …Chỉ ph bandum test, ph bandum verify và web Bandum ghi file này, và chúng chỉ thêm vào cuối, không sửa hay xóa lần cũ.
Tiêu đề mỗi lần có dạng ## Run <N> · <giờ> · @<người> · commit <sha 12 ký tự> · Approved|Sent back. Mỗi dòng kết quả có dạng | TC-n | <mã AC> | <kết quả> | <ghi chú> |, trong đó kết quả là ✅ Pass hoặc ❌ Fail. Ký tự | trong ghi chú phải viết thành \|. Dòng General note: ở cuối là tùy chọn.
Format vẫn là version 1. File ghi trước đây bằng tiếng Việt (# Kiểm thử nghiệm thu, ## Lần, Đạt, Trả lại, Không đạt, Kết quả, Ghi chú, Ghi chú chung, <điền tên>) vẫn đọc được. Bandum và Phillip chỉ ghi tiếng Anh.
.bandum.json
File JSON ở gốc repo, cho Bandum biết cách chạy ứng dụng và test nghiệm thu trên máy bạn.
| Khóa | Kiểu | Ý nghĩa |
|---|---|---|
setup | chuỗi | Lệnh chuẩn bị |
run | chuỗi | Lệnh chạy ứng dụng |
url | chuỗi | Địa chỉ ứng dụng sau khi chạy |
test | chuỗi | Lệnh chạy test nghiệm thu tự động |
report | chuỗi | Đường dẫn báo cáo JUnit |
notes | chuỗi | Ghi chú |
startTimeout | số | Số giây chờ ứng dụng khởi động |
stagingUrl | chuỗi | URL http hoặc https của môi trường staging. Có khóa này thì trang kiểm thử tay hiện nút Open staging (mở môi trường staging) |
Thiếu test hoặc report thì ph bandum verify không chấm tự động được và báo cảnh báo. Khóa lạ cũng chỉ là cảnh báo, còn JSON hỏng là lỗi.
Test tự động theo mã TC
Bandum ghép test với TC qua tên test (hoặc classname), nên tên phải chứa mã TC đứng riêng, ví dụ TC-1 (AC-1.1) đăng nhập đúng mật khẩu. TC-1 không khớp TC-10. TC có nhiều test chỉ đạt khi mọi test đạt. TC không có test, hoặc test bị bỏ qua, tính là không đạt.
ph bandum check
ph bandum check [GH-n] [--offline] [--junit <file>] [--json]Lệnh thoát với mã 0 khi không có lỗi (cảnh báo vẫn là 0) và mã 2 khi có lỗi.
| Mức | Mã | Ý nghĩa |
|---|---|---|
| lỗi | missing_testcases | Không có testcases.md |
| lỗi | format_version | Version không hỗ trợ hoặc marker sai dạng |
| lỗi | malformed_heading | Tiêu đề trông như TC nhưng sai cú pháp |
| lỗi | empty_testcases | Không có testcase nào |
| lỗi | duplicate_tc | Trùng mã TC |
| lỗi | tc_without_ac | TC không gắn AC |
| lỗi | unfilled_testcase | Còn khung chưa điền |
| lỗi | misplaced_testcases | Testcase nằm sai file hoặc sai chỗ |
| lỗi | uncovered_ac | AC chưa có TC |
| lỗi | malformed_run | Tiêu đề ## Run sai dạng |
| lỗi | acceptance_edited | acceptance.md bị sửa nội dung cũ |
| lỗi | bandum_json | .bandum.json hỏng |
| lỗi | tc_without_test, junit_missing | Khi dùng --junit: TC không có test, hoặc không đọc được file |
| cảnh báo | unknown_ac | TC tham chiếu AC không có trong nguồn |
| cảnh báo | ac_source_empty, ac_source_unavailable | Nguồn AC không có AC hoặc không lấy được |
| cảnh báo | bandum_json_no_test, bandum_json_unknown_key, bandum_json_staging_url | Thiếu test hoặc report; khóa lạ; stagingUrl không hợp lệ |
| cảnh báo | test_skipped | Khi dùng --junit: test bị bỏ qua |
Thêm --json thì lệnh in { issue, dir, formatVersion, findings: [{ level, code, file?, line?, message }] }.
Quy tắc tiến hóa
Nếu chỉ thêm trường tùy chọn mà bộ đọc cũ bỏ qua được, như cột mới cuối bảng hay khóa mới của .bandum.json, thì version giữ nguyên. Nếu đổi cú pháp tiêu đề hoặc bảng, hay đổi nghĩa của thứ đã có, thì tăng version.
Bộ đọc mới đọc được mọi version cũ. Bộ đọc cũ gặp version mới sẽ báo lỗi và yêu cầu nâng cấp, chứ không đọc sai trong im lặng.