rspec-core 2.3.1 → 2.4.0

data/History.markdown

@@ -1,5 +1,27 @@
 ## rspec-core release history (incomplete)
 
+### 2.4.0 / 2011-01-02
+
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.3.1...v2.4.0)
+
+* Enhancements
+  * start the debugger on -d so the stack trace is visible when it stops
+    (Clifford Heath)
+  * apply hook filtering to examples as well as groups (Myron Marston)
+  * support multiple formatters, each with their own output
+  * show exception classes in failure messages unless they come from RSpec
+    matchers or message expectations
+  * before(:all) { pending } sets all examples to pending
+
+* Bug fixes
+  * fix bug due to change in behavior of reject in Ruby 1.9.3-dev (Shota Fukumori)
+  * fix bug when running in jruby: be explicit about passing block to super
+    (John Firebaugh)
+  * rake task doesn't choke on paths with quotes (Janmejay Singh)
+  * restore --options option from rspec-1
+  * require 'ostruct' to fix bug with its([key]) (Kim Burgestrand)
+  * --configure option generates .rspec file instead of autotest/discover.rb
+
 ### 2.3.1 / 2010-12-16
 
 [full changelog](http://github.com/rspec/rspec-core/compare/v2.3.0...v2.3.1)

data/Rakefile

@@ -57,10 +57,10 @@ task :clobber do
   rm_rf 'coverage'
 end
 
-desc "Push cukes to relishapp using the relish-client-gem"
+desc "Push docs/cukes to relishapp using the relish-client-gem"
 task :relish, :version do |t, args|
   raise "rake relish[VERSION]" unless args[:version]
-  sh "relish push --organization rspec --project rspec-core -v #{args[:version]}"
+  sh "relish push rspec/rspec-core:#{args[:version]}"
 end
 
 Rake::RDocTask.new do |rdoc|

data/features/command_line/README.md

@@ -0,0 +1,6 @@
+The `rspec` command comes with several options you can use to customize RSpec's
+behavior, including output formats, filtering examples, etc.
+
+For a full list of options, run the `rspec` command with the `--help` flag:
+
+    $ rspec --help

data/features/command_line/configure.feature

@@ -1,20 +1,22 @@
-Feature: configure
+Feature: --configure option
 
   Use the --configure option on the command line to generate configuration
   files.
 
-  The only supported argument, so far, is "autotest", which creates an
-  autotest/discover.rb file in your project root directory.
+  The only supported argument, so far, is "autotest", which creates a .rspec
+  file in your project root directory. When autotest sees this file, it knows
+  to load RSpec's Autotest subclass.
 
-  Background:
-    Given a directory named "rspec_project"
+  Scenario: generate .rspec file for autotest
+    When I run "rspec --configure autotest"
+    Then the following files should exist:
+      | .rspec |
+    And the stdout should contain ".rspec file did not exist, so it was created."
 
-  Scenario: generate autotest directory and discover file
-    When I cd to "rspec_project"
-    And I run "rspec --configure autotest"
-    Then the following directories should exist:
-      | autotest |
-    And the following files should exist:
-      | autotest/discover.rb |
-    And the file "autotest/discover.rb" should contain "Autotest.add_discovery"
-    And the stdout should contain "autotest/discover.rb has been added"
+  Scenario: .rspec file already exists
+    Given a file named ".rspec" with:
+      """
+      --color
+      """
+    When I run "rspec --configure autotest"
+    Then the stdout should contain ".rspec file already exists, so nothing was changed."

data/features/command_line/example_name_option.feature

@@ -1,13 +1,13 @@
-Feature: example name option
+Feature: --example option
 
-  Use the --example (or -e) option to filter the examples to be run by name.
+  Use the --example (or -e) option to filter examples by name.
 
   The argument is compiled to a Ruby Regexp, and matched against the full
   description of the example, which is the concatenation of descriptions of the
   group (including any nested groups) and the example.
 
   This allows you to run a single uniquely named example, all examples with
-  similar names, all the example in a uniquely named group, etc, etc.
+  similar names, all the examples in a uniquely named group, etc, etc.
 
   Background:
     Given a file named "first_spec.rb" with:

data/features/command_line/format_option.feature

@@ -0,0 +1,73 @@
+Feature: --format option
+
+  Use the --format option to tell RSpec how to format the output.
+
+  RSpec ships with a few formatters built in. By default, it uses the progress
+  formatter, which generates output like this:
+
+      ....F.....*.....
+
+  A '.' represents a passing example, 'F' is failing, and '*' is pending.
+
+  To see the documentation strings passed to each describe(), context(), and it()
+  method, use the documentation formatter:
+
+      $ rspec spec --format documentation
+
+  You can also specify an output target (STDOUT by default) by appending a
+  filename to the argument:
+
+    $ rspec spec --format documentation:rspec.output.txt
+
+  Background:
+    Given a file named "example_spec.rb" with:
+      """
+      describe "something" do
+        it "does something that passes" do
+          5.should eq(5)
+        end
+
+        it "does something that fails" do
+          5.should eq(4)
+        end
+
+        it "does something that is pending", :pending => true do
+          5.should be > 3
+        end
+      end
+      """
+
+  Scenario: progress bar format (default)
+    When I run "rspec example_spec.rb"
+    Then the output should contain ".F*"
+
+  Scenario: documentation format
+    When I run "rspec example_spec.rb --format documentation"
+    Then the output should contain:
+      """
+      something
+        does something that passes
+        does something that fails (FAILED - 1)
+        does something that is pending (PENDING: Not Yet Implemented)
+      """
+
+  Scenario: documentation format saved to a file
+    When I run "rspec example_spec.rb --format documentation --out rspec.txt"
+    Then the file "rspec.txt" should contain:
+      """
+      something
+        does something that passes
+        does something that fails (FAILED - 1)
+        does something that is pending (PENDING: Not Yet Implemented)
+      """
+
+  Scenario: multiple formats
+    When I run "rspec example_spec.rb --format progress --format documentation --out rspec.txt"
+    Then the output should contain ".F*"
+    And the file "rspec.txt" should contain:
+      """
+      something
+        does something that passes
+        does something that fails (FAILED - 1)
+        does something that is pending (PENDING: Not Yet Implemented)
+      """

data/features/command_line/line_number_appended_to_path.feature

@@ -2,7 +2,7 @@ Feature: line number appended to file path
 
   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
+      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,8 +1,8 @@
-Feature: line number option
+Feature: --line option
 
   To run a single example or group, you can use the --line option:
 
-    rspec path/to/example_spec.rb --line 37
+      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

@@ -1,18 +1,18 @@
-Feature: tag option
+Feature: --tag option
 
-  Use the --tag (or -t) option to filter the examples to be run by tag.
+  Use the --tag (or -t) option to filter the examples by tags.
   
   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.
+  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
+  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.
+  an @ symbol, which will be ignored.
 
   Background:
     Given a file named "tagged_spec.rb" with:

data/features/configuration/read_options_from_file.feature

@@ -8,7 +8,7 @@ Feature: read command line configuration options from files
 
   Options declared in the local file override those in the global file, while
   those declared in RSpec.configure will override any ".rspec" file.
-  
+
   Scenario: color set in .rspec
     Given a file named ".rspec" with:
       """
@@ -33,30 +33,43 @@ Feature: read command line configuration options from files
     When I run "rspec ./spec/example_spec.rb"
     Then the output should contain "1 example, 0 failures"
 
-  Scenario: formatter set in RSpec.configure overrides .rspec
-    Given a file named ".rspec" with:
+  Scenario: custom options file
+    Given a file named "my.options" with:
+      """
+      --format documentation
+      """
+    And a file named "spec/example_spec.rb" with:
+      """
+      describe "formatter set in custom options file" do
+        it "sets formatter" do
+          RSpec.configuration.formatters.first.
+            should be_a(RSpec::Core::Formatters::DocumentationFormatter)
+        end
+      end
       """
-      --format progress
+    When I run "rspec spec/example_spec.rb --options my.options"
+    Then the output should contain "1 example, 0 failures"
+
+  Scenario: RSpec ignores ./.rspec when custom options file is used
+    Given a file named "my.options" with:
       """
-    And a file named "spec/spec_helper.rb" with:
+      --format documentation
       """
-      RSpec.configure {|c| c.formatter = 'documentation'}
+    And a file named ".rspec" with:
+      """
+      --color
       """
     And a file named "spec/example_spec.rb" with:
       """
-      require "spec_helper"
-
-      describe "formatter" do
-        context "when set with RSpec.configure and in spec.opts" do
-          it "takes the value set in spec.opts" do
-            RSpec.configuration.formatter.should be_an(RSpec::Core::Formatters::DocumentationFormatter)
-          end
+      describe "custom options file" do
+        it "causes .rspec to be ignored" do
+          RSpec.configuration.color_enabled.should be_false
         end
       end
       """
-    When I run "rspec ./spec/example_spec.rb"
+    When I run "rspec spec/example_spec.rb --options my.options"
     Then the output should contain "1 example, 0 failures"
-    
+
   Scenario: using ERB in .rspec
     Given a file named ".rspec" with:
       """
@@ -66,7 +79,7 @@ Feature: read command line configuration options from files
       """
       describe "formatter" do
         it "is set to documentation" do
-          RSpec.configuration.formatter.should be_an(RSpec::Core::Formatters::DocumentationFormatter)
+          RSpec.configuration.formatters.first.should be_an(RSpec::Core::Formatters::DocumentationFormatter)
         end
       end
       """

data/features/hooks/before_and_after_hooks.feature

@@ -1,19 +1,16 @@
 Feature: before and after hooks
 
-  As a developer using RSpec
-  I want to execute arbitrary code before and after each example
-  So that I can control the environment in which it is run
+  Use `before` and `after` hooks to execute arbitrary code before and/or
+  after the body of an example is run:
 
-    This is supported by the before and after methods which each take a symbol
-    indicating the scope, and a block of code to execute.
+      before(:each) # run before each example
+      before(:all)  # run one time only, before all of the examples in a group
 
-    before(:each) blocks are run before each example
-    before(:all) blocks are run once before all of the examples in a group
+      after(:each) # run after each example
+      after(:all)  # run one time only, after all of the examples in a group
 
-    after(:each) blocks are run after each example
-    after(:all) blocks are run once after all of the examples in a group
+  Before and after blocks are called in the following order:
 
-    Before and after blocks are called in the following order:
       before suite
       before all
       before each
@@ -21,10 +18,8 @@ Feature: before and after hooks
       after  all
       after  suite
 
-    Before and after blocks can be defined in the example groups to which they
-    apply or in a configuration. When defined in a configuration, they can be
-    applied to all groups or subsets of all groups defined by example group
-    types.
+  `before` and `after` hooks can be defined directly in the example groups they
+  should run in, or in a global RSpec.configure block.
 
   Scenario: define before(:each) block
     Given a file named "before_each_spec.rb" with:

data/features/hooks/filtering.feature

@@ -0,0 +1,174 @@
+Feature: Global Hook Filtering
+
+  Before/After/Around hooks defined in the RSpec configuration block
+  can be filtered using metadata.  Arbitrary metadata can be applied
+  to an example or example group, and used to make a hook only apply
+  to examples with the given metadata.
+
+  Scenario: Filter before(:each) hooks using arbitrary metadata
+    Given a file named "filter_before_each_hooks_spec.rb" with:
+      """
+      RSpec.configure do |config|
+        config.before(:each, :foo => :bar) { puts "In hook" }
+      end
+
+      describe "group 1" do
+        it("example 1") { }
+        it("example 2", :foo => :bar) { }
+      end
+
+      describe "group 2", :foo => :bar do
+        it("example 1") { }
+        it("example 2", :foo => :bar) { }
+      end
+      """
+    When I run "rspec filter_before_each_hooks_spec.rb --format documentation"
+    Then the output should contain "4 examples, 0 failures"
+    And the output should contain:
+      """
+      group 1
+        example 1
+      In hook
+        example 2
+
+      group 2
+      In hook
+        example 1
+      In hook
+        example 2
+      """
+
+  Scenario: Filter after(:each) hooks using arbitrary metadata
+    Given a file named "filter_after_each_hooks_spec.rb" with:
+      """
+      RSpec.configure do |config|
+        config.after(:each, :foo => :bar) { puts "In hook" }
+      end
+
+      describe "group 1" do
+        it("example 1") { }
+        it("example 2", :foo => :bar) { }
+      end
+
+      describe "group 2", :foo => :bar do
+        it("example 1") { }
+        it("example 2", :foo => :bar) { }
+      end
+      """
+    When I run "rspec filter_after_each_hooks_spec.rb --format documentation"
+    Then the output should contain "4 examples, 0 failures"
+    And the output should contain:
+      """
+      group 1
+        example 1
+      In hook
+        example 2
+
+      group 2
+      In hook
+        example 1
+      In hook
+        example 2
+      """
+
+  Scenario: Filter around(:each) hooks using arbitrary metadata
+    Given a file named "filter_around_each_hooks_spec.rb" with:
+      """
+      RSpec.configure do |config|
+        config.around(:each, :foo => :bar) do |example|
+          puts "Start hook"
+          example.run
+          puts "End hook"
+        end
+      end
+
+      describe "group 1" do
+        it("example 1") { }
+        it("example 2", :foo => :bar) { }
+      end
+
+      describe "group 2", :foo => :bar do
+        it("example 1") { }
+        it("example 2", :foo => :bar) { }
+      end
+      """
+    When I run "rspec filter_around_each_hooks_spec.rb --format documentation"
+    Then the output should contain "4 examples, 0 failures"
+    And the output should contain:
+      """
+      group 1
+        example 1
+      Start hook
+      End hook
+        example 2
+
+      group 2
+      Start hook
+      End hook
+        example 1
+      Start hook
+      End hook
+        example 2
+      """
+
+  Scenario: Filter before(:all) hooks using arbitrary metadata
+    Given a file named "filter_before_all_hooks_spec.rb" with:
+      """
+      RSpec.configure do |config|
+        config.before(:all, :foo => :bar) { puts "In hook" }
+      end
+
+      describe "group 1" do
+        it("example 1") { }
+        it("example 2") { }
+      end
+
+      describe "group 2", :foo => :bar do
+        it("example 1") { }
+        it("example 2") { }
+      end
+      """
+    When I run "rspec filter_before_all_hooks_spec.rb --format documentation"
+    Then the output should contain "4 examples, 0 failures"
+    And the output should contain:
+      """
+      group 1
+        example 1
+        example 2
+
+      group 2
+      In hook
+        example 1
+        example 2
+      """
+
+  Scenario: Filter after(:all) hooks using arbitrary metadata
+    Given a file named "filter_after_all_hooks_spec.rb" with:
+      """
+      RSpec.configure do |config|
+        config.after(:all, :foo => :bar) { puts "In hook" }
+      end
+
+      describe "group 1" do
+        it("example 1") { }
+        it("example 2") { }
+      end
+
+      describe "group 2", :foo => :bar do
+        it("example 1") { }
+        it("example 2") { }
+      end
+      """
+    When I run "rspec filter_after_all_hooks_spec.rb --format documentation"
+    Then the output should contain "4 examples, 0 failures"
+    And the output should contain:
+      """
+      group 1
+        example 1
+        example 2
+
+      group 2
+        example 1
+        example 2
+      In hook
+      """