RSpec Testing skill for Codex

A healthy RSpec suite reads like a specification in --format documentation, runs in random order, creates database rows only when a test needs persistence, and tests HTTP behavior through request specs.

Inspect first

1. Read AGENTS.md, then .rspec, spec/spec_helper.rb and spec/rails_helper.rb. Note config.order, use_transactional_fixtures, filter_run_when_matching, example_status_persistence_file_path, and support files loaded from spec/support.
2. Run the command the project uses (bin/rspec, bundle exec rspec). Check for parallel_tests or knapsack in the Gemfile before adding parallelism.
3. Look at spec/factories for existing factories and traits before adding new ones.
4. Check whether config.disable_monkey_patching! is on; if so, use RSpec.describe.

Recommended configuration

# spec/spec_helper.rb
RSpec.configure do |config|
  config.disable_monkey_patching!
  config.order = :random
  Kernel.srand config.seed
  config.example_status_persistence_file_path = "tmp/rspec_examples.txt"
  config.filter_run_when_matching :focus
  config.mock_with(:rspec) { |mocks| mocks.verify_partial_doubles = true }
  config.expect_with(:rspec) { |e| e.include_chain_clauses_in_custom_matcher_descriptions = true }
end

verify_partial_doubles makes allow(obj).to receive(:nonexistent) fail, which catches stubs that drifted from the real API.

Structure

RSpec.describe Checkout::Quote do
  subject(:quote) { described_class.new(cart, country:) }

  let(:cart) { build_stubbed(:cart, subtotal_cents: subtotal) }
  let(:country) { "DE" }

  context "when the subtotal reaches the free-shipping threshold" do
    let(:subtotal) { 10_000 }

    it "charges no shipping" do
      expect(quote.shipping_cents).to eq(0)
    end
  end

  context "when shipping abroad" do
    let(:subtotal) { 5_000 }
    let(:country) { "US" }

    it "adds the international rate" do
      expect(quote.shipping_cents).to eq(2_500)
    end
  end
end

• describe names the thing; context starts with “when”, “with” or “without”; it states the outcome. The doc output then reads as sentences.
• Override only the let that varies per context. Keep the value that explains the behavior visible in that context.
• One behavior per example. Use aggregate_failures when several expectations describe one outcome (status plus body):

it "creates the order", :aggregate_failures do
  post "/orders", params: { sku: "A1" }, as: :json
  expect(response).to have_http_status(:created)
  expect(response.parsed_body).to include("status" => "pending")
end

let, let!, before

Use	When
let	lazily built value referenced by examples (default)
let!	a record that must exist even though no example references it (a competing row for a uniqueness test)
before	an action, not a value: sign in, freeze time, stub a service
subject(:name)	the object under test, named

Deep nesting with let overrides five levels up is a smell; flatten into clearer contexts.

Factories

FactoryBot.define do
  factory :order do
    customer
    status { "pending" }
    sequence(:number) { |n| "ORD-#{n.to_s.rjust(6, '0')}" }

    trait :paid do
      status { "paid" }
      paid_at { Time.current }
    end

    trait :with_items do
      transient { item_count { 2 } }
      after(:create) { |order, ctx| create_list(:line_item, ctx.item_count, order:) }
    end
  end
end

Strategy	Hits DB	Use for
build_stubbed	no, fakes an id and persisted?	unit specs of models, presenters, services that only read
build	no (but associations may be created)	validations, unsaved objects
create	yes	queries, scopes, request and system specs

• Default to build_stubbed. Switch to create only when the code queries the database.
• Keep base factories minimal (only required attributes); add traits for optional state.
• association in a factory creates the parent under create; a deep chain can insert dozens of rows per example. Profile with --profile 10 and watch for it.
• For broader factory design across languages, hand off to $test-data-factories.

Doubles

let(:gateway) { instance_double(Payments::Gateway, charge: Result.success) }

it "charges the card once" do
  described_class.new(gateway:).call(order)
  expect(gateway).to have_received(:charge).with(order.total_cents).once
end

• Use verifying doubles (instance_double, class_double) so stubbed methods must exist with a compatible arity.
• Prefer allow + have_received (spy style) so arrange and assert stay in order.
• Do not stub the object under test. Do not mock ActiveRecord query chains; use the database instead.

Request specs

Controller specs are discouraged for Rails 5+; write request specs.

RSpec.describe "Orders API", type: :request do
  let(:user) { create(:user) }
  let(:headers) { { "Authorization" => "Bearer #{token_for(user)}" } }

  describe "GET /orders/:id" do
    it "returns 404 for another customer's order" do
      order = create(:order)
      get "/orders/#{order.id}", headers:, as: :json
      expect(response).to have_http_status(:not_found)
    end
  end
end

Cover per endpoint: happy path, auth missing (401), forbidden (403/404), validation error (422) with error body shape, and pagination edges.

System specs

RSpec.describe "Checkout", type: :system do
  before { driven_by(:rack_test) }                     # fast default, no JS

  context "with the JavaScript payment form" do
    before { driven_by(:selenium, using: :headless_chrome) }   # only where JS is required

    it "completes with a saved card" do
      visit cart_path
      click_on "Pay now"
      expect(page).to have_content("Thank you")
    end
  end
end

Capybara matchers like have_content wait; expect(page.text).to include(...) does not. Never use sleep.

Time, jobs, mail

include ActiveSupport::Testing::TimeHelpers            # in rails_helper

it "expires invites after 7 days" do
  invite = create(:invite)
  travel_to(8.days.from_now) { expect(invite.reload).to be_expired }
end

it "enqueues the receipt" do
  expect { checkout.call }.to have_enqueued_job(ReceiptJob).with(order.id)
end

it "counts a new order" do
  expect { checkout.call }.to change(Order, :count).by(1)
end

Set ActiveJob::Base.queue_adapter = :test in the environment or spec helper for job matchers.

Running and debugging

bundle exec rspec spec/requests/orders_spec.rb:42      # one example by line
bundle exec rspec --only-failures                       # needs persistence file
bundle exec rspec --next-failure
bundle exec rspec --seed 12345                          # reproduce an order failure
bundle exec rspec --bisect --seed 12345                 # find the minimal polluting pair
bundle exec rspec --profile 10                          # slowest examples

Order-dependent failure: rerun with the printed seed, then --bisect. The polluter is usually a class-level cache, a stubbed constant, ENV mutation, or data committed outside the transaction (threads, after_commit with a separate connection).

Gotchas

• let is memoized per example, not across examples; before(:all) / before_all shares state and must not create records unless wrapped in a transaction helper.
• change, have_enqueued_job and raise_error need a block: expect { act }. Passing a value (expect(act)) runs the action too early and the matcher errors or checks nothing.
• create inside let in a top-level group runs for every example that touches it, including ones that did not need it.
• allow_any_instance_of hides design problems; inject the collaborator instead.

Verification

1. Run the touched spec files, then the full suite with --order random.
2. Run touched files twice with different seeds.
3. --profile 10 shows no new slow examples dominated by factory creation.
4. Break the behavior once and confirm the failure message names the expectation clearly.