rspec-core 2.7.1 → 2.8.0.rc1

data/lib/rspec/core/pending.rb

@@ -5,6 +5,47 @@ module RSpec
 
       DEFAULT_MESSAGE = 'No reason given'
 
+      # @overload pending()
+      # @overload pending(message)
+      # @overload pending(message, &block)
+      #
+      # Stops execution of an example, and reports it as pending. Takes an
+      # optional message and block.
+      #
+      # @param [String] message optional message to add to the summary report.
+      # @param [Block] block optional block. If it fails, the example is
+      #   reported as pending. If it executes cleanly the example fails.
+      #
+      # @example
+      #
+      #     describe "an example" do
+      #       # reported as "Pending: no reason given"
+      #       it "is pending with no message" do
+      #         pending
+      #         this_does_not_get_executed
+      #       end
+      #
+      #       # reported as "Pending: something else getting finished"
+      #       it "is pending with a custom message" do
+      #         pending("something else getting finished")
+      #         this_does_not_get_executed
+      #       end
+      #
+      #       # reported as "Pending: something else getting finished"
+      #       it "is pending with a failing block" do
+      #         pending("something else getting finished") do
+      #           raise "this is the failure"
+      #         end
+      #       end
+      #
+      #       # reported as failure, saying we expected the block to fail but
+      #       # it passed.
+      #       it "is pending with a passing block" do
+      #         pending("something else getting finished") do
+      #           true.should be(true)
+      #         end
+      #       end
+      #     end
       def pending(*args)
         return self.class.before(:each) { pending(*args) } unless example
 

data/lib/rspec/core/rake_task.rb

@@ -20,39 +20,26 @@ module RSpec
       #   'spec/**/*_spec.rb'
       attr_accessor :pattern
 
-      # Deprecated and has no effect. The rake task now checks
-      # ENV['BUNDLE_GEMFILE'] instead.
-      #
-      # By default, if there is a Gemfile, the generated command will include
-      # 'bundle exec'. Set this to true to ignore the presence of a Gemfile, and
-      # not add 'bundle exec' to the command.
-      #
-      # default:
-      #   false
+      # @deprecated
+      # Has no effect. The rake task now checks ENV['BUNDLE_GEMFILE'] instead.
       def skip_bundler=(*)
         RSpec.deprecate("RSpec::Core::RakeTask#skip_bundler=")
       end
 
-      # Deprecated and has no effect. The rake task now checks
-      # ENV['BUNDLE_GEMFILE'] instead.
-      #
-      # Name of Gemfile to use.
-      #
-      # default:
-      #   Gemfile
+      # @deprecated
+      # Has no effect. The rake task now checks ENV['BUNDLE_GEMFILE'] instead.
       def gemfile=(*)
         RSpec.deprecate("RSpec::Core::RakeTask#gemfile=", 'ENV["BUNDLE_GEMFILE"]')
       end
 
-      # Deprecated. Use ruby_opts="-w" instead.
+      # @deprecated
+      # Use ruby_opts="-w" instead.
       #
       # When true, requests that the specs be run with the warning flag set.
       # e.g. "ruby -w"
       #
       # default:
       #   false
-      attr_reader :warning
-
       def warning=(true_or_false)
         RSpec.deprecate("RSpec::Core::RakeTask#warning=", 'ruby_opts="-w"')
         @warning = true_or_false
@@ -110,7 +97,8 @@ module RSpec
       #   nil
       attr_accessor :rspec_opts
 
-      # Deprecated. Use rspec_opts instead.
+      # @deprecated
+      # Use rspec_opts instead.
       #
       # Command line options to pass to rspec.
       #
@@ -167,7 +155,7 @@ module RSpec
                             cmd_parts = []
                             cmd_parts << RUBY
                             cmd_parts << ruby_opts
-                            cmd_parts << "-w" if warning?
+                            cmd_parts << "-w" if @warning
                             cmd_parts << "-S"
                             cmd_parts << runner
                             if rcov
@@ -189,10 +177,6 @@ module RSpec
         rcov ? rcov_path : rspec_path
       end
 
-      def warning?
-        warning
-      end
-
       def blank
         lambda {|s| s == ""}
       end

data/lib/rspec/core/reporter.rb

@@ -3,33 +3,42 @@ module RSpec::Core
     def initialize(*formatters)
       @formatters = formatters
       @example_count = @failure_count = @pending_count = 0
-      @duration = nil
+      @duration = @start = nil
     end
 
-    def report(count)
-      start(count)
+    # @api
+    # @overload report(count, &block)
+    # @overload report(count, seed, &block)
+    # @param [Integer] count the number of examples being run
+    # @param [Integer] seed the seed used to randomize the spec run
+    # @param [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
+    # run.
+    #
+    # ### Warning:
+    #
+    # The `seed` argument is an internal API and is not guaranteed to be
+    # supported in the future.
+    #
+    # @example
+    #
+    #     reporter.report(group.examples.size) do |r|
+    #       example_groups.map {|g| g.run(r) }
+    #     end
+    #
+    def report(expected_example_count, seed=nil)
+      start(expected_example_count)
       begin
         yield self
       ensure
