rspec-unit-testing-standards

RSpec Unit Testing Standards

These rules govern the structure, organization, and quality of all RSpec unit tests in this project. Apply them when writing new tests, reviewing existing ones, or auditing test quality.

Priority Levels

Use RFC-style priority words to reduce ambiguity for AI behavior:

• MUST: mandatory; do not violate without a documented exception
• SHOULD: preferred default; may be overridden when a clearer test requires it

Contents

• How to use this skill
• Related skills
• Structure
  • Rule 1 (MUST): One top-level RSpec.describe block per class
  • Rule 2 (MUST): One describe block per public method
  • Rule 3 (SHOULD): Add # frozen_string_literal: true at the top of every spec file
  • Rule 4 (MUST): Spec file location must mirror source file location
  • Rule 5 (MUST): require 'spec_helper' and only the file(s) under test
  • Rule 6 (MUST): Test only through the public interface
• Naming and Organization
  • Rule 7 (SHOULD): Use described_class
  • Rule 8 (MUST): context blocks describe conditions
  • Rule 9 (MUST): it blocks assert one concept, and the description must match the assertion
  • Rule 10 (SHOULD): Use the standard nesting pattern
• Setup and Subject
  • Rule 11 (SHOULD): Use a named subject at the top of each describe #method block
  • Rule 12 (SHOULD): Immediately follow subject with let defaults
  • Rule 13 (SHOULD): Define let(:described_instance) at the top level when multiple describe blocks share the same instance
  • Rule 14 (SHOULD): Prefer subject to represent the method call result
  • Rule 15 (SHOULD): Do not use subject when testing side effects
  • Rule 16 (MUST): Use let/let! for inputs and shared setup; use before only for side effects
  • Rule 17 (SHOULD): Keep test setup local; extract only for substantial cross-file reuse
• Doubles and Stubbing
  • Rule 18 (MUST): Stub calls to non-trivial external objects
  • Rule 19 (MUST): Use allow for incidental stubs; use expect for behavioral assertions
  • Rule 20 (MUST): Use verifying doubles
• Coverage
  • Rule 21 (MUST): Achieve 100% branch-level coverage
  • Rule 22 (MUST): Error assertions must specify both the error class and a message pattern
  • Rule 23 (MUST): Test edge cases within the relevant context block
  • Rule 24 (MUST): Assert observable behavior, not implementation details
    • Anti-pattern: structural identity and constant-existence tests
• Test Reliability
  • Rule 25 (MUST): Keep unit tests deterministic
  • Rule 26 (MUST): Isolate and restore global/process state
  • Rule 27 (MUST): Tests must be order-independent
  • Rule 28 (MUST): Avoid allow_any_instance_of and receive_message_chain
• Verification
• Output

How to use this skill

These rules apply to all RSpec unit specs under spec/unit/. Extend this baseline with domain-specific rules from related skills as needed.

Adoption and enforcement notes:

• Apply these rules as hard requirements for new and modified unit specs.
• Legacy specs may violate some rules; treat those as incremental cleanup work.
• Branch and line coverage are both reported by SimpleCov in this repository.
• minimum_coverage: { line: 100, branch: 100 } is configured and enforced: a full rake spec:unit run fails when either threshold is missed, and CI fails the pull request with it. Rule 21 is a build gate, not just a review check. See the Test coverage policy in CONTRIBUTING.md for the full policy.
• Focused runs (SPEC=<glob> rake spec:unit, or rspec <file>) report coverage but do not fail on it, since they load all of lib/ while exercising only a slice.

Related skills

• Command Test Conventions — additional conventions for Git::Commands::* unit and integration specs, built on top of these rules
• Development Workflow — TDD process that governs when and how tests are written
• PR Readiness Review — final quality gate that verifies test compliance before opening a pull request
• Pull Request Review — PR review process that checks test quality against these standards

Structure

Rule 1 (MUST): One top-level RSpec.describe block per class

Use the class constant directly:

RSpec.describe Git::CommandLine::Capturing do

Never use a string in place of the constant, even for backward-compat aliases:

# Bad — string describe; described_class is unavailable, coverage tooling may not
# map the spec to the source file, and typos go undetected at load time.
RSpec.describe 'Git::CommandLineResult' do

If the constant is a backward-compat alias (e.g. Git::CommandLineResult = Git::CommandLine::Result), use the alias constant itself as the describe argument — the alias is a real Ruby constant and loads without issue. The test content should verify that the alias points to the correct target using object identity (be), which would not be caught implicitly by a NameError on the canonical constant:

RSpec.describe Git::CommandLineResult do
  it 'is a backward-compatible alias for Git::CommandLine::Result' do
    expect(described_class).to be(Git::CommandLine::Result)
  end
end

Do not test #initialize or other behavior here — that is already covered by the spec for the canonical class.

Rule 2 (MUST): One describe block per public method

Use #method_name for instance methods and .method_name for class methods. Include #initialize:

describe '#call' do ...
describe '.build' do ...
describe '#initialize' do ...

Inherited #initialize in concrete subclasses (SHOULD): If a class is directly instantiated by callers but does not override #initialize, its spec SHOULD still include a describe '#initialize' block using the minimal have_attributes form (see Rule 13). This serves two purposes:

1. The spec is self-contained documentation of the constructor signature — a reader does not need to consult the ancestor's spec to know what arguments the class accepts or what attributes it exposes.
2. It guards against an accidental def initialize override in the subclass that silently drops or misroutes an argument, which the ancestor's spec would not catch.

Omit the inherited #initialize block only for abstract or internal classes that callers never instantiate directly — those are sufficiently covered by the ancestor's spec alone.

Rule 3 (SHOULD): Add # frozen_string_literal: true at the top of every spec file

Matches project-wide convention and catches accidental string mutation.

Rule 4 (MUST): Spec file location must mirror source file location

lib/git/foo/bar.rb maps to spec/unit/git/foo/bar_spec.rb. Deviating from this makes specs hard to find and breaks coverage mapping.

Rule 5 (MUST): require 'spec_helper' and only the file(s) under test

Every unit spec MUST start with require 'spec_helper', then require only the Ruby file(s) it directly tests. Avoid requiring unrelated libraries or classes — doing so creates false coupling where a rename or move breaks specs that don't even test that class.

Rule 6 (MUST): Test only through the public interface

Never call private methods directly in tests. If private logic is hard to reach through the public interface, stop and propose one of these remedies to the user:

• Extract a class — move the logic to a new class with its own public interface.
• Make the method public — promote it if it is genuinely part of the contract.
• Redesign the public API — split the public method into smaller public steps.

Never use send, instance_variable_get, or __send__ to reach private state.

Naming and Organization

Ru

---

Content truncated.