rspec 1.2.2 → 1.2.3

data/lib/spec/mocks/spec_methods.rb

@@ -32,7 +32,7 @@ module Spec
       # to any message it receives that it hasn't been explicitly instructed
       # to respond to.
       def stub_everything(name = 'stub')
-        Kernel.warn(<<-WARNING)
+        Spec.warn(<<-WARNING)
 
 DEPRECATION: stub_everything('#{name}') is deprecated and will be removed
 from a future version of rspec. Please use mock('#{name}').as_null_object

data/lib/spec/runner/configuration.rb

@@ -1,6 +1,8 @@
 module Spec
   module Runner
     class Configuration
+      include Spec::Example::ArgsAndOptions
+      
       # Chooses what mock framework to use. Example:
       #
       #   Spec::Runner.configure do |config|
@@ -74,8 +76,8 @@ module Spec
       #     # *Will* include ControllerExampleHelpers
       #   end
       #
-      def include(*args)
-        include_or_extend(:include, *args)
+      def include(*modules_and_options)
+        include_or_extend(:include, *modules_and_options)
       end
       
       # :call-seq:
@@ -85,61 +87,61 @@ module Spec
       #
       # Works just like #include, but extends the example groups
       # with the modules rather than including them.
-      def extend(*args)
-        include_or_extend(:extend, *args)
-      end
-      
-      # Defines global predicate matchers. Example:
-      #
-      #   config.predicate_matchers[:swim] = :can_swim?
-      #
-      # This makes it possible to say:
-      #
-      #   person.should swim # passes if person.can_swim? returns true
-      #
-      def predicate_matchers
-        @predicate_matchers ||= {}
-      end
-      
-      # Prepends a global <tt>before</tt> block to all example groups.
-      # See #append_before for filtering semantics.
-      def prepend_before(*args, &proc)
-        add_callback(:prepend_before, *args, &proc)
+      def extend(*modules_and_options)
+        include_or_extend(:extend, *modules_and_options)
       end
       
       # Appends a global <tt>before</tt> block to all example groups.
-      #
-      # If you want to restrict the block to a subset of all the example
-      # groups then specify this in a Hash as the last argument:
-      #
-      #   config.prepend_before(:all, :type => :farm)
-      #
-      # or
-      #
-      #   config.prepend_before(:type => :farm)
-      #
-      def append_before(*args, &proc)
-        add_callback(:append_before, *args, &proc)
+      # <tt>scope</tt> can be any of <tt>:each</tt> (default), <tt>:all</tt>, or
+      # <tt>:suite</tt>. When <tt>:each</tt>, the block is executed before each
+      # example. When <tt>:all</tt>, the block is executed once per example
+      # group, before any of its examples are run. When <tt>:suite</tt> the
+      # block is run once before the entire suite is run.
+      def append_before(scope = :each, options={}, &proc)
+        add_callback(:append_before, scope, options, &proc)
       end
       alias_method :before, :append_before
 
+      # Prepends a global <tt>before</tt> block to all example groups.
+      # 
+      # See <tt>append_before</tt> for scoping semantics.
+      def prepend_before(scope = :each, options={}, &proc)
+        add_callback(:prepend_before, scope, options, &proc)
+      end
+      
       # Prepends a global <tt>after</tt> block to all example groups.
-      # See #append_before for filtering semantics.
-      def prepend_after(*args, &proc)
-        add_callback(:prepend_after, *args, &proc)
+      # 
+      # See <tt>append_before</tt> for scoping semantics.
+      def prepend_after(scope = :each, options={}, &proc)
+        add_callback(:prepend_after, scope, options, &proc)
       end
       alias_method :after, :prepend_after
       
       # Appends a global <tt>after</tt> block to all example groups.
-      # See #append_before for filtering semantics.
-      def append_after(*args, &proc)
-        add_callback(:append_after, *args, &proc)
+      # 
+      # See <tt>append_before</tt> for scoping semantics.
+      def append_after(scope = :each, options={}, &proc)
+        add_callback(:append_after, scope, options, &proc)
       end
 
