rspec-core 2.0.1 → 2.1.0

data/bin/autospec

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+require 'rspec/core/deprecation'
+RSpec.warn_deprecation <<-WARNING
+************************************************************
+REMOVAL NOTICE: you are using behaviour that has been
+removed from rspec-2.
+
+* The 'autospec' command is no longer supported.
+* Please use 'autotest' insted.
+
+This message will be removed from a future version of rspec.
+************************************************************
+WARNING

data/bin/rspec

@@ -1,2 +1,25 @@
 #!/usr/bin/env ruby
-require 'rspec/autorun'
+
+begin
+  require 'rspec/autorun'
+rescue LoadError
+  $stderr.puts <<-EOS
+#{'*'*50}
+  Could not find 'rspec/autorun'
+
+  This may happen if you're using rubygems as your package manager, but it is not
+  being required through some mechanism before executing the rspec command.
+
+  You may need to do one of the following in your shell:
+
+    # for bash/zsh
+    export RUBYOPT=rubygems
+
+    # for csh, etc.
+    set RUBYOPT=rubygems
+
+  For background, please see http://gist.github.com/54177.
+#{'*'*50}
+  EOS
+  exit(1)
+end

data/features/command_line/line_number_appended_to_path.feature

@@ -1,6 +1,8 @@
 Feature: line number appended to file path
 
-  Append a line number to the path to run a single example, or a single group.
+  To run a single example or group, you can append the line number to the path, e.g.
+
+    rspec path/to/example_spec.rb:37
   
   Background:
     Given a file named "example_spec.rb" with:

data/features/command_line/line_number_option.feature

@@ -1,6 +1,8 @@
 Feature: line number option
 
-  Use the line number option to run a single example, or a single group.
+  To run a single example or group, you can use the --line option:
+
+    rspec path/to/example_spec.rb --line 37
 
   Scenario: standard examples
     Given a file named "example_spec.rb" with:

data/features/command_line/tag.feature

@@ -0,0 +1,74 @@
+Feature: tag option
+
+  Use the --tag (or -t) option to filter the examples to be run by tag.
+  
+  The tag can be a simple name or a name:value pair. In the first case,
+  examples with :name => true will be filtered. In the second case, examples
+  with :name => value will be filtered, where value is always a string.
+  In both cases, name is converted to a symbol.
+  
+  Tags can also be used to exclude examples by adding a ~ before the tag.
+  For example ~tag will exclude all examples marked with :tag => true and
+  ~tag:value will exclude all examples marked with :tag => value.
+  
+  To be compatible with the Cucumber syntax, tags can optionally start with
+  a @, that will be ignored.
+
+  Background:
+    Given a file named "tagged_spec.rb" with:
+      """
+      describe "group with tagged specs" do
+        it "example I'm working now", :focus => true do; end
+        it "special example", :type => 'special' do; end
+        it "slow example", :skip => true do; end
+        it "ordinary example", :speed => 'slow' do; end
+        it "untagged example" do; end
+      end
+      """
+
+  Scenario: filter examples with non-existent tag
+    When I run "rspec . --tag mytag"
+    And the output should contain "0 examples, 0 failures"
+
+  Scenario: filter examples with a simple tag
+    When I run "rspec . --tag focus"
+    Then the output should contain "Run filtered using {:focus=>true}"
+    And the output should contain "1 example, 0 failures"
+
+  Scenario: filter examples with a simple tag and @
+    When I run "rspec . --tag @focus"
+    Then the output should contain "Run filtered using {:focus=>true}"
+    Then the output should contain "1 example, 0 failures"
+
+  Scenario: filter examples with a name:value tag
+    When I run "rspec . --tag type:special"
+    Then the output should contain:
+      """
+      Run filtered using {:type=>"special"}
+      """
+    And the output should contain "1 example, 0 failures"
+  
+  Scenario: filter examples with a name:value tag and @
+    When I run "rspec . --tag @type:special"
+    Then the output should contain:
+      """
+      Run filtered using {:type=>"special"}
+      """
+    And the output should contain "1 example, 0 failures"
+  
+  Scenario: exclude examples with a simple tag
+    When I run "rspec . --tag ~skip"
+    Then the output should contain "4 examples, 0 failures"
+
+  Scenario: exclude examples with a simple tag and @
+    When I run "rspec . --tag ~@skip"
+    Then the output should contain "4 examples, 0 failures"
+    
+  Scenario: exclude examples with a name:value tag
+    When I run "rspec . --tag ~speed:slow"
+    Then the output should contain "4 examples, 0 failures"
+  
+  Scenario: exclude examples with a name:value tag and @
+    When I run "rspec . --tag ~@speed:slow"
+    Then the output should contain "4 examples, 0 failures"
+

