This skill should be used when the user asks to "write specs", "create spec", "add RSpec tests", "fix failing spec", or mentions RSpec, describe blocks, it blocks, expect syntax, test doubles, or matchers. Should also be used when editing *_spec.rb files, working in spec/ directory, planning implementation phases that include tests (TDD/RGRC workflow), writing Testing Strategy or Success Criteria sections, discussing unit or integration tests, or reviewing spec output and test failures. Comprehensive RSpec and FactoryBot reference with best practices, ready-to-use patterns, and examples.
/plugin marketplace add hoblin/claude-ruby-marketplace/plugin install rspec@claude-ruby-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
examples/core/basic_structure.rbexamples/core/configuration.rbexamples/core/hooks.rbexamples/core/memoized_helpers.rbexamples/core/metadata_filtering.rbexamples/core/shared_examples.rbexamples/factory_bot/associations.rbexamples/factory_bot/build_strategies.rbexamples/factory_bot/callbacks.rbexamples/factory_bot/custom_construction.rbexamples/factory_bot/factory_definition.rbexamples/factory_bot/inheritance.rbexamples/factory_bot/traits.rbexamples/factory_bot/transients.rbexamples/matchers/change.rbexamples/matchers/collections.rbexamples/matchers/comparisons.rbexamples/matchers/composing.rbexamples/matchers/custom_matchers.rbexamples/matchers/equality.rbThis skill provides comprehensive guidance for writing effective RSpec tests in Ruby and Rails applications. Use for writing new specs, fixing failing tests, understanding matchers, using test doubles, and following RSpec best practices.
RSpec.describe Order do
subject(:order) { described_class.new(items) }
let(:items) { [item1, item2] }
let(:item1) { double("item", price: 10) }
let(:item2) { double("item", price: 20) }
describe "#total" do
it "sums item prices" do
expect(order.total).to eq(30)
end
end
context "with discount" do
let(:order) { described_class.new(items, discount: 5) }
it "applies discount" do
expect(order.total).to eq(25)
end
end
end
| Concept | Purpose |
|---|---|
describe / context | Group related examples |
it / specify | Define individual test cases |
let | Lazy-evaluated, memoized helper |
let! | Eager-evaluated helper (runs before each example) |
subject | Primary object under test |
before / after | Setup and teardown hooks |
expect | Make assertions |
describe "#calculate_total" do
subject(:total) { order.calculate_total }
it "returns sum of items" do
expect(total).to eq(100)
end
end
describe "#withdraw" do
context "with sufficient funds" do
let(:account) { build(:account, balance: 100) }
it "reduces balance" do
expect { account.withdraw(50) }.to change(account, :balance).by(-50)
end
end
context "with insufficient funds" do
let(:account) { build(:account, balance: 10) }
it "raises error" do
expect { account.withdraw(50) }.to raise_error(InsufficientFunds)
end
end
end
expect(x).to eq(y) # ==
expect(x).to eql(y) # eql? (type-sensitive)
expect(x).to be(y) # equal? (identity)
expect(x).to be_truthy # not nil or false
expect(x).to be_falsey # nil or false
expect(x).to be_nil
expect(x).to be true # exactly true
expect(x).to be > 3
expect(x).to be_between(1, 10).inclusive
expect(x).to be_within(0.1).of(3.14)
expect(arr).to include(1, 2)
expect(arr).to contain_exactly(3, 2, 1) # order-independent
expect(arr).to all(be_positive)
expect(str).to start_with("hello")
expect(hash).to have_key(:name)
expect { x += 1 }.to change { x }.by(1)
expect { x += 1 }.to change { x }.from(0).to(1)
expect { user.save }.to change(User, :count).by(1)
expect { raise "boom" }.to raise_error
expect { raise ArgumentError, "bad" }.to raise_error(ArgumentError, /bad/)
expect([]).to be_empty # [].empty?
expect(user).to be_valid # user.valid?
expect(hash).to have_key(k) # hash.has_key?(k)
# Basic double (strict)
user = double("user", name: "Bob")
# Verifying doubles (recommended)
user = instance_double("User", name: "Bob") # validates instance methods
api = class_double("Api", fetch: data) # validates class methods
logger = object_double(Rails.logger) # validates object methods
# Spy (null object for after-the-fact verification)
notifier = spy("notifier")
allow(user).to receive(:name).and_return("Bob")
allow(Api).to receive(:fetch).and_return(data)
allow(obj).to receive(:method) { computed_value }
expect(user).to receive(:save).and_return(true)
expect(Api).to receive(:post).with(hash_including(id: 1))
# Spy pattern (verify after action)
notifier = spy("notifier")
service.call(notifier)
expect(notifier).to have_received(:notify).with("done")
expect(obj).to receive(:call).with(anything)
expect(obj).to receive(:call).with(kind_of(Integer))
expect(obj).to receive(:call).with(hash_including(a: 1))
expect(obj).to receive(:call).with(array_including(1, 2))
| Spec Type | Use For | Key Helpers |
|---|---|---|
type: :model | Business logic, scopes, validations | build, create, associations |
type: :request | Controller actions (preferred) | get, post, response, have_http_status |
type: :system | Browser/UI testing | visit, fill_in, click_button, have_text |
type: :job | Background jobs | have_enqueued_job, perform_now |
type: :mailer | Email delivery | have_enqueued_mail, deliver_now |
type: :routing | Route resolution | route_to, be_routable |
See examples/rails/ for complete spec templates.
described_class instead of hardcoding class namelet for test data, let! when database records must exist before testsubject(:user) { ... }instance_double) over plain doubleit "creates user" not it "should create user"build_stubbed or build over create when database not needed@user) - use let for type safetybefore just to trigger let evaluation - use let! instead:
# BAD - before just to initialize
let(:user) { create(:user) }
before { user }
# GOOD - let! for eager evaluation
let!(:user) { create(:user) }
Use before for side-effects like sign_in(user) or driven_by(:rack_test)let! when let suffices (wastes resources)any_instance_of - prefer stubbing ClassName.new to return a double (see references/mocks.md)receive_message_chain (violates Law of Demeter)# Build strategies
user = build(:user) # In-memory, not persisted
user = create(:user) # Persisted to database
user = build_stubbed(:user) # Fake persisted (fastest)
attrs = attributes_for(:user) # Hash of attributes
# With traits and attributes
user = create(:user, :admin, :verified, name: "Bob")
# Lists
users = create_list(:user, 5, :admin)
Strategy Selection:
build_stubbed - Unit tests without database (fastest)build - Validation tests, method testscreate - Database queries, scopes, associationsattributes_for - Controller paramsSee references/factory_bot.md for traits, sequences, associations, and callbacks.
Essential settings for spec_helper.rb and rails_helper.rb:
| Setting | Purpose |
|---|---|
verify_partial_doubles = true | Validates stubbed methods exist |
filter_run_when_matching :focus | Run only focused specs (fit, fdescribe) |
order = :random | Randomize spec order to catch dependencies |
use_transactional_fixtures = true | Rollback database after each spec |
infer_spec_type_from_file_location! | Auto-detect spec type from path |
See examples/core/configuration.rb for complete setup.
For detailed patterns and complete API references, consult:
references/core.md - describe, it, hooks, let/subject, shared examples, anti-patternsreferences/factory_bot.md - Build strategies, traits, sequences, associations, callbacksreferences/matchers.md - All built-in matchers, composing matchers, custom matchersreferences/mocks.md - Test doubles, stubbing, spies, argument matchersreferences/rails.md - All Rails spec types, Rails matchers, request/system specsReady-to-use code patterns in examples/:
examples/core/ - Basic structure, hooks, let/subject, shared examples, configurationexamples/matchers/ - Equality, collections, change, errors, predicates, custom matchersexamples/mocks/ - Doubles, stubs, spies, argument matchers, any_instance, constantsexamples/rails/ - Model, request, controller, system, job, mailer, routing specsexamples/factory_bot/ - Build strategies, traits, associations, callbacks, transientsrspec # all specs
rspec spec/models # directory
rspec spec/user_spec.rb # file
rspec spec/user_spec.rb:23 # line
rspec --format doc # documentation format
rspec --only-failures # re-run failures
rspec --profile 10 # show slowest
rspec --seed 12345 # reproduce random order
rspec --fail-fast # stop on first failure
rspec --backtrace # full backtrace
Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing applications for better maintainability.