Skip to content

Bandum format ​

This page describes Bandum's conventions on GitHub or GitLab and the format of the acceptance-testing files in the repo. For how to use all of this in the workflow, see Acceptance testing.

Conventions on GitHub and GitLab ​

ConceptOn the platform
TaskIssue, with the code GH-<number>. GitLab also uses the GH- prefix with the issue number in the project
SprintMilestone
OwnerAssignee
StatusThe status: … label. No label means Todo, and a closed issue is Done
Approve, returnPR review (MR on GitLab): Approve or Request changes

Labels ​

The table below lists the labels Bandum uses. Bandum sets the status labels itself, so you only need to set type and level.

LabelValueMeaning
status: in progressIn progress
status: reviewAwaiting acceptance testing
status: approvedApproved, awaiting merge
status: rejectedReturned
level: S, level: M, level: LExactly oneSize of the work
type: feature, type: bug, type: debt, type: riskExactly oneType of work, used for Flow reports. A missing label counts as unknown
severity: high, severity: medium, severity: lowOptionalSeverity, on issues created by ph bandum bug
source: agentOptionalIssue reported by an agent

A task goes from Todo to In progress, then Review. If the Tester approves, the task moves to Approved and then Done. If the Tester returns it, the task moves to Rejected and goes back to In progress for fixes.

The task state machine. Todo moves to In progress with ph bandum start. In progress moves to Review with ph bandum review. From Review, the tester clicks Duyệt (Approve) to make it Approved, then merging the PR moves it to Done, or clicks Trả lại (Send back) to make it Rejected. Rejected returns to In progress with ph bandum fix.Todono status labelIn progressstatus: in progressReviewstatus: reviewRejectedstatus: rejectedApprovedstatus: approvedDoneissue closedph bandum startph bandum reviewSend back on web or testph bandum fixApprovemerge PR

Swipe sideways to see the whole diagram.

Bandum sets the status label itself at each transition, so you never add it by hand. A task with no status label is Todo, and a closed issue is Done.

A level L task has its own spec directory. Level S and M tasks use the shared directory described below.

File locations ​

text
docs/features/GH-12-login/         level L: next to spec.md
docs/acceptance/GH-12/             level S, M
  testcases.md
  acceptance.md
  evidence/                        screenshots, small logs
.bandum.json                       repo root

To find the exact location, run ph bandum paths GH-12 --json. ph bandum start creates the testcases.md skeleton in the right place.

Version marker ​

markdown
<!-- bandum-format: 1 -->

The marker goes in the first 10 lines of the file, before the first ## heading, usually right under the # heading. Both testcases.md and acceptance.md have the marker, and a file without a marker is treated as v1.

A malformed marker is an error. A version higher than the reader supports is also an error, with a request to upgrade Phillip or Bandum.

testcases.md ​

markdown
# Test cases GH-12
<!-- bandum-format: 1 -->

## TC-1 (AC-1.1, AC-1.2) Sign in with the correct password
Steps:
1. Open /login
2. Enter the sample account
Expected: the home page opens

Each test case is a level-2 heading on exactly one line, following the pattern ## TC-<number> (<AC code>, …) <name>. An AC code has the form AC-<number>.<number>, and multiple codes are separated by commas. The body is every line up to the next # or ## heading. It's the instructions for the tester.

TC codes must be unique within a file. Each TC links to at least one AC, and each AC of the task has at least one TC.

ACs come from spec.md (level L, headings like #### AC-1.1 …) or from the issue description (lines that start with AC-1.1, optionally after - , - [ ] , or **). Code blocks don't count.

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 | Account isn't locked |

General note: …

The format stays version 1. Files written earlier in Vietnamese (# 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>) are still read, and Bandum and Phillip write only the English form.

Only ph bandum test, ph bandum verify, and the Bandum web UI write this file, and they only append to the end. They never edit or delete earlier runs.

Each run's heading has the form ## Run <N> · <time> · @<person> · commit <12-character sha> · Approved|Sent back. Each result row has the form | TC-n | <AC code> | <result> | <note> |, where the result is ✅ Pass or ❌ Fail. A | character in a note must be written as \|. The closing General note: line is optional.

.bandum.json ​

A JSON file at the repo root that tells Bandum how to run the app and the acceptance tests on your machine.

KeyTypeMeaning
setupstringPreparation command
runstringCommand that runs the app
urlstringApp address after it starts
teststringCommand that runs the automated acceptance tests
reportstringPath to the JUnit report
notesstringNotes
startTimeoutnumberSeconds to wait for the app to start
stagingUrlstringHTTP or HTTPS URL of the staging environment. With this key, the manual testing page shows the Open staging button

If test or report is missing, ph bandum verify can't grade automatically and reports a warning. An unknown key is also only a warning, and broken JSON is an error.

Automated tests by TC code ​

Bandum matches tests to TCs by test name (or classname), so the name must contain the TC code as a standalone token, for example TC-1 (AC-1.1) sign in with the correct password. TC-1 doesn't match TC-10. A TC with several tests passes only when all of its tests pass. A TC with no tests, or with skipped tests, counts as failed.

ph bandum check ​

bash
ph bandum check [GH-n] [--offline] [--junit <file>] [--json]

The command exits with code 0 when there are no errors (warnings still give 0) and code 2 when there are errors.

LevelCodeMeaning
errormissing_testcasesNo testcases.md
errorformat_versionUnsupported version or malformed marker
errormalformed_headingA heading looks like a TC but has the wrong syntax
errorempty_testcasesNo test cases
errorduplicate_tcDuplicate TC code
errortc_without_acA TC isn't linked to an AC
errorunfilled_testcaseA skeleton hasn't been filled in
errormisplaced_testcasesA test case is in the wrong file or place
erroruncovered_acAn AC has no TC
errormalformed_runA ## Run heading is malformed
erroracceptance_editedEarlier content in acceptance.md was edited
errorbandum_json.bandum.json is broken
errortc_without_test, junit_missingWith --junit: a TC has no test, or the file can't be read
warningunknown_acA TC references an AC that isn't in the source
warningac_source_empty, ac_source_unavailableThe AC source has no ACs or can't be retrieved
warningbandum_json_no_test, bandum_json_unknown_key, bandum_json_staging_urltest or report is missing; unknown key; invalid stagingUrl
warningtest_skippedWith --junit: a test was skipped

With --json, the command prints { issue, dir, formatVersion, findings: [{ level, code, file?, line?, message }] }.

Evolution rules ​

If you only add optional fields that older readers can ignore, such as a new column at the end of a table or a new .bandum.json key, the version stays the same. If you change the heading or table syntax, or change the meaning of something that already exists, bump the version.

A newer reader can read every older version. An older reader that meets a newer version reports an error and asks you to upgrade, rather than reading it wrong in silence.

Further reading ​