rspec 0.5.3 → 0.5.4

data/doc/src/documentation/meta.info

@@ -1,22 +1,22 @@
 index.page:
-  orderInfo: 10
-  
-api.page:
-  orderInfo: 11
+  inMenu: 11
   
+underscores.page:
+  orderInfo: 13
+
 mocks.page:
-  orderInfo: 12
+  orderInfo: 14
   
 rdoc.html:
   title: RDoc
   dest: ../rdoc/index.html
   inMenu: true
-  orderInfo: 13
+  orderInfo: 15
 
 rcov.html:
   title: RCov
   dest: ../coverage/index.html
   inMenu: true
-  orderInfo: 14
+  orderInfo: 16
 
   

data/doc/src/documentation/mocks.page

@@ -8,193 +8,252 @@ RSpec contains a full featured Mock Objects framework.
 
 h3. Creating a mock
 
-<pre>
-mock(<name>)
-</pre>
+<ruby>
+my_mock = mock(<name>)
+</ruby>
 
-This creates a new mock with the given name (a string) and registers it. When the specification finishes, all registered mocks are verified.
+This creates a new mock with the given <code>name</code> (a string) and registers it. When the specification finishes, all registered mocks are verified.
 
-<pre>
-mock(<name>, <options>)
-</pre>
+<ruby>
+my_mock = mock(<name>, <options>)
+</ruby>
 
-As above, but allows you to specific options to tweak the mock's behaviour. The <code>options</code> argument is a hash. Currently the only supported option is <code>:null_object</code>. Setting this to true (i.e. <code>:null_object => true</code>) instructs the mock to ignore (quietly consume) any messages it hasn't been told to expect.
+As above, but allows you to specific options to tweak the mock's behaviour. The <code>options</code> argument is a hash. Currently the only supported option is <code>:null_object</code>. Setting this to true instructs the mock to ignore (quietly consume) any messages it hasn't been told to expect.  I.e.:
+
+<ruby>
+my_mock = mock("blah", :null_object => true)
+</ruby>
 
 h3. Expecting Messages
 
-<pre>
-mock.should.receive(<message>)
-</pre>
+<ruby>
+my_mock.should.receive(<message>)
+</ruby>
 
-The <code>message</code> argument is a symbol that is the name of a message that you want
-the mock to be expecting.
+The <code>message</code> argument is a symbol that is the name of a message that you want the mock to expect.
 
-h3. Arbitrary Message Receive Handling
+h3. Arbitrary Handling of Received Messages
 
 You can supply a block to a message expectation. When the message is received
 by the mock, the block is evaluated, and passed any arguments. The result is
 the return value of the message. For example:
 
-<pre>
-@mock.should.receive(:random_call) {| a | a.should.be true}
-</pre>
+<ruby>
+my_mock.should.receive(:random_call) {| a | a.should.be true}
+</ruby>
 
-This allows arbitrary argument validation and result computation.
+This allows arbitrary argument validation and result computation.  It's handy and kind of cool to be able to do this, but I advise against it.  Mocks should not be functional.  they should be completely declarative.  That said, it's sometimes useful to give them some minimal behaviour.
 
 h3. Expecting Arguments
 
-<pre>
-mock.should.receive(:msg).with(<args>)
-mock.should.receive(:msg).with(1, 2, 3)
-</pre>
+<ruby>
+my_mock.should.receive(:msg).with(<args>)
+</ruby>
+
+for example: 
+
+<ruby>
+my_mock.should.receive(:msg).with(1, 2, 3)
+</ruby>
 
-The <code>args</code> argument is a series of arguments (e..g. 1, 2, 3) that are expected
-to be passed as arguments to the associated message.
+The <code>args</code> argument is a series of arguments (e.g. 1, 2, 3) that are expected to be passed as arguments to the associated message.
 
-<pre>
-mock.should.receive(:msg).with(:no_args)
-</pre>
+<ruby>
+my_mock.should.receive(:msg).with(:no_args)
+</ruby>
 
-No arguments are to be accepted by the message.
+The message (<code>msg</code>) is expected to be passed no arguments.
 
-<pre>
-mock.should.receive(:msg).with(:any_args)
-</pre>
+<ruby>
+my_mock.should.receive(:msg).with(:any_args)
+</ruby>
 
