rspec 0.5.6 → 0.5.7

data/doc/src/documentation/underscores.page

@@ -4,17 +4,18 @@ 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
+The internal implementation of RSpec actually uses chained method calls, so it's possible
+to write:
 
 <ruby>
 lambda { 1.should.not.equal 1 }.should.raise
 </ruby>
 
-you can say
+However, in order to make RSpec look and feel closer to other ruby code,
+RSpec allows you to use underscores instead if you wish:
 
 <ruby>
 lambda { 1.should_not_equal 1 }.should_raise
 </ruby>
 
-This applies to regular Ruby objects as well as mocks.
+Therefore, you will see the underscored syntax throughout the documentation and examples.

data/doc/src/index.page

@@ -55,11 +55,11 @@ context "BDD framework" do
   end
 
   specify "should be adopted quickly" do
-    @bdd_framework.should.be.adopted_quickly
+    @bdd_framework.should_be_adopted_quickly
   end
   
   specify "should be intuitive" do
-    @bdd_framework.should.be.intuitive
+    @bdd_framework.should_be_intuitive
   end
 
 end

data/doc/src/tools/rails.page

@@ -15,11 +15,13 @@ h3. Features
 h3. Installation
 
 RSpec support for rails lives in a separate gem. Install that gem:
+
 <pre>
 gem install rspec_generator
 </pre>
 
 Once the gem is installed, you must configure you Rails app. Stand in the root of your Rails app and run:
+
 <pre>
 ruby script/generate rspec
 </pre>
@@ -40,17 +42,26 @@ For more information on each generator, just run them without any arguments.
 
 h3. Running specs
 
+All specs can be run with
+
+<pre>
+rake spec
+</pre>
+
 Model specs can be run with
+
 <pre>
 rake spec:models
 </pre>
 
 Controller specs can be run with
+
 <pre>
 rake spec:controllers
 </pre>
 
 To see all the RSpec related tasks, run
+
 <pre>
 rake --tasks spec
 </pre>

data/doc/src/tools/spec.page

@@ -25,10 +25,10 @@ spec will exit with the exitcode 1 if one or more specs fail.
 The general form of the command is
 
 <pre>
-spec [options] (FILE|DIRECTORY)+
+spec [options] (FILE|DIRECTORY|GLOB)+
 </pre>
 
-Any number of files and/or directories can be provided, all ruby source files
+Any number of files, directories and shell globs can be provided, all ruby source files
 that are found are loaded. Running spec on the previous example results in:
 
 <pre>
@@ -68,10 +68,25 @@ $ bin/spec failing_examples/team_spec.rb -f rdoc
 {execute: ../bin/spec ../failing_examples/team_spec.rb -f rdoc}
 </pre>
 
+h4. Custom formatters
+
+As of RSpec 0.5.7 custom formatters are supported. If the argument to the --format option is none
+of the builtin formatters, RSpec will assume it's a class name, and try to instantiate that class.
+If you're using this feature, make sure to use the --require option as well - *before* the
+--format option.
+
+See the RDoc for "Spec::Runner::BaseTextFormatter":../rdoc/classes/Spec/Runner/BaseTextFormatter.html 
+for details on how to implement your own. A custom formatter can be found under examples/custom_formatter.rb.
+
+h3. -r, --require FILE
+
+Causes FILE to be loaded (via require) before any specs are executed. If you're using a custom
+formatter, you have to specify this option *before* the --format option.
+
 h3. -d, --dry-run
 
 This option tells RSpec not to execute the specs, but they are still being parsed.
-This can be useful when generating "testdox":http://agiledox.sourceforge.net/ documents
+This can be useful when generating "testdox-like":http://agiledox.sourceforge.net/ documents
 
 h3. -b, --backtrace
 

data/doc/src/tutorials/notes.txt

@@ -7,7 +7,7 @@ context "A stack with one item" do
   end
 
   specify "should return top when you send it 'top'" do
-    @stack.top.should.equal "one item"
+    @stack.top.should_equal "one item"
   end
   
 end
@@ -64,7 +64,10 @@ 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".
+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"
 
@@ -189,17 +192,25 @@ 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.
+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:
+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
+  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...
+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

data/doc/src/tutorials/stack_04.page.orig

@@ -14,11 +14,11 @@ context "An empty stack" do
   end
   
   specify "should keep its mouth shut when you send it 'push'" do
-     lambda { @stack.push Object.new }.should.not.raise Exception
+     lambda { @stack.push Object.new }.should_not_raise Exception
   end
   
   specify "should raise a StackUnderflowError when you send it 'top'" do
-    lambda { @stack.top }.should.raise StackUnderflowError
+    lambda { @stack.top }.should_raise StackUnderflowError
   end
   
 end

data/doc/src/tutorials/stack_05.page.orig

@@ -14,11 +14,11 @@ context "An empty stack" do
   end
   
   specify "should keep its mouth shut when you send it 'push'" do
