How to DRY out your RSpec Tests using Shared Examples

As a full-stack developer, I‘ve come to appreciate the vital role that testing plays in building robust, maintainable applications. Automated tests give us the confidence to refactor and extend our code, knowing that if we break something, our tests will catch it.

However, as our application grows, so does our test suite. And if we‘re not careful, our tests can become as complex and unwieldy as the code they‘re testing. One of the biggest challenges is managing duplication in our tests.

The Problem with Duplicated Tests

Consider this statistic: in a survey of over 500 developers, 67% reported that more than half of their test code was duplicated across multiple tests (source). This duplication makes our test suite harder to maintain and understand.

When we have duplicated test setup, assertions, or teardown across multiple tests, any change to the tested behavior requires updating multiple tests. This not only takes more time, but also increases the risk of introducing bugs by forgetting to update a test.

Moreover, duplicated tests make it harder to see the unique behavior each test is covering. When multiple tests share the same setup and assertions, it‘s not immediately clear what each test is uniquely responsible for testing.

Enter Shared Examples

Luckily, RSpec provides a solution to this problem in the form of shared examples. Shared examples allow us to encapsulate common test behavior into reusable components that can be included in multiple tests.

Here‘s a simple example:

RSpec.shared_examples "a serializable model" do
  it "can be serialized to JSON" do
    expect(subject.to_json).to be_a(String)      
  end

  it "can be deserialized from JSON" do
    json = subject.to_json
    deserialized = JSON.parse(json, object_class: described_class) 
    expect(deserialized).to eq(subject)
  end
end

describe User do
  it_behaves_like "a serializable model" 
end

describe Product do
  it_behaves_like "a serializable model"
end

In this example, we define a shared example group for testing that a model can be serialized to and deserialized from JSON. Any model spec can include these shared examples, DRYing up the tests and making the serialization behavior explicit.

A More Complex Example

Let‘s look at a more involved example. Suppose we‘re testing a Searchable concern that adds search functionality to a model. Here‘s what the tests might initially look like:

describe User do
  describe ".search" do
    let!(:john) { create(:user, name: "John") }
    let!(:jane) { create(:user, name: "Jane") }

    it "returns users matching the search term" do
      expect(User.search("John")).to eq([john])
    end

    it "returns case-insensitive results" do
      expect(User.search("john")).to eq([john]) 
    end

    it "returns an empty array when no matches" do
      expect(User.search("Bob")).to eq([])
    end
  end
end

describe Product do
  describe ".search" do  
    let!(:widget) { create(:product, name: "Widget") }
    let!(:gizmo) { create(:product, name: "Gizmo") }

    it "returns products matching the search term" do
      expect(Product.search("Widget")).to eq([widget])
    end

    it "returns case-insensitive results" do 
      expect(Product.search("widget")).to eq([widget])
    end

    it "returns an empty array when no matches" do
      expect(Product.search("Thingamajig")).to eq([]) 
    end
  end
end

While these tests cover the behavior of the search method well, they are almost entirely duplicated. Let‘s refactor using shared examples:

RSpec.shared_examples "a searchable model" do |factory, attribute|
  let!(:record1) { create(factory, attribute => "Target") }    
  let!(:record2) { create(factory, attribute => "Other") }

  describe ".search" do
    it "returns records matching the search term" do
      expect(described_class.search("Target")).to eq([record1]) 
    end

    it "returns case-insensitive results" do
      expect(described_class.search("target")).to eq([record1])
    end

    it "returns an empty array when no matches" do
      expect(described_class.search("Missing")).to eq([])
    end
  end
end

describe User do
  it_behaves_like "a searchable model", :user, :name
end

describe Product do
  it_behaves_like "a searchable model", :product, :name  
end

The shared examples encapsulate the common behavior of the search method. The examples use the factory and attribute parameters to set up test data specific to each model. The described_class method allows the examples to refer to the model class being tested.

Each model spec then includes the shared examples, passing the appropriate factory and attribute for that model.

The Benefits of DRY Tests

By extracting common test behavior into shared examples, we‘ve made our test suite more maintainable and expressive. If we need to change how search works, we only need to update the shared examples in one place.

Moreover, the shared examples make the behavior of the search method explicit. Any model that includes the "a searchable model" examples is expected to behave in the same way. This makes the tests serve as a form of living documentation for the system.

DRY tests also tend to be more readable and focused. By extracting setup and common assertions into shared examples, each individual test can focus on a single, specific behavior. This makes it easier to understand what each test is responsible for.

Pitfalls to Avoid

While shared examples are a powerful tool, it‘s possible to over-use them. Shared examples are most effective when they capture truly common behavior. If you find yourself passing many parameters to a shared example, or if the setup in the shared example is very complex, it might be a sign that the behavior is not truly shared.

In these cases, it‘s often better to have some duplication in your tests rather than over-complicated shared examples. The goal is to strike a balance between DRY tests and tests that are easy to understand and modify.

Another risk with shared examples is that they can make your tests more coupled. If many tests rely on the same shared examples, changes to those shared examples can potentially break many tests. Therefore, it‘s important to keep shared examples focused and stable.

Shared Examples and BDD

Shared examples are particularly useful in a Behavior-Driven Development (BDD) context. In BDD, we focus on specifying the behavior of the system in a way that is meaningful to stakeholders. Shared examples allow us to express these common behaviors in a reusable way.

For instance, consider this feature specification:

Feature: Search
  Scenario: Search finds matching records
    Given there are records in the system
    When I search for a term
    Then I should see the records that match that term

  Scenario: Search is case-insensitive 
    Given there are records in the system
    When I search for a term in a different case
    Then I should still see the matching records

  Scenario: Search handles no matches gracefully
    Given there are records in the system  
    When I search for a term that doesn‘t match anything
    Then I should see an empty result set

These scenarios could map directly to a "a searchable model" shared example. The shared example encapsulates the common behavior, while the specific contexts (models) provide the concrete implementation.

Conclusion

Shared examples are a powerful tool for DRYing up your RSpec tests. By extracting common test behavior, they make your test suite more maintainable, understandable, and expressive.

However, it‘s important to use shared examples judiciously. Overusing shared examples can lead to tests that are hard to understand and modify. The key is to find the right balance for your project and team.

As with any testing strategy, the goal of shared examples is to increase your confidence in your code while keeping your test suite manageable. By thoughtfully applying shared examples, you can achieve both of these goals, leading to a more robust and maintainable system overall.

Resources

Here are some additional resources to learn more about RSpec and testing best practices:

• RSpec Documentation – The official documentation for RSpec, including detailed guides on shared examples.
• Better Specs – A collection of best practices for writing effective and maintainable RSpec tests.
• Effective Testing with RSpec 3 – A comprehensive book on using RSpec for BDD-style testing, including advice on structuring tests and using shared examples effectively.
• The RSpec Style Guide – A community-driven style guide for RSpec, with recommendations for naming, structure, and usage of features like shared examples.

By continually learning and applying best practices, you can keep your test suite lean, effective, and a joy to work with. Happy testing!