-        finish
+        finish(seed)
       end
     end
 
-    def finish
-      begin
-        stop
-        notify :start_dump
-        notify :dump_pending
-        notify :dump_failures
-        notify :dump_summary, @duration, @example_count, @failure_count, @pending_count
-      ensure
-        notify :close
-      end
-    end
-
-    alias_method :abort, :finish
-
     def start(expected_example_count)
+      @start = Time.now
       notify :start, expected_example_count
     end
 
@@ -64,8 +73,23 @@ module RSpec::Core
       notify :example_pending, example
     end
 
+    def finish(seed)
+      begin
+        stop
+        notify :start_dump
+        notify :dump_pending
+        notify :dump_failures
+        notify :dump_summary, @duration, @example_count, @failure_count, @pending_count
+        notify :seed, seed if seed
+      ensure
+        notify :close
+      end
+    end
+
+    alias_method :abort, :finish
+
     def stop
-      @duration = Time.now - $rspec_start_time
+      @duration = Time.now - @start if @start
       notify :stop
     end
 

data/lib/rspec/core/shared_context.rb

@@ -1,7 +1,26 @@
 module RSpec
   module Core
+    # Exposes [ExampleGroup](ExampleGroup)-level methods to a module, so you
+    # can include that module in an [ExampleGroup](ExampleGroup).
+    #
+    # @note exposed as `RSpec::SharedContext`
+    #
+    # @example
+    #
+    #     module LoggedInAsAdmin
+    #       extend RSpec::SharedContext
+    #       before(:each) do
+    #         log_in_as :admin
+    #       end
+    #     end
+    #
+    #     describe "admin section" do
+    #       include LoggedInAsAdmin
+    #       # ...
+    #     end
     module SharedContext
       include Hooks
+      include Let::ClassMethods
 
       def included(group)
         [:before, :after].each do |type|
@@ -9,8 +28,24 @@ module RSpec
             group.hooks[type][scope].concat hooks[type][scope]
           end
         end
+        _nested_group_declarations.each do |name, block, *args|
+          group.describe name, *args, &block
+        end
+      end
+
+      def describe(name, *args, &block)
+        _nested_group_declarations << [name, block, *args]
       end
 
+      alias_method :context, :describe
+
+      private
+
+      def _nested_group_declarations
+        @_nested_group_declarations ||= []
+      end
     end
   end
+
+  SharedContext = Core::SharedContext
 end

data/lib/rspec/core/shared_example_group.rb

@@ -15,7 +15,6 @@ module RSpec
             host.class_eval(&block)
           end
           RSpec.configuration.extend(mod, *args)
-        else
         end
       end
 

data/lib/rspec/core/subject.rb

@@ -11,7 +11,7 @@ module RSpec
         # declared in the example group, then +subject+ will return a new
         # instance of that class.
         #
-        # == Examples
+        # @example
         #
         #   # explicit subject defined by the subject method
         #   describe Person do
@@ -45,7 +45,7 @@ module RSpec
           # an implicit subject (see +subject+), this supports very concise
           # expressions.
           #
-          # == Examples
+          # @example
           #
           #   describe Person do
           #     it { should be_eligible_to_vote }
@@ -57,7 +57,7 @@ module RSpec
           # Just like +should+, +should_not+ delegates to the subject (implicit or
           # explicit) of the example group.
           #
-          # == Examples
+          # @example
           #
           #   describe Person do
           #     it { should_not be_eligible_to_vote }
@@ -139,7 +139,7 @@ module RSpec
         # Defines an explicit subject for an example group which can then be the
         # implicit receiver (through delegation) of calls to +should+.
         #
-        # == Examples
+        # @example
         #
         #   describe CheckingAccount, "with $50" do
         #     subject { CheckingAccount.new(:amount => 50, :currency => :USD) }

data/lib/rspec/core/version.rb

@@ -1,7 +1,7 @@
 module RSpec
   module Core
     module Version
-      STRING = '2.7.1'
+      STRING = '2.8.0.rc1'
     end
   end
 end

data/lib/rspec/core/world.rb

@@ -2,27 +2,6 @@ module RSpec
   module Core
     class World
 
