rspec 0.5.11 → 0.5.12

data/doc/src/tutorials/stack.rb

@@ -1,11 +0,0 @@
-class Stack
-  def empty?
-    @item.nil?
-  end
-  def push item
-    @item = item
-  end
-  def top
-     @item
-  end
-end

data/doc/src/tutorials/stack_01.page

@@ -1,226 +0,0 @@
-h2. A Simple Stack - The First Specification
-
-h3. Where do we start?
-
-We want to start off with the simplest thing that we can specify, just as we would in TDD. Remember that in spite of some important (if subtle) distinctions, BDD <em>is</em> TDD at its core.
-
-As discussed in the <a href="index.html">Overview</a>, a common first specification is that a new stack should be empty, and we typically verify this by checking that its size is 0. This simplicity is what we're looking for, but we want to avoid the "size" question. Well, let's think about how a client might use a stack:
-
-<ruby>
-#example usage
-stack.pop unless stack.empty?
-</ruby>
-
-So let's start with "A new stack should be empty".
-
-h3. Create a spec file
-
-Start by creating a file called stack_spec.rb in /projects/ruby/stack/. You can use any filename and directory you wish, but the following will assume these names and locations.
-
-h3. Add a context
-
-Add the following to stack_spec.rb
-
-<ruby>
-context "A new stack" do
-end
-</ruby>
-
-A context represents an object (or set of objects) in a known state. This is the same concept as a fixture in xUnit. For each known state from which we wish to specify behaviour, we'll add a new context.
-
-To see what damage we've done so far, open a command shell, cd to /projects/ruby/stack/, and enter the following:
-
-<pre>
-$ spec stack_spec.rb
-</pre>
-
-You should see output similar to this
-
-<pre>
-Finished in 6.9e-05 seconds
-
-1 context, 0 specifications, 0 failures
-</pre>
-
-The <code>spec</code> command is installed when you install rSpec. It requires (using the ruby <code>require</code> method) any file(s) (or all of the files in a directory) that you specify on the command line. The <code>context</code> method accepts a name ("An empty stack") and a block (do ... end) and processes everything inside the block. Since there's nothing in this block to process, we discover that rSpec processed 1 context, but 0 specifications.
-
-You may wonder why bother with the name? Try adding the <code>-f s</code> option to the command
-
-<pre>
-$ spec stack_spec.rb -f s
-
-A new stack
-
-Finished in 6.9e-05 seconds
-
-1 context, 0 specifications, 0 failures
-</pre>
-
-The option <code>-f s</code> is a shortcut for <code>--format specdoc</code>, which tells rSpec to print out the names of all the contexts and specifications as they are run. As we progress, you'll see how choosing these names carefully not only documents things well inside the spec files, but also in generated output.
-
-h3. Add a specification
-
-The spec that we are starting with is "A new stack should be empty". So far we have the context, "A new stack", but we need the specification, "should be empty" :
-
-<ruby>
-context "A new stack" do
-  specify "should be empty" do
-  end
-end
-</ruby>
-
-<pre>
-$ spec stack_spec.rb -f s
-
-A new stack
-- should be empty
-
-Finished in 0.000188 seconds
-
-1 context, 1 specification, 0 failures
-</pre>
-
-As you can see, this reads like a specification. This is just like the output you get from running jUnit tests through agiledox. Agiledox was an important part of the inception of BDD, so we built it right into rspec. Of course, we haven't actually written any code in the specification, so we need to add some. Just as we do in TDD, we're going to add one little bit at a time - just enough to produce a failed expectation - followed by just enough code to meet the expectation.
-
-Let's start by creating the new stack.
-
-<ruby>
-context "A new stack" do
-  setup do
-    @stack = Stack.new
-  end
-  specify "should be empty" do
-  end
-end
-</ruby>
-
-Introducing a setup here may seem a bit premature to some, but we know what the context is here: it's a new stack. We want to express that context in the setup method to clearly define it as the starting state for each of the specifications within this context.
-
-<pre>
-$ spec stack_spec.rb -f s
-
-A new stack
-- should be empty (FAILED - 1)
-
-1)
-NameError in 'A new stack should be empty'
-uninitialized constant Stack
-./stack_spec.rb:3:in `setup'
-
-Finished in 0.00031 seconds
-
-1 context, 1 specification, 1 failure
-</pre>
-
-This tells us that there is a NameError, that it can't find the name Stack, and that the problem is in the setup block of this context. To resolve this, create a new file named stack.rb and add the following:
-
-<ruby>
-class Stack
-end
-</ruby>
-
-Then require that file in stack_spec.rb:
-
-<ruby>
-require 'stack'
-
-context "A new stack" do
-...
-</ruby>
-
-and run the specs.
-
-<pre>
-$ spec stack_spec.rb -f s
-
-A new stack
-- should be empty
-
-Finished in 0.000229 seconds
-
-1 context, 1 specification, 0 failures
-</pre>
-
-We're getting closer, but we still need more to exercise this specification.
-
-<ruby>
-context "A new stack" do
-  setup do
-    @stack = Stack.new
-  end
-  specify "should be empty" do
-    @stack.should_be_empty
-  end
-end
-</ruby>
-
-<pre>
-$ spec stack_spec.rb -f s
-
-A new stack
-- should be empty (FAILED - 1)
-
-1)
-NoMethodError in 'A new stack should be empty'
-undefined method `empty?' for #<Stack:0x36e6fc>
-./stack_spec.rb:8:in `should be empty'
-
-Finished in 0.000361 seconds
-
-1 context, 1 specification, 1 failure
-</pre>
-
-In this case, rspec interprets the message <code>should_be_empty</code>, and sends <code>empty?</code> to <code>stack</code>. This will work for any predicate (ruby methods that end with a "?" and return boolean).
-
-You can think of <code>NameError</code> as the equivalent of a compilation failure in java or C#. <code>Stack</code> doesn't respond to the <code>empty?</code> message ... yet.
-
-<ruby>
-class Stack
-  def empty?
-  end
-end
-</ruby>
-
-<pre>
-$ spec stack_spec.rb -f s
-
-A new stack
-- should be empty (FAILED - 1)
-
-1)
-ExpectationNotMetError in 'A new stack should be empty'
-Stack #<Stack:0x36e60c> should be empty
-./stack_spec.rb:8:in `should be empty'
-
-Finished in 0.000389 seconds
-
-1 context, 1 specification, 1 failure
-</pre>
-
-... and NOW we get a failing expectation. "Stack #&lt;Stack:0x36e60c&gt; should be empty" is the detail of this <code>ExpectationNotMetError</code>. The expectation is that <code>empty?</code> should return <code>true</code>, but it does not. Let's make it so ...
-
-<ruby>
-class Stack
-  def empty?
-    true
-  end
-end
-</ruby>
-
-<pre>
-spec stack_spec.rb -f s
-
-A new stack
-- should be empty
-
-Finished in 0.000256 seconds
-
-1 context, 1 specification, 0 failures
-</pre>
-
-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,182 +0,0 @@
-h2. A Simple Stack
-
-h3. Choosing the next Specification
-
-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.
-
-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
-  specify "should not be empty after 'push'" do
-  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'
-
-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>
-
-<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>
-
-<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>
-
-<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>
-
-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
-  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>
-
-<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>
-
-<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

@@ -1,283 +0,0 @@
-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 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 item, while pop also removes it from the stack.
-
-h3. Send top to a stack with one item
-
-Start by adding a new context and spec in stack_spec.rb.
-
-<ruby>
-context "A stack with one item" do
-  specify "should return top when you send it 'top'" do
-  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'
-
-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>
-
-<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.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>
-
-<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' (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>
-
-<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' (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>
-
-<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.000744 seconds
-
-3 contexts, 4 specifications, 0 failures
-</pre>
-
-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 save the item we add and return that from <code>top</code> ...
-
-<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>
-
-<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.000846 seconds
-
-3 contexts, 4 specifications, 0 failures
-</pre>
-
-Now let's use the item 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>
-
-<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.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>
-
-<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.000737 seconds
-
-3 contexts, 4 specifications, 0 failures
-</pre>
-
-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...
-
-<a href="stack_02.html">Previous</a> |
-<a href="stack_04.html">Next</a>