rspec 0.5.3 → 0.5.4

data/doc/src/tutorials/stack_04.page

@@ -0,0 +1,203 @@
+h2. A Simple Stack - when a new expectation passes
+
+At this point stack_spec.rb should look like this...
+
+<ruby>
+require 'stack'
+
+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
+
+  specify "should not be empty after 'push'" do
+    @stack.push 37
+    @stack.should_not_be_empty
+  end
+end
+  
+context "A stack with one item" do
+  setup 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
+end
+</ruby>
+
+stack.rb should look like this...
+
+<ruby>
+class Stack
+  def empty?
+    @item.nil?
+  end
+  def push item
+    @item = item
+  end
+  def top
+     @item
+  end
+end
+</ruby>
+
+...and the output should look like this:
+
+<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'
+
+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'.
+
+<ruby>
+context "A stack with one item" do
+  setup do
+    @stack = Stack.new
+    @stack.push "one item"
+  end
+  
+  ...  
+  
+  specify "should not be empty after 'top'" do
+    @stack.top
+    @stack.should_not_be_empty
+  end
+end
+</ruby>
+<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'
+
+Finished in 0.000853 seconds
+
+3 contexts, 5 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>.
+
+<ruby>
+class Stack
+  def empty?
+    true
+    #@item.nil?
+  end
+  def push item
+    @item = item
+  end
+  def top
+     @item
+  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 ...
+
+<ruby>
+class Stack
+  def empty?
+    @item.nil?
+  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 ...
+
+<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'
+
+Finished in 0.000859 seconds
+
+3 contexts, 5 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.
+
+<a href="stack_03.html">Previous</a> |
+<a href="stack_05.html">Next</a>

data/doc/src/tutorials/stack_04.page.orig

@@ -0,0 +1,123 @@
+h2. A Simple Stack - Top - IN PROGRESS - DISREGARD THIS PAGE
+
+What should happen when you call top on an empty stack? We could just return nil, 
+but how does the client know whether the stack was empty or contained nil as an element? 
+Perhaps the client doesn't care. Let's assume the client does care, in which case we'd want to raise an error.
+
+We already have our "empty stack" context, so let's add a specification to it.
+
+<ruby>
+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 Exception
+  end
+  
+  specify "should raise a StackUnderflowError when you send it 'top'" do
+    lambda { @stack.top }.should.raise StackUnderflowError
+  end
+  
+end
+</ruby>
+
+Running the spec...
+
+<pre>
+$ spec stack_spec.rb -v
+
+An empty stack
+- should keep its mouth shut when you send it 'push'
+- should raise a StackUnderflowError when you send it 'top' (FAILED - 1)
+
+A stack with one item
+- should return top when you send it 'top'
+
+
+1)
+NameError in 'An empty stack should raise a StackUnderflowError when you send it 'top''
+uninitialized constant StackUnderflowError
+./stack_spec.rb:14:in `should raise a StackUnderflowError when you send it 'top''
+
+Finished in 0.000582 seconds
+
+2 contexts, 3 specifications, 1 failure
+</pre>
+
+"uninitialized constant StackUnderflowError" tells us that we need to create a StackUndeflowError. We'll just stick that in the file with the Stack:
+
+<ruby>
+class StackUnderflowError < RuntimeError
+end
+</ruby>
+
+and run the spec again.
+
+<pre>
+$ spec stack_spec.rb -v
+
+An empty stack
+- should keep its mouth shut when you send it 'push'
+- should raise a StackUnderflowError when you send it 'top' (FAILED - 1)
+
+A stack with one item
+- should return top when you send it 'top'
+
+
+1)
+ExpectationNotMetError in 'An empty stack should raise a StackUnderflowError when you send it 'top''
+<Proc> should raise <StackUnderflowError> but raised nothing
+./stack_spec.rb:14:in `should raise a StackUnderflowError when you send it 'top''
+
+Finished in 0.000788 seconds
+
+2 contexts, 3 specifications, 1 failure
+</pre>
+
+Now the error report tells us that the expectation was not met - executing the block did not 
+raise the error we specified. Now we can implement code to meet this specification. Sticking 
+with the principle that we want to implement the least amount of code to meet the specification, 
+we enhance our top method:
+
+<ruby>
+def top
+  raise StackUnderflowError if @item.nil?
+  @item
+end
+</ruby>
+
+run the specs and they all pass.
+
+<pre>
+$ spec stack_spec.rb -v
+
+An empty stack
+- should keep its mouth shut when you send it 'push'
+- should raise a StackUnderflowError when you send it 'top'
+
+A stack with one item
+- should return top when you send it 'top'
+
+
+Finished in 0.000557 seconds
+
+2 contexts, 3 specifications, 0 failures
+</pre>
+
+Do you see how the verbose output is looking more and more like a specification? That's pretty nice, but as your projects grow, you may not want all of that output all of the time. You can, if you wish, run the specs without the <code>-v</code> flag, in which case you get a "." for every passing spec and an "F" for every failing spec. Run them now and you'll see nothing but dots.
+
+<pre>
+$ spec stack_spec.rb 
+
+...
+
+Finished in 0.000458 seconds
+
+2 contexts, 3 specifications, 0 failures
+</pre>
+
+<a href="stack_02.html">Previous</a> |
+<a href="stack_04.html">Next</a>

