Code Testing Extensions

Ruby Extension

Language-specific guidance for Ruby test generation.

Rule #0: Confirm the Test Target

If the prompt does not name a specific file (e.g. "test the repository", "cover one core module", "comprehensive suite"), do not assume the largest or top-level upstream code is the intended target. In real workflows the user usually wants to test code they have just added, and large upstream repos contain hundreds of modules already covered by existing specs.

Run these read-only discovery commands first — they are the deliberate exception to Rule #1's "before writing any test or running any command" rule, and their output is the ground truth Rule #1's reading is meant to interpret. Do not write or execute any tests until Rule #0 and Rule #1 are both complete.

Prefer targets that match all of:

1. Untracked or recently added (git status / git log --diff-filter=A).

2. Small and pure (a few hundred lines, no I/O, no global state).

3. Located under a conventional source root (lib/, app/models/, app/services/).

4. Have no existing matching *_spec.rb / *_test.rb.

If spec/spec_helper.rb already requires one specific file (e.g. require "string_utils"), that file is almost certainly the target — start there.

Test Placement Contract

RSpec only discovers specs under spec/ by default, and verification harnesses (CI, msbench, coverage tools) typically scope discovery to spec/ alone. Place every spec there, mirroring the source layout:

A spec placed anywhere outside spec/ (e.g. next to the source under lib/) will be invisible to bundle exec rspec and to the harness. The same applies to Minitest: place tests under test/ and use *_test.rb naming.

Gem-monorepo trap (fastlane, ruby/ruby, large gems with sub-gems): if the repo contains multiple */spec/ directories (each sub-gem with its own specs), bundle exec rspec from the repo root only loads ./spec/ by default — sub-gem specs are invisible to the harness. Either:

• place the new spec inside the root ./spec/ (with a require_relative to the sub-gem's lib/), or

• run the sub-gem's bundle exec rspec from the sub-gem dir AND verify in the Harness Discovery Check below that the root command also enumerates it (often it won't — you'll need to extend .rspec with --default-path or the root Rakefile's test task).

For interpreter-build repos (ruby/ruby itself) the test runner requires make test-all after make miniruby — ruby test/foo_test.rb alone is not what the harness runs.

First-Test Sanity Loop

After writing the first spec — before writing any others:

1. Run bundle exec rspec --dry-run and confirm the example count is > 0. If it is 0, RSpec is not seeing your file; fix the location, filename, or $LOAD_PATH before continuing.

2. Run the spec (bundle exec rspec spec/<your_spec>.rb); fix LoadError, missing require, or constant errors before adding more tests.

3. Only then expand to cover the remaining methods.

This catches placement and load-path mistakes on turn 1 instead of after dozens of failed-test iterations.

Harness Discovery Check

Before reporting success, run the harness-equivalent discovery command from the repo root and confirm the example count went up by at least the number of tests you generated. CI/msbench/coverage harnesses do not know which file or sub-gem dir you targeted; they run the framework's default discovery from the repo root, so a spec that passes via bundle exec rspec fastlane_core/spec/foo_spec.rb is still worthless if bundle exec rspec --dry-run from the repo root doesn't enumerate it.

Choose the repository's configured runner before execution. Run the selected commands from the repo root in the same Bash process as set -euo pipefail, and require exit code zero before using any count as evidence. Do not suppress stderr, pipe the runner into a counting command, or switch runners after failure.

For RSpec, use its dry-run example summary:

set -euo pipefail
bundle exec rspec --dry-run --format progress

For Minitest without a repository-supported discovery mode, run the configured real test task and use its actual <N> runs, <N> assertions summary, not the number of Rake tasks. For a repository whose harness uses rake test:

set -euo pipefail
bundle exec rake test

If the harness instead uses bin/rails test or another task, substitute that command before execution; it is not a fallback for a failed selected task. For custom runners (Homebrew, ruby/ruby, etc.), use the repository's documented discovery mode or real harness-equivalent test task, with the same exit-status requirements.

Require a successful runner exit and a nonzero test/example count, then compare the baseline and updated summaries for the same harness scope. If the count did not increase, your spec is invisible to the harness. Move it into ./spec/, extend .rspec/Rakefile so the harness picks up the sub-gem dir, or switch to a require_relative strategy from a root-level spec. A failed runner or missing summary is a blocker, not evidence of empty discovery. Do not report success until the harness-equivalent command sees your new tests.

Rule #1: Investigate the Repo First

Before writing any test or running any command, read:

