update filtering features

features/filtering/exclusion_filters.feature

@@ -1,16 +1,21 @@
 Feature: exclusion filters
+
+  You can exclude examples from a run by declaring an exclusion filter and
+  then tagging examples, or entire groups, with that filter.
 
-  Scenario: exclude one example
+  Scenario: exclude an example
     Given a file named "spec/sample_spec.rb" with:
       """
       RSpec.configure do |c|
+        # declare an exclusion filter
         c.filter_run_excluding :broken => true
       end
 
       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
@@ -19,7 +24,7 @@ Feature: exclusion filters
     Then the output should contain "does one thing"
     And the output should not contain "does another thing"
 
-  Scenario: exclude one group
+  Scenario: exclude a group
     Given a file named "spec/sample_spec.rb" with:
       """
       RSpec.configure do |c|
@@ -44,7 +49,7 @@ Feature: exclusion filters
     And  the output should not contain "group 1 example 1"
     And  the output should not contain "group 1 example 2"
 
-  Scenario: exclude all groups
+  Scenario: exclude multiple groups
     Given a file named "spec/sample_spec.rb" with:
       """
       RSpec.configure do |c|
@@ -78,24 +83,24 @@ Feature: exclusion filters
     And  the output should not contain "group 1"
     And  the output should not contain "group 2"
 
-  Scenario: before/after(:all) hook in excluded example group
+  Scenario: before/after(:all) hooks in excluded example group are not run
     Given a file named "spec/before_after_all_exclusion_filter_spec.rb" with:
       """
       RSpec.configure do |c|
         c.filter_run_excluding :broken => true
       end
 
       describe "group 1" do
-        before(:all) { puts "before all in focused group" }
-        after(:all)  { puts "after all in focused group"  }
+        before(:all) { puts "before all in included group" }
+        after(:all)  { puts "after all in included group"  }
 
         it "group 1 example" do
         end
       end
 
       describe "group 2", :broken => true do
-        before(:all) { puts "before all in unfocused group" }
-        after(:all)  { puts "after all in unfocused group"  }
+        before(:all) { puts "before all in excluded group" }
+        after(:all)  { puts "after all in excluded group"  }
 
         context "context 1" do
           it "group 2 context 1 example 1" do
@@ -104,7 +109,7 @@ Feature: exclusion filters
       end
       """
     When I run "rspec ./spec/before_after_all_exclusion_filter_spec.rb"
-    Then the output should contain "before all in focused group"
-     And the output should contain "after all in focused group"
-     And the output should not contain "before all in unfocused group"
-     And the output should not contain "after all in unfocused group"
+    Then the output should contain "before all in included group"
+     And the output should contain "after all in included group"
+     And the output should not contain "before all in excluded group"
+     And the output should not contain "after all in excluded group"

features/filtering/inclusion_filters.feature

@@ -1,11 +1,22 @@
 Feature: inclusion filters
-
-  Scenario: focus on one example
-    Given a file named "spec/sample_spec.rb" with:
+
+  You can restrict 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.
+
+  Background:
+    Given a file named "spec/spec_helper.rb" with:
       """
       RSpec.configure do |c|
+        # filter_run is short-form alias for filter_run_including
         c.filter_run :focus => true
       end
+      """
+
+  Scenario: focus on an example
+    Given a file named "spec/sample_spec.rb" with:
+      """
+      require "spec_helper"
 
       describe "something" do
         it "does one thing" do
@@ -15,16 +26,14 @@ Feature: inclusion filters
         end
       end
       """
-    When I run "rspec ./spec/sample_spec.rb --format doc"
+    When I run "rspec spec/sample_spec.rb --format doc"
     Then the output should contain "does another thing"
     And the output should not contain "does one thing"
 
-  Scenario: focus on one group
+  Scenario: focus on a group
     Given a file named "spec/sample_spec.rb" with:
       """
-      RSpec.configure do |c|
-        c.filter_run :focus => true
-      end
+      require "spec_helper"
 
       describe "group 1", :focus => true do
         it "group 1 example 1" do
@@ -39,45 +48,15 @@ Feature: inclusion filters
         end
       end
       """
-    When I run "rspec ./spec/sample_spec.rb --format doc"
+    When I run "rspec spec/sample_spec.rb --format doc"
     Then the output should contain "group 1 example 1"
     And  the output should contain "group 1 example 2"
     And  the output should not contain "group 2 example 1"
 
-  Scenario: no examples match filter
-    Given a file named "spec/sample_spec.rb" with:
-      """
-      RSpec.configure do |c|
-        c.filter_run :focus => true
-        c.run_all_when_everything_filtered = true
-      end
-
-      describe "group 1" do
-        it "group 1 example 1" do
-        end
-
-        it "group 1 example 2" do
-        end
-      end
-
-      describe "group 2" do
-        it "group 2 example 1" do
-        end
-      end
-      """
-    When I run "rspec ./spec/sample_spec.rb --format doc"
-    Then the output should contain "No examples were matched by {:focus=>true}, running all"
-    And  the output should contain "group 1 example 1"
-    And  the output should contain "group 1 example 2"
-    And  the output should contain "group 2 example 1"
-    And  the output should contain "3 examples, 0 failures"
-
-  Scenario: before/after(:all) hook in unmatched example group
+  Scenario: before/after(:all) hooks in unmatched example group are not run
     Given a file named "spec/before_after_all_inclusion_filter_spec.rb" with:
       """
-      RSpec.configure do |c|
-        c.filter_run :focus => true
-      end
+      require "spec_helper"
 
       describe "group 1", :focus => true do
         before(:all) { puts "before all in focused group" }

features/filtering/run_all_when_everything_filtered.feature

@@ -0,0 +1,46 @@
+Feature: run all when everything filtered
+
+  Use the run_all_when_everything_filtered configuration option to do just
+  that.  This works well when paired with an inclusion filter like ":focus =>
+  true", as it will run all the examples when none match the inclusion filter.
+
+  Background:
+    Given a file named "spec/spec_helper.rb" with:
+      """
+      RSpec.configure do |c|
+        c.filter_run :focus => true
+        c.run_all_when_everything_filtered = true
+      end
+      """
+
+  Scenario: no examples match filter (runs all examples)
+    Given a file named "spec/sample_spec.rb" with:
+      """
+      require "spec_helper"
+
+      describe "group 1" do
+        it "group 1 example 1" do
+        end
+
+        it "group 1 example 2" do
+        end
+      end
+
+      describe "group 2" do
+        it "group 2 example 1" do
+        end
+      end
+      """
+    When I run "rspec spec/sample_spec.rb --format doc"
+    Then the output should contain "No examples were matched by {:focus=>true}, running all"
+    And the output should contain "3 examples, 0 failures"
+    And the output should contain:
+      """
+      group 1
+        group 1 example 1
+        group 1 example 2
+
+      group 2
+        group 2 example 1
+      """
+