rspec 0.5.11 → 0.5.12

data/doc/src/tools/test2spec.page

@@ -1,103 +0,0 @@
----
-title: Test::Unit Migration
-inMenu: true
----
-h2. Overview of test2spec
-
-RSpec's test2spec command line tool translates existing Test::Unit classes to RSpec.  
-
-Before you can use test2spec you must gem install ParseTree (and RubyInline).
-RubyInline only works on systems that have a C compiler - i.e. most anything except Windows.
-
-If you're stuck on Windows, ask a friend who has a POSIX system to translate your specs.
-Once translated they can run on any Ruby platform (including Windows). After all, it's
-just Ruby.
-
-h2. The test2spec command line
-
-<pre>
-test2spec --help
-{execute: ruby ../bin/test2spec --help}
-</pre>
-
-A typical invocation might look like this:
-
-<pre>
-test2spec --template spec/test2spec.erb --specdir spec test
-</pre>
-
-Where spec/test2spec.erb contains the following:
-
-<pre>
-{includeFile: {filename: ../../../spec/test2spec.erb, processOutput: false}}
-</pre>
-
-
-h2. Sample translation
-
-<notextile>
-<table>
-  <thead>
-    <tr>
-      <td>Test::Unit (input)</td>
-      <td>RSpec (output)</td>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>
-        <ruby file="../test/spec/test_to_spec/testfiles/test_unit_api_test.rb"/>
-      </td>
-      <td>
-        <ruby file="../spec/translated/test_unit_api_spec.rb"/>
-      </td>
-    </tr>
-  </tbody>
-</table>
-</notextile>
-
-h2. What's translated?
-
-test2spec only translates classes that extend from Test::Unit - and their methods. It will not bring over any 
-code that isn't inside a Test::Unit class. This means that require statements at the top of your file, any 
-non-Test::Unit classes (even if they are in in the same file as the test class) *will not be translated*.
-
-We recommend that you manually write a spec_helper.rb file with require statements and put it at the top 
-of your spec directory. Also, write a test2spec.erb file that will put a <tt>require</tt> of that file at 
-the top of each translated spec. Use the <tt>--template</tt> option to specify this erb file when you run test2spec.
-
-Sometimes, test classes have helper methods that don't start with test_ (and that are not setup or teardown).
-These methods will be moved inside the setup block, and will also have any core Test::Unit assert_* methods
-translated. (Non-Test::Unit core assert_ methods will not be translated.)
-
-So, there is a fair chance that you will have to do some manual editing after test2spec has run. We're only
-aiming to get most of the translation job done for you - not all of it.
-
-If you're translating Rails tests, please refer to the RSpec on Rails page for more detail of what needs to 
-be done.
-
-h2. Troubleshooting
-
-In some cases, test2spec will not be able to translate a test class. In that case, please submit a bug report
-at RSpec's bug report system  along with some code so we can reproduce (and hopefully - fix) the problem. 
--Or better - submit a patch.
-
-h2. Internals
-
-The test2spec commandline 'runs' the tests with a special test runner - one that translates and writes out
-the translations to disk instead of actually executing the tests.
-
-The translation is done by the <tt>Test::Unit::TestCase#to_rspec</tt> method (which test2spec adds to all 
-test classes). This method will load the parse tree for the class, transform that tree to an RSpec context 
-and return the source code (using RubyToRuby).
-
-test2spec is based directly on two other tools:
-
-* "RubyToRuby":http://blog.zenspider.com/archives/2005/02/rubytoruby.html
-* "ParseTree":http://rubyforge.org/projects/parsetree/
-
-In fact, it's based on a modified version of "George Moschovitis' RubyToRuby enhancement":http://dark.fhtr.org/ruby2ruby.rb
-of "Ryan Davis' original RubyToRuby":http://blog.zenspider.com/archives/2005/02/rubytoruby.html.
-
-It has been modified to fix some subtle bugs that were not found by Gerorge's tests. The modified RubyToRuby
-currently lives in RSpec's subversion repository.

data/doc/src/tutorials/index.page

@@ -1,52 +0,0 @@
----
-title: Overview
----
-h2. A Simple Stack - Overview
-
-h3. A simple (very much in progress) tutorial by David Chelimsky
-
-In this tutorial, we're going to explore Behaviour Driven Development using rSpec. A primary goal of BDD is to think about specifications rather than testing. We'll explore what that means, and how it affects the process of specifying components in a system. For example, one of the examples I've used in TDD classes is test-driving a Stack. It would usually start with a test like this:
-
-<ruby>
-#NOT A BDD EXAMPLE
-def test_new_stack_should_be_empty
-  stack = Stack.new
-  assert_equal(0, stack.size)
-end
-</ruby>
-
-We start with that because it is a VERY simple place to start. To get that test to pass, you need very little code...
-
-<ruby>
-class Stack
-  def size
-    0
-  end
-end
-</ruby>
-
-...and you're off and running. So here's a question: what is the <em><b>behaviour</b></em> that is exhibited by <code>size</code>? You could say that the stack is answering the question correctly. But then the question becomes "what is the question?"
-
-Think of it this way: does size really matter? Keeping focused on the Stack example, I'd say the answer is often "no". Most clients probably care about whether they can push something on to the stack, or pop something off of it. But knowing whether it has 0 or 1000 items is only helpful if the client knows what those numbers mean. And that often requires asking more questions. For example, let's say we want to push but we want to check if we can first:
-
-<ruby>
-stack.push item if stack.size < stack.capacity
-</ruby>
-
-Instead, we could ask if the stack is full...
-
-<ruby>
-stack.push item unless stack.full?
-</ruby>
-
-...but even then we have to know what it means to be full and adapt that knowledge to our real question which is "can I push something on to you"?
-
-<ruby>
-stack.push item if stack.accept? item
-</ruby>
-
-This is not to argue that "accept" is the best or right choice. The point is that all of this discussion has been about how our stack appears from the outside. We want to think about how other clients can use the object, not how the object will satisfy its clients' needs.
-
-"Tell, Don't Ask" is a powerful guideline, but sometimes you have to ask questions. So let's extend TDA with this: "...but if you MUST ask, then ask for what you really need". Do we need to know the stack's size? Probably not. We <em>do</em>, however, need to know whether we can push onto it.
-
-We'll be exploring these questions in this tutorial in addition to getting you started with rSpec. So <a href="stack_01.html">let's get started!</a>

data/doc/src/tutorials/meta.info

@@ -1,36 +0,0 @@
-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: false
-  orderInfo: 15
-
-stack_05.page:
-  title: '6'
-  inMenu: false
-  orderInfo: 16
-
-  

data/doc/src/tutorials/notes.txt

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