1. Existing tests — find spec/**/*_spec.rb (RSpec) or test/**/*_test.rb (Minitest) and copy their style (matchers, helpers, factories, contexts)

2. Gemfile / Gemfile.lock — Ruby version, test framework, supporting gems (rspec, minitest, factory_bot, webmock, vcr, rails)

3. .ruby-version / .tool-versions — pinned Ruby version

4. Test helpers — spec/spec_helper.rb, spec/rails_helper.rb, test/test_helper.rb — these dictate the load path, requires, and global config

5. Rake tasks — Rakefile may define a default task that runs the full test suite

Use the framework the repo already uses. Do not introduce RSpec into a Minitest project (or vice versa).

Toolchain Detection

Always run inside bundle exec if a Gemfile.lock is present — otherwise you may pick up a system gem version that disagrees with the lockfile.

Build Commands

Ruby is interpreted — there is no compile step. The closest validations:

For Rails: load all classes once with bundle exec rails zeitwerk:check to catch missing constants before running tests.

Test Commands

RSpec

Minitest

Rails (any framework)

Always prefer the wrapper script (bin/rails, bin/rspec) when present — they enforce the project's loader/setup.

Lint Command

• bundle exec rubocop — autocorrect with bundle exec rubocop -A (only if existing tests already conform; do not autocorrect unrelated files)

• bundle exec standardrb --fix if standard is in the Gemfile

• Some Rails projects add rubocop-rails, rubocop-rspec, rubocop-performance — they enforce extra rules

Project Layout and Loading

Loading source code:

• RSpec: spec/spec_helper.rb typically does require 'my_gem' or sets $LOAD_PATH. Match its pattern in new specs by require 'spec_helper' (or require 'rails_helper' in Rails)

• Minitest: each _test.rb typically require 'test_helper'

• Rails uses Zeitwerk autoloading — do not add require_relative '../../app/models/widget'; just require 'rails_helper' and reference the constant

Test File Naming

RSpec Template

require 'spec_helper'
require 'calculator'

RSpec.describe Calculator do
  subject(:calculator) { described_class.new }

  describe '#add' do
    it 'returns the sum of two positive numbers' do
      expect(calculator.add(2, 3)).to eq(5)
    end

    context 'with negative numbers' do
      it 'returns the correct sum' do
        expect(calculator.add(-1, 1)).to eq(0)
      end
    end

    it 'raises when given non-numeric input' do
      expect { calculator.add('a', 1) }.to raise_error(TypeError)
    end
  end
end

Common Errors

Mocking Rules (RSpec)

• Use instance_double(Klass) and class_double(Klass) — they verify that the method actually exists, unlike double

• allow(obj).to receive(:method).and_return(value) for stubs; expect(obj).to receive(:method) for interaction expectations

• Prefer instance_double over plain double; prefer dependency injection over allow_any_instance_of

• Use let for memoized helpers; use let! only when the side effect must run before each example

• Avoid global state mutation in tests — wrap in around blocks or use ClimateControl for env vars

• For HTTP, use webmock (stub_request(:get, ...)) or vcr cassettes if the project already uses them

• If a test needs more than 3 mocks, flag it as a design smell

Mocking Rules (Minitest)

• Use Minitest::Mock for simple cases: mock = Minitest::Mock.new; mock.expect(:method, return_value, [arg])

• For richer mocking, projects commonly add mocha: obj.expects(:method).returns(value) (in test_helper.rb: require 'mocha/minitest')

• Always verify mocks at end of test (mock.verify for Minitest::Mock); Mocha verifies automatically

Rails Specifics

• Use the smallest spec type that covers the behavior: model spec for pure logic, request spec for HTTP, system spec only when JS/UI matters

• rails-controller-testing gem must be present for assigns(:foo) and assert_template

• ActiveJob::TestHelper and ActiveSupport::Testing::TimeHelpers (travel_to) come with Rails — use them instead of Timecop if Rails ≥ 5

• Use fixtures only if the project already uses them; factory_bot is more common in modern Rails apps

• Database transactions wrap each test by default — for system tests with browser drivers, use DatabaseCleaner strategies the project already configures

Dependency Installation (Last Resort)

Only add gems after investigation confirms they are missing. Edit Gemfile:

group :test do
  gem 'rspec'
  gem 'webmock'
end

Then run:

bundle install

Never gem install outside Bundler — it bypasses the lockfile and changes the global Ruby environment.

Skip Coverage Tools

Do not configure or run coverage tools (SimpleCov). Coverage is measured separately by the evaluation harness.