rspec-core 3.0.0.beta2 → 3.0.0.rc1

data/lib/rspec/core/option_parser.rb

@@ -2,7 +2,7 @@
 require 'optparse'
 
 module RSpec::Core
-  # @api private
+  # @private
   class Parser
     def self.parse(args)
       new.parse(args)
@@ -11,8 +11,6 @@ module RSpec::Core
     def parse(args)
       return {} if args.empty?
 
-      convert_deprecated_args(args)
-
       options = args.delete('--tty') ? {:tty => true} : {}
       begin
         parser(options).parse!(args)
@@ -23,19 +21,6 @@ module RSpec::Core
       options
     end
 
-    def convert_deprecated_args(args)
-      args.map! { |arg|
-        case arg
-        when "--default_path"
-          "--default-path"
-        when "--line_number"
-          "--line-number"
-        else
-          arg
-        end
-      }
-    end
-
     def parser(options)
       OptionParser.new do |parser|
         parser.banner = "Usage: rspec [options] [files or directories]\n\n"
@@ -92,7 +77,7 @@ module RSpec::Core
         end
 
         parser.on('--init', 'Initialize your project with RSpec.') do |cmd|
-          require 'rspec/core/project_initializer'
+          RSpec::Support.require_rspec_core "project_initializer"
           ProjectInitializer.new.run
           exit
         end
@@ -118,6 +103,10 @@ module RSpec::Core
           options[:formatters].last << o
         end
 
+        parser.on('--deprecation-out FILE', 'Write deprecation warnings to a file instead of $stderr.') do |file|
+          options[:deprecation_stream] = file
+        end
+
         parser.on('-b', '--backtrace', 'Enable full backtrace.') do |o|
           options[:full_backtrace] = true
         end
@@ -145,7 +134,7 @@ module RSpec::Core
         end
 
         parser.on('-w', '--warnings', 'Enable ruby warnings') do
-          options[:warnings] = true
+          $VERBOSE = true
         end
 
         parser.separator <<-FILTERING
@@ -169,11 +158,6 @@ FILTERING
           (options[:full_description] ||= []) << Regexp.compile(Regexp.escape(o))
         end
 