-Any arguments are to be accepted by the message. This includes cases where no
-arguments are provided. *This is the default when no <code>with()</code> clause is
-specified.*  Even so, sometimes you want to be explicit about it.
+Any arguments (and any number of arguments) are to be accepted. This includes cases where no arguments are provided. *This is the default when no <code>with()</code> clause is specified.*  Even so, sometimes you want to be explicit about it.
 
 h3. Argument Constraints
 
-Constraints can be placed on individual arguments which are looser than value equivalence.
+Constraints can be placed on individual arguments which are looser than value equivalence (as above).
 
 h4. :anything
 
-accepts any value for this argument
+accepts any value for this argument, e.g.:
 
-<pre>
-mock.should.receive(:msg).with(1, :anything, "A")
-</pre>
+<ruby>
+my_mock.should.receive(:msg).with(1, :anything, "A")
+</ruby>
 
 h4. :numeric
 
-accepts any numeric value for this argument
+accepts any numeric value for this argument, e.g.:
 
-<pre>
-mock.should.receive(:msg).with(a, :numeric, "b")
-</pre>
+<ruby>
+my_mock.should.receive(:msg).with(a, :numeric, "b")
+</ruby>
 
 h4. :boolean
 
-accepts a boolean value for this argument
+accepts a boolean value for this argument, e.g.:
 
-<pre>
-mock.should.receive(:msg).with(a, :boolean, "b")
-</pre>
+<ruby>
+my_mock.should.receive(:msg).with(a, :boolean, "b")
+</ruby>
 
 h4. :string
 
-accepts any string for this argument
+accepts any string for this argument, e.g.:
 
-<pre>
-mock.should.receive(:msg).with(a, :string, "b")
-</pre>
+<ruby>
+my_mock.should.receive(:msg).with(a, :string, "b")
+</ruby>
 	
 h4. duck_type(message(s))
 
-accepts any object that responds to the prescribed message(s)
+accepts any object that responds to the prescribed message(s), e.g.:
 
-<pre>
+<ruby>
 #accepts a Fixnum for the second arg
-mock.should.receive(:msg).with(a, duck_type(:abs, :div), "b") 
-</pre>
+my_mock.should.receive(:msg).with(a, duck_type(:abs, :div), "b") 
+</ruby>
 
 h3. Receive Counts
 
-<pre>
-mock.should.receive(:msg).never
-</pre>
+<ruby>
+my_mock.should.receive(:msg).never
+</ruby>
 
-A problem is reported if the message is ever received.
+An exception is raised if the message is ever received.
 
-<pre>
-mock.should.receive(:msg).any.number.of.times
-</pre>
+<ruby>
+my_mock.should.receive(:msg).any.number.of.times
+</ruby>
 
 The message can be received 0 or more times.
 
-<pre>
-mock.should.receive(:msg).once
-</pre>
+<ruby>
+my_mock.should.receive(:msg).once
+</ruby>
 
-A problem is reported is the message is never received, or it is received more
-than once.
+An exception is raised if the message is never received, or it is received more than once.
 
-<pre>
-mock.should.receive(:msg).twice
-</pre>
+<ruby>
+my_mock.should.receive(:msg).twice
+</ruby>
 
-A problem is reported is the message is received anything but two times.
+An exception is raised if the message is received anything but two times.
 
-<pre>
-mock.should.receive(:msg).exactly(n).times
-</pre>
+<ruby>
+my_mock.should.receive(:msg).exactly(n).times
+</ruby>
 
-A problem is reported is the message is received anything but n times.
+An exception is raised if the message is received anything but <code>n</code> times.
 
-<pre>
-mock.should.receive(:msg).at.least(:once)
-</pre>
+<ruby>
+my_mock.should.receive(:msg).at.least(:once)
+</ruby>
 
-A problem is reported if the message is never received.
+An exception is raised if the message is never received.
 
-<pre>
-mock.should.receive(:msg).at.least(:twice)
-</pre>
+<ruby>
+my_mock.should.receive(:msg).at.least(:twice)
+</ruby>
 
-A problem is reported is the message is never received or is received only once.
+An exception is raised if the message is never received or is received only once.
 
