Inclusion filters

You can constrain which examples are run by declaring an inclusion filter.
The most common use case is to focus on a subset of examples as you’re focused
on a particular problem. You can also specify metadata using only symbols.BackgroundGivena file named “spec/spec_helper.rb” with:

RSpec.configure do |c|
  c.filter_run_including :focus => true
end

Scenarios

1. Focus on an example
2. Focus on a group
3. `before`/`after(:context)` hooks in unmatched example group are not run
4. Use symbols as metadata

Focus on an exampleGivena file named “spec/sample_spec.rb” with:

require "spec_helper"

RSpec.describe "something" do
  it "does one thing" do
  end

  it "does another thing", :focus => true do
  end
end

WhenI run rspec spec/sample_spec.rb --format docThenthe output should contain “does another thing”Andthe output should not contain “does one thing”Focus on a groupGivena file named “spec/sample_spec.rb” with:

require "spec_helper"

RSpec.describe "group 1", :focus => true do
  it "group 1 example 1" do
  end

  it "group 1 example 2" do
  end
end

RSpec.describe "group 2" do
  it "group 2 example 1" do
  end
end

WhenI run rspec spec/sample_spec.rb --format docThenthe output should contain “group 1 example 1″Andthe output should contain “group 1 example 2″Andthe output should not contain “group 2 example 1”`before`/`after(:context)` hooks in unmatched example group are not runGivena file named “spec/before_after_all_inclusion_filter_spec.rb” with:

require "spec_helper"

RSpec.describe "group 1", :focus => true do
  before(:context) { puts "before all in focused group" }
  after(:context)  { puts "after all in focused group"  }

  it "group 1 example" do
  end
end

RSpec.describe "group 2" do
  before(:context) { puts "before all in unfocused group" }
  after(:context)  { puts "after all in unfocused group"  }

  context "context 1" do
    it "group 2 context 1 example 1" do
    end
  end
end

WhenI run rspec ./spec/before_after_all_inclusion_filter_spec.rbThenthe output should contain “before all in focused group”Andthe output should contain “after all in focused group”Andthe output should not contain “before all in unfocused group”Andthe output should not contain “after all in unfocused group”Use symbols as metadataGivena file named “symbols_as_metadata_spec.rb” with:

RSpec.configure do |c|
  c.filter_run :current_example
end

RSpec.describe "something" do
  it "does one thing" do
  end

  it "does another thing", :current_example do
  end
end

WhenI run rspec symbols_as_metadata_spec.rb --format docThenthe output should contain “does another thing”Andthe output should not contain “does one thing”

Exclusion filters

You can exclude examples from a run by declaring an exclusion filter and then
tagging examples, or entire groups, with that filter. You can also specify
metadata using only symbols.Scenarios

1. Exclude an example
2. Exclude a group
3. Exclude multiple groups
4. `before`/`after(:context)` hooks in excluded example group are not run
5. Use symbols as metadata

Exclude an exampleGivena file named “spec/sample_spec.rb” with:

RSpec.configure do |c|
  # declare an exclusion filter
  c.filter_run_excluding :broken => true
end

RSpec.describe "something" do
  it "does one thing" do
  end

  # tag example for exclusion by adding metadata
  it "does another thing", :broken => true do
  end
end

WhenI run rspec ./spec/sample_spec.rb --format docThenthe output should contain “does one thing”Andthe output should not contain “does another thing”Exclude a groupGivena file named “spec/sample_spec.rb” with:

RSpec.configure do |c|
  c.filter_run_excluding :broken => true
end

RSpec.describe "group 1", :broken => true do
  it "group 1 example 1" do
  end

  it "group 1 example 2" do
  end
end

RSpec.describe "group 2" do
  it "group 2 example 1" do
  end
end

WhenI run rspec ./spec/sample_spec.rb --format docThenthe output should contain “group 2 example 1″Andthe output should not contain “group 1 example 1″Andthe output should not contain “group 1 example 2”Exclude multiple groupsGivena file named “spec/sample_spec.rb” with:

RSpec.configure do |c|
  c.filter_run_excluding :broken => true
end

RSpec.describe "group 1", :broken => true do
  before(:context) do
    raise "you should not see me"
  end

  it "group 1 example 1" do
  end

  it "group 1 example 2" do
  end
end

RSpec.describe "group 2", :broken => true do
  before(:example) do
    raise "you should not see me"
  end

  it "group 2 example 1" do
  end
end

WhenI run rspec ./spec/sample_spec.rb --format docThenthe process should succeed even though no examples were runAndthe output should not contain “group 1″Andthe output should not contain “group 2”`before`/`after(:context)` hooks in excluded example group are not runGivena file named “spec/before_after_context_exclusion_filter_spec.rb” with:

RSpec.configure do |c|
  c.filter_run_excluding :broken => true
end

RSpec.describe "group 1" do
  before(:context) { puts "before context in included group" }
  after(:context)  { puts "after context in included group"  }

  it "group 1 example" do
  end
end

RSpec.describe "group 2", :broken => true do
  before(:context) { puts "before context in excluded group" }
  after(:context)  { puts "after context in excluded group"  }

  context "context 1" do
    it "group 2 context 1 example 1" do
    end
  end
end

WhenI run rspec ./spec/before_after_context_exclusion_filter_spec.rbThenthe output should contain “before context in included group”Andthe output should contain “after context in included group”Andthe output should not contain “before context in excluded group”Andthe output should not contain “after context in excluded group”Use symbols as metadataGivena file named “symbols_as_metadata_spec.rb” with:

RSpec.configure do |c|
  c.filter_run_excluding :broken
end

RSpec.describe "something" do
  it "does one thing" do
  end

  # tag example for exclusion by adding metadata
  it "does another thing", :broken do
  end
end

WhenI run rspec symbols_as_metadata_spec.rb --format docThenthe output should contain “does one thing”Andthe output should not contain “does another thing”

Conditional Filters

The :if and :unless metadata keys can be used to filter examples without
needing to configure an exclusion filter.Scenarios

1. Implicit `:if` filter
2. Implicit `:unless` filter
3. Combining implicit filter with explicit inclusion filter
4. Combining implicit filter with explicit exclusion filter
5. The :if and :unless exclusions stay in effect when there are explicit inclusions

Implicit `:if` filterGivena file named “implicit_if_filter_spec.rb” with:

RSpec.describe ":if => true group", :if => true do
  it(":if => true group :if => true example", :if => true) { }
  it(":if => true group :if => false example", :if => false) { }
  it(":if => true group no :if example") { }
end

RSpec.describe ":if => false group", :if => false do
  it(":if => false group :if => true example", :if => true) { }
  it(":if => false group :if => false example", :if => false) { }
  it(":if => false group no :if example") { }
end

RSpec.describe "no :if group" do
  it("no :if group :if => true example", :if => true) { }
  it("no :if group :if => false example", :if => false) { }
  it("no :if group no :if example") { }
end

WhenI run rspec implicit_if_filter_spec.rb --format docThenthe output should contain all of these:

:if => true group :if => true example

:if => true group no :if example

:if => false group :if => true example

no :if group :if => true example

no :if group no :if example

Andthe output should not contain any of these:

:if => true group :if => false example

:if => false group :if => false example

:if => false group no :if example

no :if group :if => false example

Implicit `:unless` filterGivena file named “implicit_unless_filter_spec.rb” with:

RSpec.describe ":unless => true group", :unless => true do
  it(":unless => true group :unless => true example", :unless => true) { }
  it(":unless => true group :unless => false example", :unless => false) { }
  it(":unless => true group no :unless example") { }
end

RSpec.describe ":unless => false group", :unless => false do
  it(":unless => false group :unless => true example", :unless => true) { }
  it(":unless => false group :unless => false example", :unless => false) { }
  it(":unless => false group no :unless example") { }
end

RSpec.describe "no :unless group" do
  it("no :unless group :unless => true example", :unless => true) { }
  it("no :unless group :unless => false example", :unless => false) { }
  it("no :unless group no :unless example") { }
end

WhenI run rspec implicit_unless_filter_spec.rb --format docThenthe output should contain all of these:

:unless => true group :unless => false example

:unless => false group :unless => false example

:unless => false group no :unless example

no :unless group :unless => false example

no :unless group no :unless example

Andthe output should not contain any of these:

:unless => true group :unless => true example

:unless => true group no :unless example

:unless => false group :unless => true example

no :unless group :unless => true example

Combining implicit filter with explicit inclusion filterGivena file named “explicit_inclusion_filter_spec.rb” with:

RSpec.configure do |c|
  c.filter_run :focus => true
end

RSpec.describe "group with :focus", :focus => true do
  it("focused example") { }
  it("focused :if => true example", :if => true) { }
  it("focused :if => false example", :if => false) { }
  it("focused :unless => true example", :unless => true) { }
  it("focused :unless => false example", :unless => false) { }
end

RSpec.describe "group without :focus" do
  it("unfocused example") { }
  it("unfocused :if => true example", :if => true) { }
  it("unfocused :if => false example", :if => false) { }
  it("unfocused :unless => true example", :unless => true) { }
  it("unfocused :unless => false example", :unless => false) { }
end

WhenI run rspec explicit_inclusion_filter_spec.rb --format docThenthe output should contain all of these:

focused example

focused :if => true example

focused :unless => false example

Andthe output should not contain any of these:

focused :if => false example

focused :unless => true example

unfocused

Combining implicit filter with explicit exclusion filterGivena file named “explicit_exclusion_filter_spec.rb” with:

RSpec.configure do |c|
  c.filter_run_excluding :broken => true
end

RSpec.describe "unbroken group" do
  it("included example") { }
  it("included :if => true example", :if => true) { }
  it("included :if => false example", :if => false) { }
  it("included :unless => true example", :unless => true) { }
  it("included :unless => false example", :unless => false) { }
end

RSpec.describe "broken group", :broken => true do
  it("excluded example") { }
  it("excluded :if => true example", :if => true) { }
  it("excluded :if => false example", :if => false) { }
  it("excluded :unless => true example", :unless => true) { }
  it("excluded :unless => false example", :unless => false) { }
end

WhenI run rspec explicit_exclusion_filter_spec.rb --format docThenthe output should contain all of these:

included example

included :if => true example

included :unless => false example

Andthe output should not contain any of these:

included :if => false example

included :unless => true example

excluded

The :if and :unless exclusions stay in effect when there are explicit inclusionsGivena file named “if_and_unless_spec.rb” with:

RSpec.describe "Using inclusions" do
  context "inclusion target" do
    it "is filtered out by :if", :if => false do
    end

    it 'is filtered out by :unless', :unless => true do
    end

    it 'is still run according to :if', :if => true do
    end

    it 'is still run according to :unless', :unless => false do
    end
  end
end

WhenI run rspec if_and_unless_spec.rb --format doc -e 'inclusion target'Thenthe output should contain all of these:

is still run according to :if

is still run according to :unless

Andthe output should not contain any of these:

is filtered out by :if

is filtered out by :unless