rspec 0.5.11 → 0.5.12

data/doc/src/tutorials/stack_04.page

@@ -1,164 +0,0 @@
-h2. A Simple Stack - when a new expectation passes - IN PROGRESS - DISREGARD THIS PAGE
-
-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 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 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 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
-  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
-  
-  specify "should not be empty" do
-    @stack.should_not_be_empty
-  end
-end
-</ruby>
-
-<pre>
-$ spec stack_spec.rb -f s
-
-A new stack
-- should be empty
-
-An empty stack
-- should not be empty after 'push'
-
-A stack with one item
-- should return top when you send it 'top'
-- should not be empty
-
-Finished in 0.000849 seconds
-
-3 contexts, 4 specifications, 0 failures
-</pre>
-
-And now we can just remove "An empty spec" from stack_spec.rb.
-
-<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 "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
-  
-  specify "should not be empty" do
-    @stack.should_not_be_empty
-  end
-end
-</ruby>
-
-<pre>
-$ spec stack_spec.rb -f s
-
-A new stack
-- should be empty
-
-A stack with one item
-- should return top when you send it 'top'
-- should not be empty
-
-Finished in 0.000565 seconds
-
-2 contexts, 3 specifications, 0 failures
-</pre>
-
-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>

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

@@ -1,123 +0,0 @@
-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

@@ -1,90 +0,0 @@
-h2. A Simple Stack - Moving specs between contexts - IN PROGRESS - DISREGARD THIS PAGE
-
-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>
-
-<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

@@ -1,124 +0,0 @@
-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>