Command Test Conventions

Command Test Conventions

Conventions for writing and reviewing unit and integration tests for Git::Commands::* classes.

• Related skills
• Input
  • Version-aware test scope
• Reference
  • Unit tests
    • Cover these cases
    • Expectations for command invocation
    • #initialize — omit from command specs
    • Unit test grouping
  • Integration tests
    • Integration test grouping
    • Guard tests for options introduced after the minimum supported Git version
    • Additional integration conventions
  • Shared conventions
• Workflow
• Output

Related skills

• RSpec Unit Testing Standards — baseline RSpec rules that govern all unit test structure, naming, setup, stubbing, and coverage; this skill adds command-specific conventions on top
• Review Arguments DSL — verifying DSL entries match git CLI
• Command Implementation — class structure, phased rollout gates, and internal compatibility contracts
• Command YARD Documentation — documentation completeness for command classes

Input

The invocation needs the unit and/or integration spec file(s) to review. Including the corresponding command source file provides useful context for verifying argument coverage.

Prerequisite: Read the entire RSpec Unit Testing Standards skill (line 1 through EOF) before beginning. It defines the baseline Rules 1–28 that this skill extends. Without it, MUST-level structural, naming, stubbing, and coverage checks will not be applied.

Version-aware test scope

Before deciding that test coverage is missing for an option, alias, or flag form, determine the repository's minimum supported Git version from project metadata. In this repository, git.gemspec declares git 2.43.0 or greater.

Coverage expectations for CLI forms must be based on the minimum supported Git version, not only on the locally installed Git. Use version-matched upstream documentation first, version-matched upstream source when needed, and local git <command> -h output only as a supplemental check.

Do not require tests for newer-version-only forms that are not supported by the minimum supported Git version. Symmetrically, if the local Git omits or abbreviates a form that is supported in the minimum version, tests should still cover the minimum-version behavior.

Reference

Unit tests

Unit tests verify CLI argument building and command-layer behavior for each command.

Cover these cases

• Base invocation (no options): verify literals and return pass-through. Store the .and_return value in an expected_result variable and assert expect(result).to eq(expected_result) to verify that #call passes through what execution_context.command_capturing returns. This assertion belongs only in the base invocation test — do not repeat it in every test.
• Each positional operand variation (e.g., single value, multiple values)
• Each flag option, including aliases (e.g., :force and :f)
• max_times: flag options: test with true (emits once) and the maximum integer (emits N times), plus each alias with true
• Flag options combined with operands where meaningful (e.g., an option that modifies how operands are interpreted)
• Value options with each accepted form (e.g., boolean true vs a string value like 'lines,cumulative')
• Pathspecs or other repeatable/end_of_options-based operands, both alone and combined with preceding operands
• Execution options forwarding where applicable (e.g., timeout:)
• Exit-status behavior for commands using allow_exit_status with a non-default range: test that exit codes within the declared range return a result without raising, and that exit codes outside the range raise FailedError. For example, if the command declares allow_exit_status 0..1, test that exit codes 0 and 1 succeed, and that exit codes 2 and 128 raise FailedError. Commands that only succeed at exit code 0 (the default) do not need a unit-level exit code test — the integration error-handling test covers that path.
• Input validation (ArgumentError) for per-argument validation failures: unknown options, required: violations, type: mismatches, etc. Command classes generally do not declare cross-argument constraint methods (conflicts, requires, requires_one_of, requires_exactly_one_of, forbid_values, allowed_values, etc.) — git validates its own option semantics. Every constraint a command does declare gets an ArgumentError test. What makes a constraint permitted is defined in Project Context — Validation Boundaries.

Expectations for command invocation

Use the expect_command_capturing helper from spec_helper.rb (or expect_command_streaming for streaming commands) which automatically includes raise_on_failure: false:

expect_command_capturing('clone', '--', url, dir).and_return(command_result)

When testing execution options, include forwarded keywords:

expect_command_capturing('clone', '--', url, dir, timeout: 30).and_return(command_result)

