feat(coverage): report loop constructs as branch points

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- Branch coverage now reports loop constructs (`while`/`until`/`for`/`select`): the loop body is a single-arm branch, marked covered only when the loop ran at least once, so a never-entered zero-iteration loop surfaces as an uncovered branch (#855)
+
 ### Changed
 - Core string assertions (`assert_contains`/`assert_not_contains`, `assert_matches`/`assert_not_matches`, `assert_string_starts_with`/`assert_string_ends_with` and their negations) no longer fork a subshell per call to join their arguments; a fork-free join with identical behaviour replaces it (#844)
 - The array, date, duration, json, files and folders assertions now resolve their failure label through the fork-free slot helper instead of a per-call command substitution — same labels, fewer forks

adrs/adr-007-branch-coverage-mvp.md

@@ -82,7 +82,22 @@ Deferred (potential follow-ups):
 * Synthetic "implicit-else" outcomes for `if/elif` chains without an explicit `else`.
 * Per-sub-expression decisions inside `if A && B`.
 * `&&` / `||` short-circuit branches outside `if`.
-* Loop-entry decisions (`while`/`until`).
+
+## Update (2026-07-24): loop-body branches
+
+Loop constructs (`while`/`until`/`for`/`select`) are now emitted as **single-arm**
+branch points (`<line>|loop|<body_start>:<body_end>`), extending the same static
++ line-hit-inference model with no runtime-cost change. The body arm is "taken"
+iff an executable line inside it was hit — i.e. the loop ran at least once — so a
+never-entered loop body surfaces as an uncovered zero-iteration branch. Every
+`done`-closed opener (including `select`) pushes a loop frame so `done` pairs
+with the correct opener when nested.
+
+Still deferred, and for the same root reason — the DEBUG trap records **line**
+hits, not sub-line outcomes: same-line short-circuit guards (`[ cond ] && action`,
+`... || action`) cannot be measured, because both outcomes share one line. Those
+require a finer-grained mechanism (see the coverage-tracing-engine spike) rather
+than the line-range model.
 
 ## Links
 

src/coverage.sh

@@ -940,6 +940,23 @@ function bashunit::coverage::_branch_open_case_pattern() {
  case_in_pattern[idx]=1
 }
 
+# A loop (while/until/for/select) is a single-arm branch: its body. The arm is
+# taken iff the loop ran at least once (an executable body line was hit); a
+# never-taken body is an uncovered zero-iteration branch. Every `done`-closed
+# construct must push so `done` pairs with the right opener when nested.
+function bashunit::coverage::_branch_push_loop() {
+ local lineno=$1
+ loop_decision_line[loop_depth]=$lineno
+ loop_arm_start[loop_depth]=$((lineno + 1))
+ loop_depth=$((loop_depth + 1))
+}
+
+function bashunit::coverage::_branch_emit_loop() {
+ local lineno=$1 idx=$((loop_depth - 1))
+ echo "${loop_decision_line[$idx]}|loop|${loop_arm_start[$idx]}:$((lineno - 1))"
+ loop_depth=$idx
+}
+
 function bashunit::coverage::extract_branches() {
  local file="$1"
 
@@ -958,6 +975,8 @@ function bashunit::coverage::extract_branches() {
  local if_depth=0
  local -a case_decision_line=() case_arms=() case_arm_start=() case_in_pattern=()
  local case_depth=0
+ local -a loop_decision_line=() loop_arm_start=()
+ local loop_depth=0
 
  local lineno=0 line trimmed first
  while [ "$lineno" -lt "$total_lines" ]; do
@@ -982,6 +1001,12 @@ function bashunit::coverage::extract_branches() {
  'esac')
  [ "$case_depth" -gt 0 ] && bashunit::coverage::_branch_emit_case "$lineno"
  ;;
+ 'while' | 'until' | 'for' | 'select')
+ bashunit::coverage::_branch_push_loop "$lineno"
+ ;;
+ 'done')
+ [ "$loop_depth" -gt 0 ] && bashunit::coverage::_branch_emit_loop "$lineno"
+ ;;
  *)
  [ "$case_depth" -eq 0 ] && continue
  case "$trimmed" in

tests/unit/coverage_branches_test.sh

@@ -46,7 +46,86 @@ function tear_down() {
 
 # extract_branches output format:
 # <decision_line>|<kind>|<arm_start>:<arm_end>[,<arm_start>:<arm_end>]...
-# kind ∈ {if, case}
+# kind ∈ {if, case, loop}
+# A loop is a single-arm branch: the body range, taken iff the loop ran at
+# least once (any executable body line was hit).
+
+function test_extract_branches_finds_while_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_for_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2 3; do
+ echo "$x"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_until_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+until [ "$ok" = "yes" ]; do
+ ok=$(check)
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_nested_loops() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2; do
+ while [ "$x" -gt 0 ]; do
+ echo hi
+ x=$((x - 1))
+ done
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ # Inner while (line 3) body on 4-5; outer for (line 2) body on 3-6.
+ assert_contains "3|loop|4:5" "$result"
+ assert_contains "2|loop|3:6" "$result"
+
+ rm -f "$fixture"
+}
 
 function test_extract_branches_finds_simple_if_else() {
  local fixture
@@ -209,6 +288,54 @@ EOF
  rm -f "$fixture"
 }
 
+function test_compute_branch_hits_marks_loop_body_taken_when_iterated() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # The loop body (line 3) ran at least once.
+ echo "${fixture}:3" >>"$_BASHUNIT_COVERAGE_DATA_FILE"
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ # Single-arm loop branch on line 2, arm taken.
+ assert_contains "2|0|0|1" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_compute_branch_hits_marks_loop_body_not_taken_on_zero_iterations() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # No hits recorded: the loop never iterated (zero-iteration branch uncovered).
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ assert_contains "2|0|0|0" "$result"
+
+ rm -f "$fixture"
+}
+
 function test_compute_branch_hits_assigns_distinct_blocks_per_decision() {
  bashunit::coverage::init
 

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- Branch coverage now reports loop constructs (`while`/`until`/`for`/`select`): the loop body is a single-arm branch, marked covered only when the loop ran at least once, so a never-entered zero-iteration loop surfaces as an uncovered branch (#855)
+
 ### Changed
 - Core string assertions (`assert_contains`/`assert_not_contains`, `assert_matches`/`assert_not_matches`, `assert_string_starts_with`/`assert_string_ends_with` and their negations) no longer fork a subshell per call to join their arguments; a fork-free join with identical behaviour replaces it (#844)
 - The array, date, duration, json, files and folders assertions now resolve their failure label through the fork-free slot helper instead of a per-call command substitution — same labels, fewer forks

adrs/adr-007-branch-coverage-mvp.md

@@ -82,7 +82,22 @@ Deferred (potential follow-ups):
 * Synthetic "implicit-else" outcomes for `if/elif` chains without an explicit `else`.
 * Per-sub-expression decisions inside `if A && B`.
 * `&&` / `||` short-circuit branches outside `if`.
-* Loop-entry decisions (`while`/`until`).
+
+## Update (2026-07-24): loop-body branches
+
+Loop constructs (`while`/`until`/`for`/`select`) are now emitted as **single-arm**
+branch points (`<line>|loop|<body_start>:<body_end>`), extending the same static
++ line-hit-inference model with no runtime-cost change. The body arm is "taken"
+iff an executable line inside it was hit — i.e. the loop ran at least once — so a
+never-entered loop body surfaces as an uncovered zero-iteration branch. Every
+`done`-closed opener (including `select`) pushes a loop frame so `done` pairs
+with the correct opener when nested.
+
+Still deferred, and for the same root reason — the DEBUG trap records **line**
+hits, not sub-line outcomes: same-line short-circuit guards (`[ cond ] && action`,
+`... || action`) cannot be measured, because both outcomes share one line. Those
+require a finer-grained mechanism (see the coverage-tracing-engine spike) rather
+than the line-range model.
 
 ## Links
 

src/coverage.sh

@@ -940,6 +940,23 @@ function bashunit::coverage::_branch_open_case_pattern() {
  case_in_pattern[idx]=1
 }
 
+# A loop (while/until/for/select) is a single-arm branch: its body. The arm is
+# taken iff the loop ran at least once (an executable body line was hit); a
+# never-taken body is an uncovered zero-iteration branch. Every `done`-closed
+# construct must push so `done` pairs with the right opener when nested.
+function bashunit::coverage::_branch_push_loop() {
+ local lineno=$1
+ loop_decision_line[loop_depth]=$lineno
+ loop_arm_start[loop_depth]=$((lineno + 1))
+ loop_depth=$((loop_depth + 1))
+}
+
+function bashunit::coverage::_branch_emit_loop() {
+ local lineno=$1 idx=$((loop_depth - 1))
+ echo "${loop_decision_line[$idx]}|loop|${loop_arm_start[$idx]}:$((lineno - 1))"
+ loop_depth=$idx
+}
+
 function bashunit::coverage::extract_branches() {
  local file="$1"
 
@@ -958,6 +975,8 @@ function bashunit::coverage::extract_branches() {
  local if_depth=0
  local -a case_decision_line=() case_arms=() case_arm_start=() case_in_pattern=()
  local case_depth=0
+ local -a loop_decision_line=() loop_arm_start=()
+ local loop_depth=0
 
  local lineno=0 line trimmed first
  while [ "$lineno" -lt "$total_lines" ]; do
@@ -982,6 +1001,12 @@ function bashunit::coverage::extract_branches() {
  'esac')
  [ "$case_depth" -gt 0 ] && bashunit::coverage::_branch_emit_case "$lineno"
  ;;
+ 'while' | 'until' | 'for' | 'select')
+ bashunit::coverage::_branch_push_loop "$lineno"
+ ;;
+ 'done')
+ [ "$loop_depth" -gt 0 ] && bashunit::coverage::_branch_emit_loop "$lineno"
+ ;;
  *)
  [ "$case_depth" -eq 0 ] && continue
  case "$trimmed" in

tests/unit/coverage_branches_test.sh

@@ -46,7 +46,86 @@ function tear_down() {
 
 # extract_branches output format:
 # <decision_line>|<kind>|<arm_start>:<arm_end>[,<arm_start>:<arm_end>]...
-# kind ∈ {if, case}
+# kind ∈ {if, case, loop}
+# A loop is a single-arm branch: the body range, taken iff the loop ran at
+# least once (any executable body line was hit).
+
+function test_extract_branches_finds_while_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_for_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2 3; do
+ echo "$x"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_until_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+until [ "$ok" = "yes" ]; do
+ ok=$(check)
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_nested_loops() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2; do
+ while [ "$x" -gt 0 ]; do
+ echo hi
+ x=$((x - 1))
+ done
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ # Inner while (line 3) body on 4-5; outer for (line 2) body on 3-6.
+ assert_contains "3|loop|4:5" "$result"
+ assert_contains "2|loop|3:6" "$result"
+
+ rm -f "$fixture"
+}
 
 function test_extract_branches_finds_simple_if_else() {
  local fixture
@@ -209,6 +288,54 @@ EOF
  rm -f "$fixture"
 }
 
+function test_compute_branch_hits_marks_loop_body_taken_when_iterated() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # The loop body (line 3) ran at least once.
+ echo "${fixture}:3" >>"$_BASHUNIT_COVERAGE_DATA_FILE"
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ # Single-arm loop branch on line 2, arm taken.
+ assert_contains "2|0|0|1" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_compute_branch_hits_marks_loop_body_not_taken_on_zero_iterations() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # No hits recorded: the loop never iterated (zero-iteration branch uncovered).
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ assert_contains "2|0|0|0" "$result"
+
+ rm -f "$fixture"
+}
+
 function test_compute_branch_hits_assigns_distinct_blocks_per_decision() {
  bashunit::coverage::init
 

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- Branch coverage now reports loop constructs (`while`/`until`/`for`/`select`): the loop body is a single-arm branch, marked covered only when the loop ran at least once, so a never-entered zero-iteration loop surfaces as an uncovered branch (#855)
+
 ### Changed
 - Core string assertions (`assert_contains`/`assert_not_contains`, `assert_matches`/`assert_not_matches`, `assert_string_starts_with`/`assert_string_ends_with` and their negations) no longer fork a subshell per call to join their arguments; a fork-free join with identical behaviour replaces it (#844)
 - The array, date, duration, json, files and folders assertions now resolve their failure label through the fork-free slot helper instead of a per-call command substitution — same labels, fewer forks

adrs/adr-007-branch-coverage-mvp.md

@@ -82,7 +82,22 @@ Deferred (potential follow-ups):
 * Synthetic "implicit-else" outcomes for `if/elif` chains without an explicit `else`.
 * Per-sub-expression decisions inside `if A && B`.
 * `&&` / `||` short-circuit branches outside `if`.
-* Loop-entry decisions (`while`/`until`).
+
+## Update (2026-07-24): loop-body branches
+
+Loop constructs (`while`/`until`/`for`/`select`) are now emitted as **single-arm**
+branch points (`<line>|loop|<body_start>:<body_end>`), extending the same static
++ line-hit-inference model with no runtime-cost change. The body arm is "taken"
+iff an executable line inside it was hit — i.e. the loop ran at least once — so a
+never-entered loop body surfaces as an uncovered zero-iteration branch. Every
+`done`-closed opener (including `select`) pushes a loop frame so `done` pairs
+with the correct opener when nested.
+
+Still deferred, and for the same root reason — the DEBUG trap records **line**
+hits, not sub-line outcomes: same-line short-circuit guards (`[ cond ] && action`,
+`... || action`) cannot be measured, because both outcomes share one line. Those
+require a finer-grained mechanism (see the coverage-tracing-engine spike) rather
+than the line-range model.
 
 ## Links
 

src/coverage.sh

@@ -940,6 +940,23 @@ function bashunit::coverage::_branch_open_case_pattern() {
  case_in_pattern[idx]=1
 }
 
+# A loop (while/until/for/select) is a single-arm branch: its body. The arm is
+# taken iff the loop ran at least once (an executable body line was hit); a
+# never-taken body is an uncovered zero-iteration branch. Every `done`-closed
+# construct must push so `done` pairs with the right opener when nested.
+function bashunit::coverage::_branch_push_loop() {
+ local lineno=$1
+ loop_decision_line[loop_depth]=$lineno
+ loop_arm_start[loop_depth]=$((lineno + 1))
+ loop_depth=$((loop_depth + 1))
+}
+
+function bashunit::coverage::_branch_emit_loop() {
+ local lineno=$1 idx=$((loop_depth - 1))
+ echo "${loop_decision_line[$idx]}|loop|${loop_arm_start[$idx]}:$((lineno - 1))"
+ loop_depth=$idx
+}
+
 function bashunit::coverage::extract_branches() {
  local file="$1"
 
@@ -958,6 +975,8 @@ function bashunit::coverage::extract_branches() {
  local if_depth=0
  local -a case_decision_line=() case_arms=() case_arm_start=() case_in_pattern=()
  local case_depth=0
+ local -a loop_decision_line=() loop_arm_start=()
+ local loop_depth=0
 
  local lineno=0 line trimmed first
  while [ "$lineno" -lt "$total_lines" ]; do
@@ -982,6 +1001,12 @@ function bashunit::coverage::extract_branches() {
  'esac')
  [ "$case_depth" -gt 0 ] && bashunit::coverage::_branch_emit_case "$lineno"
  ;;
+ 'while' | 'until' | 'for' | 'select')
+ bashunit::coverage::_branch_push_loop "$lineno"
+ ;;
+ 'done')
+ [ "$loop_depth" -gt 0 ] && bashunit::coverage::_branch_emit_loop "$lineno"
+ ;;
  *)
  [ "$case_depth" -eq 0 ] && continue
  case "$trimmed" in

tests/unit/coverage_branches_test.sh

@@ -46,7 +46,86 @@ function tear_down() {
 
 # extract_branches output format:
 # <decision_line>|<kind>|<arm_start>:<arm_end>[,<arm_start>:<arm_end>]...
-# kind ∈ {if, case}
+# kind ∈ {if, case, loop}
+# A loop is a single-arm branch: the body range, taken iff the loop ran at
+# least once (any executable body line was hit).
+
+function test_extract_branches_finds_while_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_for_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2 3; do
+ echo "$x"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_until_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+until [ "$ok" = "yes" ]; do
+ ok=$(check)
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_nested_loops() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2; do
+ while [ "$x" -gt 0 ]; do
+ echo hi
+ x=$((x - 1))
+ done
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ # Inner while (line 3) body on 4-5; outer for (line 2) body on 3-6.
+ assert_contains "3|loop|4:5" "$result"
+ assert_contains "2|loop|3:6" "$result"
+
+ rm -f "$fixture"
+}
 
 function test_extract_branches_finds_simple_if_else() {
  local fixture
@@ -209,6 +288,54 @@ EOF
  rm -f "$fixture"
 }
 
+function test_compute_branch_hits_marks_loop_body_taken_when_iterated() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # The loop body (line 3) ran at least once.
+ echo "${fixture}:3" >>"$_BASHUNIT_COVERAGE_DATA_FILE"
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ # Single-arm loop branch on line 2, arm taken.
+ assert_contains "2|0|0|1" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_compute_branch_hits_marks_loop_body_not_taken_on_zero_iterations() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # No hits recorded: the loop never iterated (zero-iteration branch uncovered).
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ assert_contains "2|0|0|0" "$result"
+
+ rm -f "$fixture"
+}
+
 function test_compute_branch_hits_assigns_distinct_blocks_per_decision() {
  bashunit::coverage::init
 

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- Branch coverage now reports loop constructs (`while`/`until`/`for`/`select`): the loop body is a single-arm branch, marked covered only when the loop ran at least once, so a never-entered zero-iteration loop surfaces as an uncovered branch (#855)
+
 ### Changed
 - Core string assertions (`assert_contains`/`assert_not_contains`, `assert_matches`/`assert_not_matches`, `assert_string_starts_with`/`assert_string_ends_with` and their negations) no longer fork a subshell per call to join their arguments; a fork-free join with identical behaviour replaces it (#844)
 - The array, date, duration, json, files and folders assertions now resolve their failure label through the fork-free slot helper instead of a per-call command substitution — same labels, fewer forks

adrs/adr-007-branch-coverage-mvp.md

@@ -82,7 +82,22 @@ Deferred (potential follow-ups):
 * Synthetic "implicit-else" outcomes for `if/elif` chains without an explicit `else`.
 * Per-sub-expression decisions inside `if A && B`.
 * `&&` / `||` short-circuit branches outside `if`.
-* Loop-entry decisions (`while`/`until`).
+
+## Update (2026-07-24): loop-body branches
+
+Loop constructs (`while`/`until`/`for`/`select`) are now emitted as **single-arm**
+branch points (`<line>|loop|<body_start>:<body_end>`), extending the same static
++ line-hit-inference model with no runtime-cost change. The body arm is "taken"
+iff an executable line inside it was hit — i.e. the loop ran at least once — so a
+never-entered loop body surfaces as an uncovered zero-iteration branch. Every
+`done`-closed opener (including `select`) pushes a loop frame so `done` pairs
+with the correct opener when nested.
+
+Still deferred, and for the same root reason — the DEBUG trap records **line**
+hits, not sub-line outcomes: same-line short-circuit guards (`[ cond ] && action`,
+`... || action`) cannot be measured, because both outcomes share one line. Those
+require a finer-grained mechanism (see the coverage-tracing-engine spike) rather
+than the line-range model.
 
 ## Links
 

src/coverage.sh

@@ -940,6 +940,23 @@ function bashunit::coverage::_branch_open_case_pattern() {
  case_in_pattern[idx]=1
 }
 
+# A loop (while/until/for/select) is a single-arm branch: its body. The arm is
+# taken iff the loop ran at least once (an executable body line was hit); a
+# never-taken body is an uncovered zero-iteration branch. Every `done`-closed
+# construct must push so `done` pairs with the right opener when nested.
+function bashunit::coverage::_branch_push_loop() {
+ local lineno=$1
+ loop_decision_line[loop_depth]=$lineno
+ loop_arm_start[loop_depth]=$((lineno + 1))
+ loop_depth=$((loop_depth + 1))
+}
+
+function bashunit::coverage::_branch_emit_loop() {
+ local lineno=$1 idx=$((loop_depth - 1))
+ echo "${loop_decision_line[$idx]}|loop|${loop_arm_start[$idx]}:$((lineno - 1))"
+ loop_depth=$idx
+}
+
 function bashunit::coverage::extract_branches() {
  local file="$1"
 
@@ -958,6 +975,8 @@ function bashunit::coverage::extract_branches() {
  local if_depth=0
  local -a case_decision_line=() case_arms=() case_arm_start=() case_in_pattern=()
  local case_depth=0
+ local -a loop_decision_line=() loop_arm_start=()
+ local loop_depth=0
 
  local lineno=0 line trimmed first
  while [ "$lineno" -lt "$total_lines" ]; do
@@ -982,6 +1001,12 @@ function bashunit::coverage::extract_branches() {
  'esac')
  [ "$case_depth" -gt 0 ] && bashunit::coverage::_branch_emit_case "$lineno"
  ;;
+ 'while' | 'until' | 'for' | 'select')
+ bashunit::coverage::_branch_push_loop "$lineno"
+ ;;
+ 'done')
+ [ "$loop_depth" -gt 0 ] && bashunit::coverage::_branch_emit_loop "$lineno"
+ ;;
  *)
  [ "$case_depth" -eq 0 ] && continue
  case "$trimmed" in

tests/unit/coverage_branches_test.sh

@@ -46,7 +46,86 @@ function tear_down() {
 
 # extract_branches output format:
 # <decision_line>|<kind>|<arm_start>:<arm_end>[,<arm_start>:<arm_end>]...
-# kind ∈ {if, case}
+# kind ∈ {if, case, loop}
+# A loop is a single-arm branch: the body range, taken iff the loop ran at
+# least once (any executable body line was hit).
+
+function test_extract_branches_finds_while_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_for_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2 3; do
+ echo "$x"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_until_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+until [ "$ok" = "yes" ]; do
+ ok=$(check)
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_nested_loops() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2; do
+ while [ "$x" -gt 0 ]; do
+ echo hi
+ x=$((x - 1))
+ done
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ # Inner while (line 3) body on 4-5; outer for (line 2) body on 3-6.
+ assert_contains "3|loop|4:5" "$result"
+ assert_contains "2|loop|3:6" "$result"
+
+ rm -f "$fixture"
+}
 
 function test_extract_branches_finds_simple_if_else() {
  local fixture
@@ -209,6 +288,54 @@ EOF
  rm -f "$fixture"
 }
 
+function test_compute_branch_hits_marks_loop_body_taken_when_iterated() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # The loop body (line 3) ran at least once.
+ echo "${fixture}:3" >>"$_BASHUNIT_COVERAGE_DATA_FILE"
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ # Single-arm loop branch on line 2, arm taken.
+ assert_contains "2|0|0|1" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_compute_branch_hits_marks_loop_body_not_taken_on_zero_iterations() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # No hits recorded: the loop never iterated (zero-iteration branch uncovered).
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ assert_contains "2|0|0|0" "$result"
+
+ rm -f "$fixture"
+}
+
 function test_compute_branch_hits_assigns_distinct_blocks_per_decision() {
  bashunit::coverage::init
 

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- Branch coverage now reports loop constructs (`while`/`until`/`for`/`select`): the loop body is a single-arm branch, marked covered only when the loop ran at least once, so a never-entered zero-iteration loop surfaces as an uncovered branch (#855)
+
 ### Changed
 - Core string assertions (`assert_contains`/`assert_not_contains`, `assert_matches`/`assert_not_matches`, `assert_string_starts_with`/`assert_string_ends_with` and their negations) no longer fork a subshell per call to join their arguments; a fork-free join with identical behaviour replaces it (#844)
 - The array, date, duration, json, files and folders assertions now resolve their failure label through the fork-free slot helper instead of a per-call command substitution — same labels, fewer forks

adrs/adr-007-branch-coverage-mvp.md

@@ -82,7 +82,22 @@ Deferred (potential follow-ups):
 * Synthetic "implicit-else" outcomes for `if/elif` chains without an explicit `else`.
 * Per-sub-expression decisions inside `if A && B`.
 * `&&` / `||` short-circuit branches outside `if`.
-* Loop-entry decisions (`while`/`until`).
+
+## Update (2026-07-24): loop-body branches
+
+Loop constructs (`while`/`until`/`for`/`select`) are now emitted as **single-arm**
+branch points (`<line>|loop|<body_start>:<body_end>`), extending the same static
++ line-hit-inference model with no runtime-cost change. The body arm is "taken"
+iff an executable line inside it was hit — i.e. the loop ran at least once — so a
+never-entered loop body surfaces as an uncovered zero-iteration branch. Every
+`done`-closed opener (including `select`) pushes a loop frame so `done` pairs
+with the correct opener when nested.
+
+Still deferred, and for the same root reason — the DEBUG trap records **line**
+hits, not sub-line outcomes: same-line short-circuit guards (`[ cond ] && action`,
+`... || action`) cannot be measured, because both outcomes share one line. Those
+require a finer-grained mechanism (see the coverage-tracing-engine spike) rather
+than the line-range model.
 
 ## Links
 

src/coverage.sh

@@ -940,6 +940,23 @@ function bashunit::coverage::_branch_open_case_pattern() {
  case_in_pattern[idx]=1
 }
 
+# A loop (while/until/for/select) is a single-arm branch: its body. The arm is
+# taken iff the loop ran at least once (an executable body line was hit); a
+# never-taken body is an uncovered zero-iteration branch. Every `done`-closed
+# construct must push so `done` pairs with the right opener when nested.
+function bashunit::coverage::_branch_push_loop() {
+ local lineno=$1
+ loop_decision_line[loop_depth]=$lineno
+ loop_arm_start[loop_depth]=$((lineno + 1))
+ loop_depth=$((loop_depth + 1))
+}
+
+function bashunit::coverage::_branch_emit_loop() {
+ local lineno=$1 idx=$((loop_depth - 1))
+ echo "${loop_decision_line[$idx]}|loop|${loop_arm_start[$idx]}:$((lineno - 1))"
+ loop_depth=$idx
+}
+
 function bashunit::coverage::extract_branches() {
  local file="$1"
 
@@ -958,6 +975,8 @@ function bashunit::coverage::extract_branches() {
  local if_depth=0
  local -a case_decision_line=() case_arms=() case_arm_start=() case_in_pattern=()
  local case_depth=0
+ local -a loop_decision_line=() loop_arm_start=()
+ local loop_depth=0
 
  local lineno=0 line trimmed first
  while [ "$lineno" -lt "$total_lines" ]; do
@@ -982,6 +1001,12 @@ function bashunit::coverage::extract_branches() {
  'esac')
  [ "$case_depth" -gt 0 ] && bashunit::coverage::_branch_emit_case "$lineno"
  ;;
+ 'while' | 'until' | 'for' | 'select')
+ bashunit::coverage::_branch_push_loop "$lineno"
+ ;;
+ 'done')
+ [ "$loop_depth" -gt 0 ] && bashunit::coverage::_branch_emit_loop "$lineno"
+ ;;
  *)
  [ "$case_depth" -eq 0 ] && continue
  case "$trimmed" in

tests/unit/coverage_branches_test.sh

@@ -46,7 +46,86 @@ function tear_down() {
 
 # extract_branches output format:
 # <decision_line>|<kind>|<arm_start>:<arm_end>[,<arm_start>:<arm_end>]...
-# kind ∈ {if, case}
+# kind ∈ {if, case, loop}
+# A loop is a single-arm branch: the body range, taken iff the loop ran at
+# least once (any executable body line was hit).
+
+function test_extract_branches_finds_while_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_for_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2 3; do
+ echo "$x"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_until_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+until [ "$ok" = "yes" ]; do
+ ok=$(check)
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_nested_loops() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2; do
+ while [ "$x" -gt 0 ]; do
+ echo hi
+ x=$((x - 1))
+ done
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ # Inner while (line 3) body on 4-5; outer for (line 2) body on 3-6.
+ assert_contains "3|loop|4:5" "$result"
+ assert_contains "2|loop|3:6" "$result"
+
+ rm -f "$fixture"
+}
 
 function test_extract_branches_finds_simple_if_else() {
  local fixture
@@ -209,6 +288,54 @@ EOF
  rm -f "$fixture"
 }
 
+function test_compute_branch_hits_marks_loop_body_taken_when_iterated() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # The loop body (line 3) ran at least once.
+ echo "${fixture}:3" >>"$_BASHUNIT_COVERAGE_DATA_FILE"
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ # Single-arm loop branch on line 2, arm taken.
+ assert_contains "2|0|0|1" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_compute_branch_hits_marks_loop_body_not_taken_on_zero_iterations() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # No hits recorded: the loop never iterated (zero-iteration branch uncovered).
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ assert_contains "2|0|0|0" "$result"
+
+ rm -f "$fixture"
+}
+
 function test_compute_branch_hits_assigns_distinct_blocks_per_decision() {
  bashunit::coverage::init
 

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- Branch coverage now reports loop constructs (`while`/`until`/`for`/`select`): the loop body is a single-arm branch, marked covered only when the loop ran at least once, so a never-entered zero-iteration loop surfaces as an uncovered branch (#855)
+
 ### Changed
 - Core string assertions (`assert_contains`/`assert_not_contains`, `assert_matches`/`assert_not_matches`, `assert_string_starts_with`/`assert_string_ends_with` and their negations) no longer fork a subshell per call to join their arguments; a fork-free join with identical behaviour replaces it (#844)
 - The array, date, duration, json, files and folders assertions now resolve their failure label through the fork-free slot helper instead of a per-call command substitution — same labels, fewer forks

adrs/adr-007-branch-coverage-mvp.md

@@ -82,7 +82,22 @@ Deferred (potential follow-ups):
 * Synthetic "implicit-else" outcomes for `if/elif` chains without an explicit `else`.
 * Per-sub-expression decisions inside `if A && B`.
 * `&&` / `||` short-circuit branches outside `if`.
-* Loop-entry decisions (`while`/`until`).
+
+## Update (2026-07-24): loop-body branches
+
+Loop constructs (`while`/`until`/`for`/`select`) are now emitted as **single-arm**
+branch points (`<line>|loop|<body_start>:<body_end>`), extending the same static
++ line-hit-inference model with no runtime-cost change. The body arm is "taken"
+iff an executable line inside it was hit — i.e. the loop ran at least once — so a
+never-entered loop body surfaces as an uncovered zero-iteration branch. Every
+`done`-closed opener (including `select`) pushes a loop frame so `done` pairs
+with the correct opener when nested.
+
+Still deferred, and for the same root reason — the DEBUG trap records **line**
+hits, not sub-line outcomes: same-line short-circuit guards (`[ cond ] && action`,
+`... || action`) cannot be measured, because both outcomes share one line. Those
+require a finer-grained mechanism (see the coverage-tracing-engine spike) rather
+than the line-range model.
 
 ## Links
 

src/coverage.sh

@@ -940,6 +940,23 @@ function bashunit::coverage::_branch_open_case_pattern() {
  case_in_pattern[idx]=1
 }
 
+# A loop (while/until/for/select) is a single-arm branch: its body. The arm is
+# taken iff the loop ran at least once (an executable body line was hit); a
+# never-taken body is an uncovered zero-iteration branch. Every `done`-closed
+# construct must push so `done` pairs with the right opener when nested.
+function bashunit::coverage::_branch_push_loop() {
+ local lineno=$1
+ loop_decision_line[loop_depth]=$lineno
+ loop_arm_start[loop_depth]=$((lineno + 1))
+ loop_depth=$((loop_depth + 1))
+}
+
+function bashunit::coverage::_branch_emit_loop() {
+ local lineno=$1 idx=$((loop_depth - 1))
+ echo "${loop_decision_line[$idx]}|loop|${loop_arm_start[$idx]}:$((lineno - 1))"
+ loop_depth=$idx
+}
+
 function bashunit::coverage::extract_branches() {
  local file="$1"
 
@@ -958,6 +975,8 @@ function bashunit::coverage::extract_branches() {
  local if_depth=0
  local -a case_decision_line=() case_arms=() case_arm_start=() case_in_pattern=()
  local case_depth=0
+ local -a loop_decision_line=() loop_arm_start=()
+ local loop_depth=0
 
  local lineno=0 line trimmed first
  while [ "$lineno" -lt "$total_lines" ]; do
@@ -982,6 +1001,12 @@ function bashunit::coverage::extract_branches() {
  'esac')
  [ "$case_depth" -gt 0 ] && bashunit::coverage::_branch_emit_case "$lineno"
  ;;
+ 'while' | 'until' | 'for' | 'select')
+ bashunit::coverage::_branch_push_loop "$lineno"
+ ;;
+ 'done')
+ [ "$loop_depth" -gt 0 ] && bashunit::coverage::_branch_emit_loop "$lineno"
+ ;;
  *)
  [ "$case_depth" -eq 0 ] && continue
  case "$trimmed" in

tests/unit/coverage_branches_test.sh

@@ -46,7 +46,86 @@ function tear_down() {
 
 # extract_branches output format:
 # <decision_line>|<kind>|<arm_start>:<arm_end>[,<arm_start>:<arm_end>]...
-# kind ∈ {if, case}
+# kind ∈ {if, case, loop}
+# A loop is a single-arm branch: the body range, taken iff the loop ran at
+# least once (any executable body line was hit).
+
+function test_extract_branches_finds_while_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_for_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2 3; do
+ echo "$x"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_until_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+until [ "$ok" = "yes" ]; do
+ ok=$(check)
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_nested_loops() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2; do
+ while [ "$x" -gt 0 ]; do
+ echo hi
+ x=$((x - 1))
+ done
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ # Inner while (line 3) body on 4-5; outer for (line 2) body on 3-6.
+ assert_contains "3|loop|4:5" "$result"
+ assert_contains "2|loop|3:6" "$result"
+
+ rm -f "$fixture"
+}
 
 function test_extract_branches_finds_simple_if_else() {
  local fixture
@@ -209,6 +288,54 @@ EOF
  rm -f "$fixture"
 }
 
+function test_compute_branch_hits_marks_loop_body_taken_when_iterated() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # The loop body (line 3) ran at least once.
+ echo "${fixture}:3" >>"$_BASHUNIT_COVERAGE_DATA_FILE"
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ # Single-arm loop branch on line 2, arm taken.
+ assert_contains "2|0|0|1" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_compute_branch_hits_marks_loop_body_not_taken_on_zero_iterations() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # No hits recorded: the loop never iterated (zero-iteration branch uncovered).
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ assert_contains "2|0|0|0" "$result"
+
+ rm -f "$fixture"
+}
+
 function test_compute_branch_hits_assigns_distinct_blocks_per_decision() {
  bashunit::coverage::init
 

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- Branch coverage now reports loop constructs (`while`/`until`/`for`/`select`): the loop body is a single-arm branch, marked covered only when the loop ran at least once, so a never-entered zero-iteration loop surfaces as an uncovered branch (#855)
+
 ### Changed
 - Core string assertions (`assert_contains`/`assert_not_contains`, `assert_matches`/`assert_not_matches`, `assert_string_starts_with`/`assert_string_ends_with` and their negations) no longer fork a subshell per call to join their arguments; a fork-free join with identical behaviour replaces it (#844)
 - The array, date, duration, json, files and folders assertions now resolve their failure label through the fork-free slot helper instead of a per-call command substitution — same labels, fewer forks

adrs/adr-007-branch-coverage-mvp.md

@@ -82,7 +82,22 @@ Deferred (potential follow-ups):
 * Synthetic "implicit-else" outcomes for `if/elif` chains without an explicit `else`.
 * Per-sub-expression decisions inside `if A && B`.
 * `&&` / `||` short-circuit branches outside `if`.
-* Loop-entry decisions (`while`/`until`).
+
+## Update (2026-07-24): loop-body branches
+
+Loop constructs (`while`/`until`/`for`/`select`) are now emitted as **single-arm**
+branch points (`<line>|loop|<body_start>:<body_end>`), extending the same static
++ line-hit-inference model with no runtime-cost change. The body arm is "taken"
+iff an executable line inside it was hit — i.e. the loop ran at least once — so a
+never-entered loop body surfaces as an uncovered zero-iteration branch. Every
+`done`-closed opener (including `select`) pushes a loop frame so `done` pairs
+with the correct opener when nested.
+
+Still deferred, and for the same root reason — the DEBUG trap records **line**
+hits, not sub-line outcomes: same-line short-circuit guards (`[ cond ] && action`,
+`... || action`) cannot be measured, because both outcomes share one line. Those
+require a finer-grained mechanism (see the coverage-tracing-engine spike) rather
+than the line-range model.
 
 ## Links
 

src/coverage.sh

@@ -940,6 +940,23 @@ function bashunit::coverage::_branch_open_case_pattern() {
  case_in_pattern[idx]=1
 }
 
+# A loop (while/until/for/select) is a single-arm branch: its body. The arm is
+# taken iff the loop ran at least once (an executable body line was hit); a
+# never-taken body is an uncovered zero-iteration branch. Every `done`-closed
+# construct must push so `done` pairs with the right opener when nested.
+function bashunit::coverage::_branch_push_loop() {
+ local lineno=$1
+ loop_decision_line[loop_depth]=$lineno
+ loop_arm_start[loop_depth]=$((lineno + 1))
+ loop_depth=$((loop_depth + 1))
+}
+
+function bashunit::coverage::_branch_emit_loop() {
+ local lineno=$1 idx=$((loop_depth - 1))
+ echo "${loop_decision_line[$idx]}|loop|${loop_arm_start[$idx]}:$((lineno - 1))"
+ loop_depth=$idx
+}
+
 function bashunit::coverage::extract_branches() {
  local file="$1"
 
@@ -958,6 +975,8 @@ function bashunit::coverage::extract_branches() {
  local if_depth=0
  local -a case_decision_line=() case_arms=() case_arm_start=() case_in_pattern=()
  local case_depth=0
+ local -a loop_decision_line=() loop_arm_start=()
+ local loop_depth=0
 
  local lineno=0 line trimmed first
  while [ "$lineno" -lt "$total_lines" ]; do
@@ -982,6 +1001,12 @@ function bashunit::coverage::extract_branches() {
  'esac')
  [ "$case_depth" -gt 0 ] && bashunit::coverage::_branch_emit_case "$lineno"
  ;;
+ 'while' | 'until' | 'for' | 'select')
+ bashunit::coverage::_branch_push_loop "$lineno"
+ ;;
+ 'done')
+ [ "$loop_depth" -gt 0 ] && bashunit::coverage::_branch_emit_loop "$lineno"
+ ;;
  *)
  [ "$case_depth" -eq 0 ] && continue
  case "$trimmed" in

tests/unit/coverage_branches_test.sh

@@ -46,7 +46,86 @@ function tear_down() {
 
 # extract_branches output format:
 # <decision_line>|<kind>|<arm_start>:<arm_end>[,<arm_start>:<arm_end>]...
-# kind ∈ {if, case}
+# kind ∈ {if, case, loop}
+# A loop is a single-arm branch: the body range, taken iff the loop ran at
+# least once (any executable body line was hit).
+
+function test_extract_branches_finds_while_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_for_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2 3; do
+ echo "$x"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_until_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+until [ "$ok" = "yes" ]; do
+ ok=$(check)
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_nested_loops() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2; do
+ while [ "$x" -gt 0 ]; do
+ echo hi
+ x=$((x - 1))
+ done
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ # Inner while (line 3) body on 4-5; outer for (line 2) body on 3-6.
+ assert_contains "3|loop|4:5" "$result"
+ assert_contains "2|loop|3:6" "$result"
+
+ rm -f "$fixture"
+}
 
 function test_extract_branches_finds_simple_if_else() {
  local fixture
@@ -209,6 +288,54 @@ EOF
  rm -f "$fixture"
 }
 
+function test_compute_branch_hits_marks_loop_body_taken_when_iterated() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # The loop body (line 3) ran at least once.
+ echo "${fixture}:3" >>"$_BASHUNIT_COVERAGE_DATA_FILE"
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ # Single-arm loop branch on line 2, arm taken.
+ assert_contains "2|0|0|1" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_compute_branch_hits_marks_loop_body_not_taken_on_zero_iterations() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # No hits recorded: the loop never iterated (zero-iteration branch uncovered).
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ assert_contains "2|0|0|0" "$result"
+
+ rm -f "$fixture"
+}
+
 function test_compute_branch_hits_assigns_distinct_blocks_per_decision() {
  bashunit::coverage::init
 

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+### Added
+- Branch coverage now reports loop constructs (`while`/`until`/`for`/`select`): the loop body is a single-arm branch, marked covered only when the loop ran at least once, so a never-entered zero-iteration loop surfaces as an uncovered branch (#855)
+
 ### Changed
 - Core string assertions (`assert_contains`/`assert_not_contains`, `assert_matches`/`assert_not_matches`, `assert_string_starts_with`/`assert_string_ends_with` and their negations) no longer fork a subshell per call to join their arguments; a fork-free join with identical behaviour replaces it (#844)
 - The array, date, duration, json, files and folders assertions now resolve their failure label through the fork-free slot helper instead of a per-call command substitution — same labels, fewer forks

adrs/adr-007-branch-coverage-mvp.md

@@ -82,7 +82,22 @@ Deferred (potential follow-ups):
 * Synthetic "implicit-else" outcomes for `if/elif` chains without an explicit `else`.
 * Per-sub-expression decisions inside `if A && B`.
 * `&&` / `||` short-circuit branches outside `if`.
-* Loop-entry decisions (`while`/`until`).
+
+## Update (2026-07-24): loop-body branches
+
+Loop constructs (`while`/`until`/`for`/`select`) are now emitted as **single-arm**
+branch points (`<line>|loop|<body_start>:<body_end>`), extending the same static
++ line-hit-inference model with no runtime-cost change. The body arm is "taken"
+iff an executable line inside it was hit — i.e. the loop ran at least once — so a
+never-entered loop body surfaces as an uncovered zero-iteration branch. Every
+`done`-closed opener (including `select`) pushes a loop frame so `done` pairs
+with the correct opener when nested.
+
+Still deferred, and for the same root reason — the DEBUG trap records **line**
+hits, not sub-line outcomes: same-line short-circuit guards (`[ cond ] && action`,
+`... || action`) cannot be measured, because both outcomes share one line. Those
+require a finer-grained mechanism (see the coverage-tracing-engine spike) rather
+than the line-range model.
 
 ## Links
 

src/coverage.sh

@@ -940,6 +940,23 @@ function bashunit::coverage::_branch_open_case_pattern() {
  case_in_pattern[idx]=1
 }
 
+# A loop (while/until/for/select) is a single-arm branch: its body. The arm is
+# taken iff the loop ran at least once (an executable body line was hit); a
+# never-taken body is an uncovered zero-iteration branch. Every `done`-closed
+# construct must push so `done` pairs with the right opener when nested.
+function bashunit::coverage::_branch_push_loop() {
+ local lineno=$1
+ loop_decision_line[loop_depth]=$lineno
+ loop_arm_start[loop_depth]=$((lineno + 1))
+ loop_depth=$((loop_depth + 1))
+}
+
+function bashunit::coverage::_branch_emit_loop() {
+ local lineno=$1 idx=$((loop_depth - 1))
+ echo "${loop_decision_line[$idx]}|loop|${loop_arm_start[$idx]}:$((lineno - 1))"
+ loop_depth=$idx
+}
+
 function bashunit::coverage::extract_branches() {
  local file="$1"
 
@@ -958,6 +975,8 @@ function bashunit::coverage::extract_branches() {
  local if_depth=0
  local -a case_decision_line=() case_arms=() case_arm_start=() case_in_pattern=()
  local case_depth=0
+ local -a loop_decision_line=() loop_arm_start=()
+ local loop_depth=0
 
  local lineno=0 line trimmed first
  while [ "$lineno" -lt "$total_lines" ]; do
@@ -982,6 +1001,12 @@ function bashunit::coverage::extract_branches() {
  'esac')
  [ "$case_depth" -gt 0 ] && bashunit::coverage::_branch_emit_case "$lineno"
  ;;
+ 'while' | 'until' | 'for' | 'select')
+ bashunit::coverage::_branch_push_loop "$lineno"
+ ;;
+ 'done')
+ [ "$loop_depth" -gt 0 ] && bashunit::coverage::_branch_emit_loop "$lineno"
+ ;;
  *)
  [ "$case_depth" -eq 0 ] && continue
  case "$trimmed" in

tests/unit/coverage_branches_test.sh

@@ -46,7 +46,86 @@ function tear_down() {
 
 # extract_branches output format:
 # <decision_line>|<kind>|<arm_start>:<arm_end>[,<arm_start>:<arm_end>]...
-# kind ∈ {if, case}
+# kind ∈ {if, case, loop}
+# A loop is a single-arm branch: the body range, taken iff the loop ran at
+# least once (any executable body line was hit).
+
+function test_extract_branches_finds_while_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_for_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2 3; do
+ echo "$x"
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_until_loop() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+until [ "$ok" = "yes" ]; do
+ ok=$(check)
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ assert_contains "2|loop|3:3" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_extract_branches_finds_nested_loops() {
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+for x in 1 2; do
+ while [ "$x" -gt 0 ]; do
+ echo hi
+ x=$((x - 1))
+ done
+done
+EOF
+
+ local result
+ result=$(bashunit::coverage::extract_branches "$fixture")
+
+ # Inner while (line 3) body on 4-5; outer for (line 2) body on 3-6.
+ assert_contains "3|loop|4:5" "$result"
+ assert_contains "2|loop|3:6" "$result"
+
+ rm -f "$fixture"
+}
 
 function test_extract_branches_finds_simple_if_else() {
  local fixture
@@ -209,6 +288,54 @@ EOF
  rm -f "$fixture"
 }
 
+function test_compute_branch_hits_marks_loop_body_taken_when_iterated() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # The loop body (line 3) ran at least once.
+ echo "${fixture}:3" >>"$_BASHUNIT_COVERAGE_DATA_FILE"
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ # Single-arm loop branch on line 2, arm taken.
+ assert_contains "2|0|0|1" "$result"
+
+ rm -f "$fixture"
+}
+
+function test_compute_branch_hits_marks_loop_body_not_taken_on_zero_iterations() {
+ bashunit::coverage::init
+
+ local fixture
+ fixture=$(mktemp)
+ cat >"$fixture" <<'EOF'
+#!/usr/bin/env bash
+while [ "$i" -lt 3 ]; do
+ echo "$i"
+done
+EOF
+
+ echo "$fixture" >"$_BASHUNIT_COVERAGE_TRACKED_FILES"
+ # No hits recorded: the loop never iterated (zero-iteration branch uncovered).
+
+ local result
+ result=$(bashunit::coverage::compute_branch_hits "$fixture")
+
+ assert_contains "2|0|0|0" "$result"
+
+ rm -f "$fixture"
+}
+
 function test_compute_branch_hits_assigns_distinct_blocks_per_decision() {
  bashunit::coverage::init