-     lambda { @stack.push Object.new }.should.not.raise Exception
+     lambda { @stack.push Object.new }.should_not_raise Exception
   end
   
   specify "should raise a StackUnderflowError when you send it 'top'" do
-    lambda { @stack.top }.should.raise StackUnderflowError
+    lambda { @stack.top }.should_raise StackUnderflowError
   end
   
 end
@@ -31,7 +31,7 @@ context "A stack with one item" do
   end
 
   specify "should return top when sent the 'top' message" do
-    @stack.top.should.equal "one item"
+    @stack.top.should_equal "one item"
   end
   
 end
@@ -80,11 +80,11 @@ context "A stack with one item" do
   end
 
   specify "should keep its mouth shut when you send it 'push'" do
-     lambda { @stack.push Object.new }.should.not.raise Exception
+     lambda { @stack.push Object.new }.should_not_raise Exception
   end
   
   specify "should return top when you send it 'top'" do
-    @stack.top.should.equal "one item"
+    @stack.top.should_equal "one item"
   end
   
 end

data/doc/src/tutorials/stack_06.page

@@ -10,15 +10,15 @@ context "An empty stack" do
   end
   
   specify "should keep its mouth shut when you send it 'push'" do
-     lambda { @stack.push Object.new }.should.not.raise Exception
+     lambda { @stack.push Object.new }.should_not.raise Exception
   end
   
   specify "should raise a StackUnderflowError when you send it 'top'" do
-    lambda { @stack.top }.should.raise StackUnderflowError
+    lambda { @stack.top }.should_raise StackUnderflowError
   end
   
   specify "should raise a StackUnderflowError when you send it 'pop'" do
-    lambda { @stack.pop }.should.raise StackUnderflowError
+    lambda { @stack.pop }.should_raise StackUnderflowError
   end
   
 end
@@ -121,15 +121,15 @@ context "A stack with one item" do
   end
 
   specify "should keep its mouth shut when you send it 'push'" do
-     lambda { @stack.push Object.new }.should.not.raise Exception
+     lambda { @stack.push Object.new }.should_not.raise Exception
   end
   
   specify "should return top when you send it 'top'" do
-    @stack.top.should.equal "one item"
+    @stack.top.should_equal "one item"
   end
   
   specify "should return top when you send it 'pop'" do
-    @stack.pop.should.equal "one item"
+    @stack.pop.should_equal "one item"
   end
   
 end
@@ -236,7 +236,7 @@ What we're looking for here is observable behaviour. How does a one-element stac
 <ruby>
 specify "should raise a StackUnderflowError the second time you sent it 'pop'" do
   @stack.pop
-  lambda { @stack.pop }.should.raise StackUnderflowError
+  lambda { @stack.pop }.should_raise StackUnderflowError
 end
 </ruby>
 

data/doc/src/tutorials/stack_06.page.orig

@@ -295,20 +295,20 @@ context "A stack with one item" do
   end
 
   specify "should keep its mouth shut when you send it 'push'" do
-     lambda { @stack.push Object.new }.should.not.raise Exception
+     lambda { @stack.push Object.new }.should_not_raise Exception
   end
   
   specify "should return top when you send it 'top'" do
-    @stack.top.should.equal "one item"
+    @stack.top.should_equal "one item"
   end
   
   specify "should return top when you send it 'pop'" do
-    @stack.pop.should.equal "one item"
+    @stack.pop.should_equal "one item"
   end
   
   specify "should raise a StackUnderflowError the second time you sent it 'pop'" do
     @stack.pop
-    lambda { @stack.pop }.should.raise StackUnderflowError
+    lambda { @stack.pop }.should_raise StackUnderflowError
   end
   
 end
@@ -322,9 +322,9 @@ context "A stack with one item" do
   ...
   
   specify "should return top repeatedly when you send it 'top'" do
-    @stack.top.should.equal "one item"
-    @stack.top.should.equal "one item"
-    @stack.top.should.equal "one item"
+    @stack.top.should_equal "one item"
+    @stack.top.should_equal "one item"
+    @stack.top.should_equal "one item"
   end
 
   ...

data/examples/custom_formatter.rb

@@ -0,0 +1,21 @@
+require 'spec/runner/base_text_formatter'
+
+# Example of a custom formatter. Run me with:
+# bin/spec examples -r examples/custom_formatter.rb -f CustomFormatter
+class CustomFormatter < Spec::Runner::BaseTextFormatter
+  def add_context(name, first)
+    @output << "\n" if first
+  end
+  
+  def spec_failed(name, counter)
+    @output << 'X'
+  end
+  
+  def spec_passed(name)
+    @output << '_'
+  end
+  
+  def start_dump
+    @output << "\n"
+  end
+end

data/examples/mocking_spec.rb

@@ -4,7 +4,7 @@ context "Mocker" do
 
   specify "should be able to call mock()" do
     mock = mock("poke me")
-    mock.should.receive(:poke)
+    mock.should_receive(:poke)
     mock.poke
   end
 

data/examples/stack_spec.rb

