Skill v1.0.1

currentLLM-judged scan100/100

dgalarza/claude-code-workflows/rspec-testing

4 files

──Details

PublishedJune 26, 2026 at 04:44 AM

Content Hashsha256:cc42bdb552784c48...

Git SHA93cd3161891e

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 13.5 KB)

SKILL.md13.5 KBactive

SKILL.md · 574 lines · 13.5 KB

version: "1.0.1" name: rspec-testing description: This skill should be used when writing, reviewing, or improving RSpec tests for Ruby on Rails applications. Use this skill for all testing tasks including model specs, controller specs, system specs, component specs, service specs, and integration tests. The skill provides comprehensive RSpec best practices from Better Specs and thoughtbot guides.

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:

ruby

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:

ruby

# 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:

ruby

# 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:

ruby

# 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:

ruby

# 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

ruby

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

Context Blocks

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

ruby

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

ruby

# ✅ 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):

ruby

# ✅ 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:

ruby

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:

ruby

# 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:

ruby

# ✅ 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:

ruby

# ✅ 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')
expect(page).to have_css('.bg-red-500')
expect(page).to have_css('.rounded-lg')

Factory Patterns

Organization

Associations (implicit) first
Attributes (alphabetical)
Traits (alphabetical)

ruby

FactoryBot.define do
  factory :article do
    # Associations
    user
    category
 
    # Attributes (alphabetical)
    body { 'Article content goes here...' }
    published_at { Time.current }
    status { :draft }
    title { 'Sample Article Title' }
 
    # Traits (alphabetical)
    trait :published do
      status { :published }
      published_at { 1.day.ago }
    end
 
    trait :with_tags do
      after(:create) do |article|
        create_list(:tag, 3, article: article)
      end
    end
  end
end

Prefer Build Over Create

Use build and build_stubbed when database persistence isn't needed:

ruby

# ✅ Good - fast, no database hit
it 'validates title format' do
  article = build(:article, title: '')
  expect(article).not_to be_valid
end
 
# Less optimal - unnecessary database hit
it 'validates title format' do
  article = create(:article, title: '')
  expect(article).not_to be_valid
end

Common Testing Patterns

Testing Validations

ruby

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
 
  it 'validates length of title' do
    article = build(:article, title: 'a' * 256)
    expect(article).not_to be_valid
  end
 
  it 'allows valid titles' do
    article = build(:article, title: 'Valid Title')
    expect(article).to be_valid
  end
end

Testing Enums

ruby

describe 'enums' do
  it 'defines status enum' do
    expect(described_class.statuses).to eq({
      'draft' => 'draft',
      'published' => 'published',
      'archived' => 'archived'
    })
  end
 
  it 'has correct default' do
    article = described_class.new
    expect(article.status).to eq('draft')
  end
end

Testing Authorization

ruby

context 'when user is not admin' do
  it 'raises authorization error' do
    user = create(:user, role: :member)
    session[:user_id] = user.id
 
    expect do
      get :admin_dashboard
    end.to raise_error(Pundit::NotAuthorizedError)
  end
end

Using Shoulda Matchers

ruby

describe 'associations' do
  it { is_expected.to belong_to(:user) }
  it { is_expected.to have_many(:comments) }
end
 
describe 'validations' do
  it { is_expected.to validate_presence_of(:title) }
  it { is_expected.to validate_length_of(:title).is_at_most(255) }
end

What to Avoid

❌ Don't Stub the System Under Test

Never mock or stub methods on the class being tested:

ruby

# ❌ Bad
it 'processes payment' do
  order = Order.new
  allow(order).to receive(:calculate_total).and_return(100)
  expect(order.process_payment).to be true
end
 
# ✅ Good
it 'processes payment' do
  order = Order.new(line_items: [line_item])
  expect(order.process_payment).to be true
end

❌ Don't Test Private Methods

Test the public interface. Private methods are tested indirectly:

ruby

# ❌ Bad
describe '#calculate_total (private)' do
  it 'sums line items' do
    order.send(:calculate_total)
  end
end
 
# ✅ Good
describe '#total' do
  it 'returns sum of line items' do
    expect(order.total).to eq(100)
  end
end

❌ Avoid `any_instance_of`

Use dependency injection instead:

ruby

# ❌ Bad
allow_any_instance_of(PaymentService).to receive(:charge)
 
# ✅ Good
payment_service = instance_double(PaymentService)
allow(payment_service).to receive(:charge).and_return(success)
order = Order.new(payment_service: payment_service)

Quick Reference

Test Organization

ruby

RSpec.describe ClassName do
  # Setup (let, before)
  let(:resource) { create(:resource) }
 
  before do
    # common setup
  end
 
  # Validations
  describe 'validations' do
  end
 
  # Associations
  describe 'associations' do
  end
 
  # Class methods
  describe '.class_method' do
  end
 
  # Instance methods
  describe '#instance_method' do
    context 'when condition' do
      it 'does something' do
      end
    end
  end
end

Expectation Matchers

ruby

# Equality
expect(value).to eq(expected)
expect(value).to be(expected)           # same object
expect(value).to match(/regex/)
 
# Predicates
expect(object).to be_valid
expect(object).to be_persisted
expect(collection).to be_empty
 
# Collections
expect(array).to include(item)
expect(array).to contain_exactly(1, 2, 3)
expect(hash).to have_key(:name)
 
# Changes
expect { action }.to change(Model, :count).by(1)
expect { action }.to change { object.attribute }.from(old).to(new)
 
# Errors
expect { action }.to raise_error(ErrorClass)
expect { action }.not_to raise_error

Resources

This skill includes detailed reference documentation in the references/ directory:

`references/better_specs_guide.md`

Comprehensive patterns from Better Specs including:

Describe/context/it block conventions
Subject and let usage
Mocking strategies
Shared examples
Factory patterns

`references/thoughtbot_patterns.md`

thoughtbot's RSpec best practices covering:

Modern RSpec syntax
Test structure and organization
What to avoid in tests
Capybara patterns for system tests
Factory organization

Load these references when you need detailed examples or are unsure about a specific pattern.

← v1.0.0 All versions

Skill v1.0.1

RSpec Testing for Rails

Overview

Core Testing Principles

1. Test-Driven Development (TDD)

2. Test Structure (Arrange-Act-Assert)

3. Single Responsibility

4. Test Real Behavior

Test Type Decision Tree

When to Write Model Specs

When to Write Controller Specs

When to Write System Specs

When to Write Component Specs

When to Write Service/Integration Specs

RSpec Syntax & Style Guide

Describe Blocks

Context Blocks

It Blocks

Expectations

One-Liners

System Test Best Practices

Authentication in System Tests

Controller Test Authentication

Avoid CSS Class Testing

Factory Patterns

Organization

Prefer Build Over Create

Common Testing Patterns

Testing Validations

Testing Enums

Testing Authorization

Using Shoulda Matchers

What to Avoid

❌ Don't Stub the System Under Test

❌ Don't Test Private Methods

❌ Avoid any_instance_of

Quick Reference

Test Organization

Expectation Matchers

Resources

references/better_specs_guide.md

references/thoughtbot_patterns.md

❌ Avoid `any_instance_of`

`references/better_specs_guide.md`

`references/thoughtbot_patterns.md`