[quality] test: unit coverage for scripts/build-iso.sh named-arg wrapper — tests/test_build_iso_args.py

[kubestellar-hive]

Test Improvement

Adds tests/test_build_iso_args.py — the first behavioural coverage for scripts/build-iso.sh.

Exact ground claimed by this PR

• File under test: scripts/build-iso.sh (33-line named-flag wrapper) — argument parsing loop, required-flag guard, and the exec delegation to live/src/build-iso.sh.
• New file added: tests/test_build_iso_args.py (only file added or changed).
• Read-only references (not modified): .github/workflows/test-plain-install.yml call site, live/src/build-iso.sh existence check.

Why it matters

scripts/build-iso.sh translates the named-flag interface used by .github/workflows/test-plain-install.yml:

scripts/build-iso.sh --squashfs <sfs> --boot-tar <tar> --output <iso>

into the positional interface of live/src/build-iso.sh:

live/src/build-iso.sh <boot-tar> <squashfs> <output-iso>

The two interfaces order boot tar and rootfs squashfs differently. A slip in the wrapper swaps them, which still produces an ISO — one that only fails hours later in the QEMU plain-install E2E lane, with no unit signal.

What the 13 tests cover

TestArgumentTranslation

• flags map to the documented <boot-tar> <squashfs> <output-iso> order
• flag order on the command line does not change positional order (3 subtests)
• values containing spaces stay single arguments
• last occurrence of a repeated flag wins
• the delegate exit status is propagated (the wrapper execs, so a failed build must not report success)

TestArgumentValidation

• no arguments prints usage and exits non-zero
• each of --squashfs, --boot-tar, --output is individually required (3 subtests)
• a flag given without a value fails instead of consuming the next flag (3 subtests)
• unknown flags (e.g. --oci-image) are rejected
• a stray positional path is rejected

TestWorkflowContract

• wrapper and delegate exist, wrapper passes bash -n
• test-plain-install.yml passes exactly the flag set the wrapper accepts

Method

Each test copies the real wrapper into a temporary <root>/scripts + <root>/live/src tree whose delegate is a recording stub, because the wrapper resolves its delegate as "$(dirname "$0")/../live/src/build-iso.sh". The real live/src/build-iso.sh (needs xorriso, mtools, root) is never executed — the suite stays fast and hermetic and needs no new CI dependencies.

Verification

• pytest tests/test_build_iso_args.py → 13 passed, 9 subtests passed
• Mutation check: swapping "$BOOT_TAR" "$SQUASHFS" in the wrapper fails 6 tests
• Full suite: pytest tests/ → 116 passed, 2 skipped, 1 pre-existing unrelated failure (TestSkillCatalogUpToDate, already tracked as [quality] TestSkillCatalogUpToDate fails every day after index.json is written — generated_at uses date.today() #137)

Disjointness with open PRs

• [architect] refactor: single source of truth for host-side variant config — scripts/variant-config.sh replaces 5 duplicated readers in justfile + scripts/{iso-sd-boot,luks-install-qemu,plain-install-qemu,build-live-squashfs}.sh #146 (architect, variant-config SoT) touches scripts/{build-live-squashfs,iso-sd-boot,luks-install-qemu,plain-install-qemu}.sh, justfile, tests/test_variant_config.py — not scripts/build-iso.sh.
• [quality] test: unit coverage for scripts/generate_skill_index.py #143 covers scripts/generate_skill_index.py; [quality] test: unit coverage for scripts/fisherman-install.sh #138 covers scripts/fisherman-install.sh.
• [sec-check] fix: cosign-verify ghcr images before ISO build consumes them #142 covers scripts/verify-image-signature.sh; [architect] refactor: make live/src the single source of the live ISO tree — delete unreferenced dakota/src/ #140 deletes dakota/src/ and edits tests/test_live_build_invariants.py / tests/test_luks_unlock.py.
• [sec-check] fix: test.yml add permissions block (contents: read) #124/[sec-check] fix: lint.yml pin action-shellcheck SHA, add permissions block #125/[sec-check] fix: label-enforcement.yml pin reusable workflow to full SHA #126/[sec-check] fix: declare top-level permissions: {} in build-iso-bluefin.yml build-iso.yml  #130 touch workflow YAML only.
• No open PR adds or edits tests/test_build_iso_args.py or scripts/build-iso.sh.

No production code changes.

---

Filed by quality agent (hold-gated mode). Human review required — do not merge automatically.

— hive: agent=quality backend=copilot model=claude-opus-5