rspec 0.5.3 → 0.5.4

data/doc/src/tutorials/meta.info

@@ -0,0 +1,31 @@
+index.page:
+  title: Overview
+  inMenu: true
+  orderInfo: 10
+  
+stack_01.page:
+  title: '1'
+  inMenu: true
+  orderInfo: 11
+  
+stack_02.page:
+  title: '2'
+  inMenu: true
+  orderInfo: 12
+  
+stack_03.page:
+  title: '3'
+  inMenu: true
+  orderInfo: 13
+  
+stack_04.page:
+  title: '4'
+  inMenu: true
+  orderInfo: 14
+
+stack_05.page:
+  title: '5'
+  inMenu: true
+  orderInfo: 15
+
+  

data/doc/src/tutorials/notes.txt

@@ -0,0 +1,252 @@
+<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>
+
+Run the spec...
+
+<pre>
+$ spec stack_spec.rb -v
+
+An empty stack
+- should keep its mouth shut when you send it '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:0x3703bc @item="one item">
+./stack_spec.rb:35:in `should return top when you send it 'top''
+
+Finished in 0.000677 seconds
+
+2 contexts, 2 specifications, 1 failure
+</pre>
+
+Again, running the spec tells us what we have to implement next. <code>undefined method `top' for #<Stack:0x3703bc @item="one item"></code> tells us to implement a <code>top</code> method. So, back in stack.rb...
+
+<ruby>
+def top
+end
+</ruby>
+
+Why not implement the return now? Well, this becomes a matter of taste and level of discipline. While you're learning BDD (especially if you have no prior TDD experience), you want to take very, very small steps. There's usually something to learn after each one. In this case, if we run the spec now...
+
+<pre>
+$ spec stack_spec.rb -v
+
+An empty stack
+- should keep its mouth shut when you send it '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.000531 seconds
+
+2 contexts, 2 specifications, 1 failure
+</pre>
+
+This is a very interesting result. <code>nil should equal "one item"</code> tells us that the expression <code>@stack.top</code> returned nil. In ruby, nil is a real object to which you can send messages. <code>should.equal "one item"</code> tells rspec that the object returned by the expression (in this case nil) should be equal to the string literal "one item".
+
+So let's get the code to meet this specification. When we do this, we want to implement the simplest thing that we can to satisfy the existing specs. Given the current set of specs, we can simply return "one item"
+
+<ruby>
+class Stack
+  
+  def push item
+  end
+  
+  def top
+	"one item"
+  end
+  
+end
+</ruby>
+
+Run the specs...
+
+<pre>
+$ spec stack_spec.rb -v
+
+An empty stack
+- should keep its mouth shut when you send it 'push'
+
+A stack with one item
+- should return top when you send it 'top'
+
+
+Finished in 0.0004 seconds
+
+2 contexts, 2 specifications, 0 failures
+</pre>
+
+Seems odd? We know that we don't want to always return "one item", so the implementation seems silly. But that implementation did something great. It made it so all of our expectations are met and we didn't have to change much to get there. We always want to take really small steps, with all the specs passing between each step. Now that we have passing specs, we're free to refactor - and we WANT to refactor because we've introduced duplication between the specs and the implementation.
+
+So let's refactor to eliminate this duplication. We can use the existing push method to setup the item that top will return.
+
+<ruby>
+class Stack
+  
+  def push item
+    @item = item
+  end
+  
+  def top
+    @item
+  end
+  
+end
+</ruby>
+
+So now we have two specifications, each with their own context. We've implemented two simple methods that satisfy the existing specifications. If you've never done any TDD before this, this may seem really odd. We all know that this isn't enough to meet the specs that we intend. But right now, at this moment, as far as the code is concerned, there are only two simple specifications. To move our implementation along, we first have to specify more about how we want our stack to behave.
+
+<a href="stack_01.html">Previous</a> |
+<a href="stack_03.html">Next</a>
+
+
+
+
+
+
+
+
+
+
+
+
+
+OK. That's pretty standard stuff so far, but it's all about the object's <em><b>state</b></em>, not its behaviour. We want to think about what our Stack does - how it responds to various messages that we can send it. What should an empty Stack do when you send it the push method? Absolutely nothing, right? It should just accept the object and keep its mouth shut:
+
+<ruby>
+context "An empty stack" do
+  ...
+  specify "should keep its mouth shut when you send it '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'
+- should keep its mouth shut when you send it 'push'
+
+Finished in 0.000552 seconds
+
+2 contexts, 3 specifications, 0 failures
+</pre>
+
+Actually, I'd like the "keep its mouth shut" spec to come first - I think it reads better. So let's just switch them around in the context:
+
+<ruby>
+context "An empty stack" do
+  setup do
+    @stack = Stack.new
+  end
+
+  specify "should keep its mouth shut when you send it 'push'" do
+  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 keep its mouth shut when you send it 'push'
+- should not be empty after 'push'
+
+Finished in 0.000557 seconds
+
+2 contexts, 3 specifications, 0 failures
+</pre>
+
+RSpec reads the contexts and specs within a given file in the order in which they appear, giving you some control over this output.
+
+So what can we expect here? The name of the spec tells us - "should keep its mouth shut". That implies that it should not react in any way - including raising an error. So let's set the expectation that there will be no error raised:
+
+<ruby>
+specify "should keep its mouth shut when you send it 'push'" do
+  lambda { @stack.push Object.new }.should.not.raise
+end
+</ruby>
+
+If you're not familiar, <code>lambda</code> accepts a block but does not execute it. It then constructs a Proc object, which can called at any time. So, in this case, the block <code>{ stack.push Object.new }</code> gets saved in a Proc object. <code>should.not.raise</code> then tells rSpec to call the Proc and raise an ExpectationNotMetError if it raises any errors at all. Running the spec...
+
+<pre>
+$ spec stack_spec.rb -v
+
+An empty stack
+- should keep its mouth shut when you send it 'push' (FAILED - 1)
+
+
+1)
+ExpectationNotMetError in 'An empty stack should keep its mouth shut when you send it 'push''
+<Proc> should not raise <Exception> but raised #<NoMethodError: undefined method `push' for #<Stack:0x370d94>>
+./stack_spec.rb:10:in `should keep its mouth shut when you send it 'push''
+
+Finished in 0.000418 seconds
+
+1 context, 1 specification, 1 failure
+</pre> 
+
+The first line tells us the rSpec error that was raised: we were expecting that nothing would be raised, but something (anything) was, so we get an "ExpectationNotMetError".
+
+The second line tells us that we specified that there should be no Exception (in this case we didn't specify what type of exception, so by default rSpec assumes Exception), but that there was a NoMethodError raised.
+
+The third line tells us that the error was raised in the block defining the specification "should keep its mouth shut when you send it 'push'".
+
+We get a NoMethodError because our stack doesn't know what to do with the "push" message. So we add it...
+
+<ruby>
+class Stack
+  def push item
+  end
+end
+</ruby>
+
+...and run the spec and voila!...
+
+<pre>
+$ spec stack_spec.rb -v
+
+An empty stack
+- should keep its mouth shut when you send it 'push'
+
+
+Finished in 0.000209 seconds
+
+1 context, 1 specification, 0 failures
+</pre>
+
+... the code meets the first specification. Now obviously this code doesn't do much, but that's because we have more specifications to write!
+
+One important thing to note here is that we did not begin by setting any expectations about the size or emptiness of the stack. That may feel funny to experienced TDDers, as it is standard faire to verify that an empty collection is empty. As explained in the <a href="index.html">Overview</a>, we're going to explore what it means to specify behaviour rather than testing state. Based on our existing spec thus far, there is no need to have a size or empty method. Let's see how far we can go without them...

data/doc/src/tutorials/stack.rb

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

@@ -0,0 +1,224 @@
+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>
+<br>
+<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>
+<br>
+<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>
+<br>
+<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>
+<br>
+<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"
+
+<a href="stack_02.html">Next</a>
+