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
| Concept | On the platform |
|---|---|
| Task | Issue, with the code GH-<number>. GitLab also uses the GH- prefix with the issue number in the project |
| Sprint | Milestone |
| Owner | Assignee |
| Status | The status: … label. No label means Todo, and a closed issue is Done |
| Approve, return | PR 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.
| Label | Value | Meaning |
|---|---|---|
status: in progress | In progress | |
status: review | Awaiting acceptance testing | |
status: approved | Approved, awaiting merge | |
status: rejected | Returned | |
level: S, level: M, level: L | Exactly one | Size of the work |
type: feature, type: bug, type: debt, type: risk | Exactly one | Type of work, used for Flow reports. A missing label counts as unknown |
severity: high, severity: medium, severity: low | Optional | Severity, on issues created by ph bandum bug |
source: agent | Optional | Issue 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.
Swipe sideways to see the whole diagram.
A level L task has its own spec directory. Level S and M tasks use the shared directory described below.
File locations
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 rootTo 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
<!-- 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
# 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 opensEach 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
# 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.
| Key | Type | Meaning |
|---|---|---|
setup | string | Preparation command |
run | string | Command that runs the app |
url | string | App address after it starts |
test | string | Command that runs the automated acceptance tests |
report | string | Path to the JUnit report |
notes | string | Notes |
startTimeout | number | Seconds to wait for the app to start |
stagingUrl | string | HTTP 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
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.
| Level | Code | Meaning |
|---|---|---|
| error | missing_testcases | No testcases.md |
| error | format_version | Unsupported version or malformed marker |
| error | malformed_heading | A heading looks like a TC but has the wrong syntax |
| error | empty_testcases | No test cases |
| error | duplicate_tc | Duplicate TC code |
| error | tc_without_ac | A TC isn't linked to an AC |
| error | unfilled_testcase | A skeleton hasn't been filled in |
| error | misplaced_testcases | A test case is in the wrong file or place |
| error | uncovered_ac | An AC has no TC |
| error | malformed_run | A ## Run heading is malformed |
| error | acceptance_edited | Earlier content in acceptance.md was edited |
| error | bandum_json | .bandum.json is broken |
| error | tc_without_test, junit_missing | With --junit: a TC has no test, or the file can't be read |
| warning | unknown_ac | A TC references an AC that isn't in the source |
| warning | ac_source_empty, ac_source_unavailable | The AC source has no ACs or can't be retrieved |
| warning | bandum_json_no_test, bandum_json_unknown_key, bandum_json_staging_url | test or report is missing; unknown key; invalid stagingUrl |
| warning | test_skipped | With --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.