-        parser.on('-l', '--line-number LINE', 'Specify line number of an example or group (may be',
-                                              '  used more than once).') do |o|
-          (options[:line_numbers] ||= []) << o
-        end
-
         parser.on('-t', '--tag TAG[:VALUE]',
                   'Run examples with the specified tag, or exclude examples',
                   'by adding ~ before the tag.',
@@ -210,12 +194,19 @@ FILTERING
           exit
         end
 
+        # these options would otherwise be confusing to users, so we forcibly prevent them from executing
+        # --I is too similar to -I
+        # -d was a shorthand for --debugger, which is removed, but now would trigger --default-path
+        invalid_options = %w[-d --I]
+
         parser.on_tail('-h', '--help', "You're looking at it.") do
-          puts parser
+          # removing the blank invalid options from the output
+          puts parser.to_s.gsub(/^\s+(#{invalid_options.join('|')})\s*$\n/,'')
           exit
         end
 
-        %w[-d --I].each do |option|
+        # this prevents usage of the invalid_options
+        invalid_options.each do |option|
           parser.on(option) do
             raise OptionParser::InvalidOption.new
           end

data/lib/rspec/core/ordering.rb

@@ -1,9 +1,11 @@
 module RSpec
   module Core
     if defined?(::Random)
+      # @private
       RandomNumberGenerator = ::Random
     else
-      require 'rspec/core/backport_random'
+      RSpec::Support.require_rspec_core "backport_random"
+      # @private
       RandomNumberGenerator = RSpec::Core::Backports::Random
     end
 

data/lib/rspec/core/pending.rb

@@ -1,6 +1,9 @@
 module RSpec
   module Core
+    # Provides methods to mark examples as pending. These methods are available to be
+    # called from within any example or hook.
     module Pending
+      # Raised in the middle of an example to indicate that it should be marked as skipped.
       class SkipDeclaredInExample < StandardError
         attr_reader :argument
 
@@ -9,7 +12,7 @@ module RSpec
         end
       end
 
-      # If Test::Unit is loaed, we'll use its error as baseclass, so that Test::Unit
+      # If Test::Unit is loaded, we'll use its error as baseclass, so that Test::Unit
       # will report unmet RSpec expectations as failures rather than errors.
       begin
         class PendingExampleFixedError < Test::Unit::AssertionFailedError; end
@@ -17,26 +20,27 @@ module RSpec
         class PendingExampleFixedError < StandardError; end
       end
 
+      # @private
       NO_REASON_GIVEN = 'No reason given'
+
+      # @private
       NOT_YET_IMPLEMENTED = 'Not yet implemented'
 
       # @overload pending()
       # @overload pending(message)
-      # @overload pending(message, &block)
       #
       # Marks an example as pending. The rest of the example will still be
       # executed, and if it passes the example will fail to indicate that the
       # pending can be removed.
       #
-      # @param [String] message optional message to add to the summary report.
+      # @param message [String] optional message to add to the summary report.
       #
       # @example
-      #
       #     describe "an example" do
       #       # reported as "Pending: no reason given"
       #       it "is pending with no message" do
       #         pending
-      #         raise "broken" 
+      #         raise "broken"
       #       end
       #
       #       # reported as "Pending: something else getting finished"
@@ -46,7 +50,7 @@ module RSpec
       #       end
       #     end
       #
-      # @note `before(:each)` hooks are eval'd when you use the `pending`
+      # @note `before(:example)` hooks are eval'd when you use the `pending`
       #   method within an example. If you want to declare an example `pending`
       #   and bypass the `before` hooks as well, you can pass `:pending => true`
       #   to the `it` method:
@@ -61,32 +65,43 @@ module RSpec
       #       it "does something", :pending => "something else getting finished" do
       #         # ...
       #       end
-      def pending(*args)
+      def pending(message=nil)
         current_example = RSpec.current_example
 
-        if current_example
-          Pending.mark_pending! current_example, args.first
+        if block_given?
+          raise ArgumentError, <<-EOS.gsub(/^\s+\|/, '')
+            |The semantics of `RSpec::Core::Pending#pending` have changed in
+            |RSpec 3.  In RSpec 2.x, it caused the example to be skipped. In
+            |RSpec 3, the rest of the example is still run but is expected to
+            |fail, and will be marked as a failure (rather than as pending) if
+            |the example passes.
+            |
+            |Passing a block within an example is now deprecated. Marking the
+            |example as pending provides the same behavior in RSpec 3 which was
+            |provided only by the block in RSpec 2.x.
+            |
+            |Move the code in the block provided to `pending` into the rest of
+            |the example body.
+            |
+            |Called from #{CallerFilter.first_non_rspec_line}.
+            |
+          EOS
+        elsif current_example
+          Pending.mark_pending! current_example, message
         else
           raise "`pending` may not be used outside of examples, such as in " +
-                "before(:all). Maybe you want `skip`?"
+                "before(:context). Maybe you want `skip`?"
         end
       end
 
       # @overload skip()
       # @overload skip(message)
-      # @overload skip(message, &block)
       #
-      # Marks an example as pending and skips execution when called without a
-      # block. When called with a block, skips just that block and does not
-      # mark the example as pending. The block form is provided as replacement
-      # for RSpec 2's pending-with-block feature, and is not recommended for
-      # new code. Use simple conditionals instead.
+      # Marks an example as pending and skips execution.
       #
-      # @param [String] message optional message to add to the summary report.
-      # @block [Block] block optional block to be skipped
+      # @param message [String] optional message to add to the summary report.
       #
       # @example
-      #
       #     describe "an example" do
       #       # reported as "Pending: no reason given"
       #       it "is skipped with no message" do
@@ -97,29 +112,34 @@ module RSpec
       #       it "is skipped with a custom message" do
       #         skip "something else getting finished"
       #       end
-      #
-      #       # Passes
-      #       it "contains a skipped statement" do
-      #         skip do
-      #           fail
-      #         end
-      #       end
       #     end
-      def skip(*args)
+      def skip(message=nil)
         current_example = RSpec.current_example
 
         if current_example
-          Pending.mark_skipped! current_example, args.first
+          Pending.mark_skipped! current_example, message
         end
 
-        raise SkipDeclaredInExample.new(args.first)
+        raise SkipDeclaredInExample.new(message)
       end
 
+      # @private
+      #
+      # Mark example as skipped
+      #
+      # @param example [RSpec::Core::Example] the example to mark as skipped
+      # @param message_or_bool [Boolean, String] the message to use, or true
       def self.mark_skipped!(example, message_or_bool)
         Pending.mark_pending! example, message_or_bool
         example.metadata[:skip] = true
       end
 
+      # @private
+      #
+      # Mark example as pending
+      #
+      # @param example [RSpec::Core::Example] the example to mark as pending
+      # @param message_or_bool [Boolean, String] the message to use, or true
       def self.mark_pending!(example, message_or_bool)
         message = if !message_or_bool || !(String === message_or_bool)
           NO_REASON_GIVEN
@@ -128,13 +148,17 @@ module RSpec
         end
 
         example.metadata[:pending] = true
-        example.metadata[:execution_result][:pending_message] = message
-        example.execution_result[:pending_fixed] = false
+        example.execution_result.pending_message = message
+        example.execution_result.pending_fixed = false
       end
 
+      # @private
+      #
+      # Mark example as fixed
+      #
+      # @param example [RSpec::Core::Example] the example to mark as fixed
       def self.mark_fixed!(example)
-        example.metadata[:pending] = false
-        example.metadata[:execution_result][:pending_fixed] = true
+        example.execution_result.pending_fixed = true
       end
     end
   end

data/lib/rspec/core/project_initializer.rb

@@ -1,5 +1,7 @@
 module RSpec
   module Core
+    # @private
+    # Generates conventional files for an rspec project
     class ProjectInitializer
       def run
         create_spec_helper_file

data/lib/rspec/core/project_initializer/spec_helper.rb

@@ -5,9 +5,10 @@
 #
 # Given that it is always loaded, you are encouraged to keep this file as
 # light-weight as possible. Requiring heavyweight dependencies from this file
-# (such as loading up an entire rails app) will add to the boot time of your
-# test suite on EVERY test run, even for an individual file that may not need
-# all of that loaded.
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, make a
+# separate helper file that requires this one and then use it only in the specs
+# that actually need it.
 #
 # The `.rspec` file also contains a few flags that are not defaults but that
 # users commonly want.
@@ -36,7 +37,7 @@ RSpec.configure do |config|
     # Use the documentation formatter for detailed output,
     # unless a formatter has already been configured
     # (e.g. via a command-line flag).
-    config.formatter = 'doc' if config.formatters.none?
+    config.default_formatter = 'doc'
   end
 
   # Print the 10 slowest examples and example groups at the

data/lib/rspec/core/rake_task.rb

@@ -1,13 +1,25 @@
-require 'rspec/support/warnings'
+require 'rspec/support'
+require 'rspec/core/version'
+RSpec::Support.require_rspec_support "warnings"
+
 require 'rake'
 require 'rake/tasklib'
 require 'shellwords'
 
 module RSpec
   module Core
+    # Rspec rake task
+    #
+    # @see Rakefile
     class RakeTask < ::Rake::TaskLib
       include ::Rake::DSL if defined?(::Rake::DSL)
 
+      # Default path to the rspec executable
+      DEFAULT_RSPEC_PATH = File.expand_path('../../../../exe/rspec', __FILE__)
+
+      # Default pattern for spec files.
+      DEFAULT_PATTERN = './spec{,/*/**}/*_spec.rb'
+
       # Name of task.
       #
       # default:
@@ -55,27 +67,18 @@ module RSpec
       attr_accessor :rspec_opts
 
       def initialize(*args, &task_block)
-        setup_ivars(args)
-
-        desc "Run RSpec code examples" unless ::Rake.application.last_comment
-
-        task name, *args do |_, task_args|
-          RakeFileUtils.__send__(:verbose, verbose) do
-            task_block.call(*[self, task_args].slice(0, task_block.arity)) if task_block
-            run_task verbose
-          end
-        end
-      end
-
-      def setup_ivars(args)
-        @name = args.shift || :spec
-        @ruby_opts, @rspec_opts = nil, nil, nil
-        @verbose, @fail_on_error = true, true
-
-        @rspec_path = 'rspec'
-        @pattern    = './spec{,/*/**}/*_spec.rb'
+        @name          = args.shift || :spec
+        @ruby_opts     = nil
+        @rspec_opts    = nil
+        @verbose       = true
+        @fail_on_error = true
+        @rspec_path    = DEFAULT_RSPEC_PATH
+        @pattern       = DEFAULT_PATTERN
+
+        define(args, &task_block)
       end
 
+      # @private
       def run_task(verbose)
         command = spec_command
 
@@ -93,6 +96,18 @@ module RSpec
 
     private
 
+      # @private
+      def define(args, &task_block)
+        desc "Run RSpec code examples" unless ::Rake.application.last_comment
+
+        task name, *args do |_, task_args|
+          RakeFileUtils.__send__(:verbose, verbose) do
+            task_block.call(*[self, task_args].slice(0, task_block.arity)) if task_block
+            run_task verbose
+          end
+        end
+      end
+
       def files_to_run
         if ENV['SPEC']
           FileList[ ENV['SPEC'] ].sort
@@ -105,6 +120,7 @@ module RSpec
         cmd_parts = []
         cmd_parts << RUBY
         cmd_parts << ruby_opts
+        cmd_parts << rspec_load_path
         cmd_parts << "-S" << rspec_path
         cmd_parts << files_to_run
         cmd_parts << rspec_opts
@@ -114,6 +130,15 @@ module RSpec
       def blank
         lambda {|s| s.nil? || s == ""}
       end
+
+      def rspec_load_path
+        @rspec_load_path ||= begin
+          core_and_support = $LOAD_PATH.grep \
+            %r{#{File::SEPARATOR}rspec-(core|support)[^#{File::SEPARATOR}]*#{File::SEPARATOR}lib}
+
+          "-I#{core_and_support.map(&:shellescape).join(File::PATH_SEPARATOR)}"
+        end
+      end
     end
   end
 end

data/lib/rspec/core/reporter.rb

@@ -1,19 +1,25 @@
 module RSpec::Core
+  # A reporter will send notifications to listeners, usually formatters for the
+  # spec suite run.
   class Reporter
 
     def initialize(configuration)
       @configuration = configuration
       @listeners = Hash.new { |h,k| h[k] = Set.new }
-      @example_count = @failure_count = @pending_count = 0
-      @duration = @start = nil
+      @examples = []
+      @failed_examples = []
+      @pending_examples = []
+      @duration = @start = @load_time = nil
     end
 
-    # @api
-    # @param [Object] An obect that wishes to be notified of reporter events
-    # @param [Array] Array of symbols represents the events a listener wishes to subscribe too
-    #
+    # @private
+    attr_reader :examples, :failed_examples, :pending_examples
+
     # Registers a listener to a list of notifications. The reporter will send notification of
     # events to all registered listeners
+    #
+    # @param listener [Object] An obect that wishes to be notified of reporter events
+    # @param notifications [Array] Array of symbols represents the events a listener wishes to subscribe too
     def register_listener(listener, *notifications)
       notifications.each do |notification|
         @listeners[notification.to_sym] << listener
@@ -21,6 +27,7 @@ module RSpec::Core
       true
     end
 
+    # @private
     def registered_listeners(notification)
       @listeners[notification].to_a
     end
@@ -28,8 +35,8 @@ module RSpec::Core
     # @api
     # @overload report(count, &block)
     # @overload report(count, &block)
-    # @param [Integer] count the number of examples being run
-    # @param [Block] block yields itself for further reporting.
+    # @param expected_example_count [Integer] the number of examples being run
+    # @yield [Block] block yields itself for further reporting.
     #
     # Initializes the report run and yields itself for further reporting. The
     # block is required, so that the reporter can manage cleaning up after the
@@ -50,65 +57,81 @@ module RSpec::Core
       end
     end
 
-    def start(expected_example_count)
-      @start = RSpec::Core::Time.now
-      notify :start, Notifications::CountNotification.new(expected_example_count)
+    # @private
+    def start(expected_example_count, time = RSpec::Core::Time.now)
+      @start = time
+      @load_time = (@start - @configuration.start_time).to_f
+      notify :start, Notifications::StartNotification.new(expected_example_count, @load_time)
     end
 
+    # @private
     def message(message)
       notify :message, Notifications::MessageNotification.new(message)
     end
 
+    # @private
     def example_group_started(group)
       notify :example_group_started, Notifications::GroupNotification.new(group) unless group.descendant_filtered_examples.empty?
     end
 
+    # @private
     def example_group_finished(group)
       notify :example_group_finished, Notifications::GroupNotification.new(group) unless group.descendant_filtered_examples.empty?
     end
 
+    # @private
     def example_started(example)
-      @example_count += 1
-      notify :example_started, Notifications::ExampleNotification.new(example)
+      @examples << example
+      notify :example_started, Notifications::ExampleNotification.for(example)
     end
 
+    # @private
     def example_passed(example)
-      notify :example_passed, Notifications::ExampleNotification.new(example)
+      notify :example_passed, Notifications::ExampleNotification.for(example)
     end
 
+    # @private
     def example_failed(example)
-      @failure_count += 1
-      notify :example_failed, Notifications::ExampleNotification.new(example)
+      @failed_examples << example
+      notify :example_failed, Notifications::ExampleNotification.for(example)
     end
 
+    # @private
     def example_pending(example)
-      @pending_count += 1
-      notify :example_pending, Notifications::ExampleNotification.new(example)
+      @pending_examples << example
+      notify :example_pending, Notifications::ExampleNotification.for(example)
     end
 
+    # @private
     def deprecation(hash)
       notify :deprecation, Notifications::DeprecationNotification.from_hash(hash)
     end
 
+    # @private
     def finish
       begin
         stop
         notify :start_dump,    Notifications::NullNotification
-        notify :dump_pending,  Notifications::NullNotification
-        notify :dump_failures, Notifications::NullNotification
-        notify :dump_summary, Notifications::SummaryNotification.new(@duration, @example_count, @failure_count, @pending_count)
+        notify :dump_pending,  Notifications::ExamplesNotification.new(self)
+        notify :dump_failures, Notifications::ExamplesNotification.new(self)
         notify :deprecation_summary, Notifications::NullNotification
+        notify :dump_summary, Notifications::SummaryNotification.new(@duration, @examples, @failed_examples, @pending_examples, @load_time)
+        unless mute_profile_output?
+          notify :dump_profile, Notifications::ProfileNotification.new(@duration, @examples, @configuration.profile_examples)
+        end
         notify :seed, Notifications::SeedNotification.new(@configuration.seed, seed_used?)
       ensure
         notify :close, Notifications::NullNotification
       end
     end
 
+    # @private
     def stop
       @duration = (RSpec::Core::Time.now - @start).to_f if @start
-      notify :stop, Notifications::NullNotification
+      notify :stop, Notifications::ExamplesNotification.new(self)
     end
 
+    # @private
     def notify(event, notification)
       registered_listeners(event).each do |formatter|
         formatter.__send__(event, notification)
@@ -117,6 +140,11 @@ module RSpec::Core
 
   private
 
+    def mute_profile_output?
+      # Don't print out profiled info if there are failures and `--fail-fast` is used, it just clutters the output
+      !@configuration.profile_examples? || (@configuration.fail_fast? && @failed_examples.size > 0)
+    end
+
     def seed_used?
       @configuration.seed && @configuration.seed_used?
     end