-      module Describable
-        PROC_HEX_NUMBER = /0x[0-9a-f]+@/
-        PROJECT_DIR = File.expand_path('.')
-
-        def description
-          reject { |k, v| RSpec::Core::Configuration::CONDITIONAL_FILTERS[k] == v }.inspect.gsub(PROC_HEX_NUMBER, '').gsub(PROJECT_DIR, '.').gsub(' (lambda)','')
-        end
-
-        def empty_without_conditional_filters?
-          reject { |k, v| RSpec::Core::Configuration::CONDITIONAL_FILTERS[k] == v }.empty?
-        end
-
-        def reject
-          super rescue {}
-        end
-
-        def empty?
-          super rescue false
-        end
-      end
-
       include RSpec::Core::Hooks
 
       attr_reader :example_groups, :filtered_examples, :wants_to_quit
@@ -30,13 +9,13 @@ module RSpec
 
       def initialize(configuration=RSpec.configuration)
         @configuration = configuration
-        @example_groups = []
+        @example_groups = [].extend(Extensions::Ordered)
         @filtered_examples = Hash.new { |hash,group|
           hash[group] = begin
             examples = group.examples.dup
-            examples = apply_exclusion_filters(examples, exclusion_filter)
-            examples = apply_inclusion_filters(examples, inclusion_filter)
+            examples = filter_manager.prune(examples)
             examples.uniq
+            examples.extend(Extensions::Ordered)
           end
         }
       end
@@ -45,17 +24,21 @@ module RSpec
         example_groups.clear
       end
 
+      def filter_manager
+        @configuration.filter_manager
+      end
+
       def register(example_group)
         example_groups << example_group
         example_group
       end
 
       def inclusion_filter
-        @configuration.inclusion_filter.extend(Describable)
+        @configuration.inclusion_filter
       end
 
       def exclusion_filter
-        @configuration.exclusion_filter.extend(Describable)
+        @configuration.exclusion_filter
       end
 
       def configure_group(group)
@@ -70,16 +53,6 @@ module RSpec
         example_groups.collect {|g| g.descendants}.flatten.inject(0) { |sum, g| sum += g.filtered_examples.size }
       end
 
-      def apply_inclusion_filters(examples, filters)
-        filters.empty? ? examples : examples.select {|e| e.metadata.any_apply?(filters)}
-      end
-
-      alias_method :find, :apply_inclusion_filters
-
-      def apply_exclusion_filters(examples, filters)
-        filters.empty? ? examples : examples.reject {|e| e.metadata.any_apply?(filters)}
-      end
-
       def preceding_declaration_line(filter_line)
         declaration_line_numbers.sort.inject(nil) do |highest_prior_declaration_line, line|
           line <= filter_line ? line : highest_prior_declaration_line
@@ -93,43 +66,52 @@ module RSpec
       def announce_filters
         filter_announcements = []
 
+        announce_inclusion_filter filter_announcements
+        announce_exclusion_filter filter_announcements
+
+        unless filter_manager.empty?
+          if filter_announcements.length == 1
+            reporter.message("Run options: #{filter_announcements[0]}")
+          else
+            reporter.message("Run options:\n  #{filter_announcements.join("\n  ")}")
+          end
+        end
+
         if @configuration.run_all_when_everything_filtered? && example_count.zero?
-          reporter.message( "No examples matched #{inclusion_filter.description}. Running all.")
+          reporter.message("#{everything_filtered_message}; ignoring #{inclusion_filter.description}")
           filtered_examples.clear
-          @configuration.clear_inclusion_filter
+          inclusion_filter.clear
         end
 
-        announce_inclusion_filter filter_announcements
-        announce_exclusion_filter filter_announcements
-
         if example_count.zero?
           example_groups.clear
-          if filter_announcements.empty?
+          if filter_manager.empty?
             reporter.message("No examples found.")
-          elsif !inclusion_filter.empty?
-            message = "No examples matched #{inclusion_filter.description}."
+          elsif exclusion_filter.empty_without_conditional_filters?
+            message = everything_filtered_message
             if @configuration.run_all_when_everything_filtered?
-              message << " Running all."
+              message << "; ignoring #{inclusion_filter.description}"
             end
             reporter.message(message)
-          elsif !exclusion_filter.empty?
-            reporter.message(
-              "No examples were matched. Perhaps #{exclusion_filter.description} is excluding everything?")
+          elsif inclusion_filter.empty?
+            reporter.message(everything_filtered_message)
           end
-        elsif !filter_announcements.empty?
-          reporter.message("Run filtered #{filter_announcements.join(', ')}")
         end
       end
 
+      def everything_filtered_message
+        "\nAll examples were filtered out"
+      end
+
       def announce_inclusion_filter(announcements)
         unless inclusion_filter.empty?
-          announcements << "including #{inclusion_filter.description}"
+          announcements << "include #{inclusion_filter.description}"
         end
       end
 
       def announce_exclusion_filter(announcements)
         unless exclusion_filter.empty_without_conditional_filters?
-          announcements << "excluding #{exclusion_filter.description}"
+          announcements << "exclude #{exclusion_filter.description}"
         end
       end