rspec 0.5.4 → 0.5.5

data/doc/src/tutorials/stack_01.page

@@ -220,5 +220,7 @@ Finished in 0.000256 seconds
 
 And thus we have completed our first specification: "A new stack should be empty"
 
+If you've never had any experience, returning <code>true</code> from <code>empty?</code> may seem a bit strange. Even if you have, you may not feel that the cycle is complete yet. "Test-Code-Refactor", right? Or rather "Spec-Code-Refactor". At this point, we should refactor to eliminate duplication, and you might argue that there is duplication between the spec expecting true and the method returning true. The problem right now is that we have no specs with expectations of the stack being anything other than empty. Any conditional logic we might implement here would be adding new behaviour. Refactoring is defined as changing structure without changing behaviour. And so, as much as we'd like to change <code>true</code> to something more useful, we need to take that urge and recognize that, in this case, we have a deficiency in our specifications - not in the code.
+
 <a href="stack_02.html">Next</a>
 

data/doc/src/tutorials/stack_02.page

@@ -1,10 +1,10 @@
 h2. A Simple Stack
 
-h3. An Empty Stack
+h3. Choosing the next Specification
 
-So now we know that when you first create a stack it is empty. What's next? We could make some more specifications about a new stack, but the fact that it is an empty stack is more interesting from a behavioural perspective than a new stack. So let's start talking about the behaviour of an <em>empty</em> stack.
+We left our code in a state in which it could not be refactored because adding conditional logic would be adding new behaviour at this point (which is not refactoring). We wanted to refactor because we had a hard-coded return value from a method that is begging for some conditional logic. So let's choose a specification to focus on next that will help us to address that. We want a specification that will result in a non-empty stack.
 
-We all know the standard messages we want on a stack: some variation of push, pop and top. What should happen when we send 'push' to an empty stack? The usual first move is to specify that it has a size of 1, but we don't have a <code>size</code> method, nor do we want one if we can avoid it. We can, however, specify that it is no longer empty after a push.
+Since an "empty stack" seems more interesting from a behavioural perspective than a "new stack", let's start talking about the behaviour of an <em>empty</em> stack.
 
 <ruby>
 context "An empty stack" do
@@ -111,7 +111,9 @@ Finished in 0.000427 seconds
 2 contexts, 2 specifications, 0 failures
 </pre>
 
