test: gem.bats tests 5-6 are grep-based regression guards, not functional unit tests

[gtrabanco]

Problem

PR #270 (fix/265-gem-update-false-positive) added two bats tests in tests/package/gem.bats that use grep -q on the source file to verify the fix is present, rather than calling gem::update_apps and asserting on its behavior:

@test "gem::update_apps checks exit code of gem outdated (not just stdout)" {
    local gem_script="$SLOTH_PATH/scripts/package/src/package_managers/gem.sh"
    [[ -f "$gem_script" ]]
    grep -q 'gem_outdated_exit' "$gem_script"
    grep -q 'gem_outdated_exit.*-ne 0' "$gem_script"
}

@test "gem::update_apps discards stderr to avoid parsing error text as packages" {
    local gem_script="$SLOTH_PATH/scripts/package/src/package_managers/gem.sh"
    [[ -f "$gem_script" ]]
    grep -q 'gem outdated 2> /dev/null' "$gem_script"
}

These tests verify implementation details (presence of specific strings in source) rather than functional behavior. They are fragile — renaming gem_outdated_exit or reformatting the gem outdated line breaks the test even if the actual bug fix is still correct.

Why not fix now

gem::update_apps shells out to the external gem command. Writing a true functional test requires mocking gem outdated to:

• Exit 1 with empty stdout (the [Bug] gem::update_apps silently fails when system Ruby has broken native extensions #265 failure case)
• Exit 0 with empty stdout (the "Already up-to-date" case)
• Exit 0 with populated stdout (the "has updates" case)

…then asserting on gem::update_apps return code and output. This needs a mock/stub harness for gem that the test suite does not currently have.

Acceptance criteria

• Tests 5-6 in tests/package/gem.bats call gem::update_apps (or a sourced version of it) instead of grepping the source file
• A mock/stub for the gem command is provided (e.g. a fake gem on PATH or a function override) that can simulate the three exit-code/stdout scenarios above
• Tests assert on the return code and/or output of gem::update_apps, not on source-file string presence
• Existing grep-based tests are removed or converted (not duplicated)

Context

• Found during review of PR fix(gem): check exit code of gem outdated to prevent false positive #270
• The grep-based tests are acceptable as a regression guard in the interim — they ensure the fix pattern for [Bug] gem::update_apps silently fails when system Ruby has broken native extensions #265 stays present
• This issue tracks upgrading them to true functional tests when a mock harness is available

[gtrabanco]

Triage verdict (ship-roadmap issue sweep, 2026-07-06)

Classification: postpone

Reason

This issue requires a mock/stub harness for the gem command that the test suite does not currently have. The issue body itself states: "This issue tracks upgrading them to true functional tests when a mock harness is available."

Trigger to reopen

When a mock/stub harness for external commands (gem, brew, etc.) is added to the test suite, this issue should be re-evaluated. Until then, the grep-based regression guards are acceptable.

Context

• Found during review of PR fix(gem): check exit code of gem outdated to prevent false positive #270 (fix/265-gem-update-false-positive)
• The grep-based tests are a deliberate interim regression guard
• No blocking dependency — this is a test-quality improvement, not a defect

[gtrabanco]

Triage (2026-07-08): postpone. Grep-based regression tests in gem.bats — explicitly out of scope for this run (confirmed in SHIP_DECISIONS Round 2). Trigger: next test-improvement pass. Leave open.