RSpec Testing for Rails

Overview

Write comprehensive, maintainable RSpec tests following industry best practices. This skill combines guidance from Better Specs and thoughtbot's testing guides to produce high-quality test coverage for Rails applications.

Core Testing Principles

1. Test-Driven Development (TDD)

Follow the Red-Green-Refactor cycle:

• Red: Write failing tests that define expected behavior
• Green: Implement minimal code to make tests pass
• Refactor: Improve code while tests continue to pass

2. Test Structure (Arrange-Act-Assert)

Organize tests with clear phases separated by newlines:

it 'creates a new article' do
  # Arrange - set up test data
  user = create(:user)
  attributes = {title: 'Test Article', body: 'Content here'}

  # Act - perform the action
  article = Article.create(attributes)

  # Assert - verify the outcome
  expect(article).to be_persisted
  expect(article.title).to eq('Test Article')
end

3. Single Responsibility

Each test should verify one behavior. For unit tests, use one expectation per test. For integration tests, multiple expectations are acceptable when testing a complete flow.

4. Test Real Behavior

Avoid over-mocking. Test actual application behavior when possible. Only stub external services, slow operations, and dependencies outside your control.

Test Type Decision Tree

When to Write Model Specs

Use model specs (spec/models/) for:

• Validations
• Associations
• Scopes
• Instance methods
• Class methods
• Enums and constants
• Database constraints

Example:

# spec/models/article_spec.rb
RSpec.describe Article do
  describe 'validations' do
    it 'validates presence of title' do
      article = build(:article, title: nil)
      expect(article).not_to be_valid
      expect(article.errors[:title]).to include("can't be blank")
    end
  end

  describe 'associations' do
    it { is_expected.to belong_to(:user) }
    it { is_expected.to have_many(:comments) }
  end

  describe '#published?' do
    it 'returns true when status is published' do
      article = build(:article, status: :published)
      expect(article.published?).to be true
    end
  end
end

When to Write Controller Specs

Use controller specs (spec/controllers/) for:

• Authorization checks (Pundit/CanCanCan)
• Request routing and parameter handling
• Response status codes
• Instance variable assignments
• Flash messages
• Redirects

Example:

# spec/controllers/articles_controller_spec.rb
RSpec.describe ArticlesController do
  describe 'POST #create' do
    context 'with valid parameters' do
      it 'creates a new article and redirects' do
        user = create(:user)
        session[:user_id] = user.id

        valid_attributes = {
          title: 'Test Article',
          body: 'Article content'
        }

        expect do
          post :create, params: {article: valid_attributes}
        end.to change(Article, :count).by(1)

        expect(response).to redirect_to(Article.last)
      end
    end

    context 'with invalid parameters' do
      it 'does not create article and renders new template' do
        user = create(:user)
        session[:user_id] = user.id

        invalid_attributes = {title: '', body: ''}

        expect do
          post :create, params: {article: invalid_attributes}
        end.not_to change(Article, :count)

        expect(response).to render_template(:new)
      end
    end
  end
end

When to Write System Specs

Use system specs (spec/system/) for:

• End-to-end user workflows
• Multi-step interactions
• JavaScript functionality
• Form submissions
• Navigation flows
• Real user scenarios

Naming convention: user_action_spec.rb or feature_description_spec.rb

Example:

# spec/system/article_creation_spec.rb
RSpec.describe 'Article Creation' do
  it 'allows a user to create a new article' do
    user = create(:user)

    # Sign in
    visit '/login'
    fill_in 'Email', with: user.email
    fill_in 'Password', with: 'password'
    click_button 'Sign In'

    # Navigate to new article page
    click_link 'New Article'
    expect(page).to have_current_path(new_article_path)

    # Fill out the article form
    fill_in 'Title', with: 'My Test Article'
    fill_in 'Body', with: 'This is the article content'
    select 'Published', from: 'Status'

    # Submit the form
    click_button 'Create Article'

    expect(page).to have_content('Article created successfully!')
    expect(page).to have_content('My Test Article')
  end
end

When to Write Component Specs

Use component specs (spec/components/) for:

• ViewComponent rendering
• Variant behavior
• Slot functionality
• Conditional rendering
• Component attributes

Example:

# spec/components/button_component_spec.rb
RSpec.describe ButtonComponent, type: :component do
  describe 'variants' do
    it 'renders primary variant' do
      render_inline(described_class.new(variant: :primary)) { 'Click me' }

      button = page.find('button')
      expect(button[:class]).to include('btn-primary')
      expect(page).to have_button('Click me')
    end

    it 'renders secondary variant' do
      render_inline(described_class.new(variant: :secondary)) { 'Cancel' }

      button = page.find('button')
      expect(button[:class]).to include('btn-secondary')
    end
  end
end

When to Write Service/Integration Specs

Use service/integration specs (spec/services/, spec/integration/) for:

• Complex business logic
• Multi-step workflows
• External API integrations
• Background job processing
• Data transformations

RSpec Syntax & Style Guide

Describe Blocks

Use Ruby documentation conventions:

• .method_name for class methods
• #method_name for instance methods

describe '.find_by_title' do      # class method
describe '#publish' do              # instance method
describe 'validations' do           # grouping

Context Blocks

Start with "when," "with," or "without":

context 'when user is admin' do
context 'with valid parameters' do
context 'without authentication' do

It Blocks

• Keep descriptions under 40 characters
• Use third-person present tense
• Never use "should" in descriptions

# ✅ Good
it 'creates a new article' do
it 'validates presence of title' do
it 'redirects to dashboard' do

# ❌ Bad
it 'should create a new article' do
it 'should validate presence of title' do

Expectations

Always use expect syntax (never should):

# ✅ Good
expect(article).to be_valid
expect(response).to have_http_status(:success)
expect { action }.to change(Article, :count).by(1)

# ❌ Bad (deprecated)
article.should be_valid
response.should have_http_status(:success)

One-Liners

Use is_expected for concise one-line specs:

subject { article }

it { is_expected.to be_valid }
it { is_expected.to be_persisted }

System Test Best Practices

Authentication in System Tests

Test authentication flows directly without stubbing:

# Good - test the actual login flow
visit '/login'
fill_in 'Email', with: user.email
fill_in 'Password', with: 'password'
click_button 'Sign In'

expect(page).to have_content('Dashboard')

Controller Test Authentication

For controller tests, use direct session assignment rather than stubbing:

# ✅ Good - direct session assignment
session[:user_id] = user.id

# ❌ Avoid - stubbing authentication
allow_any_instance_of(Controller).to receive(:logged_in?).and_return(true)

Avoid CSS Class Testing

Don't test implementation details like CSS utility classes. Test semantic selectors and content:

# ✅ Good - semantic selectors
expect(page).to have_selector(:test_id, 'user-modal')
expect(page).to have_css("[aria-hidden='false']")
expect(page).to have_content('Success message')
expect(page).to have_button('Submit')

# ❌ Bad - coupling to CSS implementation
expect(page).to have_css('.opacity-100')