-Remember, add a little bit at a time, run the specs and resolve name errors (these are like compilation failures in java and C#). Next we set our expectation:
+The idea is to add a little bit of spec, just enough to get some kind of failure, then just enough code to get the code to meet the expectations expressed in the spec. In this case, the NameError was like a compilation failure in java or C#.
+
+Next we set our expectation:
 
 <ruby>
 context "An empty stack" do

data/doc/src/tutorials/stack_03.page

@@ -4,13 +4,13 @@ h3. What to specify next?
 
 Picking the next thing to specify is always a challenge (just as picking the next thing to test is in TDD). Ideally, you want to specify the simplest thing that you can imagine implementing. Of course, thinking about implementation seems to fly in the face of a core tenet of TDD and BDD: focus on interface - focus on behaviour. So you have a couple of opposing forces and notions guiding this decision. The bottom line is that it's not that important which one you pick next. The important thing is that as soon as you recognize that you've headed down the wrong path (one which requires a lot of implementation to meet the newest specification), roll back immediately and pick a different "next step".
 
-For our problem, there seem to be (at least) two logical potential next steps. We know that pushing on to an empty stack results in the stack no longer being empty. So one logical next step might be to specify how an empty stack behaves when sending it a different message. Another might be to send push to a non-empty stack. But what I'd really like to know is what happened to the object we just pushed!
+For our problem, there seem to be (at least) two logical potential next steps. We know that pushing on to an empty stack results in the stack no longer being empty. So one logical next step might be to specify how an empty stack behaves when sending it a different message. Another might be to send push to a non-empty stack. But what I'd really like to know is what happened to the item we just pushed onto the stack!
 
-To specify that, we have to move diagonally a bit. We need to specify the stack's response to a new message starting in a new state - a new context. We're going to start with a stack with one item already pushed onto it and specify what happens when you send it 'top'. Why top and not pop? In this case, top is simpler than pop - top just returns the top object, while pop also removes it from the stack.
+To specify that, we have to move diagonally a bit. We need to specify the stack's response to a new message starting in a new state - a new context. We're going to start with a stack with one item already pushed onto it and specify what happens when you send it 'top'. Why top and not pop? In this case, top is simpler than pop - top just returns the top item, while pop also removes it from the stack.
 
 h3. Send top to a stack with one item
 
-Start by adding a new context in stack_spec.rb. Remember, the context is an object (or set of objects) in a known state, so we'll go ahead and add the setup right away
+Start by adding a new context and spec in stack_spec.rb.
 
 <ruby>
 context "A stack with one item" do
@@ -26,7 +26,6 @@ A new stack
 - should be empty
 
 An empty stack
-- should keep its mouth shut when you send it 'push'
 - should not be empty after 'push'
 
 A stack with one item
@@ -58,7 +57,6 @@ A new stack
 - should be empty
 
 An empty stack
-- should keep its mouth shut when you send it 'push'
 - should not be empty after 'push'
 
 A stack with one item
@@ -91,7 +89,6 @@ A new stack
 - should be empty
 
 An empty stack
-- should keep its mouth shut when you send it 'push'
 - should not be empty after 'push'
 
 A stack with one item
@@ -124,7 +121,6 @@ A new stack
 - should be empty
 
 An empty stack
-- should keep its mouth shut when you send it 'push'
 - should not be empty after 'push'
 
 A stack with one item
@@ -158,7 +154,6 @@ A new stack
 - should be empty
 
 An empty stack
-- should keep its mouth shut when you send it 'push'
 - should not be empty after 'push'
 
 A stack with one item
@@ -169,11 +164,11 @@ Finished in 0.000744 seconds
 3 contexts, 4 specifications, 0 failures
 </pre>
 
-So now we've hard coded something even more obviously wrong than before. True/false/empty, etc - that was all a bit more subtle. This case is much more obvious. There are a couple of ways to view the problem. One is that we've got this hard coded value. The bigger problem is that we now have duplication between the specs and the code. We want to get rid of it. How do you eliminate duplication? Refactor! And since we have a suite (albeit small) of passing specifications, we can now refactor safely.
+Again we have duplication between the specs and the code ("one item") and we want to get rid of it. This time, however, we have enough specs and entry points that there is actually something to refactor to.
 
 If you're not familiar with refactoring, check out <a href="http://www.refactoring.com/">http://www.refactoring.com/</a>. We'll do some now, but we won't be examining the steps too deeply. The basic idea is that we want to change structure/implementation without affecting behaviour. Running the specs and watching them pass between each step proves that the behaviour is in tact.
 
-First, we keep track of the item we add...
+First, we save the item we add and return that from <code>top</code> ...
 
 <ruby>
 class Stack
@@ -200,7 +195,6 @@ A new stack
 - should be empty
 
 An empty stack
-- should keep its mouth shut when you send it 'push'
 - should not be empty after 'push'
 
 A stack with one item
@@ -211,7 +205,7 @@ Finished in 0.000846 seconds
 3 contexts, 4 specifications, 0 failures
 </pre>
 
-Now let's use that to determine "emptiness"...
+Now let's use the item to determine "emptiness"...
 
 <ruby>
 class Stack
@@ -238,7 +232,6 @@ A new stack
 - should be empty
 
 An empty stack
-- should keep its mouth shut when you send it 'push'
 - should not be empty after 'push'
 
 A stack with one item
@@ -272,7 +265,6 @@ A new stack
 - should be empty
 
 An empty stack
-- should keep its mouth shut when you send it 'push'
 - should not be empty after 'push'
 
 A stack with one item
@@ -283,7 +275,7 @@ Finished in 0.000737 seconds
 3 contexts, 4 specifications, 0 failures
 </pre>
 
-You may wonder why we chose to refactor at this point, but we didn't the first time we had duplication between the tests and code. Remember the first step we took? It was to return <code>true</code> for <code>empty?</code>. Though more subtle than "one item", that was duplication between the specs and the code. The problem was that we didn't have any other methods on the stack that we could use. We would have had to contrive implementation that we had no specification for. At this point, however, we were able to make use of data we were passing into the the stack from the specification, so we were in a position to change things without adding things we hadn't specified yet.
+So this time we were able to refactor, and in doing so not only reduce the duplication but also reduce the size of the stack class. Sweet.
 
 To be continued...
 

data/doc/src/tutorials/stack_04.page

@@ -1,4 +1,4 @@
-h2. A Simple Stack - when a new expectation passes
+h2. A Simple Stack - when a new expectation passes - IN PROGRESS - DISREGARD THIS PAGE
 
 At this point stack_spec.rb should look like this...
 
@@ -20,10 +20,6 @@ context "An empty stack" do
     @stack = Stack.new
   end
 
-  specify "should keep its mouth shut when you send it 'push'" do
-    lambda { @stack.push Object.new }.should.not.raise
-  end
-
   specify "should not be empty after 'push'" do
     @stack.push 37
     @stack.should_not_be_empty
@@ -67,7 +63,6 @@ A new stack
 - should be empty
 
 An empty stack
-- should keep its mouth shut when you send it 'push'
 - should not be empty after 'push'
 
 A stack with one item
@@ -78,7 +73,11 @@ Finished in 0.000741 seconds
 3 contexts, 4 specifications, 0 failures
 </pre>
 
-Again, a really nice feature of using the <code>--format specdoc</code> option (<code>-f s</code> for short) is that you can easily see all of the contexts you've specified and the balance of specifications between contexts. As your specification is evolving, this helps to inform you regarding the next step. Comparing "An empty stack" to "A stack with one item", there are a couple of ways to go here, which is nice (better than having no obvious next step). On "An empty stack", we know two things about the 'push' message. Let's balance "A stack with one item" with that, and specify the 'emptiness' of the stack after 'top'.
+Again, a really nice feature of using the <code>--format specdoc</code> option (<code>-f s</code> for short) is that you can see the big picture very clearly.
+
+Look closely at the "An empty stack" context. We say that it "should not be empty after 'push'". Does that strike you as confusing? It may not, but if you think about it, we're taking an object in one state ("An empty stack"), changing its state by pushing an item onto it and THEN setting an expectation about it. You could argue that we're not really specifying behaviour of an empty stack at all here, but rather behaviour of a stack with one element when you call push.
+
+So let's add that spec to "A stack with one item".
 
 <ruby>
 context "A stack with one item" do
@@ -86,11 +85,12 @@ context "A stack with one item" do
     @stack = Stack.new
     @stack.push "one item"
   end
+
+  specify "should return top when you send it 'top'" do
+    @stack.top.should_equal "one item"
+  end
   
-  ...  
-  
-  specify "should not be empty after 'top'" do
-    @stack.top
+  specify "should not be empty" do
     @stack.should_not_be_empty
   end
 end
@@ -103,101 +103,62 @@ A new stack
 - should be empty
 
 An empty stack
-- should keep its mouth shut when you send it 'push'
 - should not be empty after 'push'
 
 A stack with one item
 - should return top when you send it 'top'
-- should not be empty after 'top'
+- should not be empty
 
-Finished in 0.000853 seconds
+Finished in 0.000849 seconds
 
-3 contexts, 5 specifications, 0 failures
+3 contexts, 4 specifications, 0 failures
 </pre>
 
-This one passes right away. This situation comes up a lot as you progress through a specification. You add a specification and the expectations are already met. You never saw the failure, so how do you know that you wrote the specification correctly, or that it exercises the code that you want to exercise? We should see the expectation fail before moving on. So now the question is what is the best approach to making it fail? Well, we want to see the failure so that when we make a change to the code to make it pass, we know that we've exercised the right place in the code from the spec. To ensure that, we really want to make the change in the code.
-
-In this case, the simplest way to approach this is to return <code>true</code> from <code>empty?</code>.
+And now we can just remove "An empty spec" from stack_spec.rb.
 
 <ruby>
-class Stack
-  def empty?
-    true
-    #@item.nil?
-  end
-  def push item
-    @item = item
+require 'stack'
+
+context "A new stack" do
+  setup do
+    @stack = Stack.new
   end
-  def top
-     @item
+  specify "should be empty" do
+    @stack.should_be_empty
   end
 end
-</ruby>
-<br>
-<pre>
-$ spec stack_spec.rb -f s -s "A stack with one item should not be empty after 'top'"
-
-A stack with one item
-- should not be empty after 'top' (FAILED - 1)
-
-1)
-ExpectationNotMetError in 'A stack with one item should not be empty after 'top''
-Stack #<Stack:0x36ad18 @item="one item"> should not be empty
-./stack_spec.rb:39:in `should not be empty after 'top''
-
-Finished in 0.000398 seconds
 
-1 context, 1 specification, 1 failure
-</pre>
-
-Here we used the <code>-s</code> option, which allows you to specify a single specification by supplying its full name (context name + space + spec name).
-
-The failure tells us that there was an ExpectationNotMetError, as we expected. Revert the code ...
+context "A stack with one item" do
+  setup do
+    @stack = Stack.new
+    @stack.push "one item"
+  end
 
-<ruby>
-class Stack
-  def empty?
-    @item.nil?
+  specify "should return top when you send it 'top'" do
+    @stack.top.should_equal "one item"
+  end
+  
+  specify "should not be empty" do
+    @stack.should_not_be_empty
   end
-  ...
 end
 </ruby>
-
-... run the single spec ...
-
-<pre>
-$ spec stack_spec.rb -f s -s "A stack with one item should not be empty after 'top'"
-
-A stack with one item
-- should not be empty after 'top'
-
-Finished in 0.00028 seconds
-
-1 context, 1 specification, 0 failures
-</pre>
-
-... and then run all the specs ...
-
+<br>
 <pre>
 $ spec stack_spec.rb -f s
 
 A new stack
 - should be empty
 
-An empty stack
-- should keep its mouth shut when you send it 'push'
-- should not be empty after 'push'
-
 A stack with one item
 - should return top when you send it 'top'
-- should not be empty after 'top'
+- should not be empty
 
-Finished in 0.000859 seconds
+Finished in 0.000565 seconds
 
-3 contexts, 5 specifications, 0 failures
+2 contexts, 3 specifications, 0 failures
 </pre>
 
-... and we can press on with confidence that the last spec we added is really exercising and setting expectations on the code we want it to.
+So keep your eye on the contexts and specifications as they evolve. Don't be afraid to move specs around. There are many different benefits that we get from these executable specifications. One is that it helps us to drive code, resulting in very simple and well tested code. Another very important benefit is that future developers can look at them and understand how to use a component (module, class, method, etc). Keep them in mind. "They" may even be you!
 
-<a href="stack_03.html">Previous</a> |
-<a href="stack_05.html">Next</a>
+<a href="stack_03.html">Previous</a>

data/doc/src/tutorials/stack_05.page

@@ -1,4 +1,4 @@
-h2. A Simple Stack - Moving specs between contexts
+h2. A Simple Stack - Moving specs between contexts - IN PROGRESS - DISREGARD THIS PAGE
 
 So we now have the following spec.
 

data/doc/src/tutorials/stack_spec.rb

@@ -4,38 +4,22 @@ context "A new stack" do
   setup do
     @stack = Stack.new
   end
-
   specify "should be empty" do
     @stack.should_be_empty
   end
 end
 
-context "An empty stack" do
-  setup do
-    @stack = Stack.new
-  end
-
-  specify "should keep its mouth shut when you send it 'push'" do
-    lambda { @stack.push Object.new }.should.not.raise
-  end
-end
-  
 context "A stack with one item" do
   setup do
     @stack = Stack.new
     @stack.push "one item"
   end
 
-  specify "should not be empty" do
-    @stack.should_not_be_empty
-  end
-
   specify "should return top when you send it 'top'" do
     @stack.top.should_equal "one item"
   end
   
-  specify "should not be empty after 'top'" do
-    @stack.top
+  specify "should not be empty" do
     @stack.should_not_be_empty
   end
-end
+end

data/lib/spec/rake/rcov_verify.rb

@@ -10,7 +10,7 @@ module RCov
     # Defaults to 'coverage/index.html'
     attr_accessor :index_html
     
-    # Whether or not to output details
+    # Whether or not to output details. Defaults to true.
     attr_accessor :verbose
     
     # The threshold value (in percent) for coverage. If the 
@@ -21,7 +21,7 @@ module RCov
     def initialize(name=:rcov_verify)
       @name = name
       @index_html = 'coverage/index.html'
-      @verbose = false
+      @verbose = true
       yield self if block_given?
       raise "Threshold must be set" if @threshold.nil?
       define

data/lib/spec/rake/spectask.rb

@@ -82,6 +82,9 @@ module Rake
       lib_path = @libs.join(File::PATH_SEPARATOR)
       desc "Run specs" + (@name==:spec ? "" : " for #{@name}")
       task @name do
+        specs = file_list
+        raise "No spec files found." if specs.empty?
+        
         spec = File.dirname(__FILE__) + '/../../../bin/spec'
         file_prefix = @rcov ? " -- " : ""
         interpreter = @rcov ? "rcov" : "ruby"
@@ -94,7 +97,7 @@ module Rake
           " \"#{spec}\" " +
           " #{@spec_opts.join(' ')} " +
           file_prefix +
-          file_list.collect { |fn| "\"#{fn}\"" }.join(' ') +
+          specs.collect { |fn| "\"#{fn}\"" }.join(' ') +
           redirect
       end
       self
@@ -111,14 +114,6 @@ module Rake
       end
     end
 
-    def find_file(fn) # :nodoc:
-      $LOAD_PATH.each do |path|
-      file_path = File.join(path, "#{fn}.rb")
-        return file_path if File.exist? file_path
-      end
-      nil
-    end
-
     def run(interpreter, *args, &block)
       if Hash === args.last
         options = args.pop

data/lib/spec/runner.rb

@@ -10,3 +10,4 @@ require 'spec/runner/base_text_formatter'
 require 'spec/runner/progress_bar_formatter'
 require 'spec/runner/rdoc_formatter'
 require 'spec/runner/specdoc_formatter'
+require 'spec/runner/spec_matcher'

data/lib/spec/runner/backtrace_tweaker.rb

@@ -27,6 +27,8 @@ module Spec
           line = nil if line =~ /\/lib\/spec\/api\//
           line = nil if line =~ /\/lib\/spec\/runner\//
           line = nil if line =~ /bin\/spec:/
+          # TextMate's Ruby plugin
+          line = nil if line =~ /Ruby\.tmbundle\/Support\/tmruby.rb:/
           line
         end
         error.backtrace.compact!

data/lib/spec/runner/context.rb

@@ -32,17 +32,19 @@ module Spec
         @specifications.length
       end
       
-      def matches? name
-        return false unless name =~ /^#{@name} /
+      def matches? name, matcher=nil
+        matcher ||= SpecMatcher.new name, @name
         @specifications.each do |spec|
-          return true if spec.matches? name[(@name.length + 1)..-1]
+          return true if spec.matches_matcher? matcher 
         end
         return false
       end
       
-      def isolate name
+      def run_single_spec name
+        return if @name == name
+        matcher = SpecMatcher.new name, @name
         @specifications.reject! do |spec|
-          !spec.matches? name[(@name.length + 1)..-1]
+          !spec.matches_matcher? matcher
         end
       end
     end