feat(reports): include file line in GitHub Actions annotations (#710)

Author: Chemaclass

CHANGELOG.md

@@ -9,6 +9,7 @@
 
 ### Changed
 - `install.sh` now verifies the release checksum by default (set `BASHUNIT_VERIFY_CHECKSUM=false` to opt out); it soft-skips with a warning when a checksum asset is unavailable unless verification was explicitly requested (#703)
+- `--log-gha` annotations now include the failing test's `line` (`::error file=…,line=…`), so they pin to the exact line in a pull request's "Files changed" tab (#704)
 
 ## [0.38.0](https://github.com/TypedDevs/bashunit/compare/0.37.0...0.38.0) - 2026-06-07
 

docs/command-line.md

@@ -361,11 +361,12 @@ bashunit test tests/ --log-junit results.xml
 bashunit test tests/ --report-html report.html
 ```
 ```bash [GitHub Actions]
-bashunit test tests/ --log-gha gha.log && cat gha.log
+# Stream annotations straight to the runner log:
+bashunit test tests/ --log-gha /dev/stdout
 ```
 :::
 
-The `--log-gha` flag writes GitHub Actions workflow commands (`::error`, `::warning`, `::notice`) for failed, risky and incomplete tests. When streamed to stdout on a runner, they appear as inline annotations in the "Files changed" tab of a pull request.
+The `--log-gha` flag writes GitHub Actions workflow commands (`::error`, `::warning`, `::notice`) for failed, risky and incomplete tests, including the failing test's `file` and `line`. Point it at `/dev/stdout` (or stream a log file to stdout) on a runner and the failures appear as inline annotations in the "Files changed" tab of a pull request.
 
 ### Show Output on Failure
 

src/reports.sh

@@ -7,6 +7,7 @@ _BASHUNIT_REPORTS_TEST_STATUSES=()
 _BASHUNIT_REPORTS_TEST_DURATIONS=()
 _BASHUNIT_REPORTS_TEST_ASSERTIONS=()
 _BASHUNIT_REPORTS_TEST_FAILURES=()
+_BASHUNIT_REPORTS_TEST_LINES=()
 
 function bashunit::reports::add_test_snapshot() {
   bashunit::reports::add_test "$1" "$2" "$3" "$4" "snapshot"
@@ -47,12 +48,21 @@ function bashunit::reports::add_test() {
   local status="$5"
   local failure_message="${6:-}"
 
+  # Capture the line number from the current test location ("file:line"),
+  # but only when it belongs to this test's file, so a stale location from a
+  # prior test never mislabels this entry.
+  local line=""
+  case "${_BASHUNIT_TEST_LOCATION:-}" in
+    "$file":*) line="${_BASHUNIT_TEST_LOCATION##*:}" ;;
+  esac
+
   _BASHUNIT_REPORTS_TEST_FILES[${#_BASHUNIT_REPORTS_TEST_FILES[@]}]="$file"
   _BASHUNIT_REPORTS_TEST_NAMES[${#_BASHUNIT_REPORTS_TEST_NAMES[@]}]="$test_name"
   _BASHUNIT_REPORTS_TEST_STATUSES[${#_BASHUNIT_REPORTS_TEST_STATUSES[@]}]="$status"
   _BASHUNIT_REPORTS_TEST_ASSERTIONS[${#_BASHUNIT_REPORTS_TEST_ASSERTIONS[@]}]="$assertions"
   _BASHUNIT_REPORTS_TEST_DURATIONS[${#_BASHUNIT_REPORTS_TEST_DURATIONS[@]}]="$duration"
   _BASHUNIT_REPORTS_TEST_FAILURES[${#_BASHUNIT_REPORTS_TEST_FAILURES[@]}]="$failure_message"
+  _BASHUNIT_REPORTS_TEST_LINES[${#_BASHUNIT_REPORTS_TEST_LINES[@]}]="$line"
 }
 
 function bashunit::reports::__xml_escape() {
@@ -131,17 +141,18 @@ function bashunit::reports::__gha_encode() {
   printf '%s' "$text"
 }
 
-function bashunit::reports::generate_gha_log() {
-  local output_file="$1"
-
-  : >"$output_file"
+# Echoes GitHub Actions workflow-command annotations to stdout.
+# Arguments: $1 - "failed-only" to emit just errors (default: all reportable).
+function bashunit::reports::print_gha_annotations() {
+  local only="${1:-all}"
 
   local i
   for i in "${!_BASHUNIT_REPORTS_TEST_NAMES[@]}"; do
     local file="${_BASHUNIT_REPORTS_TEST_FILES[$i]:-}"
     local name="${_BASHUNIT_REPORTS_TEST_NAMES[$i]:-}"
     local status="${_BASHUNIT_REPORTS_TEST_STATUSES[$i]:-}"
     local failure_message="${_BASHUNIT_REPORTS_TEST_FAILURES[$i]:-}"
+    local line="${_BASHUNIT_REPORTS_TEST_LINES[$i]:-}"
     local level="" message=""
 
     case "$status" in
@@ -162,12 +173,27 @@ function bashunit::reports::generate_gha_log() {
         ;;
     esac
 
+    if [ "$only" = "failed-only" ] && [ "$status" != "failed" ]; then
+      continue
+    fi
+
+    local location="file=${file}"
+    if [ -n "$line" ]; then
+      location="${location},line=${line}"
+    fi
+
     local encoded_message
     encoded_message=$(bashunit::reports::__gha_encode "$message")
-    echo "::${level} file=${file},title=${name}::${encoded_message}" >>"$output_file"
+    echo "::${level} ${location},title=${name}::${encoded_message}"
   done
 }
 
+function bashunit::reports::generate_gha_log() {
+  local output_file="$1"
+
+  bashunit::reports::print_gha_annotations all >"$output_file"
+}
+
 function bashunit::reports::generate_report_html() {
   local output_file="$1"
 

tests/unit/reports_test.sh

@@ -14,6 +14,8 @@ function set_up() {
   _BASHUNIT_REPORTS_TEST_DURATIONS=()
   _BASHUNIT_REPORTS_TEST_ASSERTIONS=()
   _BASHUNIT_REPORTS_TEST_FAILURES=()
+  _BASHUNIT_REPORTS_TEST_LINES=()
+  _BASHUNIT_TEST_LOCATION=""
 
   # Unset report env vars by default
   unset BASHUNIT_LOG_JUNIT
@@ -387,6 +389,36 @@ function test_generate_gha_log_skips_skipped_test() {
   assert_empty "$content"
 }
 
+function test_generate_gha_log_includes_line_when_location_known() {
+  _mock_state_functions
+  BASHUNIT_LOG_GHA="gha.log"
+  _BASHUNIT_TEST_LOCATION="tests/foo_test.sh:42"
+
+  bashunit::reports::add_test "tests/foo_test.sh" "test_fail" "100" "1" "failed" "boom"
+  bashunit::reports::generate_gha_log "$_TEMP_OUTPUT_FILE"
+
+  local content
+  content=$(cat "$_TEMP_OUTPUT_FILE")
+
+  assert_contains '::error file=tests/foo_test.sh,line=42,title=test_fail' "$content"
+}
+
+function test_print_gha_annotations_failed_only_to_stdout() {
+  _mock_state_functions
+  BASHUNIT_LOG_GHA="gha.log"
+
+  bashunit::reports::add_test "tests/foo_test.sh" "test_ok" "100" "1" "passed"
+  bashunit::reports::add_test "tests/foo_test.sh" "test_bad" "100" "1" "failed" "boom"
+  bashunit::reports::add_test "tests/foo_test.sh" "test_risky" "10" "0" "risky"
+
+  local output
+  output=$(bashunit::reports::print_gha_annotations failed-only)
+
+  assert_contains '::error file=tests/foo_test.sh' "$output"
+  assert_not_contains '::warning' "$output"
+  assert_not_contains 'test_risky' "$output"
+}
+
 function test_generate_gha_log_encodes_newlines_in_message() {
   _mock_state_functions
   BASHUNIT_LOG_GHA="gha.log"