-<pre>
-mock.should.receive(:msg).at.least(n).times
-</pre>
+<ruby>
+my_mock.should.receive(:msg).at.least(n).times
+</ruby>
 
-A problem is reported is the message is received fewer than n times.
+An exception is raised if the message is received fewer than <code>n</code> times.
 
 h3. Return Values
 
-<pre>
-mock.should.receive(:msg).once.and.return(<value>)
-</pre>
+h4. Single return value
 
-When the expected message is received, <code>value</code> will be returned as the result.
+<ruby>
+my_mock.should.receive(:msg).once.and.return(<value>)
+</ruby>
 
-<pre>
+Each time the expected message is received, <code>value</code> will be returned as the result.
+
+h4. Consequtive return values
+
+<ruby>
 and.return([<value-1>, <value-2>, ..., <value-n>])
-</pre>
+</ruby>
+
+When the expected message is received, <code>value-i</code> will be returned as the result for the ith reception of the message. After the message has been received <code>i</code> times, <code>value-n</code> is returned for all
+subsequent receives.  
 
-When the expected message is received, <code>value-i</code> will be returned as the result
-for the ith reception of the message. Once <code>i > n</code>, <code>value-n</code> is returned for all
-subsequent receives of the message.
+*Note:* if you wish to have a single return value that is an array, you must use this form, with one item that is the array to return.  Otherwise your array will be interpreted as a series of return values.  For example:
 
-<pre>
-mock.should.receive(:msg).once.and.return {...} 
-</pre>
+<ruby>  
+and.return([[1, 2, 3]])
+</ruby>
+
+h4. Computed return value
+
+<ruby>
+my_mock.should.receive(:msg).once.and.return {...} 
+</ruby>
 
 When the expected message is received, the result of evaluating the supplied
 block will be returned as the result. The block is passed any arguments passed
-as parts of the message. This capability can be used to compute return values
-based on the arguments.  For example:
+as arguments of the message. This capability can be used to compute return values based on the arguments.  For example:
 
-<pre>
-mock.should.receive(:msg).once.and.return {|a, b| a + b}
-</pre>
+<ruby>
+my_mock.should.receive(:msg).with(:numeric, :numeric) once.and.return {|a, b| a + b}
+</ruby>
 
 h3. Raising and Throwing
 
-<pre>
-mock.should.receive(:msg).once.and.raise(<exception>)
-mock.should.receive(:msg).once.and.throw(<symbol>) 
-</pre>
+<ruby>
+my_mock.should.receive(:msg).once.and.raise(<exception>)
+my_mock.should.receive(:msg).once.and.throw(<symbol>) 
+</ruby>
+
+These instruct the mock to raise an exception or throw a symbol, respectively, instead of returning a value.
+
+h3. Yielding
+
+<ruby>
+my_mock.should.receive(:msg).once.and.yield([<value-1>, <value-2>, ..., <value-n>])
+</ruby>
+
+When the expected message is received, the mock will yield the values to the passed block.
+
+h3. Ordering
+
+There are times when you want to specify the order of messages sent to a mock.
+It shouldn't be the case very often, but it can be handy at times. 
+
+Labeling expectations as being ordered is done by the <code>ordered</code> call:
+
+<ruby>
+my_mock.should.receive(:flip).once.ordered
+my_mock.should.receive(:flop).once.ordered
+</ruby>
+
+If the send of <code>flop</code> is seen before <code>flip</code> the specification will fail.
+
+Of course, chains of ordered expectations can be set up:
+
+<ruby>
+my_mock.should.receive(:one).ordered
+my_mock.should.receive(:two).ordered
+my_mock.should.receive(:three).ordered
+</ruby>
+
+The expected order is the order in which the expectations are declared.
+
+Order-independant expectations can be set anywhere in the expectation sequence, in any order.  Only the order of expectations tagged with the <code>ordered</code> call is significant.  Likewise, calls to order-independant methods can be made in any order, even interspersed with calls to order-dependant methods.  For example:
 
