Git Facade Test Conventions

Facade Test Conventions

Conventions for writing and reviewing unit and integration tests for facade methods on Git::Repository::* modules.

Contents

• How to use this skill
• Related skills
• Input
• Reference
  • Unit tests
    • Setup pattern
    • Cover these cases
    • Expectations for command invocation
    • What not to test
    • Unit test grouping
  • Integration tests
    • When to write integration tests
    • When to skip integration tests
    • Integration test grouping
    • What integration tests assert
    • What integration tests do not assert
• Workflow
• Output
  • When writing new facade tests
  • When reviewing existing facade tests

How to use this skill

Attach this file to your Copilot Chat context, then invoke with the spec file(s) to write or review. Include the corresponding facade module for context. Examples:

Using the Facade Test Conventions skill, scaffold tests for Git::Repository::Staging.

Facade Test Conventions review: spec/unit/git/repository/committing_spec.rb.

Related skills

• RSpec Unit Testing Standards — baseline RSpec rules that govern all unit test structure, naming, setup, stubbing, and coverage; this skill adds facade-specific conventions on top
• Facade Implementation — facade module structure and orchestration patterns
• Facade YARD Documentation — YARD docs for facade modules and methods
• Command Test Conventions — sibling skill that tests the underlying Git::Commands::* classes the facade calls

Input

The invocation needs the unit and/or integration spec file(s) to review. Including the corresponding facade module file (lib/git/repository/<topic>.rb) provides useful context for verifying delegation contracts and option forwarding.

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.

Reference

Unit tests

Facade unit tests verify the orchestration contract between the facade method and the components it calls (Git::Commands::*, Git::Parsers::*, Git::ExecutionContext::Repository). They do not run real git.

The collaborators (commands, parsers) are stubbed via instance_double. The unit test asserts:

1. The facade constructs each command class with the injected @execution_context.
2. Each command's #call is invoked with the expected positional and keyword arguments (verifying argument pre-processing).
3. For multi-command sequences, the calls happen in the documented order.
4. The parser/result-class is invoked with the command's stdout (when applicable).
5. The facade returns the value its public contract documents.

Setup pattern

RSpec.describe Git::Repository::Staging do
  let(:execution_context) { instance_double(Git::ExecutionContext::Repository) }
  let(:described_instance) { Git::Repository.new(execution_context: execution_context) }
  let(:command_result) { instance_double(Git::CommandLine::Result, stdout: '') }
  let(:add_command) { instance_double(Git::Commands::Add) }
  let(:add_result) { command_result }

  before do
    allow(Git::Commands::Add).to receive(:new).with(execution_context).and_return(add_command)
  end

  describe '#add' do
    # ...
  end
end

The shared command_result let provides a default empty-stdout result; each per-command alias (add_result, branch_list_result, ...) lets individual tests override stdout in isolation — e.g. let(:add_result) { instance_double(Git::CommandLine::Result, stdout: 'fixture output') } in a nested context — without affecting other tests in the file.

Setup invariants:

• The subject is an instance of Git::Repository, not the module itself. Modules are mixed into the class; tests must exercise the class to reflect real call sites.
• execution_context is an instance_double(Git::ExecutionContext::Repository) — never a double('ExecutionContext'). The one exception is a facade whose behavior under test is deriving a new context (dup_with): there a real Git::ExecutionContext::Repository is allowed because it is a value object with no disk access, and a stub of dup_with would re-implement it. Say so in a comment on the let.
• Each command class is stubbed with allow(Klass).to receive(:new).with(execution_context).and_return(...) so the facade's command construction (with the right execution context) is verified by the stub.

Cover these cases

