rspec-core 2.0.0.beta.22 → 2.6.4

data/features/hooks/around_hooks.feature

@@ -1,52 +1,66 @@
 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:
+
+  WARNING: around hooks do not share state with the example the way before and
+  after hooks do. This means that you can not share instance variables between
+  around hooks and examples.
+
+  Also, mock frameworks are set up and torn down within the context of running
+  the example, so you can not interact with them directly in around hooks.
+
+  Scenario: use the example as a proc 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
+      describe "around hook" do
+        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 +68,24 @@ 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: access the example metadata
+    Given a file named "example_spec.rb" with:
+      """
+      describe "something" do
+        around(:each) do |example|
+          puts example.metadata[:foo]
+          example.run
+        end
+
+        it "does something", :foo => "this should show up in the output" do
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the output should contain "this should show up in the output"
+
+  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 +101,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 +110,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 +132,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 +143,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 +165,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 +175,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 +196,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 +210,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 +220,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 +233,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,41 +241,41 @@ 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:
-    """
-    describe "if there are multiple around hooks in the same scope" do
-      around(:each) do |example|
-        puts "first around hook before"
-        example.run
-        puts "first around hook after"
-      end
+  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|
+          puts "first around hook before"
+          example.run
+          puts "first around hook after"
+        end
 
-      around(:each) do |example|
-        puts "second around hook before"
-        example.run
-        puts "second around hook after"
-      end
+        around(:each) do |example|
+          puts "second around hook before"
+          example.run
+          puts "second around hook after"
+        end
 
-      it "they should all be run" do
-        puts "in the example"
-        1.should == 1
+        it "they should all be run" do
+          puts "in the example"
+          1.should == 1
+        end
       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:
-    """
-    first around hook before
-    second around hook before
-    in the example
-    second around hook after
-    first around hook after
-    """
+      """
+      first around hook before
+      second around hook before
+      in the example
+      second around hook after
+      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 +323,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:
     """

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:
@@ -57,8 +52,8 @@ Feature: before and after hooks
         end
       end
       """
-    When I run "rspec ./before_each_spec.rb"
-    Then the output should contain "3 examples, 0 failures"
+    When I run `rspec before_each_spec.rb`
+    Then the examples should all pass
 
   Scenario: define before(:all) block in example group
     Given a file named "before_all_spec.rb" with:
@@ -91,11 +86,11 @@ Feature: before and after hooks
         end
       end
       """
-    When I run "rspec ./before_all_spec.rb"
-    Then the output should contain "3 examples, 0 failures"
+    When I run `rspec before_all_spec.rb`
+    Then the examples should all pass
 
-    When I run "rspec ./before_all_spec.rb:15"
-    Then the output should contain "1 example, 0 failures"
+    When I run `rspec before_all_spec.rb:15`
+    Then the examples should all pass
 
   Scenario: failure in before(:all) block
     Given a file named "before_all_spec.rb" with:
@@ -114,25 +109,65 @@ Feature: before and after hooks
         after(:all) do
           puts "after all ran"
         end
+
+        describe "nested group" do
+          it "fails this third example" do
+          end
+
+          it "fails this fourth example" do
+          end
+
+          describe "yet another level deep" do
+            it "fails this last example" do
+            end
+          end
+        end
       end
       """
-    When I run "rspec ./before_all_spec.rb --format documentation"
-    Then the output should contain "2 examples, 2 failures"
+    When I run `rspec before_all_spec.rb --format documentation`
+    Then the output should contain "5 examples, 5 failures"
     And the output should contain:
       """
       an error in before(:all)
         fails this example (FAILED - 1)
         fails this example, too (FAILED - 2)
+        nested group
+          fails this third example (FAILED - 3)
+          fails this fourth example (FAILED - 4)
+          yet another level deep
+            fails this last example (FAILED - 5)
       after all ran
       """
 
-    When I run "rspec ./before_all_spec.rb:9 --format documentation"
+    When I run `rspec before_all_spec.rb:9 --format documentation`
     Then the output should contain "1 example, 1 failure"
     And the output should contain:
       """
       an error in before(:all)
         fails this example, too (FAILED - 1)