-These instruct the mock to raise an exception or throw a symbol instead of returning a value.
+<ruby>
+  my_mock.should.receive(:zero)
+  my_mock.should.receive(:one).ordered
+  my_mock.should.receive(:two).ordered
+  my_mock.should.receive(:one_and_a_half)
+  my_mock.one
+  my_mock.one_and_a_half
+  my_mock.zero
+  my_mock.two
+</ruby>

data/doc/src/documentation/underscores.page

@@ -0,0 +1,20 @@
+---
+title: Underscore sugar
+inMenu: true
+---
+h2. Underscore sugar
+
+If you feel that the various dots hurt your eyes and is not very 'rubyish',
+you can replace your dots with underscores, so that instead of saying
+
+<ruby>
+lambda { 1.should.not.equal 1 }.should.raise
+</ruby>
+
+you can say
+
+<ruby>
+lambda { 1.should_not_equal 1 }.should_raise
+</ruby>
+
+This applies to regular Ruby objects as well as mocks.

data/doc/src/examples.page

@@ -5,4 +5,5 @@ inMenu: true
 h2. Examples
 
 Here is an example of an RSpec spec:
-{ruby_inline: {filename: ../examples/stack_spec.rb}}
+
+<ruby file="../examples/stack_spec.rb" />

data/doc/src/index.page

@@ -1,7 +1,74 @@
 ---
-title: Overview
+title: Overview 
 inMenu: true
----
+--- 
+
+h2. Behaviour Driven Development 
+
+Test Driven Development (TDD) has you define the behaviour of your system by
+writing small tests that precisely define some small piece of your system's
+behaviour. Then you implement that behaviour. Then you clean up & improve your
+design.
+
+At least that's how you're supposed to do it.
+
+This focus on behaviour is the real value in TDD, and marks the genuinely
+experienced TDD practitioner.
+
+However, with the ubiquity of testing related terminology in TDD and it's
+supporting frameworks, it is no surprise that it takes beginners some time to
+get to the understanding that TDD isn't about testing at all... if they ever
+do.
+
+The aim of BDD is to address this shortcoming and, by using terminology
+focused on the behavioural aspects of the system rather than testing, attempt
+to help direct developers towards a focus on the real value to be found in TDD
+at its most successful, or BDD as we call it.
+
+(paraphrased from "behaviour-driven.org":http://behaviour-driven.org)
+
+Dan North, who was the first to coin the term BDD, and who has been actively 
+refining it since, started promoting BDD in 2003. "JBehave":http://jbehave.codehaus.org/ 
+was the first BDD framework to support this new thinking.
+
 h2. RSpec
 
-bla bla bla
+RSpec is a framework for practicing __Behaviour Driven Development__ (BDD) in Ruby.
+
+It all started with a blogpost 
+("A New Look at Test Driven Development":http://blog.daveastels.com/articles/2005/07/05/a-new-look-at-test-driven-development) 
+of Dave's where he talked about his ideas for BDD and a BDD framework. One thing he mentioned was that his ideas
+would be easily implemented in Smalltalk, and probably Ruby.
+
+Steven Baker wrote the first version of the rspec core.  Dave added mock support (initially inspired from Schmock by 
+Ben Griffiths). Dave and David had met & talked about BDD at Agile'05 just after Dave's blog
+post (above). David started thinking about a BDD framework in C#. As fate, or
+the gods, would have it Dave & David ended up working at the same client in
+the greater Chicago area, allowing them to explore some ideas resulting in the totally rewriting of the expectation mechanism. 
+Aslak joined in and the three rewrote the higher level syntax and the core, reworking RSpec into what you see now:
+
+<ruby>
+context "BDD framework" do
+
+  setup do
+    @bdd_framework = BddFramework.new
+  end
+
+  specify "should be adopted quickly" do
+    @bdd_framework.should.be.adopted_quickly
+  end
+  
+  specify "should be intuitive" do
+    @bdd_framework.should.be.intuitive
+  end
+
+end
+</ruby>
+
+RSpec provides a framework for writing what we call __executable
+specifications of program behaviour__. Since that's rather wordy, we usually
+just call them __specs__. 
+"Some other people":http://www.testing.com/cgi-bin/blog/2006/04/12#spec-vs-example call these things __examples__.
+
+On this site you will find examples, documentation, and tutorials as well as
+links to download and community resources.