Skip to main content

Filtering

before, after, and around hooks defined in the block passed to RSpec.configure can be constrained to specific examples and/or groups using metadata as a filter.

RSpec.configure do |c|
  c.before(:example, :type => :model) do
  end
end

RSpec.describe "something", :type => :model do
end

Note that filtered :context hooks will still be applied to individual examples with matching metadata -- in effect, every example has a singleton example group containing just the one example (analogous to Ruby's singleton classes).

You can also specify metadata using only symbols.

Filter before(:example) hooks using arbitrary metadata​

Given a file named "filter_before_example_hooks_spec.rb" with:

RSpec.configure do |config|
  config.before(:example, :foo => :bar) do
    invoked_hooks << :before_example_foo_bar
  end
end

RSpec.describe "a filtered before :example hook" do
  let(:invoked_hooks) { [] }

  describe "group without matching metadata" do
    it "does not run the hook" do
      expect(invoked_hooks).to be_empty
    end

    it "runs the hook for an example with matching metadata", :foo => :bar do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end

  describe "group with matching metadata", :foo => :bar do
    it "runs the hook" do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end
end

When I run rspec filter_before_example_hooks_spec.rb

Then the examples should all pass.

Filter after(:example) hooks using arbitrary metadata​

Given a file named "filter_after_example_hooks_spec.rb" with:

RSpec.configure do |config|
  config.after(:example, :foo => :bar) do
    raise "boom!"
  end
end

RSpec.describe "a filtered after :example hook" do
  describe "group without matching metadata" do
    it "does not run the hook" do
      # should pass
    end

    it "runs the hook for an example with matching metadata", :foo => :bar do
      # should fail
    end
  end

  describe "group with matching metadata", :foo => :bar do
    it "runs the hook" do
      # should fail
    end
  end
end

When I run rspec filter_after_example_hooks_spec.rb

Then the output should contain "3 examples, 2 failures".

Filter around(:example) hooks using arbitrary metadata​

Given a file named "filter_around_example_hooks_spec.rb" with:

RSpec.configure do |config|
  config.around(:example, :foo => :bar) do |example|
    order << :before_around_example_foo_bar
    example.run
    expect(order).to eq([:before_around_example_foo_bar, :example])
  end
end

RSpec.describe "a filtered around(:example) hook" do
  let(:order) { [] }

  describe "a group without matching metadata" do
    it "does not run the hook" do
      expect(order).to be_empty
    end

    it "runs the hook for an example with matching metadata", :foo => :bar do
      expect(order).to eq([:before_around_example_foo_bar])
      order << :example
    end
  end

  describe "a group with matching metadata", :foo => :bar do
    it "runs the hook for an example with matching metadata", :foo => :bar do
      expect(order).to eq([:before_around_example_foo_bar])
      order << :example
    end
  end
end

When I run rspec filter_around_example_hooks_spec.rb

Then the examples should all pass.

Filter before(:context) hooks using arbitrary metadata​

Given a file named "filter_before_context_hooks_spec.rb" with:

RSpec.configure do |config|
  config.before(:context, :foo => :bar) { @hook = :before_context_foo_bar }
end

RSpec.describe "a filtered before(:context) hook" do
  describe "a group without matching metadata" do
    it "does not run the hook" do
      expect(@hook).to be_nil
    end

    it "runs the hook for a single example with matching metadata", :foo => :bar do
      expect(@hook).to eq(:before_context_foo_bar)
    end

    describe "a nested subgroup with matching metadata", :foo => :bar do
      it "runs the hook" do
        expect(@hook).to eq(:before_context_foo_bar)
      end
    end
  end

  describe "a group with matching metadata", :foo => :bar do
    it "runs the hook" do
      expect(@hook).to eq(:before_context_foo_bar)
    end

    describe "a nested subgroup" do
      it "runs the hook" do
        expect(@hook).to eq(:before_context_foo_bar)
      end
    end
  end
end

When I run rspec filter_before_context_hooks_spec.rb

Then the examples should all pass.

Filter after(:context) hooks using arbitrary metadata​

Given a file named "filter_after_context_hooks_spec.rb" with:

example_msgs = []

RSpec.configure do |config|
  config.after(:context, :foo => :bar) do
    puts "after :context"
  end
end

RSpec.describe "a filtered after(:context) hook" do
  describe "a group without matching metadata" do
    it "does not run the hook" do
      puts "unfiltered"
    end

    it "runs the hook for a single example with matching metadata", :foo => :bar do
      puts "filtered 1"
    end
  end

  describe "a group with matching metadata", :foo => :bar do
    it "runs the hook" do
      puts "filtered 2"
    end
  end

  describe "another group without matching metadata" do
    describe "a nested subgroup with matching metadata", :foo => :bar do
      it "runs the hook" do
        puts "filtered 3"
      end
    end
  end
end

When I run rspec --format progress filter_after_context_hooks_spec.rb --order defined

Then the examples should all pass

And the output should contain:

unfiltered
.filtered 1
after :context
.filtered 2
.after :context
filtered 3
.after :context

Use symbols as metadata​

Given a file named "less_verbose_metadata_filter.rb" with:

RSpec.configure do |c|
  c.before(:example, :before_example) { puts "before example" }
  c.after(:example,  :after_example) { puts "after example" }
  c.around(:example, :around_example) do |example|
    puts "around example (before)"
    example.run
    puts "around example (after)"
  end
  c.before(:context, :before_context) { puts "before context" }
  c.after(:context,  :after_context) { puts "after context" }
end

RSpec.describe "group 1", :before_context, :after_context do
  it("") { puts "example 1" }
  it("", :before_example) { puts "example 2" }
  it("", :after_example) { puts "example 3" }
  it("", :around_example) { puts "example 4" }
end

When I run rspec --format progress less_verbose_metadata_filter.rb

Then the examples should all pass

And the output should contain:

before context
example 1
.before example
example 2
.example 3
after example
.around example (before)
example 4
around example (after)
.after context

Filtering hooks using symbols​

Given a file named "filter_example_hooks_with_symbol_spec.rb" with:

RSpec.configure do |config|
  config.before(:example, :foo) do
    invoked_hooks << :before_example_foo_bar
  end
end

RSpec.describe "a filtered before :example hook" do
  let(:invoked_hooks) { [] }

  describe "group without a matching metadata key" do
    it "does not run the hook" do
      expect(invoked_hooks).to be_empty
    end

    it "does not run the hook for an example with metadata hash containing the key with a falsey value", :foo => nil do
      expect(invoked_hooks).to be_empty
    end

    it "runs the hook for an example with metadata hash containing the key with a truthy value", :foo => :bar do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end

    it "runs the hook for an example with only the key defined", :foo do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end

  describe "group with matching metadata key", :foo do
    it "runs the hook" do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end
end

When I run rspec filter_example_hooks_with_symbol_spec.rb

Then the examples should all pass.

Filtering hooks using a hash​

Given a file named "filter_example_hooks_with_hash_spec.rb" with:

RSpec.configure do |config|
  config.before(:example, :foo => { :bar => :baz, :slow => true }) do
    invoked_hooks << :before_example_foo_bar
  end
end

RSpec.describe "a filtered before :example hook" do
  let(:invoked_hooks) { [] }

  describe "group without matching metadata" do
    it "does not run the hook" do
      expect(invoked_hooks).to be_empty
    end

    it "does not run the hook for an example if only part of the filter matches", :foo => { :bar => :baz } do
      expect(invoked_hooks).to be_empty
    end

    it "runs the hook for an example if the metadata contains all key value pairs from the filter", :foo => { :bar => :baz, :slow => true, :extra => :pair } do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end

  describe "group with matching metadata", :foo => { :bar => :baz, :slow => true } do
    it "runs the hook" do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end
end

When I run rspec filter_example_hooks_with_hash_spec.rb

Then the examples should all pass.

Filtering hooks using a Proc​

Given a file named "filter_example_hooks_with_proc_spec.rb" with:

RSpec.configure do |config|
  config.before(:example, :foo => Proc.new { |value| value.is_a?(String) } ) do
    invoked_hooks << :before_example_foo_bar
  end
end

RSpec.describe "a filtered before :example hook" do
  let(:invoked_hooks) { [] }

  describe "group without matching metadata" do
    it "does not run the hook" do
      expect(invoked_hooks).to be_empty
    end

    it "does not run the hook if the proc returns false", :foo => :bar do
      expect(invoked_hooks).to be_empty
    end

    it "runs the hook if the proc returns true", :foo => 'bar' do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end

  describe "group with matching metadata", :foo => 'bar' do
    it "runs the hook" do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end
end

When I run rspec filter_example_hooks_with_proc_spec.rb

Then the examples should all pass.

Filtering hooks using a regular expression​

Given a file named "filter_example_hooks_with_regexp_spec.rb" with:

RSpec.configure do |config|
  config.before(:example, :foo => /bar/ ) do
    invoked_hooks << :before_example_foo_bar
  end
end

RSpec.describe "a filtered before :example hook" do
  let(:invoked_hooks) { [] }

  describe "group without matching metadata" do
    it "does not run the hook" do
      expect(invoked_hooks).to be_empty
    end

    it "does not run the hook if the value does not match", :foo => 'baz' do
      expect(invoked_hooks).to be_empty
    end

    it "runs the hook if the value matches", :foo => 'bar' do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end

  describe "group with matching metadata", :foo => 'bar' do
    it "runs the hook" do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end
end

When I run rspec filter_example_hooks_with_regexp_spec.rb

Then the examples should all pass.

Filtering hooks using string comparison​

Given a file named "filter_example_hooks_with_strcmp_spec.rb" with:

RSpec.configure do |config|
  config.before(:example, :foo => :bar ) do
    invoked_hooks << :before_example_foo_bar
  end
end

RSpec.describe "a filtered before :example hook" do
  let(:invoked_hooks) { [] }

  describe "group without matching metadata" do
    it "does not run the hook" do
      expect(invoked_hooks).to be_empty
    end

    it "does not run the hook if the coerced values do not match", :foo => 'baz' do
      expect(invoked_hooks).to be_empty
    end

    it "runs the hook if the coerced values match", :foo => 'bar' do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end

  describe "group with matching metadata", :foo => 'bar' do
    it "runs the hook" do
      expect(invoked_hooks).to eq([:before_example_foo_bar])
    end
  end
end

When I run rspec filter_example_hooks_with_strcmp_spec.rb

Then the examples should all pass.