+      # DEPRECATED - use Spec::Matchers::DSL instead
+      #
+      # Defines global predicate matchers. Example:
+      #
+      #   config.predicate_matchers[:swim] = :can_swim?
+      #
+      # This makes it possible to say:
+      #
+      #   person.should swim # passes if person.can_swim? returns true
+      #
+      def predicate_matchers
+        @predicate_matchers ||= Spec::HashWithDeprecationNotice.new("predicate_matchers", "the new Matcher DSL")
+      end
+      
     private
     
       def include_or_extend(action, *args)
-        modules, options = Spec::Example.args_and_options(*args)
+        modules, options = args_and_options(*args)
         [get_type_from_options(options)].flatten.each do |required_example_group|
           required_example_group = required_example_group.to_sym if required_example_group
           modules.each do |mod|
@@ -149,7 +151,7 @@ module Spec
       end
 
       def add_callback(sym, *args, &proc)
-        scope, options = Spec::Example.scope_and_options(*args)
+        scope, options = scope_and_options(*args)
         example_group = Spec::Example::ExampleGroupFactory[get_type_from_options(options)]
         example_group.__send__(sym, scope, &proc)
       end
@@ -161,6 +163,15 @@ module Spec
       def mock_framework_path(framework_name)
         File.expand_path(File.join(File.dirname(__FILE__), "/../adapters/mock_frameworks/#{framework_name}"))
       end
+
+      def scope_and_options(*args) # :nodoc:
+        args, options = args_and_options(*args)
+        return scope_from(*args), options
+      end
+
+      def scope_from(*args) # :nodoc:
+        args[0] || :each
+      end
     end
   end
 end

data/lib/spec/runner/drb_command_line.rb

@@ -12,7 +12,7 @@ module Spec
           DRb.start_service("druby://localhost:0")
           spec_server = DRbObject.new_with_uri("druby://127.0.0.1:8989")
           spec_server.run(options.argv, options.error_stream, options.output_stream)
-        rescue DRb::DRbConnError => e
+        rescue DRb::DRbConnError
           options.error_stream.puts "No server is running"
         end
       end

data/lib/spec/runner/example_group_runner.rb

@@ -55,17 +55,5 @@ module Spec
         @options.number_of_examples
       end
     end
-    
-    class BehaviourRunner < ExampleGroupRunner
-      def initialize(options)
-        Kernel.warn <<-WARNING
-DEPRECATED: The BeheviourRunner class is deprecated and will
-be removed from rspec-1.2.
-
-Use ExampleGroupRunner instead.
-WARNING
-        super
-      end
-    end
   end
 end

data/lib/spec/runner/formatter/base_formatter.rb

@@ -1,14 +1,29 @@
 module Spec
   module Runner
     module Formatter
-      # Formatter base-class, which implements all required methods.
-      # Almost all of the implementations are no-ops, with the exception
-      # of +add_example_group+ (see below).
+      # Formatter base-class, which implements all required methods as no-ops, with the exception
       class BaseFormatter
-        attr_accessor :example_group, :options, :where
-        def initialize(options, where)
-          @options = options
-          @where = where
+        # Formatters are initialized with <tt>options</tt> and <tt>output</tt>
+        # arguments. RSpec's built-in formatters already expect this, and any
+        # custom formatters should as well.
+        #
+        # ==== Parameters
+        # options::
+        #   A struct containing boolean values for colour, autospec,
+        #   and dry_run
+        # output::
+        #   Used by RSpec's built-in formatters to determine where to
+        #   write the output. Default is <tt>STDOUT</tt>, otherwise a
+        #   filename is expected.
+        #
+        # === Example
+        # If you invoke the <tt>spec</tt> command with:
+        #
+        #   --format progress:progress_report.txt
+        #
+        # ... the value of <tt>output</tt> will be progress_report.txt. If you
+        # don't identify an output destination, the default is STDOUT.
+        def initialize(options, output)
         end
         
         # This method is invoked before any examples are run, right after
@@ -16,55 +31,77 @@ module Spec
         # 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_example_group
+        # is #example_group_started
+        #
+        # ==== Parameters
+        # example_count:: the total number of examples to be run
         def start(example_count)
         end
 
-        # This method is invoked at the beginning of the execution of each example_group.
-        # +example_group_proxy+ is an instance of Spec::Example::ExampleGroupProxy, and
-        # is assigned as the value returned by subsequent calls to +example_group()+
+        # This method is invoked at the beginning of the execution of each
+        # example_group. The next method to be invoked after this is
+        # #example_started
         #
