Getting your Trinity Audio player ready...

For Ruby developers, RSpec is more than just a testing framework; it’s a way to describe the behaviour of our applications with clarity and precision. Well-written tests not only ensure our code works as expected but also serve as living documentation. However, as test suites grow, they can become slow, brittle, and hard to understand if not crafted with care. Without a disciplined approach, a test suite that was once a safety net can quickly devolve into a source of frustration. This technical debt slows down development and ultimately erodes confidence in the codebase.

Yet, this decay from a helpful guide into a maintenance nightmare is not inevitable. It’s a sign that our tests themselves require the same level of design and care as the code they verify.

This is where adopting best practices becomes crucial. Let’s explore how to write RSpecs that are clean, readable, and genuinely “nice” to work with, transforming your test suite into a powerful asset.

Why Focus on Clean RSpecs?

Before diving into the “how,” let’s touch upon the “why”:

• Readability: Tests should clearly communicate what is being tested and what the expected outcome is.
• Maintainability: As your application evolves, tests will need updates. Clean tests are easier and faster to modify.
• Reliability: Well-structured tests are less prone to flakiness and provide more trustworthy feedback.
• Debugging Speed: When a test fails, a clear message and focused scope make it easier to pinpoint the issue in the application code.
• Documentation: Your spec suite can be the best form of documentation for your application’s behaviour.

Core Principles for Nicer RSpecs

Let’s break down some key principles and techniques.

1. Structure with describe and context

Clarity starts with organization. describe and context are your primary tools for structuring your specs logically.

• describe for Classes/Methods: Use describe to group tests for a specific class, module, or a public method.

# Good: Describing a class
RSpec.describe User do
  # ...
end

# Good: Describing a public method
RSpec.describe Calculator do
  describe '#add' do
    # ...
  end
end

• context (or when/with) for Scenarios/States: Use context (or its aliases when or with) to delineate different scenarios, conditions, or states within a describe block. This makes it easier to understand the specific situation a group of examples is testing.

RSpec.describe AuthenticationService do
  describe '#authenticate' do
    context 'with valid credentials' do
      it 'returns a user token' do
        # ...
      end
    end

    context 'with invalid credentials' do
      it 'returns nil' do
        # ...
      end
    end

    context 'when the user account is locked' do
      it 'raises an AccountLockedError' do
        # ...
      end
    end
  end
end

• A good rule of thumb is that the string for context should often complete a sentence started by the describe string, providing a narrative flow.

2. Embrace let and subject for Setup

Avoid instance variables (@user = ...) for test setup. let and subject provide memoization and lazy loading, leading to cleaner and more efficient specs.

• let() for Test Data: Use let to define test data or helper objects. It’s lazily evaluated and memoized within the scope of an example.

RSpec.describe Post do
  describe '#publish!' do
    let(:author) { User.create(name: 'Jane Doe', role: 'author') }
    let(:post) { Post.new(title: 'My Great Post', author: author, published_at: nil) }

    it 'sets the published_at timestamp' do
      post.publish!
      expect(post.published_at).not_to be_nil
    end
  end
end

• subject for the Object Under Test: subject (and its named variant subject(:name)) clearly defines the primary object being tested in the current scope. RSpec matchers like is_expected.to work directly with subject.

RSpec.describe Article do
  subject(:published_article) { described_class.new(status: 'published') } # `described_class` refers to Article

  describe '#published?' do
    context 'when status is "published"' do
      it 'is true' do # Implicit subject
        expect(subject.published?).to be true
      end
      # Or using is_expected (works on the implicit subject)
      # it { is_expected.to be_published } # if you define `be_published` custom matcher or it's attribute
    end

    context 'when status is "draft"' do
      subject(:draft_article) { described_class.new(status: 'draft') }
      it 'is false' do
        expect(draft_article.published?).to be false
      end
    end
  end
end

3. One Expectation Per Example (Mostly)

While not a rigid rule, striving for one logical assertion per it block often leads to more focused tests and clearer failure messages. When a test with multiple assertions fails, it’s harder to tell which one caused the problem without careful inspection.