data/doc/src/tutorials/stack_05.page

@@ -0,0 +1,90 @@
+h2. A Simple Stack - Moving specs between contexts
+
+So we now have the following spec.
+
+<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'
+
+Finished in 0.000882 seconds
+
+3 contexts, 5 specifications, 0 failures
+</pre>
+
+One thing that's odd about this is that "An empty stack should not be empty after 'push'". If you think about it, "An empty stack" is no longer empty after sending it 'push'. It's now "A stack with one item". Conveniently, we already have a context that  expresses that. So it may make more sense to move that spec to the "one item" context. Remove it from "An empty stack" ...
+
+<ruby>
+context "An empty stack" do
+  specify "should not be empty after 'push'" do
+    @stack.push 37
+    @stack.should_not_be_empty
+  end
+end
+</ruby>
+
+... add it to "A stack with one item" ...
+
+<ruby>
+context "A stack with one item" do
+  setup do
+    @stack = Stack.new
+    @stack.push "one item"
+  end
+
+  specify "should not be empty after 'push'" do
+    @stack.push 37
+    @stack.should_not_be_empty
+  end
+  
+  ...
+end
+</ruby>
+
+... and adjust so it works better in this context. We're already pushing "one item", so we don't have to push 37. And we can adjust the name as well:
+
+<ruby>
+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
+  ...
+end
+</ruby>
+<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'
+
+A stack with one item
+- should not be empty
+- should return top when you send it 'top'
+- should not be empty after 'top'
+
+Finished in 0.000838 seconds
+
+3 contexts, 5 specifications, 0 failures
+</pre>
+
+So keep your eye out for misplaced specifications like this. Feel free to move things around - carefully, of course. It may seem trivial at this point, but as your spec grows it's going to become more and more important. These specifications are documentation of your system. They must be clear, well organized, and readable.
+
+<a href="stack_04.html">Previous</a>

data/doc/src/tutorials/stack_05.page.orig

