rspec-core 2.0.0.beta.22 → 2.6.4

data/features/filtering/inclusion_filters.feature

@@ -1,11 +1,25 @@
 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.
+
+  If you set the `treat_symbols_as_metadata_keys_with_true_values` config option
+  to `true`, you can specify metadata using only symbols.
+
+  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 +29,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,36 +51,56 @@ 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:
+  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
-        c.run_all_when_everything_filtered = true
-      end
+      require "spec_helper"
 
-      describe "group 1" do
-        it "group 1 example 1" do
-        end
+      describe "group 1", :focus => true do
+        before(:all) { puts "before all in focused group" }
+        after(:all)  { puts "after all in focused group"  }
 
-        it "group 1 example 2" do
+        it "group 1 example" do
         end
       end
 
       describe "group 2" do
-        it "group 2 example 1" do
+        before(:all) { puts "before all in unfocused group" }
+        after(:all)  { puts "after all in unfocused group"  }
+
+        context "context 1" do
+          it "group 2 context 1 example 1" do
+          end
         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"
+    When I run `rspec ./spec/before_after_all_inclusion_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"
 
+  Scenario: Use symbols as metadata
+    Given a file named "symbols_as_metadata_spec.rb" with:
+      """
+      RSpec.configure do |c|
+        c.treat_symbols_as_metadata_keys_with_true_values = true
+        c.filter_run :current_example
+      end
+
+      describe "something" do
+        it "does one thing" do
+        end
+
+        it "does another thing", :current_example do
+        end
+      end
+      """
+    When I run `rspec symbols_as_metadata_spec.rb --format doc`
+    Then the output should contain "does another thing"
+    And the output should not contain "does one thing"

data/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 matched {:focus=>true}"
+    And the examples should all pass
+    And the output should contain:
+      """
+      group 1
+        group 1 example 1
+        group 1 example 2
+
+      group 2
+        group 2 example 1
+      """
+

data/features/formatters/custom_formatter.feature

@@ -1,32 +1,36 @@
 Feature: custom formatters
 
-  In order to format output/reporting to my particular needs
-  As an RSpec user
-  I want to create my own custom output formatters
+  RSpec ships with general purpose output formatters. You can tell RSpec which
+  one to use using the [`--format` command line
+  option]('../command_line/format_option').
+  
+  When RSpec's built-in output formatters don't, however, give you everything
+  you need, you can write your own custom formatter and tell RSpec to use that
+  one instead.  The simplest way is to subclass RSpec's `BaseTextFormatter`,
+  and then override just the methods that you want to modify.
 
-  @wip
-  Scenario: specdoc format
+  Scenario: custom formatter
     Given a file named "custom_formatter.rb" with:
       """
-      require "rspec/runner/formatter/base_formatter"
+      require "rspec/core/formatters/base_text_formatter"
 
-      class CustomFormatter < RSpec::Runner::Formatter::BaseFormatter
-        def initialize(options, output)
-          @output = output
+      class CustomFormatter < RSpec::Core::Formatters::BaseTextFormatter
+        def initialize(output)
+          super(output)
         end
+
         def example_started(proxy)
-          @output << "example: " << proxy.description
+          output << "example: " << proxy.description
         end
       end
       """
-    And a file named "simple_example_spec.rb" with:
+    And a file named "example_spec.rb" with:
       """
       describe "my group" do
         specify "my example" do
         end
       end
       """
-
-    When I run "rspec ./simple_example_spec.rb --require custom_formatter.rb --format CustomFormatter"
+    When I run `rspec example_spec.rb --require ./custom_formatter.rb --format CustomFormatter`
     Then the output should contain "example: my example"
     And  the exit status should be 0

data/features/formatters/text_formatter.feature

@@ -0,0 +1,43 @@
+Feature: text formatter
+
+  In order to easily see the result of running my specs
+  As an RSpec user
+  I want clear, concise, well-formatted output
+
+  Scenario: Backtrace formatting for failing specs in multiple files
+    Given a file named "string_spec.rb" with:
+      """
+      describe String do
+        it "has a failing example" do
+          "foo".reverse.should == "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
+        end
+      end
+      """
+    When I run `ruby ./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
+             expected: 11
+                  got: 12 (using ==)
+           # ./integer_spec.rb:5
+
+        2) String has a failing example
+           Failure/Error: "foo".reverse.should == "ofo"
+             expected: "ofo"
+                  got: "oof" (using ==)
+           # ./string_spec.rb:3
+      """
+

data/features/helper_methods/arbitrary_methods.feature

@@ -0,0 +1,40 @@
+Feature: arbitrary helper methods
+
+  You can define methods in any example group using Ruby's `def` keyword or
+  `define_method` method. These _helper_ methods are exposed to examples in the
+  group in which they are defined and groups nested within that group, but not
+  parent or sibling groups.
+
+  Scenario: use a method defined in the same group
+    Given a file named "example_spec.rb" with:
+      """
+      describe "an example" do
+        def help
+          :available
+        end
+
+        it "has access to methods defined in its group" do
+          help.should be(:available)
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the examples should all pass
+
+  Scenario: use a method defined in a parent group
+    Given a file named "example_spec.rb" with:
+      """
+      describe "an example" do
+        def help
+          :available
+        end
+
+        describe "in a nested group" do
+          it "has access to methods defined in its parent group" do
+            help.should be(:available)
+          end
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the examples should all pass

data/features/helper_methods/let.feature

@@ -0,0 +1,50 @@
+Feature: let and let!
+
+  Use `let` to define a memoized helper method.  The value will be cached
+  across multiple calls in the same example but not across examples.
+
+  Note that `let` is lazy-evaluated: it is not evaluated until the first time
+  the method it defines is invoked. You can use `let!` to force the method's
+  invocation before each example.
+
+  Scenario: use let to define memoized helper method
+    Given a file named "let_spec.rb" with:
+      """
+      $count = 0
+      describe "let" do
+        let(:count) { $count += 1 }
+
+        it "memoizes the value" do
+          count.should == 1
+          count.should == 1
+        end
+
+        it "is not cached across examples" do
+          count.should == 2
+        end
+      end
+      """
+    When I run `rspec let_spec.rb`
+    Then the examples should all pass
+
+  Scenario: use let! to define a memoized helper method that is called in a before hook
+    Given a file named "let_bang_spec.rb" with:
+      """
+      $count = 0
+      describe "let!" do
+        invocation_order = []
+
+        let!(:count) do
+          invocation_order << :let!
+          $count += 1
+        end
+
+        it "calls the helper method in a before hook" do
+          invocation_order << :example
+          invocation_order.should == [:let!, :example]
+          count.should == 1
+        end
+      end
+      """
+    When I run `rspec let_bang_spec.rb`
+    Then the examples should all pass

data/features/helper_methods/modules.feature

@@ -0,0 +1,149 @@
+Feature: Define helper methods in a module
+
+  You can define helper methods in a module and include it in
+  your example groups using the `config.include` configuration
+  option.  `config.extend` can be used to extend the module onto
+  your example groups so that the methods in the module are available
+  in the example groups themselves (but not in the actual examples).
+
+  You can also include or extend the module onto only certain example
+  groups by passing a metadata hash as the last argument.  Only groups
+  that match the given metadata will include or extend the module.
+
+  If you set the `treat_symbols_as_metadata_keys_with_true_values` config option
+  to `true`, you can specify metadata using only symbols.
+
+  Background:
+    Given a file named "helpers.rb" with:
+      """
+      module Helpers
+        def help
+          :available
+        end
+      end
+      """
+
+  Scenario: include a module in all example groups
+    Given a file named "include_module_spec.rb" with:
+      """
+      require './helpers'
+
+      RSpec.configure do |c|
+        c.include Helpers
+      end
+
+      describe "an example group" do
+        it "has access the helper methods defined in the module" do
+          help.should be(:available)
+        end
+      end
+      """
+    When I run `rspec include_module_spec.rb`
+    Then the examples should all pass
+
+  Scenario: extend a module in all example groups
+    Given a file named "extend_module_spec.rb" with:
+      """
+      require './helpers'
+
+      RSpec.configure do |c|
+        c.extend Helpers
+      end
+
+      describe "an example group" do
+        puts "Help is #{help}"
+
+        it "does not have access to the helper methods defined in the module" do
+          expect { help }.to raise_error(NameError)
+        end
+      end
+      """
+    When I run `rspec extend_module_spec.rb`
+    Then the examples should all pass
+    And the output should contain "Help is available"
+
+  Scenario: include a module in only some example groups
+    Given a file named "include_module_in_some_groups_spec.rb" with:
+      """
+      require './helpers'
+
+      RSpec.configure do |c|
+        c.include Helpers, :foo => :bar
+      end
+
+      describe "an example group with matching metadata", :foo => :bar do
+        it "has access the helper methods defined in the module" do
+          help.should be(:available)
+        end
+      end
+
+      describe "an example group without matching metadata" do
+        it "does not have access to the helper methods defined in the module" do
+          expect { help }.to raise_error(NameError)
+        end
+      end
+      """
+    When I run `rspec include_module_in_some_groups_spec.rb`
+    Then the examples should all pass
+
+  Scenario: extend a module in only some example groups
+    Given a file named "extend_module_in_only_some_groups_spec.rb" with:
+      """
+      require './helpers'
+
+      RSpec.configure do |c|
+        c.extend Helpers, :foo => :bar
+      end
+
+      describe "an example group with matching metadata", :foo => :bar do
+        puts "In a matching group, help is #{help}"
+
+        it "does not have access to the helper methods defined in the module" do
+          expect { help }.to raise_error(NameError)
+        end
+      end
+
+      describe "an example group without matching metadata" do
+        puts "In a non-matching group, help is #{help rescue 'not available'}"
+
+        it "does not have access to the helper methods defined in the module" do
+          expect { help }.to raise_error(NameError)
+        end
+      end
+      """
+    When I run `rspec extend_module_in_only_some_groups_spec.rb`
+    Then the examples should all pass
+    And the output should contain "In a matching group, help is available"
+    And the output should contain "In a non-matching group, help is not available"
+
+  Scenario: use symbols as metadata
+    Given a file named "symbols_as_metadata_spec.rb" with:
+      """
+      require './helpers'
+
+      RSpec.configure do |c|
+        c.treat_symbols_as_metadata_keys_with_true_values = true
+        c.include Helpers, :include_helpers
+        c.extend  Helpers, :extend_helpers
+      end
+
+      describe "an example group with matching include metadata", :include_helpers do
+        puts "In a group not matching the extend filter, help is #{help rescue 'not available'}"
+
+        it "has access the helper methods defined in the module" do
+          help.should be(:available)
+        end
+      end
+
+      describe "an example group with matching extend metadata", :extend_helpers do
+        puts "In a group matching the extend filter, help is #{help}"
+
+        it "does not have access to the helper methods defined in the module" do
+          expect { help }.to raise_error(NameError)
+        end
+      end
+      """
+    When I run `rspec symbols_as_metadata_spec.rb`
+    Then the examples should all pass
+    And the output should contain "In a group not matching the extend filter, help is not available"
+    And the output should contain "In a group matching the extend filter, help is available"