data/features/filtering/exclusion_filters.feature

@@ -78,7 +78,7 @@ Feature: exclusion filters
       end
       """
     When I run "rspec ./spec/sample_spec.rb --format doc"
-    Then the output should contain "No examples were matched. Perhaps {:broken=>true} is excluding everything?"
+    Then the output should match /No examples were matched. Perhaps \{.*:broken=>true.*\} is excluding everything?/
     And  the output should contain "0 examples, 0 failures"
     And  the output should not contain "group 1"
     And  the output should not contain "group 2"

data/features/filtering/implicit_filters.feature

@@ -0,0 +1,166 @@
+Feature: implicit filters
+
+  The `:if` and `:unless` metadata keys can be used to filter examples without
+  needing to configure an exclusion filter.
+
+  Scenario: implicit :if filter
+    Given a file named "implicit_if_filter_spec.rb" with:
+      """
+      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
+
+      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
+
+      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
+      """
+    When I run "rspec implicit_if_filter_spec.rb --format doc"
+    Then the 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            |
+    And the 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       |
+
+  Scenario: implicit :unless filter
+    Given a file named "implicit_unless_filter_spec.rb" with:
+      """
+      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
+
+      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
+
+      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
+      """
+    When I run "rspec implicit_unless_filter_spec.rb --format doc"
+    Then the 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             |
+    And the 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       |
+
+  Scenario: combining implicit filter with explicit inclusion filter
+    Given a file named "explicit_inclusion_filter_spec.rb" with:
+      """
+      RSpec.configure do |c|
+        c.filter_run :focus => true
+      end
+
+      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
+
+      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
+      """
+    When I run "rspec explicit_inclusion_filter_spec.rb --format doc"
+    Then the output should contain all of these:
+      | focused example                  |
+      | focused :if => true example      |
+      | focused :unless => false example |
+    And the output should not contain any of these:
+      | focused :if => false example     |
+      | focused :unless => true example  |
+      | unfocused                        |
+
+  Scenario: combining implicit filter with explicit exclusion filter
+    Given a file named "explicit_exclusion_filter_spec.rb" with:
+      """
+      RSpec.configure do |c|
+        c.filter_run_excluding :broken => true
+      end
+
+      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
+
+      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
+      """
+    When I run "rspec explicit_exclusion_filter_spec.rb --format doc"
+    Then the output should contain all of these:
+      | included example                  |
+      | included :if => true example      |
+      | included :unless => false example |
+    And the output should not contain any of these:
+      | included :if => false example     |
+      | included :unless => true example  |
+      | excluded                          |
+
+  Scenario: override implicit :if and :unless exclusion filters
+    Given a file named "override_implicit_filters_spec.rb" with:
+      """
+      RSpec.configure do |c|
+        c.filter_run_excluding :if => :exclude_me, :unless => :exclude_me_for_unless
+      end
+
+      describe ":if filtering" do
+        it(":if => true example", :if => true) { }
+        it(":if => false example", :if => false) { }
+        it(":if => :exclude_me example", :if => :exclude_me) { }
+      end
+
+      describe ":unless filtering" do
+        it(":unless => true example", :unless => true) { }
+        it(":unless => false example", :unless => false) { }
+        it(":unless => :exclude_me_for_unless example", :unless => :exclude_me_for_unless) { }
+      end
+      """
+    When I run "rspec override_implicit_filters_spec.rb --format doc"
+    Then the output should contain all of these:
+      | :if => true example      |
+      | :if => false example     |
+      | :unless => true example  |
+      | :unless => false example |
+    And the output should not contain "exclude_me"
+

data/features/hooks/around_hooks.feature

@@ -1,52 +1,59 @@
 Feature: around hooks
 
-  As a developer using RSpec
-  I want to run the examples as part of a block given to a an arbitary function
-  So that I can control the environment in which it is run
+  Around hooks receive the example as a block argument, extended to behave like
+  a proc.  This lets you define code that should be executed before and after
+  the example. Of course, you can do the same thing with before and after hooks,
+  and it's often cleaner to do so.
 
-  Scenario: around hooks defined in a group are run
-    Given a file named "ensure_around_blocks_are_run.rb" with:
+  Where around hooks shine is when you want to run an example in a block. For
+  example, if your database library offers a transaction method that receives
+  a block, you can use an around hook as described in the first scenario:
+
+  Scenario: use the example as a block within the block passed to around()
+    Given a file named "example_spec.rb" with:
       """