These helpers expand to expect(execution_context).to receive(:command_capturing)... — expect rather than allow because the call itself (the correct arguments reaching git) is the behavior under test. See Rule 19 in the RSpec Unit Testing Standards.

Expectations for stdin-feeding commands

Commands that use Base#with_stdin pass an IO pipe read end as in: to execution_context.command_capturing. Unit tests must capture that IO object and assert its content. Use a block form on the expect to intercept keyword arguments:

# Helper defined in the spec file. The mode flag is an ordinary option on the class,
# so it is passed in by the caller rather than baked into the helper:
def expect_batch_command(*expected_cli_args, stdin_content: nil, **extra_opts)
  expect(execution_context).to receive(:command_capturing) do |*args, **kwargs|
    expect(args).to eq(['cat-file', *expected_cli_args])
    expect(kwargs).to include(raise_on_failure: false, **extra_opts)
    expect(kwargs[:in].read).to eq(stdin_content) if stdin_content
    command_result
  end
end

# Usage:
it 'passes the object via stdin and runs --batch-check' do
  expect_batch_command('--batch-check', stdin_content: "HEAD\n")
  command.call('HEAD', batch_check: true)
end

it 'writes each object on its own line to stdin' do
  expect_batch_command('--batch-check', stdin_content: "HEAD\nv1.0\nabc123\n")
  command.call('HEAD', 'v1.0', 'abc123', batch_check: true)
end

it 'includes --batch-all-objects and writes nothing to stdin' do
  expect_batch_command('--batch-check', '--batch-all-objects', stdin_content: '')
  command.call(batch_all_objects: true, batch_check: true)
end

# argv-invisible argument exception: :object is skip_cli: true, so it reaches git
# over stdin and never in argv. Git has no token to detect these incompatibilities
# with, so Ruby must enforce them.
# conflicts: can't pass objects AND bypass stdin; requires_one_of: must choose one.
it 'raises when mutually exclusive DSL inputs are combined' do
  expect { command.call('HEAD', batch_all_objects: true, batch_check: true) }
    .to raise_error(ArgumentError, /cannot specify :object and :batch_all_objects/)
end

kwargs[:in].read works because Base#with_stdin writes to stdin on a background thread and yields the read end immediately; the read call blocks until the writer thread closes the pipe and EOF is reached, so the full content is returned. Test stdin_content: '' explicitly for the no-input case (e.g. --batch-all-objects) to confirm nothing is written.

What not to test

Unit tests should exercise each code path through the command, not each possible input value. Avoid these patterns:

• option: false for any flag_option. Passing false to a flag_option (negatable or non-negatable) produces no output — identical to the base invocation with no options. The "no arguments" test already covers this path. To exercise the negative form of a negatable flag, use the no_ companion key: e.g.: no_single_branch: true emits --no-single-branch, which is a distinct code path worth testing.
• Repeating the return value assertion. The base invocation test asserts expect(result).to eq(expected_result) once as a contract check. Do not repeat this assertion in other tests — one check per file is sufficient.
• Intermediate integers for max_times: flags. When a flag declares max_times: N, test only true and the max integer N. Do not test intermediate values (e.g. force: 1 when max_times: 2) — the DSL handles all valid integers uniformly and intermediate values exercise the same code path.
• String-variant pass-through tests. Do not write multiple tests that pass different string values through the same positional argument or value option. Tests like "handles paths with spaces" and "handles paths with unicode" exercise the same code path — the command passes strings unchanged. One test per operand/option is sufficient.
• Multiple format variants for the same operand. For example, a stash command that accepts a stash reference does not need separate tests for stash@{0}, stash@{2}, and 1 — they all flow through the same positional argument.
• Varying mocked stdout for the same invocation. If the command has no output parsing, testing the same #call with different mocked stdout values exercises identical code. One test is sufficient unless the command parses or branches on the output.