-        # The next method to be invoked after this is #example_started
+        # ==== Parameters
+        # example_group_proxy:: instance of Spec::Example::ExampleGroupProxy
+        def example_group_started(example_group_proxy)
+        end
+        
+        # Deprecated - use example_group_started instead
         def add_example_group(example_group_proxy)
-          @example_group = example_group_proxy
+          Spec.deprecate("BaseFormatter#add_example_group", "BaseFormatter#example_group_started")
+          example_group_started(example_group_proxy)
         end
 
-        # This method is invoked when an +example+ starts.
-        # +example_proxy+ is an instance of Spec::Example::ExampleProxy
+        # This method is invoked when an +example+ starts. The next method to be
+        # invoked after this is #example_passed, #example_failed, or
+        # #example_pending
         #
-        # The next method to be invoked after this is #example_passed, #example_failed,
-        # or #example_pending
+        # ==== Parameters
+        # example_proxy:: instance of Spec::Example::ExampleProxy
         def example_started(example_proxy)
         end
 
         # This method is invoked when an +example+ passes.
         # +example_proxy+ is the same instance of Spec::Example::ExampleProxy
         # that was passed to example_started
+        #
+        # ==== Parameters
+        # example_proxy:: instance of Spec::Example::ExampleProxy
         def example_passed(example_proxy)
         end
 
         # This method is invoked when an +example+ fails, i.e. an exception occurred
-        # inside it (such as a failed should or other exception). +counter+ is the 
-        # sequence number of the failure (starting at 1) and +failure+ is the associated 
-        # Failure object.
-        # +example_proxy+ is the same instance of Spec::Example::ExampleProxy
-        # that was passed to example_started
+        # inside it (such as a failed should or other exception).
+        #
+        # ==== Parameters
+        # example_proxy::
+        #   The same instance of Spec::Example::ExampleProxy that was passed
+        #   to <tt>example_started</tt>
+        #
+        # counter:: the sequential number of this failure
+        #
+        # failure:: instance of Spec::Runner::Reporter::Failure
         def example_failed(example_proxy, counter, failure)
         end
         
         # This method is invoked when an example is not yet implemented (i.e. has not
         # been provided a block), or when an ExamplePendingError is raised.
         # +message+ is the message from the ExamplePendingError, if it exists, or the
-        # default value of "Not Yet Implemented"
-        # +pending_caller+ is the file and line number of the spec which
-        # has called the pending method
-        # +example_proxy+ is the same instance of Spec::Example::ExampleProxy
-        # that was passed to example_started
-        def example_pending(example_proxy, message, pending_caller)
+        # default value of "Not Yet Implemented". +deprecated_pending_location+ is
+        # deprecated - use example_proxy.location instead
+        #
+        # ==== Parameters
+        # example_proxy:: instance of Spec::Example::ExampleProxy
+        # message::
+        #   the message passed to the pending message, or an internal
+        #   default
+        #
+        def example_pending(example_proxy, message, deprecated_pending_location=nil)
         end
 
         # This method is invoked after all of the examples have executed. The next method
-        # to be invoked after this one is #dump_failure (once for each failed example),
+        # to be invoked after this one is #dump_failure (once for each failed example)
         def start_dump
         end
 
@@ -72,14 +109,24 @@ module Spec
         # This method is invoked for each failed example after all examples have run. +counter+ is the sequence number
         # of the associated example. +failure+ is a Failure object, which contains detailed
         # information about the failure.
+        #
+        # ==== Parameters
+        # counter:: the sequential number of this failure
+        # failure:: instance of Spec::Runner::Reporter::Failure
         def dump_failure(counter, failure)
         end
       
         # This method is invoked after the dumping of examples and failures.
+        #
+        # ==== Parameters
+        # duration:: the total time for the entire run
+        # example_count:: the number of examples run
+        # failure_count:: the number of examples that failed
+        # pending_count:: the number of examples that are pending
         def dump_summary(duration, example_count, failure_count, pending_count)
         end
         
-        # This gets invoked after the summary if option is set to do so.
+        # This gets invoked after the summary
         def dump_pending
         end
 

data/lib/spec/runner/formatter/base_text_formatter.rb