# Less Ideal: Multiple assertions, unclear failure focus
RSpec.describe OrderProcessor do
  let(:order) { Order.new(status: 'pending', item_count: 1) }
  subject(:processor) { described_class.new(order) }

  it 'processes the order correctly' do
    processor.process!
    expect(order.status).to eq('completed')
    expect(order.processed_at).not_to be_nil
    expect(NotificationService).to have_received(:notify_customer).with(order.customer_id) # assuming a spy
  end
end

# Better: Focused examples
RSpec.describe OrderProcessor do
  let(:order) { Order.new(status: 'pending', item_count: 1, customer_id: 123) }
  subject(:processor) { described_class.new(order) }
  before { allow(NotificationService).to receive(:notify_customer) } # setup spy

  context 'after processing' do
    before { processor.process! }

    it 'updates the order status to completed' do
      expect(order.status).to eq('completed')
    end

    it 'sets the processed_at timestamp' do
      expect(order.processed_at).not_to be_nil
    end

    it 'notifies the customer' do
      expect(NotificationService).to have_received(:notify_customer).with(order.customer_id)
    end
  end
end

Sometimes, multiple expectations are acceptable if they cohesively test a single logical concept (e.g., asserting several attributes of a newly created object). The key is to use your judgment to maintain clarity.

4. Descriptive it Block Messages

The string you pass to it should clearly describe the behavior being tested. It should read like a specification.

• Avoid “should”: RSpec does this implicitly.
• Focus on behaviour/outcome:

# Less Ideal
it 'should be valid'
it 'validates name'

# Better
it 'is valid with a name and email'
it 'is invalid without a name'
it 'returns true if the user is an admin'
it 'correctly calculates the total price including tax'

5. Write Readable Expectations

Choose matchers that make your expectations read like plain English.

• Predicate Matchers: For methods ending in ? (e.g., empty?, valid?), use be_ or have_ matchers.

expect([]).to be_empty
expect(user).to be_valid
expect(cart).to have_items # if cart.has_items? exists

• Use Specific Matchers: RSpec offers a rich set of matchers. Prefer them over generic eq true/false.

# Less Ideal
expect(user.errors.empty?).to eq(true)
expect(array.include?(item)).to eq(true)

# Better
expect(user.errors).to be_empty
expect(array).to include(item)
expect { dangerous_operation }.to raise_error(SpecificError)
expect(service_call).to change(User, :count).by(1)

6. Test Behaviour, Not Implementation

Focus your tests on the public interface and the observable behaviour of your objects, not their internal implementation details. Testing private methods or internal state directly makes tests brittle; they break when you refactor internals, even if the public behaviour remains unchanged.

7. Keep it DRY with Shared Examples and Contexts

For behaviour that’s shared across multiple describe or context blocks, use shared_examples, shared_context, or include_examples.

# spec/support/shared_examples/publishable.rb
RSpec.shared_examples 'a publishable object' do
  it 'can be published' do
    subject.publish!
    expect(subject).to be_published
  end

  it 'can be unpublished' do
    subject.unpublish!
    expect(subject).not_to be_published
  end
end

# spec/models/article_spec.rb
RSpec.describe Article do
  subject(:article) { described_class.new }
  it_behaves_like 'a publishable object'
end

# spec/models/post_spec.rb
RSpec.describe Post do
  subject(:post) { described_class.new }
  it_behaves_like 'a publishable object'
end

When a test fails, the message should immediately tell you what went wrong. Using specific matchers and well-structured context blocks contributes significantly to this. If default messages aren’t enough, you can provide custom failure messages to your expectations.

Conclusion

Writing clean, readable, and maintainable RSpecs is an investment that pays off manifold. It makes your development process more efficient, your codebase more robust, and collaboration more enjoyable. By embracing these principles and thinking critically about your test structure, you can significantly elevate the quality of your test suite.

Happy RSpec-ing!

References:

1. RSpec Official Website
2. RSpec Core Documentation
3. RSpec Expectations Documentation
4. The RSpec Style Guide (Community)

Explore more articles and insights on software engineering and technology on the Rently Engineering Blog: https://engineering.rently.com/