Summary
Add --shard <index>/<total> to run a deterministic subset of tests, so a large suite can be split across parallel CI machines (e.g. matrix jobs). Different from --parallel (which parallelizes on one host).
Motivation
Big suites want horizontal scaling across CI runners. Standard pattern (Jest/Playwright): --shard 1/4, --shard 2/4, … each runner executes its slice; union == full suite, no overlap. Verified missing: grep -- --shard src/*.sh → none.
Proposed API
bashunit --shard 1/4 tests/ # runner 1 of 4
bashunit --shard 2/4 tests/ # runner 2 of 4
- 1-indexed
index, 1 <= index <= total.
- Partition the collected test list deterministically (e.g.
i-th, i+total-th, … round-robin, or contiguous chunks — pick and document). Round-robin balances better when files vary in size.
- Invalid input (
index > total, total < 1, non-numeric) → clear error, non-zero exit.
- Composable with
--parallel (shard first, then parallelize the slice).
Files
- Flag parsing + validation:
src/globals.sh.
- Partition logic:
src/runner.sh (after the full test list is collected, before execution).
- Docs:
docs/command-line.md + a CI matrix example in docs/command-line.md or docs/common-patterns.md.
- Tests:
tests/acceptance/bashunit_test.sh.
TDD steps
- RED: with N fixture tests,
--shard 1/2 and --shard 2/2 run disjoint subsets whose union is all N (assert counts / list of executed names).
- RED:
--shard 3/2 errors out with non-zero exit and a clear message.
- GREEN: minimal partition.
- REFACTOR: verify
--shard 1/2 --parallel works.
Acceptance criteria
Constraints
- Bash 3.0+ only. See
.claude/rules/bash-style.md.
- Must pass
make sa, make lint, shfmt -w ., ./bashunit tests/, ./bashunit --parallel tests/.
Summary
Add
--shard <index>/<total>to run a deterministic subset of tests, so a large suite can be split across parallel CI machines (e.g. matrix jobs). Different from--parallel(which parallelizes on one host).Motivation
Big suites want horizontal scaling across CI runners. Standard pattern (Jest/Playwright):
--shard 1/4,--shard 2/4, … each runner executes its slice; union == full suite, no overlap. Verified missing:grep -- --shard src/*.sh→ none.Proposed API
index,1 <= index <= total.i-th, i+total-th, …round-robin, or contiguous chunks — pick and document). Round-robin balances better when files vary in size.index > total,total < 1, non-numeric) → clear error, non-zero exit.--parallel(shard first, then parallelize the slice).Files
src/globals.sh.src/runner.sh(after the full test list is collected, before execution).docs/command-line.md+ a CI matrix example indocs/command-line.mdordocs/common-patterns.md.tests/acceptance/bashunit_test.sh.TDD steps
--shard 1/2and--shard 2/2run disjoint subsets whose union is all N (assert counts / list of executed names).--shard 3/2errors out with non-zero exit and a clear message.--shard 1/2 --parallelworks.Acceptance criteria
--shard i/nparsed and validated (bad input → error + non-zero exit).--parallel.Constraints
.claude/rules/bash-style.md.make sa,make lint,shfmt -w .,./bashunit tests/,./bashunit --parallel tests/.