The Arguments DSL has its own comprehensive spec (arguments_spec.rb) that tests flag handling, value options, positionals, end_of_options, edge cases, and error conditions. Command specs should test that the command uses the DSL correctly (i.e., the right arguments reach execution_context.command_capturing), not re-test the DSL's own behavior.

Two specific DSL re-test patterns that commonly appear but should be avoided:

• end_of_options protection tests (dash-prefixed operands). When a command declares end_of_options, the existing operand tests already verify that '--' appears before operands in the expected argv sequence. Do not add a separate test that passes a dash-prefixed operand (e.g. '-feature') to prove the separator prevents misinterpretation: a dash-prefixed string exercises the identical code path as any other string, and the DSL spec (arguments_spec.rb) already covers end_of_options protection. The command spec only needs to show '--' at the right position; the DSL spec demonstrates why that matters.
• required: operand rejection tests. When a command declares operand :name, required: true, do not test that calling with no arguments raises ArgumentError — the DSL spec covers required-operand validation. The command spec should test what happens when the operand IS provided, not that the DSL reports missing-argument errors correctly.

Policy vs. interface testing: Command classes are neutral, faithful representations of the git CLI. Their unit tests verify CLI argument building (the neutral interface), not policy enforcement. Tests should not hardcode policy assumptions — for example, a command spec should not always pass no_edit: true or expect --no-edit unless the test is specifically exercising that option.

Anti-pattern: every it block in a command spec passes no_edit: true, no_progress: true, or no_color: true — this tests the facade's policy, not the command's interface.

Correct pattern: test each option independently (it 'passes --no-edit when no_edit is true'); test the default (no option passed) separately. Policy enforcement (which options the facade passes and why) is tested at the facade layer (for example, spec/unit/git/repository/remote_operations_spec.rb).

Where to test policy enforcement: Policy tests belong in the facade layer, not in command specs. When a Git::Repository::* facade method sets policy defaults like no_edit: true or no_progress: true, the corresponding facade unit spec (e.g. spec/unit/git/repository/remote_operations_spec.rb) should verify those defaults reach the command:

# spec/unit/git/repository/remote_operations_spec.rb — facade policy-default test
describe '#pull' do
  let(:pull_command) { instance_double(Git::Commands::Pull) }
  let(:pull_result) { command_result('') }

  it 'adds no_edit: true and no_progress: true for non-interactive execution' do
    expect(Git::Commands::Pull).to receive(:new).with(execution_context).and_return(pull_command)
    expect(pull_command)
      .to receive(:call).with('origin', 'main', no_edit: true, no_progress: true).and_return(pull_result)
    described_instance.pull('origin', 'main')
  end
end

This separation ensures:

• Command specs verify the neutral interface (every option works correctly)
• Facade specs verify the policy (the right options are passed and why)
• An AI sees exactly where each concern is tested and does not conflate them

See "Command-layer neutrality" in CONTRIBUTING.md.

#initialize — omit from command specs

Do not write a describe '#initialize' block in command specs. This is a deliberate exception to Rule 2's SHOULD guidance for concrete subclasses. The full reasoning chain:

1. Rule 2's have_attributes form requires public attributes. Base#initialize stores @execution_context as a private instance variable with no attr_reader, so there is nothing to pass to have_attributes. The form that Rule 2 uses cannot be applied.

2. The only fallback is not_to raise_error, which is a Rule 24 violation. Asserting that described_class.new(execution_context) does not raise merely confirms the code runs — it is not an observable behavioral assertion.

3. Both Rule 2 purposes are already satisfied by other means:

   • Documentation: the let(:command) { described_class.new(execution_context) } declaration at the top of every spec documents the constructor signature as clearly as a dedicated block would.
   • Accidental-override guard: let(:command) is evaluated before every example. If a subclass accidentally introduced a def initialize with a different signature, every test in the file would immediately raise ArgumentError — providing the same protection a dedicated block would.

4. Base#initialize is covered by base_spec.rb. Command subclasses that do not override #initialize gain nothing from repeating it.

Required fix if found: Remove any describe '#initialize' block that contains only expect { described_class.new(execution_context) }.not_to raise_error — it is a Rule 24 violation and provides no coverage value.