+      class Database
+        def self.transaction
+          puts "open transaction"
+          yield
+          puts "close transaction"
+        end
+      end
+
       describe "around filter" do
         around(:each) do |example|
-          puts "around each before"
-          example.run
-          puts "around each after"
+          Database.transaction(&example)
         end
 
         it "gets run in order" do
-          puts "in the example"
+          puts "run the example"
         end
       end
       """
-    When I run "rspec ./ensure_around_blocks_are_run.rb"
+    When I run "rspec example_spec.rb"
     Then the output should contain:
       """
-      around each before
-      in the example
-      around each after
+      open transaction
+      run the example
+      close transaction
       """
 
-  Scenario: argument passed to around hook can be treated as a proc
-    Given a file named "treat_around_hook_arg_as_a_proc.rb" with:
+  Scenario: invoke the example using run()
+    Given a file named "example_spec.rb" with:
       """
       describe "around filter" do
-        def perform_around
+        around(:each) do |example|
           puts "around each before"
-          yield
+          example.run
           puts "around each after"
         end
 
-        around(:each) do |example|
-          perform_around(&example)
-        end
-
         it "gets run in order" do
           puts "in the example"
         end
       end
       """
-    When I run "rspec ./treat_around_hook_arg_as_a_proc.rb"
+    When I run "rspec example_spec.rb"
     Then the output should contain:
       """
       around each before
@@ -54,8 +61,8 @@ Feature: around hooks
       around each after
       """
 
-  Scenario: around hooks defined globally are run
-    Given a file named "ensure_around_blocks_are_run.rb" with:
+  Scenario: define a global around hook
+    Given a file named "example_spec.rb" with:
       """
       RSpec.configure do |c|
         c.around(:each) do |example|
@@ -71,7 +78,7 @@ Feature: around hooks
         end
       end
       """
-    When I run "rspec ./ensure_around_blocks_are_run.rb"
+    When I run "rspec example_spec.rb"
     Then the output should contain:
       """
       around each before
@@ -80,7 +87,7 @@ Feature: around hooks
       """
 
   Scenario: before/after(:each) hooks are wrapped by the around hook
-    Given a file named "ensure_around_blocks_are_run.rb" with:
+    Given a file named "example_spec.rb" with:
       """
       describe "around filter" do
         around(:each) do |example|
@@ -102,7 +109,7 @@ Feature: around hooks
         end
       end
       """
-    When I run "rspec ./ensure_around_blocks_are_run.rb"
+    When I run "rspec example_spec.rb"
     Then the output should contain:
       """
       around each before
