Bỏ qua, đến phần nội dung

Đị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ệmTrên nền tảng
TaskIssue, mã GH-<số>. GitLab cũng dùng tiền tố GH- với số issue trong project
SprintMilestone
Người phụ tráchAssignee
Trạng tháiLabel status: …. Chưa có label là Todo, issue đã đóng là Done
Duyệt, trả lạiReview 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.

LabelGiá trịÝ nghĩa
status: in progressĐang làm
status: reviewChờ kiểm thử nghiệm thu
status: approvedĐã duyệt, chờ merge
status: rejectedBị trả lại
level: S, level: M, level: LMột trong baCỡ việc
type: feature, type: bug, type: debt, type: riskĐúng mộtLoại việc, dùng cho báo cáo Flow. Thiếu label thì tính là unknown
severity: high, severity: medium, severity: lowTùy chọnMức độ, nằm trên issue do ph bandum bug tạo
source: agentTùy chọnIssue 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.

Máy trạng thái của task. Todo chuyển sang In progress bằng ph bandum start. In progress chuyển sang Review bằng ph bandum review. Từ Review, người kiểm thử bấm Duyệt thì thành Approved rồi merge PR để sang Done, hoặc bấm Trả lại thì thành Rejected. Rejected quay về In progress bằng ph bandum fix.Todochưa có nhãn statusIn progressstatus: in progressReviewstatus: reviewRejectedstatus: rejectedApprovedstatus: approvedDoneissue đã đóngph bandum startph bandum reviewTrả lại trên web hoặc testph bandum fixDuyệtmerge PR

Vuốt ngang để xem hết sơ đồ.

Nhãn status do Bandum tự đặt ở mỗi lần chuyển, bạn không cần gắn tay. Task chưa có nhãn status là Todo, issue đã đóng là Done.

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 ​

text
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 repo

Muố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 ​

markdown
<!-- 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 ​

markdown
# 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 ​

markdown
# 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óaKiểuÝ nghĩa
setupchuỗiLệnh chuẩn bị
runchuỗiLệnh chạy ứng dụng
urlchuỗiĐịa chỉ ứng dụng sau khi chạy
testchuỗiLệnh chạy test nghiệm thu tự động
reportchuỗiĐường dẫn báo cáo JUnit
noteschuỗiGhi chú
startTimeoutsốSố giây chờ ứng dụng khởi động
stagingUrlchuỗiURL 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 ​

bash
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ứcMãÝ nghĩa
lỗimissing_testcasesKhông có testcases.md
lỗiformat_versionVersion không hỗ trợ hoặc marker sai dạng
lỗimalformed_headingTiêu đề trông như TC nhưng sai cú pháp
lỗiempty_testcasesKhông có testcase nào
lỗiduplicate_tcTrùng mã TC
lỗitc_without_acTC không gắn AC
lỗiunfilled_testcaseCòn khung chưa điền
lỗimisplaced_testcasesTestcase nằm sai file hoặc sai chỗ
lỗiuncovered_acAC chưa có TC
lỗimalformed_runTiêu đề ## Run sai dạng
lỗiacceptance_editedacceptance.md bị sửa nội dung cũ
lỗibandum_json.bandum.json hỏng
lỗitc_without_test, junit_missingKhi dùng --junit: TC không có test, hoặc không đọc được file
cảnh báounknown_acTC tham chiếu AC không có trong nguồn
cảnh báoac_source_empty, ac_source_unavailableNguồn AC không có AC hoặc không lấy được
cảnh báobandum_json_no_test, bandum_json_unknown_key, bandum_json_staging_urlThiếu test hoặc report; khóa lạ; stagingUrl không hợp lệ
cảnh báotest_skippedKhi 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.

Đọc thêm ​