rspec-core 2.6.0 → 2.7.0.rc1

data/README.md

@@ -3,7 +3,7 @@
 RSpec Core provides the structure for writing executable examples of how your
 code should behave.
 
-[![build status](http://travis-ci.org/rspec/rspec-core.png)](http://travis-ci.org/rspec/rspec-core)
+[![build status](https://secure.travis-ci.org/rspec/rspec-core.png)](http://travis-ci.org/rspec/rspec-core)
 
 ## Documentation
 

data/features/Upgrade.md

@@ -1,3 +1,14 @@
+# rspec-core-2.7 (not yet released - coming soon)
+
+## `--default_path`
+
+Add the following to `.rspec`:
+
+    # in .rspec
+    --default_path spec
+
+And now you can just type `rspec` to run all the specs in the `spec` directory.
+
 # rspec-core-2.6
 
 ## new APIs for sharing content

data/features/command_line/exit_status.feature

@@ -1,7 +1,7 @@
 Feature: exit status
 
-  In order to fail the build when it should, the spec CLI exits with an
-  appropriate exit status
+  The rspec command exits with an exit status of 0 if all examples pass,
+  and 1 if any examples fail.
 
   Scenario: exit with 0 when all examples pass
     Given a file named "ok_spec.rb" with:
@@ -42,7 +42,7 @@ Feature: exit status
     When I run `rspec nested_ko_spec.rb`
     Then the exit status should be 1
     And the output should contain "1 example, 1 failure"
-      
+
   Scenario: exit with 0 when no examples are run
     Given a file named "a_no_examples_spec.rb" with:
       """
@@ -50,3 +50,20 @@ Feature: exit status
     When I run `rspec a_no_examples_spec.rb`
     Then the exit status should be 0
     And the output should contain "0 examples"
+
+  @wip
+  Scenario: exit with rspec's exit code when an at_exit hook is added upstream
+    Given a file named "exit_at_spec.rb" with:
+      """
+      require 'rspec/autorun'
+
+      describe "exit 0 at_exit" do
+        it "does not interfere with rspec's exit code" do
+          at_exit { exit 0 }
+          fail
+        end
+      end
+      """
+    When I run `rspec exit_at_spec.rb`
+    Then the exit status should be 1
+    And the output should contain "1 example, 1 failure"

data/features/command_line/format_option.feature

@@ -19,6 +19,14 @@ Feature: --format option
 
     $ rspec spec --format documentation:rspec.output.txt
 
+  `rspec --help` lists available formatters:
+
+      [p]rogress (default - dots)
+      [d]ocumentation (group and example names)
+      [h]tml
+      [t]extmate
+      custom formatter class name
+
   Background:
     Given a file named "example_spec.rb" with:
       """

data/features/command_line/line_number_appended_to_path.feature

@@ -1,6 +1,6 @@
 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.
+  To run one or more examples or groups, you can append the line number to the path, e.g.
 
       rspec path/to/example_spec.rb:37
   
@@ -27,6 +27,15 @@ Feature: line number appended to file path
 
       end
       """
+    And a file named "example2_spec.rb" with:
+      """
+      describe "yet another group" do
+        it "first example in second file" do
+        end
+        it "second example in second file" do
+        end
+      end
+      """
 
   Scenario: nested groups - outer group on declaration line
     When I run `rspec example_spec.rb:1 --format doc`
@@ -104,3 +113,28 @@ Feature: line number appended to file path
     And the output should contain "second example in outer group"
     But the output should not contain "first example in outer group"
     And the output should not contain "example in nested group"
+
+  Scenario: specified multiple times for different files
+    When I run `rspec example_spec.rb:7 example2_spec.rb:4 --format doc`
+    Then the examples should all pass
+    And the output should contain "second example in outer group"
+    And the output should contain "second example in second file"
+    But the output should not contain "first example in outer group"
+    And the output should not contain "nested group"
+    And the output should not contain "first example in second file"
+
+  Scenario: specified multiple times for the same file with multiple arguments
+    When I run `rspec example_spec.rb:7 example_spec.rb:11 --format doc`
+    Then the examples should all pass
+    And the output should contain "second example in outer group"
+    And the output should contain "nested group"
+    But the output should not contain "first example in outer group"
+    And the output should not contain "second file"
+
+  Scenario: specified multiple times for the same file with a single argument
+    When I run `rspec example_spec.rb:7:11 --format doc`
+    Then the examples should all pass
+    And the output should contain "second example in outer group"
+    And the output should contain "nested group"
+    But the output should not contain "first example in outer group"
+    And the output should not contain "second file"

data/features/command_line/line_number_option.feature

@@ -1,9 +1,11 @@
 Feature: --line_number option
 
-  To run a single example or group, you can use the --line_number option:
+  To run a examples or groups by line numbers, one can use the --line_number option:
 
       rspec path/to/example_spec.rb --line_number 37
 
+  This option can be specified multiple times.
+
   Scenario: standard examples
     Given a file named "example_spec.rb" with:
       """
@@ -18,13 +20,24 @@ Feature: --line_number option
         it "should be < 10" do
           9.should be < 10
         end
-        
+
+        it "should be 3 squared" do
+          9.should be 3*3
+        end
+
       end
       """
     When I run `rspec example_spec.rb --line_number 5 --format doc`
     Then the examples should all pass
-    Then the output should contain "should be > 8"
+    And the output should contain "should be > 8"
     But the output should not contain "should be < 10"
+    And the output should not contain "should be 3*3"
+
+    When I run `rspec example_spec.rb --line_number 5 --line_number 9 --format doc`
+    Then the examples should all pass
+    And the output should contain "should be > 8"
+    And the output should contain "should be < 10"
+    But the output should not contain "should be 3*3"
 
   Scenario: one liner
     Given a file named "example_spec.rb" with:

data/features/command_line/pattern_option.feature

@@ -0,0 +1,31 @@
+Feature: pattern option
+
+  By default, RSpec loads files matching the pattern:
+
+      "spec/**/*_spec.rb"
+
+  Use the `--pattern` option to declare a different pattern.
+
+  Scenario: default pattern
+    Given a file named "spec/example_spec.rb" with:
+      """
+      describe "addition" do
+        it "adds things" do
+          (1 + 2).should eq(3)
+        end
+      end
+      """
+    When I run `rspec`
+    Then the output should contain "1 example, 0 failures"
+
+  Scenario: override the default pattern on the command line
+    Given a file named "spec/example.spec" with:
+      """
+      describe "addition" do
+        it "adds things" do
+          (1 + 2).should eq(3)
+        end
+      end
+      """
+    When I run `rspec --pattern "spec/**/*.spec"`
+    Then the output should contain "1 example, 0 failures"

data/features/command_line/rake_task.feature

@@ -20,7 +20,7 @@ Feature: rake task
       end
       """
     When I run `rake`
-    Then the stderr should contain "ruby -S rspec"
+    Then the output should contain "ruby -S rspec"
     Then the exit status should be 0
 
   Scenario: default options with failing spec (exit status is 1)

data/features/command_line/ruby.feature

@@ -0,0 +1,22 @@
+Feature: run with ruby command
+
+  You can use the `ruby` command to run specs. You just need to require
+  `rspec/autorun`. 
+  
+  Generally speaking, you're better off using the `rspec` command, which
+  requires `rspec/autorun` for you, but some tools only work with the `ruby`
+  command.
+
+  Scenario:
+    Given a file named "example_spec.rb" with:
+      """
+      require 'rspec/autorun'
+
+      describe 1 do
+        it "is < 2" do
+          1.should be < 2
+        end
+      end
+      """
+    When I run `ruby example_spec.rb`
+    Then the output should contain "1 example, 0 failures"

data/features/configuration/default_path.feature

@@ -0,0 +1,38 @@
+Feature: default_path
+
+  As of rspec-2.7 (not yet released), you can just type `rspec` to run all
+  specs that live in the `spec` directory.
+
+  This is supported by a `--default_path` option, which is set to `spec` by
+  default. If you prefer to keep your specs in a different directory, or assign
+  an individual file to `--default_path`, you can do so on the command line or
+  in a configuration file (`.rspec`, `~/.rspec`, or a custom file).
+
+  NOTE: this option is not supported on `RSpec.configuration`, as it needs to
+  be set before spec files are loaded.
+
+  Scenario: run `rspec` with default default_path (`spec` directory)
+    Given a file named "spec/example_spec.rb" with:
+      """
+      describe "an example" do
+        it "passes" do
+        end
+      end
+      """
+    When I run `rspec`
+    Then the output should contain "1 example, 0 failures"
+    
+  Scenario: run `rspec` with customized default_path
+    Given a file named ".rspec" with:
+      """
+      --default_path behavior
+      """
+    Given a file named "behavior/example_spec.rb" with:
+      """      
+      describe "an example" do
+        it "passes" do
+        end
+      end
+      """
+    When I run `rspec`
+    Then the output should contain "1 example, 0 failures"

data/features/example_groups/{shared_example_group.feature → shared_examples.feature}

@@ -8,47 +8,70 @@ Feature: shared examples
   A shared group is included in another group using any of:
   
       include_examples "name"      # include the examples in the current context
-
       it_behaves_like "name"       # include the examples in a nested context
       it_should_behave_like "name" # include the examples in a nested context
 
-  Scenario: shared examples group included in two groups
+  WARNING: Files containing shared groups must be loaded before the files that
+  use them.  While there are conventions to handle this, RSpec does _not_ do
+  anything special (like autoload). Doing so would require a strict naming
+  convention for files that would break existing suites.
+
+  CONVENTIONS:
+
+  1.  The simplest approach is to require files with shared examples explicitly
+      from the files that use them. Keep in mind that RSpec adds the `spec`
+      directory to the `LOAD_PATH`, so you can say `require
+      'shared_examples_for_widgets'` to require a file at
+      `#{PROJECT_ROOT}/spec/shared_examples_for_widgets.rb`.
+
+  2.  Put files containing shared examples in `spec/support/` and require files
+      in that directory from `spec/spec_helper.rb`:
+
+          Dir["spec/support/**/*.rb"].each {|f| require f}
+
+      This is included in the generated `spec/spec_helper.rb` file in
+      `rspec-rails`
+
+  3. When all of the groups that include the shared group, just declare
+     the shared group in the same file.
+
+  Scenario: shared examples group included in two groups in one file
     Given a file named "collection_spec.rb" with:
-    """
-    require "set"
+      """
+      require "set"
 
-    shared_examples "a collection" do
-      let(:collection) { described_class.new([7, 2, 4]) }
+      shared_examples "a collection" do
+        let(:collection) { described_class.new([7, 2, 4]) }
 
-      context "initialized with 3 items" do
-        it "says it has three items" do
-          collection.size.should eq(3)
+        context "initialized with 3 items" do
+          it "says it has three items" do
+            collection.size.should eq(3)
+          end
         end
-      end
 
-      describe "#include?" do
-        context "with an an item that is in the collection" do
-          it "returns true" do
-            collection.include?(7).should be_true
+        describe "#include?" do
+          context "with an an item that is in the collection" do
+            it "returns true" do
+              collection.include?(7).should be_true
+            end
           end
-        end
 
-        context "with an an item that is not in the collection" do
-          it "returns false" do
-            collection.include?(9).should be_false
+          context "with an an item that is not in the collection" do
+            it "returns false" do
+              collection.include?(9).should be_false
+            end
           end
         end
       end
-    end
 
-    describe Array do
-      it_behaves_like "a collection"
-    end
+      describe Array do
+        it_behaves_like "a collection"
+      end
 
-    describe Set do
-      it_behaves_like "a collection"
-    end
-    """
+      describe Set do
+        it_behaves_like "a collection"
+      end
+      """
     When I run `rspec collection_spec.rb --format documentation`
     Then the examples should all pass
     And the output should contain:

data/features/expectation_framework_integration/configure_expectation_framework.feature

@@ -64,7 +64,7 @@ Feature: configure expectation framework
           assert 5 > 4, "expected 5 to be greater than 4"
         end
 
-        it "is less than 4" do
+        it "is less than 6" do
           5.should be < 6
         end
       end

data/features/filtering/inclusion_filters.feature

@@ -1,18 +1,17 @@
 Feature: inclusion filters
 
-  You can restrict which examples are run by declaring an inclusion filter. The
+  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.
 
-  If you set the `treat_symbols_as_metadata_keys_with_true_values` config option
-  to `true`, you can specify metadata using only symbols.
+  You can specify metadata using only symbols if you set the
+  `treat_symbols_as_metadata_keys_with_true_values` config option to `true`.
 
   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
+        c.filter_run_including :focus => true
       end
       """
 

data/features/formatters/text_formatter.feature

@@ -9,35 +9,38 @@ Feature: text formatter
       """
       describe String do
         it "has a failing example" do
-          "foo".reverse.should == "ofo"
+          "foo".reverse.should eq("ofo")
         end
       end
       """
     And a file named "integer_spec.rb" with:
       """
-      require 'rspec/autorun'
-
       describe Integer do
         it "has a failing example" do
-          (7 + 5).should == 11
+          (7 + 5).should eq(11)
         end
       end
       """
-    When I run `ruby ./integer_spec.rb ./string_spec.rb`
+    When I run `rspec integer_spec.rb string_spec.rb`
     Then the backtrace-normalized output should contain:
       """
       Failures:
-
+      
         1) Integer has a failing example
-           Failure/Error: (7 + 5).should == 11
+           Failure/Error: (7 + 5).should eq(11)
+             
              expected: 11
-                  got: 12 (using ==)
-           # ./integer_spec.rb:5
-
+                  got: 12
+             
+             (compared using ==)
+           # ./integer_spec.rb:3
+      
         2) String has a failing example
-           Failure/Error: "foo".reverse.should == "ofo"
+           Failure/Error: "foo".reverse.should eq("ofo")
+             
              expected: "ofo"
-                  got: "oof" (using ==)
+                  got: "oof"
+             
+             (compared using ==)
            # ./string_spec.rb:3
       """
-

data/features/helper_methods/let.feature

@@ -15,12 +15,12 @@ Feature: let and let!
         let(:count) { $count += 1 }
 
         it "memoizes the value" do
-          count.should == 1
-          count.should == 1
+          count.should eq(1)
+          count.should eq(1)
         end
 
         it "is not cached across examples" do
-          count.should == 2
+          count.should eq(2)
         end
       end
       """
@@ -42,7 +42,7 @@ Feature: let and let!
         it "calls the helper method in a before hook" do
           invocation_order << :example
           invocation_order.should == [:let!, :example]
-          count.should == 1
+          count.should eq(1)
         end
       end
       """

data/features/hooks/around_hooks.feature

@@ -259,7 +259,7 @@ Feature: around hooks
 
         it "they should all be run" do
           puts "in the example"
-          1.should == 1
+          1.should eq(1)
         end
       end
       """

data/features/hooks/before_and_after_hooks.feature

@@ -187,12 +187,12 @@ Feature: before and after hooks
       describe "stuff in before blocks" do
         describe "with :all" do
           it "should be available in the example" do
-            @before_all.should == "before all"
+            @before_all.should eq("before all")
           end
         end
         describe "with :each" do
           it "should be available in the example" do
-            @before_each.should == "before each"
+            @before_each.should eq("before each")
           end
         end
       end
@@ -363,7 +363,7 @@ Feature: before and after hooks
 
         describe "nested in parallel" do
           it "access state set in before(:all)" do
-            @value.should == 123
+            @value.should eq(123)
           end
         end
       end

data/features/hooks/filtering.feature

@@ -1,12 +1,19 @@
 Feature: filters
 
-  `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.
+  `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.
 
-  If you set the `treat_symbols_as_metadata_keys_with_true_values` config option
-  to `true`, you can specify metadata using only symbols.
+      RSpec.configure do |c|
+        c.before(:each, :type => :model) do
+        end
+      end
+
+      describe "something", :type => :model do
+      end
+
+  You can specify metadata using only symbols if you set the
+  `treat_symbols_as_metadata_keys_with_true_values` config option to `true`.
 
   Scenario: filter `before(:each)` hooks using arbitrary metadata
     Given a file named "filter_before_each_hooks_spec.rb" with:

data/features/metadata/user_defined.feature

@@ -12,9 +12,11 @@ Feature: User-defined metadata
   behavior in RSpec 3) that allows you to specify metadata using just
   symbols:
 
-    RSpec.configure do |c|
-      c.treat_symbols_as_metadata_keys_with_true_values = true
-    end
+  ```ruby
+  RSpec.configure do |c|
+    c.treat_symbols_as_metadata_keys_with_true_values = true
+  end
+  ```
 
   Each symbol passed as an argument to `describe`, `context` or `it` will
   be a key in the metadata hash, with a corresponding value of `true`.
@@ -24,7 +26,7 @@ Feature: User-defined metadata
       """
       describe "a group with user-defined metadata", :foo => 17 do
         it 'has access to the metadata in the example' do
-          example.metadata[:foo].should == 17
+          example.metadata[:foo].should eq(17)
         end
 
         it 'does not have access to metadata defined on sub-groups' do
@@ -33,11 +35,11 @@ Feature: User-defined metadata
 
         describe 'a sub-group with user-defined metadata', :bar => 12 do
           it 'has access to the sub-group metadata' do
-            example.metadata[:foo].should == 17
+            example.metadata[:foo].should eq(17)
           end
 
           it 'also has access to metadata defined on parent groups' do
-            example.metadata[:bar].should == 12
+            example.metadata[:bar].should eq(12)
           end
         end
       end
@@ -50,13 +52,13 @@ Feature: User-defined metadata
       """
       describe "a group with no user-defined metadata" do
         it 'has an example with metadata', :foo => 17 do
-          example.metadata[:foo].should == 17
+          example.metadata[:foo].should eq(17)
           example.metadata.should_not include(:bar)
         end
 
         it 'has another example with metadata', :bar => 12, :bazz => 33 do
-          example.metadata[:bar].should == 12
-          example.metadata[:bazz].should == 33
+          example.metadata[:bar].should eq(12)
+          example.metadata[:bazz].should eq(33)
           example.metadata.should_not include(:foo)
         end
       end
@@ -99,7 +101,7 @@ Feature: User-defined metadata
         end
 
         it 'can still use a hash for metadata' do
-          example.metadata[:bug].should == 73
+          example.metadata[:bug].should eq(73)
         end
 
         it 'can define simple metadata on an example', :special do