-      after all ran
+      """
+
+  Scenario: failure in after(:all) block
+    Given a file named "after_all_spec.rb" with:
+      """
+      describe "an error in after(:all)" do
+        after(:all) do
+          raise StandardError.new("Boom!")
+        end
+
+        it "passes this example" do
+        end
+
+        it "passes this example, too" do
+        end
+      end
+      """
+    When I run `rspec after_all_spec.rb`
+    Then the examples should all pass
+    And the output should contain:
+      """
+      An error occurred in an after(:all) hook.
+        StandardError: Boom!
       """
 
   Scenario: define before and after blocks in configuration
@@ -162,8 +197,8 @@ Feature: before and after hooks
         end
       end
       """
-    When I run "rspec ./befores_in_configuration_spec.rb"
-    Then the output should contain "2 examples, 0 failures"
+    When I run `rspec befores_in_configuration_spec.rb`
+    Then the examples should all pass
 
   Scenario: before/after blocks are run in order
     Given a file named "ensure_block_order_spec.rb" with:
@@ -192,7 +227,7 @@ Feature: before and after hooks
         end
       end
       """
-    When I run "rspec ./ensure_block_order_spec.rb"
+    When I run `rspec ensure_block_order_spec.rb`
     Then the output should contain:
       """
       before all
@@ -237,7 +272,7 @@ Feature: before and after hooks
         end
       end
       """
-    When I run "rspec configuration_spec.rb"
+    When I run `rspec configuration_spec.rb`
     Then the output should contain:
       """
       before suite
@@ -278,8 +313,8 @@ Feature: before and after hooks
 
       end
       """
-    When I run "rspec ./before_and_after_all_spec.rb"
-    Then the output should contain "2 examples, 0 failures"
+    When I run `rspec before_and_after_all_spec.rb`
+    Then the examples should all pass
     And the output should contain:
       """
       outer before all
@@ -288,8 +323,8 @@ Feature: before and after hooks
       outer after all
       """
 
-    When I run "rspec ./before_and_after_all_spec.rb:14"
-    Then the output should contain "1 example, 0 failures"
+    When I run `rspec before_and_after_all_spec.rb:14`
+    Then the examples should all pass
     And the output should contain:
       """
       outer before all
@@ -298,8 +333,8 @@ Feature: before and after hooks
       outer after all
       """
 
-    When I run "rspec ./before_and_after_all_spec.rb:6"
-    Then the output should contain "1 example, 0 failures"
+    When I run `rspec before_and_after_all_spec.rb:6`
+    Then the examples should all pass
     And the output should contain:
       """
       outer before all
@@ -333,8 +368,8 @@ Feature: before and after hooks
         end
       end
       """
-    When I run "rspec before_all_spec.rb"
-    Then the output should contain "3 examples, 0 failures"
+    When I run `rspec before_all_spec.rb`
+    Then the examples should all pass
 
   Scenario: before/after all blocks have access to state
     Given a file named "before_and_after_all_spec.rb" with:
@@ -364,13 +399,12 @@ Feature: before and after hooks
         end
 
         after(:all) do
-          # p @outer_state.nil?
           @outer_state.should eq("set in outer before all")
         end
       end
       """
-    When I run "rspec ./before_and_after_all_spec.rb"
-    Then the output should contain "2 examples, 0 failures"
+    When I run `rspec before_and_after_all_spec.rb`
+    Then the examples should all pass
 
   Scenario: exception in before(:each) is captured and reported as failure
     Given a file named "error_in_before_each_spec.rb" with:
@@ -384,6 +418,6 @@ Feature: before and after hooks
         end
       end
       """
-    When I run "rspec ./error_in_before_each_spec.rb"
+    When I run `rspec error_in_before_each_spec.rb`
     Then the output should contain "1 example, 1 failure"
     And the output should contain "this error"