Unit test grouping

Unit tests are organized under describe '#call' with three sections:

1. Argument building (the bulk) — flat context blocks, one per option/operand variation. These are always present and come first.
2. context 'exit code handling' — only for commands with allow_exit_status ranges beyond 0..0. Uses mocked exit codes via command_result helper to test that exit codes within the allowed range return a result and exit codes outside the range raise FailedError.
3. context 'input validation' — only for commands with validation rules. Covers unsupported options and required arguments that raise ArgumentError. Cross-argument constraints are usually absent, so there is usually nothing to test here. Test whatever constraints a command does declare (e.g. conflicts :object, :batch_all_objects and requires_one_of :object, :batch_all_objects in cat-file --batch, or conflicts :output, :out in archive) — what makes a constraint permitted is defined in Project Context — Validation Boundaries.

The exit code and input validation blocks are optional — include them only when the command has those behaviors. They always appear at the end of #call, in that order.

Required fix if found: The section names 'exit code handling' and 'input validation' are exact string literals — do not paraphrase. A context named 'with an unsupported option' or 'when the option is invalid' instead of 'input validation' MUST be renamed. These names are load-bearing identifiers: they signal to reviewers at a glance which structural section they are looking at and what it may or may not contain.

Unit test descriptions should be concise and action-oriented. Use descriptions like "includes the --cached flag", "passes both commits as operands", "combines commit with pathspecs".

Always use the emitted long-flag form in descriptions, never a short alias. The DSL canonicalises aliases to the long form (e.g. :q → --quiet, :f → --force). Writing 'adds -q flag' in an it description is misleading because the actual token asserted in the expectation is '--quiet'. Use 'adds --quiet flag' instead.

Exception to RSpec Unit Testing Standards Rules 11–12 (subject and let ordering): Command unit tests intentionally omit subject within describe '#call'. Because each test exercises a different argument combination, there is no single fixed call expressible as a shared subject. Use let(:command) at the RSpec.describe level and call command.call(...) directly inside each it block, overriding let inputs per context block as needed.

Example with all three sections:

RSpec.describe Git::Commands::Branch::Delete do
  # Duck-type collaborator: command specs depend on the #command_capturing interface,
  # not a single concrete ExecutionContext class.
  let(:execution_context) { double('ExecutionContext') }
  let(:command) { described_class.new(execution_context) }

  describe '#call' do
    # Argument building — flat contexts
    context 'with single branch name' do
      it 'passes the branch name' do
        expected_result = command_result('Deleted branch feature.')
        expect_command_capturing('branch', '-d', 'feature').and_return(expected_result)
        result = command.call('feature')
        expect(result).to eq(expected_result)
      end
    end

    context 'with :force option' do
      # ...
    end

    # Exit code handling — only when command declares allow_exit_status
    context 'exit code handling' do
      it 'returns result for exit code 0' do
        # ... mock exit code 0, assert result returned ...
      end

      it 'returns result for exit code 1 (partial failure)' do
        # ... mock exit code 1, assert result returned ...
      end

      it 'raises FailedError for exit code > 1' do
        # ... mock exit code 128, assert FailedError raised ...
      end
    end

    # Input validation — only when command validates input
    context 'input validation' do
      it 'raises ArgumentError for unsupported options' do
        expect { command.call('branch', invalid: true) }
          .to raise_error(ArgumentError, /Unsupported options/)
      end
    end
  end
end

Example with argument building only (no custom exit codes, no validation):

RSpec.describe Git::Commands::Stash::Pop do
  # Duck-type collaborator: command specs depend on the #command_capturing interface,
  # not a single concrete ExecutionContext class.
  let(:execution_context) { double('ExecutionContext') }
  let(:command) { described_class.new(execution_context) }

  describe '#call' do
    context 'with no arguments' do
      # ...
    end

    context 'with stash reference' do
      # ...
    end

    context 'with :index option' do
      # ...
    end
  end
end