@@ -8,23 +8,28 @@ module Spec
       # non-text based ones too - just ignore the +output+ constructor
       # argument.
       class BaseTextFormatter < BaseFormatter
-        attr_reader :output, :pending_examples
-        # Creates a new instance that will write to +where+. If +where+ is a
+        attr_reader :output, :example_group
+        # Creates a new instance that will write to +output+. If +output+ is a
         # String, output will be written to the File with that name, otherwise
-        # +where+ is exected to be an IO (or an object that responds to #puts and #write).
-        def initialize(options, where)
-          super
-          if where.is_a?(String)
-            FileUtils.mkdir_p(File.dirname(where))
-            @output = File.open(where, 'w')
+        # +output+ is exected to be an IO (or an object that responds to #puts
+        # and #write).
+        def initialize(options, output)
+          @options = options
+          if String === output
+            FileUtils.mkdir_p(File.dirname(output))
+            @output = File.open(output, 'w')
           else
-            @output = where
+            @output = output
           end
           @pending_examples = []
         end
+
+        def example_group_started(example_group_proxy)
+          @example_group = example_group_proxy
+        end
         
-        def example_pending(example, message, pending_caller)
-          @pending_examples << ["#{@example_group.description} #{example.description}", message, pending_caller]
+        def example_pending(example, message, ignore)
+          @pending_examples << ["#{@example_group.description} #{example.description}", message, example.location]
         end
         
         def dump_failure(counter, failure)
@@ -40,12 +45,7 @@ module Spec
         end
         
         def colourise(message, failure)
-          Kernel.warn <<-NOTICE
-DEPRECATED: BaseTextFormatter#colourise is deprecated and will be
-removed from a future version of RSpec.
-
-Please use colorize_failure instead.
-NOTICE
+          Spec::deprecate("BaseTextFormatter#colourise", "colorize_failure")
           colorize_failure(message, failure)
         end
         
@@ -126,14 +126,9 @@ NOTICE
         def red(text); colour(text, "\e[31m"); end
         def yellow(text); colour(text, "\e[33m"); end
         def blue(text); colour(text, "\e[34m"); end
-
+        
         def magenta(text)
-          Kernel.warn <<-NOTICE
-DEPRECATED: BaseTextFormatter#magenta is deprecated and will be
-removed from a future version of RSpec.
-
-Please use red instead (it is red/green/refactor after all).
-NOTICE
+          Spec::deprecate("BaseTextFormatter#magenta")
           red(text)
         end
       end

data/lib/spec/runner/formatter/failing_example_groups_formatter.rb

@@ -6,7 +6,7 @@ module Spec
       class FailingExampleGroupsFormatter < BaseTextFormatter
         def example_failed(example, counter, failure)
           if @example_group
-            @output.puts @example_group.filtered_description(/(.*) \(druby.*\)$/)
+            @output.puts @example_group.description.gsub(/ \(druby.*\)/,"")
 
             @output.flush
             @example_group = nil

data/lib/spec/runner/formatter/html_formatter.rb

@@ -1,11 +1,13 @@
 require 'erb'
 require 'spec/runner/formatter/base_text_formatter'
+require 'spec/runner/formatter/no_op_method_missing'
 
 module Spec
   module Runner
     module Formatter
       class HtmlFormatter < BaseTextFormatter
         include ERB::Util # for the #h method
+        include NOOPMethodMissing
         
         def initialize(options, output)
           super
@@ -14,10 +16,6 @@ module Spec
           @header_red = nil
         end
         
-        def method_missing(sym, *args)
-          # no-op
-        end
-
         # The number of the currently running example_group
         def example_group_number
           @example_group_number
@@ -36,7 +34,7 @@ module Spec
           @output.flush
         end
 
-        def add_example_group(example_group)
+        def example_group_started(example_group)
           super
           @example_group_red = false
           @example_group_number += 1
@@ -85,7 +83,7 @@ module Spec
           @output.flush
         end
 
-        def example_pending(example, message, pending_caller)
+        def example_pending(example, message, deprecated_pending_location=nil)
           @output.puts "    <script type=\"text/javascript\">makeYellow('rspec-header');</script>" unless @header_red
           @output.puts "    <script type=\"text/javascript\">makeYellow('example_group_#{example_group_number}');</script>" unless @example_group_red
           move_progress