Rails TDD Standards
RSpec testing standards and best practices for Rails applications. Use when writing new tests, reviewing test quality, debugging factory errors, setting up FactoryBot, or enforcing single-expectation patterns. Also use when a test fails due to factory misconfiguration, wrong association keys, or missing role traits. Triggers on phrases like "write a test", "add specs", "factory error", "test is failing", "how should I test this", or when reviewing test code in a Rails project.
Rails TDD Standards
Best practices for writing clean, reliable RSpec tests in Rails applications.
Core Principle: Single Expectation
One assertion per test. Tests should read like specifications — each it block verifies exactly one thing.
# ✅ Correct
it { is_expected.to validate_presence_of(:email) }
it { is_expected.to belong_to(:user) }
# ❌ Wrong — too many expectations in one test
it "validates the user" do
expect(user).to validate_presence_of(:email)
expect(user).to validate_presence_of(:name)
expect(user).to be_valid
end
FactoryBot Patterns
Always use role traits
# ✅ Correct
create(:user, :admin)
create(:user, :member)
create(:user, :guest)
# ❌ Wrong — missing role context
create(:user)
Association keys matter
Check your factory definitions carefully. Wrong keys cause silent failures.
# ✅ Example — if your factory uses owner:
create(:profile, owner: user)
# ❌ Wrong key
create(:profile, user: user) # fails if factory expects owner:
Always set required associations
When a model requires a specific association to be valid, always set it explicitly — don't rely on factory defaults when they might be nil or wrong.
# ✅ Explicit — clear intent, no surprises
let(:record) do
create(:model, required_association: other_record)
end
# ❌ Implicit — may break if factory default changes
let(:record) { create(:model) }
Use described_class not hardcoded class names
# ✅
subject { described_class.new(params) }
# ❌
subject { MyService.new(params) }
Common FactoryBot Gotchas
Join tables without primary key
Tables with id: false can't use .last or .first.
# ✅ Use a scoped query
record = JoinModel.find_by(field_a: a, field_b: b)
# ❌ Will raise ActiveRecord::MissingRequiredOrderError
record = JoinModel.last
RecordInvalid from missing role/trait
If you see Validation failed: X must have Y role — you're missing a trait on the user factory.
# ✅
user = create(:user, :editor)
# ❌ causes "must be an editor" validation error
user = create(:user)
Spec Structure
RSpec.describe MyClass do
# Subject
subject(:instance) { described_class.new(params) }
# Shared setup
let(:user) { create(:user, :admin) }
# Group by behavior
describe "#method_name" do
context "when condition is true" do
it "does the expected thing" do
expect(instance.method_name).to eq(expected)
end
end
context "when condition is false" do
it "does something else" do
expect(instance.method_name).to be_nil
end
end
end
end
Mocking & Stubbing
# Stub a method
allow(object).to receive(:method_name).and_return(value)
# Stub and verify it was called
expect(object).to receive(:method_name).once
# Stub HTTP calls (WebMock)
stub_request(:post, "https://api.example.com/endpoint")
.to_return(status: 200, body: { result: "ok" }.to_json)
# Allow localhost for system tests (if using WebMock)
WebMock.disable_net_connect!(allow_localhost: true)
Service Object Testing
RSpec.describe MyService do
describe "#call" do
context "with valid params" do
it "returns the expected result" do
result = described_class.new(valid_params).call
expect(result).to be_a(ExpectedClass)
end
it "creates the expected record" do
expect { described_class.new(valid_params).call }
.to change(Record, :count).by(1)
end
end
context "with invalid params" do
it "returns false" do
expect(described_class.new(invalid_params).call).to be(false)
end
end
end
end
Rails 8 Spec Compatibility
Rails 8 changed two controller-side APIs that specs interact with - strong
parameters and CSRF behavior. What changed, and how to spec it, is in
references/rails-8-controller-gotchas.md.
CI Database Setup
Critical: Never use db:prepare in CI. It runs seeds, which pollutes the test database and causes scoped queries to return unexpected results.
# ✅ CI config (GitHub Actions / etc.)
- run: bundle exec rails db:schema:load RAILS_ENV=test
# ❌ Runs seeds → pollutes test DB → scope specs fail
- run: bundle exec rails db:prepare RAILS_ENV=test
If you see scope specs randomly returning too many records, check your CI DB setup first. Seeds belong in development, not the test environment.
Callback Testing: before_create vs before_validation
before_create callbacks are skipped by FactoryBot's build(). If your callback needs to fire during build (e.g., for token generation, slug assignment), use before_validation on: :create instead.
# ✅ Works with both build() and create()
before_validation :generate_token, on: :create
# ❌ Skipped by build() — token will be nil in specs using build
before_create :generate_token
This is especially important for:
- Token generation (API keys, one-time tokens)
- Slug generation
- Setting default values that specs need to assert on
- Any callback you expect to fire when using
build(:model)
Token Authentication Testing
Never test for raw token values — tokens should be hashed on save. Test that:
- A digest was stored (not nil)
- The
authenticate/find_by_tokenmethod works correctly
RSpec.describe ApiToken do
describe "token generation" do
it "stores a hashed digest, not the raw token" do
token = build(:api_token)
token.save!
expect(token.token_digest).to be_present
end
it "authenticates with the raw token" do
token = ApiToken.new(name: "test")
token.save!
raw = token.raw_token # capture from one-time return before it's gone
expect(ApiToken.authenticate(raw)).to eq(token)
end
end
end
For request specs, generate the token in a let block and inject it as a header:
let(:user) { create(:user) }
let(:raw_token) do
t = user.api_tokens.build(name: "test")
t.save!
t.raw_token
end
before { get "/api/v1/resources", headers: { "Authorization" => "Bearer #{raw_token}" } }
The
raw_tokenmethod name is implementation-specific — adjust to match whatever your model exposes after save.
ActionCable Channel Testing
Use stub_connection to inject the authenticated user into the channel connection.
RSpec.describe NotificationsChannel, type: :channel do
let(:user) { create(:user) }
before { stub_connection current_user: user }
describe "#subscribed" do
it "subscribes to the user stream" do
subscribe
expect(subscription).to be_confirmed
expect(streams).to include("notifications:user:#{user.id}")
end
end
describe "#unsubscribed" do
it "stops all streams" do
subscribe
unsubscribe
expect(streams).to be_empty
end
end
end
Test broadcast behavior with have_broadcasted_to:
it "broadcasts a notification to the user stream" do
subscribe
expect {
NotificationsChannel.broadcast_to(user, { type: "alert", message: "You have a new message" })
}.to have_broadcasted_to(user).with(hash_including(type: "alert"))
end
External Service Stubs
Always stub external services in unit and integration specs. Never make real API calls in tests.
Geocoder
# In spec_helper or a shared context
before do
allow(Geocoder).to receive(:search).and_return(
[double(coordinates: [40.7128, -74.0060], city: "New York", state: "NY")]
)
end
Stripe
# Stub a PaymentIntent creation
before do
allow(Stripe::PaymentIntent).to receive(:create).and_return(
double(id: "pi_test_123", status: "requires_capture", client_secret: "secret_abc")
)
end
# For HTTP-level stubs (WebMock)
stub_request(:post, "https://api.stripe.com/v1/payment_intents")
.to_return(status: 200, body: { id: "pi_test_123", status: "requires_capture" }.to_json)
General pattern
Any service that hits the network should be stubbed. If you find yourself relying on VCR cassettes for unit tests, consider switching to explicit doubles — they're faster and don't require recorded responses.
Serializer Testing
Test serializers directly — don't test through controllers. Assert on the JSON output structure.
RSpec.describe ArticleSerializer do
let(:article) { create(:article, :published) }
subject(:json) { described_class.new(article).as_json }
it "includes expected public keys" do
expect(json.keys).to include(:id, :title, :body, :published_at)
end
it "excludes sensitive internal fields" do
expect(json.keys).not_to include(:internal_cost_cents, :vendor_id)
end
context "with an admin scope" do
subject(:json) { described_class.new(article, scope: { role: :admin }).as_json }
it "includes admin-only fields" do
expect(json.keys).to include(:cost_breakdown, :vendor_id)
end
end
end
Running Tests
# Run full suite
bundle exec rspec
# Run specific file
bundle exec rspec spec/models/user_spec.rb
# Run specific line
bundle exec rspec spec/models/user_spec.rb:42
# Run only failures from last run
bundle exec rspec --only-failures
# Run with documentation format
bundle exec rspec --format documentation
Browser & System Spec Testing
System spec references are split by topic so you load only what you need:
references/driver-setup.md- Capybara + Selenium driver configurationreferences/browser-divergence.md- why the same spec passes locally and fails in CI, including a spec that overrides the driverreferences/devise-and-mailers.md- Devise vs Warden sign-in, background mail delivery in specsreferences/turbo-and-stimulus.md- Turbo Stream and Frame semantics, Stimulus controllers, importmapreferences/stale-content-and-waiting.md- stale page content, frame timing conflicts, correct waitingreferences/failure-lookup.md- symptom-to-cause lookup tablereferences/rails-8-controller-gotchas.md- Rails 8 parameter and CSRF spec compatibility
The four that cause the most time loss:
A failure that reproduces on every run is not a flake. Classify before assuming randomness. Browser differences (Firefox vs Chrome, headless viewport height, driver version) produce deterministic failures that get mislabeled as flakes.
sign_in is not login_as. In a Devise app use Devise's sign_in; Warden's
login_as does not create a Devise session and current_user comes back nil with
no obvious cause. In request specs, include
Devise::Test::IntegrationHelpers, type: :request or sign_in is undefined.
deliver_later does not deliver in the test environment. The default :test
adapter only records the job. Assert with have_enqueued_job, or use
perform_enqueued_jobs { ... } / queue_adapter = :inline to also assert delivery.
turbo_stream.replace destroys its target. A replaced element's Stimulus
controller is torn down and re-initialized, losing state. Use update for a
targeted swap, append to preserve the controller.
Browser-Dependent CI Failures
A spec that passes locally and fails in CI is usually browser divergence, not flakiness. The usual causes, in order of frequency:
- Viewport height — headless Chrome's default window is ~683px tall. A modal taller than that reports elements as not visible even though they are in the DOM.
- Firefox vs Chrome — Firefox does not honour
no_proxyfor its own traffic, so WebDriver's localhost connection can get intercepted on a proxied machine. Setnetwork.proxy.no_proxies_onto includelocalhost,127.0.0.1. - Hardcoded browser in the spec — a spec that forces Firefox while CI runs Chrome tests a different engine than CI will.
- Version drift — driver and browser versions must match and must be pinned in CI.
# ✅ Pin the driver explicitly rather than inheriting whatever is on PATH
options.binary = "/path/to/chrome"
See references/driver-setup.md for the full driver setup.
RuboCop Gotchas in Specs
RuboCop's Style/NumericPredicate cop rewrites be.positive? to be_positive.
Applied to RSpec matchers, that produces a NoMethodError at runtime because
be_positive is not a valid predicate method — the cop does not know it is
editing a matcher.
# ✅ keep the matcher form
expect(result).to be.positive
# ❌ RuboCop's autocorrect produces this — NoMethodError
expect(result).to be_positive
Two ways to keep it fixed:
# spec/rails_helper.rb
config.before(:suite) do
# keep matcher predicates intact
end
# .rubocop.yml
Style/NumericPredicate:
AllowedMethods:
- be_positive
- be_negative
Always read the diff RuboCop produces before committing. An autocorrect that
changes be.positive? → be_positive is a runtime bug, not a style fix.
See Also
references/factory-patterns.md- advanced FactoryBot patternsreferences/driver-setup.md- Capybara / browser testing setupreferences/browser-divergence.md- local vs CI browser differencesreferences/devise-and-mailers.md- Devise sign-in and mail delivery in specsreferences/turbo-and-stimulus.md- Turbo and Stimulus behavior in specsreferences/stale-content-and-waiting.md- stale content and waitingreferences/failure-lookup.md- symptom-to-cause lookup table
Related skills
- Downloads
- 1.2kAll time
- Security audit
- Pass
- Last updated
- 3d ago
- Current version
- v1.1.6
- License
- MIT-0