@@ -113,7 +120,7 @@ Feature: around hooks
       """
 
   Scenario: before/after(:all) hooks are NOT wrapped by the around hook
-    Given a file named "ensure_around_blocks_are_run.rb" with:
+    Given a file named "example_spec.rb" with:
       """
       describe "around filter" do
         around(:each) do |example|
@@ -135,7 +142,7 @@ Feature: around hooks
         end
       end
       """
-    When I run "rspec ./ensure_around_blocks_are_run.rb"
+    When I run "rspec example_spec.rb"
     Then the output should contain:
       """
       before all
@@ -145,8 +152,8 @@ Feature: around hooks
       .after all
       """
 
-  Scenario: examples run by an around block should run in the configured context
-    Given a file named "around_block_with_context.rb" with:
+  Scenario: examples run by an around block are run in the configured context
+    Given a file named "example_spec.rb" with:
       """
       module IncludedInConfigureBlock
         def included_in_configure_block; true; end
@@ -166,11 +173,11 @@ Feature: around hooks
         end
       end
       """
-    When I run "rspec ./around_block_with_context.rb"
+    When I run "rspec example_spec.rb"
     Then the output should contain "1 example, 0 failure"
 
-  Scenario: implicitly pending examples should be detected as Not Yet Implemented
-    Given a file named "around_block_with_implicit_pending_example.rb" with:
+  Scenario: implicitly pending examples are detected as Not Yet Implemented
+    Given a file named "example_spec.rb" with:
       """
       describe "implicit pending example" do
         around(:each) do |example|
@@ -180,7 +187,7 @@ Feature: around hooks
         it "should be detected as Not Yet Implemented"
       end
       """
-    When I run "rspec ./around_block_with_implicit_pending_example.rb"
+    When I run "rspec example_spec.rb"
     Then the output should contain "1 example, 0 failures, 1 pending"
     And the output should contain:
       """
@@ -190,8 +197,8 @@ Feature: around hooks
       """
 
 
-  Scenario: explicitly pending examples should be detected as pending
-    Given a file named "around_block_with_explicit_pending_example.rb" with:
+  Scenario: explicitly pending examples are detected as pending
+    Given a file named "example_spec.rb" with:
       """
       describe "explicit pending example" do
         around(:each) do |example|
@@ -203,7 +210,7 @@ Feature: around hooks
         end
       end
       """
-    When I run "rspec ./around_block_with_explicit_pending_example.rb"
+    When I run "rspec example_spec.rb"
     Then the output should contain "1 example, 0 failures, 1 pending"
     And the output should contain:
       """
@@ -211,8 +218,8 @@ Feature: around hooks
           # No reason given
       """
 
-  Scenario: multiple around hooks in the same scope are all run
-    Given a file named "around_hooks_in_same_scope.rb" with:
+  Scenario: multiple around hooks in the same scope
+    Given a file named "example_spec.rb" with:
     """
     describe "if there are multiple around hooks in the same scope" do
       around(:each) do |example|
@@ -233,7 +240,7 @@ Feature: around hooks
       end
     end
     """
-    When I run "rspec ./around_hooks_in_same_scope.rb"
+    When I run "rspec example_spec.rb"
     Then the output should contain "1 example, 0 failure"
     And the output should contain:
     """
@@ -244,8 +251,8 @@ Feature: around hooks
     first around hook after
     """
 
-  Scenario: around hooks in outer scopes are run
-    Given a file named "around_hooks_in_outer_scope.rb" with:
+  Scenario: around hooks in multiple scopes
+    Given a file named "example_spec.rb" with:
     """
     describe "if there are around hooks in an outer scope" do
       around(:each) do |example|
@@ -293,7 +300,7 @@ Feature: around hooks
       end
     end
     """
-    When I run "rspec ./around_hooks_in_outer_scope.rb"
+    When I run "rspec example_spec.rb"
     Then the output should contain "1 example, 0 failure"
     And the output should contain:
     """