@@ -16,7 +16,7 @@ context "An empty stack" do
   end
   
   specify "should complain when sent pop" do
-    lambda { @stack.pop }.should.raise StackUnderflowError
+    lambda { @stack.pop }.should_raise StackUnderflowError
   end
   
 end
@@ -29,25 +29,25 @@ context "A stack with one item" do
   end
 
   specify "should accept an item when sent push" do
-    lambda { @stack.push Object.new }.should.not.raise
+    lambda { @stack.push Object.new }.should_not_raise
   end
   
   specify "should return top when sent top" do
-    @stack.top.should.be 3
+    @stack.top.should_be 3
   end
   
   specify "should not remove top when sent top" do
-    @stack.top.should.be 3
-    @stack.top.should.be 3
+    @stack.top.should_be 3
+    @stack.top.should_be 3
   end
   
   specify "should return top when sent pop" do
-    @stack.pop.should.be 3
+    @stack.pop.should_be 3
   end
   
   specify "should remove top when sent pop" do
-    @stack.pop.should.be 3
-    lambda { @stack.pop }.should.raise StackUnderflowError
+    @stack.pop.should_be 3
+    lambda { @stack.pop }.should_raise StackUnderflowError
   end
   
 end
@@ -64,21 +64,21 @@ context "An almost full stack (with one item less than capacity)" do
   end
   
   specify "should return top when sent top" do
-    @stack.top.should.be 9
+    @stack.top.should_be 9
   end
   
   specify "should not remove top when sent top" do
-    @stack.top.should.be 9
-    @stack.top.should.be 9
+    @stack.top.should_be 9
+    @stack.top.should_be 9
   end
   
   specify "should return top when sent pop" do
-    @stack.pop.should.be 9
+    @stack.pop.should_be 9
   end
   
   specify "should remove top when sent pop" do
-    @stack.pop.should.be 9
-    @stack.pop.should.be 8
+    @stack.pop.should_be 9
+    @stack.pop.should_be 8
   end
   
 end
@@ -91,25 +91,25 @@ context "A full stack" do
   end
 
   specify "should complain on push" do
-    lambda { @stack.push Object.new }.should.raise StackOverflowError
+    lambda { @stack.push Object.new }.should_raise StackOverflowError
   end
   
   specify "should return top when sent top" do
-    @stack.top.should.be 10
+    @stack.top.should_be 10
   end
   
   specify "should not remove top when sent top" do
-    @stack.top.should.be 10
-    @stack.top.should.be 10
+    @stack.top.should_be 10
+    @stack.top.should_be 10
   end
   
   specify "should return top when sent pop" do
-    @stack.pop.should.be 10
+    @stack.pop.should_be 10
   end
   
   specify "should remove top when sent pop" do
-    @stack.pop.should.be 10
-    @stack.pop.should.be 9
+    @stack.pop.should_be 10
+    @stack.pop.should_be 9
   end
   
 end

data/lib/spec/runner/base_text_formatter.rb

@@ -1,11 +1,52 @@
 module Spec
   module Runner
+    # Baseclass for text-based formatters. Can in fact be used for
+    # non-text based ones too - just ignore the +output+ constructor
+    # argument.
     class BaseTextFormatter
       def initialize(output, dry_run=false)
         @dry_run = dry_run
         @output = output
       end
 
+      # This method is invoked before any specs are run, right after
+      # they have all been collected. This can be useful for special
+      # formatters that need to provide progress on feedback (graphical ones)
+      #
+      # This method will only be invoked once, and the next one to be invoked
+      # is #add_context
+      def start(spec_count)
+      end
+
+      # This method is invoked at the beginning of the execution of each context.
+      # +name+ is the name of the context and +first+ is true if it is the
+      # first context - otherwise it's false.
+      #
+      # The next method to be invoked after this one is one of #spec_failed
+      # or #spec_passed.
+      def add_context(name, first)
+      end
+
+      # This method is invoked whenever a spec fails, i.e. an exception occurred
+      # inside it (such as a failed should or other exception). +name+ is the name
+      # of the specification.
+      def spec_failed(name)
+      end
+
+      # This method is invoked whwnever a spec passes. +name+ is the name of the
+      # specification.
+      def spec_passed(name)
+      end
+
+      # This method is invoked after all of the specs have executed. The next method
+      # to be invoked after this one is #dump_failure (once for each failed spec),
+      def start_dump
+      end
+
+      # Dumps detailed information about a spec failure.
+      # This method is invoked for each failed spec. +counter+ is the sequence number
+      # of the associated spec. +failure+ is a Failure object, which contains detailed
+      # information about the failure.
       def dump_failure(counter, failure)
         @output << "\n"
         @output << counter.to_s << ")\n"
@@ -14,6 +55,7 @@ module Spec
         @output << "#{failure.backtrace}\n"
       end
       
+      # This method is invoked at the very end.
       def dump_summary(duration, context_count, spec_count, failure_count)
         return if @dry_run
         @output << "\n"