• Default invocation — facade called with no arguments (or only required positional args) delegates with the documented defaults. Assert the return value once per facade method to verify pass-through.
• Each positional argument variation — single value, array, nil where applicable.
• Each option the facade exposes — including aliases, deprecated keys, and policy defaults the facade applies (no_edit: true, etc.).
• Multi-command sequences — when the facade calls more than one command, use expect ... receive(:call).with(...).ordered to assert ordering and intermediate-result wiring.
• Parser invocation — when the facade uses a Git::Parsers::* class, stub the parser and assert it is called with the command's stdout. Assert the facade returns what the parser returned.
• Raw Git::CommandLine::Result return — when the facade's contract is to return the command's Git::CommandLine::Result directly (not .stdout and not a parser output), assert eq(<command>_result) to verify pass-through.
• Option whitelisting — when the facade defines a <METHOD>_ALLOWED_OPTS constant and calls Git::Repository::Internal.assert_valid_opts!, test that an unknown key raises ArgumentError and a known key is forwarded.
• Deprecation handling — when the facade rewrites or warns on deprecated keys, test that the deprecation warning is emitted and the new key is forwarded.
• Signature compatibility call shapes — when a facade method preserves a legacy public contract, include tests for each call shape the 4.x public API used (positional hash and/or keyword-arg / **opts where applicable).

Expectations for command invocation

Use the standard rspec-mocks form (no command-specific helper exists for the facade layer):

it 'delegates to Git::Commands::Add#call with the given path' do
  expect(add_command).to receive(:call).with('path/to/file.rb').and_return(add_result)
  described_instance.add('path/to/file.rb')
end

For command + parser orchestration (single command whose stdout is fed to a parser), use .ordered to assert the call sequence:

it 'lists branches then parses the output' do
  expect(branch_list_command).to(
    receive(:call)
        .with(all: true, format: Git::Parsers::Branch::FORMAT_STRING)
        .and_return(branch_list_result)
        .ordered
  )

  expect(Git::Parsers::Branch).to(
    receive(:parse_list)
        .with(branch_list_result.stdout)
        .and_return(parsed_branches)
        .ordered
  )

  expect(described_instance.branch_list).to eq(parsed_branches)
end

For genuinely multi-command orchestration (the facade calls more than one command), chain .ordered across each command's #call, wiring intermediate results through as needed:

it 'saves the stash then lists stashes' do
  expect(stash_save_command).to(
    receive(:call).with(message: 'wip').and_return(stash_save_result).ordered
  )

  expect(stash_list_command).to(
    receive(:call).and_return(stash_list_result).ordered
  )

  expect(described_instance.stash_save_and_list(message: 'wip')).to eq(parsed_stashes)
end

What not to test

• Command argv building. That is the command class's contract and is covered by spec/unit/git/commands/<command>_spec.rb. The facade unit test should stub #call and assert the keyword arguments the facade passes — not assert on the CLI tokens that reach git.
• Parser internals. Stub the parser class method and assert the facade calls it with the right input. Parser parsing is covered by spec/unit/git/parsers/.
• Real command execution. Facade unit tests must not run commands through Git::ExecutionContext::Repository. Use instance_double, except for the derived-context case named under "Setup invariants".
• Multiple input strings exercising the same code path — one test per argument type is sufficient (string vs. array vs. nil), not one per value.
• #initialize of the facade module. The module is mixed into Git::Repository; constructor coverage belongs to repository_spec.rb.

Unit test grouping

One describe '#<method_name>' block per facade method. Inside, use flat context blocks per argument variation. Optional sections at the end (in order) when present:

• context 'option whitelisting' — Git::Repository::Internal.assert_valid_opts! raises on unknown keys and forwards known keys unchanged (no slice — the assertion is the only enforcement mechanism)
• context 'deprecation handling' — Git::Deprecation.warn assertions and key-rewrite tests
• context 'input validation' — ArgumentError raised by the facade itself (not by the command)
• context 'signature compatibility' — for legacy-contract methods, exercises required call shapes (legacy positional hash and/or keyword-arg / **opts forms)

The exit code section that command specs use does not apply to facade specs — exit-status handling is the command's concern; the facade's tests assume the command either returns a result or raises.