Shared examples are a good tool to describe some complex behavior and reuse it across different parts of a spec. Things get more complicated when you have the same behavior, but it has some slight variations for different contexts. In this case it’s easy to end-up having a bunch of separate one-spec behaviors instead of having some way to adjust those peculiarities in a simple way.

Example

To be more specific, let’s create a simple example. We want to describe behavior of different dogs. Every one of them can perform some common actions, but there’re also certain actions they don’t perform at all. For example, Snuff can bark and growl, but doesn’t like to jump. On the other hand, Scooby-Doo likes to jump and flee, but doesn’t growl. Scrappy-Doo is too small to bark, but he likes to growl a lot.

class Dog < Struct.new(:able_to_growl?, :able_to_bark?, :able_to_jump?, :able_to_flee?)
end
snuff = Dog.new(true, true, false, true)
scooby_doo = Dog.new(false, true, true, true)
scrappy_doo = Dog.new(true, false, true, true)

shared_examples 'a normal dog' do
  it { is_expected.to be_able_to_growl }
  it { is_expected.to be_able_to_bark }
  it { is_expected.to be_able_to_jump }
  it { is_expected.to be_able_to_flee }
end

describe 'Dogs behavior' do
  context 'Snuff' do
    subject(:snuff) { Dog.new(true, true, false, true) }
    it_behaves_like 'a normal dog'
  end

  context 'Scooby-Doo' do
    subject(:scooby_doo) { Dog.new(false, true, true, true) }
    it_behaves_like 'a normal dog'
  end

  context 'Scrappy-Doo' do
    subject(:scrappy_doo) { Dog.new(true, false, true, true) }
    it_behaves_like 'a normal dog'
  end
end

The spec looks great, but we should adjust ‘a normal dog’ behavior for each character, otherwise each context will fail due to unsupported ability.

Using params in shared_examples

Luckily, RSpec supports accepting params for shared_examples, so we can rewrite the spec like this:

shared_examples 'a normal dog' do |growl: true, bark: true, jump: true|
  it { is_expected.to be_able_to_growl } if growl
  it { is_expected.to be_able_to_bark } if bark
  it { is_expected.to be_able_to_jump } if jump
  it { is_expected.to be_able_to_flee }
end

describe 'Dogs behavior' do
  context 'Snuff' do
    subject(:snuff) { Dog.new(true, true, false, true) }
    it_behaves_like 'a normal dog', jump: false
  end

  context 'Scooby-Doo' do
    subject(:scooby_doo) { Dog.new(false, true, true, true) }
    it_behaves_like 'a normal dog', growl: false
  end

  context 'Scrappy-Doo' do
    subject(:scrappy_doo) { Dog.new(true, false, true, true) }
    it_behaves_like 'a normal dog', bark: false
  end
end

Now all specs pass successfully. We use shared_examples params to pass configuration values and adjust the way it matches. Note that this won’t work with usual let-bindings. Shared examples are created and configured at the “compile time”, while let-bindings can be used only at “run time”.

Another nice thing about shared_examples params – is that they are accessible within tests at run-time. So, for very simple specs it’s possible to use them instead of let-bound values. Here is a simple example:

shared_examples 'multiplies two numbers' do |x, y, result:|
  it 'returns correct result' do
    expect(x * y).to eq(result)
  end
end

describe 'Multiplication' do
  it_behaves_like 'multiplies two numbers', 2, 2, result: 4
  it_behaves_like 'multiplies two numbers', 3, 5, result: 15
  it_behaves_like 'multiplies two numbers', 10, 5, result: 50
end

So, instead of using 3 let-bindings for the arguments and the result, we get a very succinct way of writing simple specs.