Using shared examples

Shared examples let you describe behaviour of classes or modules. When declared, a shared group’s content is stored. It is only realized in the context of another example group, which provides any context the shared group needs to run.

A shared group is included in another group using any of:

  include_examples "name"      # include the examples in the current context
  it_behaves_like "name"       # include the examples in a nested context
  it_should_behave_like "name" # include the examples in a nested context
  matching metadata            # include the examples in the current context

WARNING: Files containing shared groups must be loaded before the files that use them. While there are conventions to handle this, RSpec does not do anything special (like autoload). Doing so would require a strict naming convention for files that would break existing suites.

WARNING: When you include parameterized examples in the current context multiple times, you may override previous method definitions and last declaration wins. So if you have this kind of shared example (or shared context)

  RSpec.shared_examples "some example" do |parameter|
    \# Same behavior is triggered also with either `def something; 'some value'; end`
    \# or `define_method(:something) { 'some value' }`
    let(:something) { parameter }
    it "uses the given parameter" do
      expect(something).to eq(parameter)
    end
  end

  RSpec.describe SomeClass do
    include_examples "some example", "parameter1"
    include_examples "some example", "parameter2"
  end

You’re actually doing this (notice that first example will fail):

  RSpec.describe SomeClass do
    \# Reordered code for better understanding of what is happening
    let(:something) { "parameter1" }
    let(:something) { "parameter2" }

    it "uses the given parameter" do
      \# This example will fail because last let "wins"
      expect(something).to eq("parameter1")
    end

    it "uses the given parameter" do
      expect(something).to eq("parameter2")
    end
  end

To prevent this kind of subtle error a warning is emitted if you declare multiple methods with the same name in the same context. Should you get this warning the simplest solution is to replace include_examples with it_behaves_like, in this way method overriding is avoided because of the nested context created by it_behaves_like

Conventions:

  1. The simplest approach is to require files with shared examples explicitly from the files that use them. Keep in mind that RSpec adds the spec directory to the LOAD_PATH, so you can say require 'shared_examples_for_widgets' to require a file at #{PROJECT_ROOT}/spec/shared_examples_for_widgets.rb.

  2. One convention is to put files containing shared examples in spec/support/ and require files in that directory from spec/spec_helper.rb:

      Dir["./spec/support/**/*.rb"].sort.each { |f| require f }

    Historically, this was included in the generated spec/spec_helper.rb file in rspec-rails. However, in order to keep your test suite boot time down, it’s a good idea to not autorequire all files in a directory like this. When running only one spec file, loading unneeded dependencies or performing unneeded setup can have a significant, noticeable effect on how long it takes before the first example runs.

  3. When all of the groups that include the shared group reside in the same file, just declare the shared group in that file.

Shared examples group included in two groups in one file

Given a file named “collection_spec.rb” with:

require "set"

RSpec.shared_examples "a collection" do
  let(:collection) { described_class.new([7, 2, 4]) }

  context "initialized with 3 items" do
    it "says it has three items" do
      expect(collection.size).to eq(3)
    end
  end

  describe "#include?" do
    context "with an item that is in the collection" do
      it "returns true" do
        expect(collection.include?(7)).to be(true)
      end
    end

    context "with an item that is not in the collection" do
      it "returns false" do
        expect(collection.include?(9)).to be(false)
      end
    end
  end
end

RSpec.describe Array do
  it_behaves_like "a collection"
end

RSpec.describe Set do
  it_behaves_like "a collection"
end

When I run rspec collection_spec.rb --format documentation

Then the examples should all pass

And the output should contain:

Array
  behaves like a collection
    initialized with 3 items
      says it has three items
    #include?
      with an item that is in the collection
        returns true
      with an item that is not in the collection
        returns false

Set
  behaves like a collection
    initialized with 3 items
      says it has three items
    #include?
      with an item that is in the collection
        returns true
      with an item that is not in the collection
        returns false

Providing context to a shared group using a block

Given a file named “sharedexamplegroup_spec.rb” with:

require "set"

