lib/test/unit/given/simple.rb in test_unit-given-0.1.1 vs lib/test/unit/given/simple.rb in test_unit-given-0.9.0

@@ -92,9 +92,79 @@
         # Returns the block that was executed
         def And(existing_block=nil,&block)
           Given(existing_block,&block)
         end
 
+        # Public: Continue the previous Given/When/Then in a new block.  The reason
+        # you might do this is if you wanted to use the existing block form of a
+        # Given/When/Then, but also need to do something custom, and that custom thing
+        # contradicts or overrides the flow, so an "And" wouldn't read properly.  This allows you to 
+        # write your test more fluently.
+        #
+        # existing_block - a callable object (e.g. a Proc) that will be called immediately
+        #                  by this Then.  If nil, &block is expected to be passed
+        # block          - a block given to this call that will be executed immediately
+        #                  by this Then.  If existing_block is non-nil, this is ignored
+        #
+        # Examples
+        #     
+        #     given_block = Given {
+        #       @options = {
+        #         :foo => 'bar',
+        #         :quux => 'baz',
+        #       }
+        #     }
+        #     Given then_block
+        #     And {
+        #       @name = 'Foo'
+        #     }
+        #     But {
+        #       @options[:quux] = 'BAZ'
+        #     }
+        #
+        # Returns the block that was executed
+        def But(existing_block=nil,&block)
+          Given(existing_block,&block)
+        end
+
+        # Public: Used to make clear the structure of tests using mocks.
+        # This returns a no-op, and is intended to be used with a "When"
+        # to delineate the creation of a mock in a Given, and the 
+        # expectations of a mock in a "Then"
+        #
+        # Example:
+        #
+        #     Given {
+        #       @google = mock()
+        #     }
+        #     When mocks_are_called
+        #     Then {
+        #       @google.expects(:search).with('foo').returns('bar')
+        #     }
+        #     Given {
+        #       @my_search = Search.new(@google)
+        #     }
+        #     When {
+        #       @result = @my_search.find('foo')
+        #     }
+        #     Then {
+        #       assert_equal 'Found bar',@result
+        #     }
+        #     And mocks_shouldve_been_called
+        def mocks_are_called
+          lambda {}
+        end
+
+        # Similar to #mocks_are_called, this is used to make clear what
+        # you are testing and what the assertions are.  Since many Ruby mock
+        # frameworks do not require an explicit "verify" step, you often have tests
+        # that have no explicit asserts, the assertions being simply that the mocks were called
+        # as expected.  This step, which is a no-op, allows you to document that you are 
+        # expecting mocks to be called. See the example in #mocks_are_called for usage.
+        def mocks_shouldve_been_called
+          lambda {}
+        end
+
         private
 
         def call_block_param_or_block_given(existing_block,&block)
           if existing_block.nil?
             block.call