rspec 0.5.3 → 0.5.4

data/doc/src/tutorials/stack_02.page

@@ -0,0 +1,180 @@
+h2. A Simple Stack
+
+h3. An Empty Stack
+
+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 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.
+
+<ruby>
+context "An empty stack" do
+  specify "should not be empty after 'push'" do
+  end
+end
+</ruby>
+<br>
+<pre>
+$ spec stack_spec.rb -f s
+
+A new stack
+- should be empty
+
+An empty stack
+- should not be empty after 'push'
+
+Finished in 0.000391 seconds
+
+2 contexts, 2 specifications, 0 failures
+</pre>
+
+See how that's reading like a specification document? OK, now let's fill in the specification. First we add the setup for our context.
+
+<ruby>
+context "An empty stack" do
+  setup do
+    @stack = Stack.new
+  end
+  specify "should not be empty after 'push'" do
+  end
+end
+</ruby>
+<br>
+<pre>
+$ spec stack_spec.rb -f s
+
+A new stack
+- should be empty
+
+An empty stack
+- should not be empty after 'push'
+
+Finished in 0.000444 seconds
+
+2 contexts, 2 specifications, 0 failures
+</pre>
+
+No change in the result. Now we'll push something on to the stack.
+
+<ruby>
+context "An empty stack" do
+  setup do
+    @stack = Stack.new
+  end
+  specify "should not be empty after 'push'" do
+    @stack.push 37
+  end
+end
+</ruby>
+<br>
+<pre>
+$ spec stack_spec.rb -f s
+
+A new stack
+- should be empty
+
+An empty stack
+- should not be empty after 'push' (FAILED - 1)
+
+1)
+NoMethodError in 'An empty stack should not be empty after 'push''
+undefined method `push' for #<Stack:0x36d0e0>
+./stack_spec.rb:17:in `should not be empty after 'push''
+
+Finished in 0.000548 seconds
+
+2 contexts, 2 specifications, 1 failure
+</pre>
+
+The <code>NoMethodError</code> tells us we need to add a push method to the stack.
+
+<ruby>
+class Stack
+  def empty?
+    true
+  end
+  def push item
+  end
+end
+</ruby>
+<br>
+<pre>
+$ spec stack_spec.rb -f s
+
+A new stack
+- should be empty
+
+An empty stack
+- should not be empty after 'push'
+
+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:
+
+<ruby>
+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
+</ruby>
+<br>
+<pre>
+$ spec stack_spec.rb -f s
+
+A new stack
+- should be empty
+
+An empty stack
+- should not be empty after 'push' (FAILED - 1)
+
+1)
+ExpectationNotMetError in 'An empty stack should not be empty after 'push''
+Stack #<Stack:0x36cf50> should not be empty
+./stack_spec.rb:18:in `should not be empty after 'push''
+
+Finished in 0.000604 seconds
+
+2 contexts, 2 specifications, 1 failure
+</pre>
+
+The <code>ExpectationNotMetError</code> tells us we have something to implement. We want to do the simplest thing that we can do to meet our existing expectations. At this point we don't know anything about collections or even specific values, so we can just manage whether or not it is empty.
+
+<ruby>
+class Stack
+  def initialize
+    @empty = true
+  end
+  def empty?
+    @empty
+  end
+  def push item
+    @empty = false
+  end
+end
+</ruby>
+<br>
+<pre>
+$ spec stack_spec.rb -f s
+
+A new stack
+- should be empty
+
+An empty stack
+- should not be empty after 'push'
+
+Finished in 0.000443 seconds
+
+2 contexts, 2 specifications, 0 failures
+</pre>
+
+Again, this may seem a little odd, but we haven't specified anything yet about what happens to things that get pushed on to the stack. That's right around the corner though...
+
+<a href="stack_01.html">Previous</a> |
+<a href="stack_03.html">Next</a>

data/doc/src/tutorials/stack_03.page

@@ -0,0 +1,291 @@
+h2. A Simple Stack - eliminating duplication
+
+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!
+
+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.
+
+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
+
+<ruby>
+context "A stack with one item" do
+  specify "should return top when you send it 'top'" do
+  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'
+
+Finished in 0.000693 seconds
+
+3 contexts, 4 specifications, 0 failures
+</pre>
+
+Add the setup...
+
+<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
+  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'
+
+Finished in 0.000733 seconds
+
+3 contexts, 4 specifications, 0 failures
+</pre>
+
+No change in the output. Add the expectation...
+
+<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
+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' (FAILED - 1)
+
+1)
+NoMethodError in 'A stack with one item should return top when you send it 'top''
+undefined method `top' for #<Stack:0x36bd44 @empty=false>
+./stack_spec.rb:35:in `should return top when you send it 'top''
+
+Finished in 0.000863 seconds
+
+3 contexts, 4 specifications, 1 failure
+</pre>
+
+The <code>NoMethodError</code> tells us to add the 'top' method.
+
+<ruby>
+class Stack
+  ...
+  def top
+  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' (FAILED - 1)
+
+1)
+ExpectationNotMetError in 'A stack with one item should return top when you send it 'top''
+nil should equal "one item"
+./stack_spec.rb:35:in `should return top when you send it 'top''
+
+Finished in 0.000867 seconds
+
+3 contexts, 4 specifications, 1 failure
+</pre>
+
+The <code>ExpectationNotMetError</code> tells us to implement something. What's the simplest thing we can add to meet all of the current expectations?
+
+<ruby>
+class Stack
+  ...
+  def top
+    "one item"
+  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'
+
+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.
+
+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...
+
+<ruby>
+class Stack
+  def initialize
+    @empty = true
+  end
+  def empty?
+    @empty
+  end
+  def push item
+    @empty = false
+    @item = item
+  end
+  def top
+     @item
+  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'
+
+Finished in 0.000846 seconds
+
+3 contexts, 4 specifications, 0 failures
+</pre>
+
+Now let's use that to determine "emptiness"...
+
+<ruby>
+class Stack
+  def initialize
+    @empty = true
+  end
+  def empty?
+    @item.nil?
+  end
+  def push item
+    @empty = false
+    @item = item
+  end
+  def top
+     @item
+  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'
+
+Finished in 0.000764 seconds
+
+3 contexts, 4 specifications, 0 failures
+</pre>
+
+Now we can eliminate <code>@empty</code> (which means we can eliminate <code>initialize</code> as well).
+
+<ruby>
+class Stack
+  def empty?
+    @item.nil?
+  end
+  def push item
+    @item = item
+  end
+  def top
+     @item
+  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'
+
+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.
+
+To be continued...
+
+<a href="stack_02.html">Previous</a> |
+<a href="stack_04.html">Next</a>