@@ -0,0 +1,124 @@
+h2. A Simple Stack - Organization and Documentation - IN PROGRESS - DISREGARD THIS PAGE
+
+h3. Spec organization
+
+Let's take a look at the spec thus far...
+
+<ruby>
+require File.dirname(__FILE__) + "/stack"
+
+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 Exception
+  end
+  
+  specify "should raise a StackUnderflowError when you send it 'top'" do
+    lambda { @stack.top }.should.raise StackUnderflowError
+  end
+  
+end
+
+context "A stack with one item" do
+  
+  setup do
+    @stack = Stack.new
+    @stack.push "one item"
+  end
+
+  specify "should return top when sent the 'top' message" do
+    @stack.top.should.equal "one item"
+  end
+  
+end
+</ruby>
+
+..and the result of executing them. First in default mode...
+
+<pre>
+$ spec stack_spec.rb 
+
+...
+
+Finished in 0.000439 seconds
+
+2 contexts, 3 specifications, 0 failures
+</pre>
+
+...and then in verbose mode...
+
+<pre>
+$ spec stack_spec.rb -v
+
+An empty stack
+- should keep its mouth shut when you send it 'push'
+- should raise a StackUnderflowError when you send it 'top'
+
+A stack with one item
+- should return top when you send it 'top'
+
+
+Finished in 0.000533 seconds
+
+2 contexts, 3 specifications, 0 failures
+</pre>
+
+We've got two contexts. In both we exercise the 'top' message, but we only exercise 'push' in one. This is a wonderful aspect of organizing the specs this way. By looking at the contexts themselves, or by looking at the generated output, and by having only one setup for each context (a guideline often suggested for xUnit, but violated just as often), we can clearly see the imbalance in what messages we're specifying in the different contexts.
+
+So now, in addition to using the principle of the simplest thing to help us decide what to specify next, we've also got this feedback that tells us that we have yet to specify how a stack with one item should respond to the 'push' message. Using both tools to guide us, that is an obvious next choice.
+
+<ruby>
+context "A stack with one item" do
+  
+  setup do
+    @stack = Stack.new
+    @stack.push "one item"
+  end
+
+  specify "should keep its mouth shut when you send it 'push'" do
+     lambda { @stack.push Object.new }.should.not.raise Exception
+  end
+  
+  specify "should return top when you send it 'top'" do
+    @stack.top.should.equal "one item"
+  end
+  
+end
+</ruby>
+
+To add that, I actually copied the spec from the "new stack" context. Cut and paste? Blasphemy! Exact duplication? More blasphemy! Well, it is blasphemy if you think of these structures as tests, or even as code. Yes, they are executable. Yes, they are code - sort of. But they also serve other very important purpose - they are documentation.
+
+h3. Specs as documentation
+
+The whole structure of contexts and specifications was deliberately chosen to feel less like the tests that we're all used to seeing in xUnit frameworks so that we wouldn't think of specs in the same way as we do tests. So while we might think of them as executable, we don't want to think of them as code.
+
+We talk about tests as documentation in TDD as well. But I can tell you that when I've tried to read them as such and found myself searching through hierarchies to find the setup for a test that was failing, my eyes have just glazed over and I've ended up looking directly at the code. Serving as documentation requires of these executable specifications that they be simple, clear and easy to understand. All the context you need to understand the test should be in one place.
+
+Also, the perception that "all duplication is evil" is based on industry-wide experience in which changes that needed to happen to duplicated code didn't happen everywhere it should have. In the case of specifications, that doesn't really fly because each specification is autonomous. If the rules change for a message in a given context, then you'd only want to make the change in that context.
+
+So we've now got 4 specifications, 2 each in 2 contexts. Run the specs...
+
+<pre>$ spec stack_spec.rb -v
+
+An empty stack
+- should keep its mouth shut when you send it 'push'
+- should raise a StackUnderflowError when you send it 'top'
+
+A stack with one item
+- should keep its mouth shut when you send it 'push'
+- should return top when you send it 'top'
+
+
+Finished in 0.000657 seconds
+
+2 contexts, 4 specifications, 0 failures
+</pre>
+
+...and there are no failures. So in this case, since 'push' results in the same behavior for an empty stack and a one-item stack, we don't have anything additional to implement.
+
+<a href="stack_03.html">Previous</a> |
+<a href="stack_05.html">Next</a>