RSpec.shared_examples "a collection object" do
  describe "<<" do
    it "adds objects to the end of the collection" do
      collection << 1
      collection << 2
      expect(collection.to_a).to match_array([1, 2])
    end
  end
end

RSpec.describe Array do
  it_behaves_like "a collection object" do
    let(:collection) { Array.new }
  end
end

RSpec.describe Set do
  it_behaves_like "a collection object" do
    let(:collection) { Set.new }
  end
end

When I run rspec shared_example_group_spec.rb --format documentation

Then the examples should all pass

And the output should contain:

Array
  behaves like a collection object
    <<
      adds objects to the end of the collection

Set
  behaves like a collection object
    <<
      adds objects to the end of the collection

Passing parameters to a shared example group

Given a file named “sharedexamplegroupparamsspec.rb” with:

RSpec.shared_examples "a measurable object" do |measurement, measurement_methods|
  measurement_methods.each do |measurement_method|
    it "should return #{measurement} from ##{measurement_method}" do
      expect(subject.send(measurement_method)).to eq(measurement)
    end
  end
end

RSpec.describe Array, "with 3 items" do
  subject { [1, 2, 3] }
  it_should_behave_like "a measurable object", 3, [:size, :length]
end

RSpec.describe String, "of 6 characters" do
  subject { "FooBar" }
  it_should_behave_like "a measurable object", 6, [:size, :length]
end

When I run rspec shared_example_group_params_spec.rb --format documentation

Then the examples should all pass

And the output should contain:

Array with 3 items
  it should behave like a measurable object
    should return 3 from #size
    should return 3 from #length

String of 6 characters
  it should behave like a measurable object
    should return 6 from #size
    should return 6 from #length

Aliasing it_should_behave_like to it_has_behavior

Given a file named “sharedexamplegroup_spec.rb” with:

RSpec.configure do |c|
  c.alias_it_should_behave_like_to :it_has_behavior, 'has behavior:'
end

RSpec.shared_examples 'sortability' do
  it 'responds to <=>' do
    expect(sortable).to respond_to(:<=>)
  end
end

RSpec.describe String do
  it_has_behavior 'sortability' do
    let(:sortable) { 'sample string' }
  end
end

When I run rspec shared_example_group_spec.rb --format documentation

Then the examples should all pass

And the output should contain:

String
  has behavior: sortability
    responds to <=>

Sharing metadata automatically includes shared example groups

Given a file named “sharedexamplemetadata_spec.rb” with:

RSpec.shared_examples "shared stuff", :a => :b do
  it 'runs wherever the metadata is shared' do
  end
end

RSpec.describe String, :a => :b do
end

When I run rspec shared_example_metadata_spec.rb

Then the output should contain:

1 example, 0 failures

Shared examples are nestable by context

Given a file named “contextspecificexamples_spec.rb” with:

RSpec.describe "shared examples" do
  context "per context" do

    shared_examples "shared examples are nestable" do
      specify { expect(true).to eq true }
    end

    it_behaves_like "shared examples are nestable"
  end
end

When I run rspec context_specific_examples_spec.rb

Then the output should contain:

1 example, 0 failures

Shared examples are accessible from offspring contexts

Given a file named “contextspecificexamples_spec.rb” with:

RSpec.describe "shared examples" do
  shared_examples "shared examples are nestable" do
    specify { expect(true).to eq true }
  end

  context "per context" do
    it_behaves_like "shared examples are nestable"
  end
end

When I run rspec context_specific_examples_spec.rb

Then the output should contain:

1 example, 0 failures

And the output should not contain:

Accessing shared_examples defined across contexts is deprecated

Shared examples are isolated per context

Given a file named “isolatedsharedexamples_spec.rb” with:

RSpec.describe "shared examples" do
  context do
    shared_examples "shared examples are isolated" do
      specify { expect(true).to eq true }
    end
  end

  context do
    it_behaves_like "shared examples are isolated"
  end
end

When I run rspec isolated_shared_examples_spec.rb

Then the output should contain:

Could not find shared examples \"shared examples are isolated\"