rspec-core 3.8.0 → 3.12.2

data/lib/rspec/core/hooks.rb

@@ -13,13 +13,14 @@ module RSpec
       # @overload before(scope, &block)
       #   @param scope [Symbol] `:example`, `:context`, or `:suite`
       #     (defaults to `:example`)
-      # @overload before(scope, conditions, &block)
+      # @overload before(scope, *conditions, &block)
       #   @param scope [Symbol] `:example`, `:context`, or `:suite`
       #     (defaults to `:example`)
-      #   @param conditions [Hash]
-      #     constrains this hook to examples matching these conditions e.g.
+      #   @param conditions [Array<Symbol>, Hash] constrains this hook to
+      #     examples matching these conditions e.g.
       #     `before(:example, :ui => true) { ... }` will only run with examples
-      #     or groups declared with `:ui => true`.
+      #     or groups declared with `:ui => true`. Symbols will be transformed
+      #     into hash entries with `true` values.
       # @overload before(conditions, &block)
       #   @param conditions [Hash]
       #     constrains this hook to examples matching these conditions e.g.
@@ -59,8 +60,10 @@ module RSpec
       #     before(:example)  # Declared in a parent group.
       #     before(:example)  # Declared in the current group.
       #
-      # If more than one `before` is declared within any one scope, they are run
-      # in the order in which they are declared.
+      # If more than one `before` is declared within any one example group, they
+      # are run in the order in which they are declared. Any `around` hooks will
+      # execute after `before` context hooks but before any `before` example
+      # hook regardless of where they are declared.
       #
       # ### Conditions
       #
@@ -74,11 +77,11 @@ module RSpec
       #       end
       #     end
       #
-      #     describe Something, :authorized => true do
+      #     RSpec.describe Something, :authorized => true do
       #       # The before hook will run in before each example in this group.
       #     end
       #
-      #     describe SomethingElse do
+      #     RSpec.describe SomethingElse do
       #       it "does something", :authorized => true do
       #         # The before hook will run before this example.
       #       end
@@ -159,7 +162,7 @@ module RSpec
       #
       # @example before(:example) declared in an {ExampleGroup}
       #
-      #     describe Thing do
+      #     RSpec.describe Thing do
       #       before(:example) do
       #         @thing = Thing.new
       #       end
@@ -171,7 +174,7 @@ module RSpec
       #
       # @example before(:context) declared in an {ExampleGroup}
       #
-      #     describe Parser do
+      #     RSpec.describe Parser do
       #       before(:context) do
       #         File.open(file_to_parse, 'w') do |f|
       #           f.write <<-CONTENT
@@ -213,13 +216,14 @@ module RSpec
       # @overload after(scope, &block)
       #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to
       #     `:example`)
-      # @overload after(scope, conditions, &block)
+      # @overload after(scope, *conditions, &block)
       #   @param scope [Symbol] `:example`, `:context`, or `:suite` (defaults to
       #     `:example`)
-      #   @param conditions [Hash]
-      #     constrains this hook to examples matching these conditions e.g.
+      #   @param conditions [Array<Symbol>, Hash] constrains this hook to
+      #     examples matching these conditions e.g.
       #     `after(:example, :ui => true) { ... }` will only run with examples
-      #     or groups declared with `:ui => true`.
+      #     or groups declared with `:ui => true`. Symbols will be transformed
+      #     into hash entries with `true` values.
       # @overload after(conditions, &block)
       #   @param conditions [Hash]
       #     constrains this hook to examples matching these conditions e.g.
@@ -260,8 +264,10 @@ module RSpec
       #     after(:suite)   # Declared in RSpec.configure.
       #
       # This is the reverse of the order in which `before` hooks are run.
-      # Similarly, if more than one `after` is declared within any one scope,
-      # they are run in reverse order of that in which they are declared.
+      # Similarly, if more than one `after` is declared within any example
+      # group, they are run in reverse order of that in which they are declared.
+      # Also `around` hooks will run after any `after` example hooks are
+      # invoked but before any `after` context hooks.
       #
       # @note The `:example` and `:context` scopes are also available as
       #       `:each` and `:all`, respectively. Use whichever you prefer.
@@ -288,13 +294,15 @@ module RSpec
       #   @param scope [Symbol] `:example` (defaults to `:example`)
       #     present for syntax parity with `before` and `after`, but
       #     `:example`/`:each` is the only supported value.
-      # @overload around(scope, conditions, &block)
+      # @overload around(scope, *conditions, &block)
       #   @param scope [Symbol] `:example` (defaults to `:example`)
       #     present for syntax parity with `before` and `after`, but
       #     `:example`/`:each` is the only supported value.
-      #   @param conditions [Hash] constrains this hook to examples matching
-      #     these conditions e.g. `around(:example, :ui => true) { ... }` will
-      #     only run with examples or groups declared with `:ui => true`.
+      #   @param conditions [Array<Symbol>, Hash] constrains this hook to
+      #     examples matching these conditions e.g.
+      #     `around(:example, :ui => true) { ... }` will only run with examples
+      #     or groups declared with `:ui => true`. Symbols will be transformed
+      #     into hash entries with `true` values.
       # @overload around(conditions, &block)
       #   @param conditions [Hash] constrains this hook to examples matching
       #     these conditions e.g. `around(:example, :ui => true) { ... }` will
@@ -304,7 +312,7 @@ module RSpec
       #
       # @note the syntax of `around` is similar to that of `before` and `after`
       #   but the semantics are quite different. `before` and `after` hooks are
-      #   run in the context of of the examples with which they are associated,
+      #   run in the context of the examples with which they are associated,
       #   whereas `around` hooks are actually responsible for running the
       #   examples. Consequently, `around` hooks do not have direct access to
       #   resources that are made available within the examples and their
@@ -329,6 +337,15 @@ module RSpec
       #     around(:example) {|ex| Database.transaction(&ex)}
       #     around(:example) {|ex| FakeFS(&ex)}
       #
+      # ### Order
+      #
+      # The `around` hooks execute surrounding an example and its hooks.
+      #
+      # This means after any `before` context hooks, but before any `before`
+      # example hooks, and similarly after any `after` example hooks but before
+      # any `after` context hooks.
+      #
+      # They are not a synonym for `before`/`after`.
       def around(*args, &block)
         hooks.register :prepend, :around, *args, &block
       end
@@ -440,6 +457,11 @@ module RSpec
                             "`#{position}(:suite)` hook, registered on an example " \
                             "group, will be ignored."
             return
+          elsif scope == :context && position == :around
+            # TODO: consider making this an error in RSpec 4. For SemVer reasons,
+            # we are only warning in RSpec 3.
+            RSpec.warn_with "WARNING: `around(:context)` hooks are not supported and " \
+                            "behave like `around(:example)."
           end
 
           hook = HOOK_TYPES[position][scope].new(block, options)

data/lib/rspec/core/invocations.rb

@@ -37,7 +37,7 @@ module RSpec
             runner, options.args, formatter
           )
 
-          success ? 0 : 1
+          runner.exit_code(success)
         end
 
       private

data/lib/rspec/core/memoized_helpers.rb

@@ -10,7 +10,7 @@ module RSpec
       # @note `subject` was contributed by Joe Ferris to support the one-liner
       #   syntax embraced by shoulda matchers:
       #
-      #       describe Widget do
+      #       RSpec.describe Widget do
       #         it { is_expected.to validate_presence_of(:name) }
       #         # or
       #         it { should validate_presence_of(:name) }
@@ -23,7 +23,7 @@ module RSpec
       # @example
       #
       #   # Explicit declaration of subject.
-      #   describe Person do
+      #   RSpec.describe Person do
       #     subject { Person.new(:birthdate => 19.years.ago) }
       #     it "should be eligible to vote" do
       #       subject.should be_eligible_to_vote
@@ -32,7 +32,7 @@ module RSpec
       #   end
       #
       #   # Implicit subject => { Person.new }.
-      #   describe Person do
+      #   RSpec.describe Person do
       #     it "should be eligible to vote" do
       #       subject.should be_eligible_to_vote
       #       # ^ ^ explicit reference to subject not recommended
@@ -40,7 +40,7 @@ module RSpec
       #   end
       #
       #   # One-liner syntax - expectation is set on the subject.
-      #   describe Person do
+      #   RSpec.describe Person do
       #     it { is_expected.to be_eligible_to_vote }
       #     # or
       #     it { should be_eligible_to_vote }
@@ -67,7 +67,7 @@ module RSpec
       #
       # @example
       #
-      #   describe Person do
+      #   RSpec.describe Person do
       #     it { should be_eligible_to_vote }
       #   end
       #
@@ -78,6 +78,7 @@ module RSpec
       # @note If you are using RSpec's newer expect-based syntax you may
       #       want to use `is_expected.to` instead of `should`.
       def should(matcher=nil, message=nil)
+        enforce_value_expectation(matcher, 'should')
         RSpec::Expectations::PositiveExpectationHandler.handle_matcher(subject, matcher, message)
       end
 
@@ -86,7 +87,7 @@ module RSpec
       #
       # @example
       #
-      #   describe Person do
+      #   RSpec.describe Person do
       #     it { should_not be_eligible_to_vote }
       #   end
       #
@@ -97,6 +98,7 @@ module RSpec
       # @note If you are using RSpec's newer expect-based syntax you may
       #       want to use `is_expected.to_not` instead of `should_not`.
       def should_not(matcher=nil, message=nil)
+        enforce_value_expectation(matcher, 'should_not')
         RSpec::Expectations::NegativeExpectationHandler.handle_matcher(subject, matcher, message)
       end
 
@@ -144,6 +146,26 @@ module RSpec
                       end
       end
 
+      # @private
+      def enforce_value_expectation(matcher, method_name)
+        return if matcher_supports_value_expectations?(matcher)
+
+        RSpec.deprecate(
+          "#{method_name} #{RSpec::Support::ObjectFormatter.format(matcher)}",
+          :message =>
+            "The implicit block expectation syntax is deprecated, you should pass " \
+            "a block to `expect` to use the provided block expectation matcher " \
+            "(#{RSpec::Support::ObjectFormatter.format(matcher)}), " \
+            "or the matcher must implement `supports_value_expectations?`."
+        )
+      end
+
+      def matcher_supports_value_expectations?(matcher)
+        matcher.supports_value_expectations?
+      rescue
+        true
+      end
+
       # @private
       class ThreadsafeMemoized
         def initialize
@@ -270,7 +292,7 @@ EOS
         #
         # @example
         #
-        #   describe Thing do
+        #   RSpec.describe Thing do
         #     let(:thing) { Thing.new }
         #
         #     it "does something" do
@@ -285,10 +307,33 @@ EOS
           # We have to pass the block directly to `define_method` to
           # allow it to use method constructs like `super` and `return`.
           raise "#let or #subject called without a block" if block.nil?
-          raise(
-            "#let or #subject called with a reserved name #initialize"
-          ) if :initialize == name
-          MemoizedHelpers.module_for(self).__send__(:define_method, name, &block)
+
+          # A list of reserved words that can't be used as a name for a memoized helper
+          # Matches for both symbols and passed strings
+          if [:initialize, :to_s].include?(name.to_sym)
+            raise ArgumentError, "#let or #subject called with reserved name `#{name}`"
+          end
+
+          our_module = MemoizedHelpers.module_for(self)
+
+          # If we have a module clash in our helper module
+          # then we need to remove it to prevent a warning.
+          #
+          # Note we do not check ancestor modules (see: `instance_methods(false)`)
+          # as we can override them.
+          if our_module.instance_methods(false).include?(name)
+            our_module.__send__(:remove_method, name)
+          end
+          our_module.__send__(:define_method, name, &block)
+
+          # If we have a module clash in the example module
+          # then we need to remove it to prevent a warning.
+          #
+          # Note we do not check ancestor modules (see: `instance_methods(false)`)
+          # as we can override them.
+          if instance_methods(false).include?(name)
+            remove_method(name)
+          end
 
           # Apply the memoization. The method has been defined in an ancestor
           # module so we can use `super` here to get the value.
@@ -323,7 +368,7 @@ EOS
         #     end
         #   end
         #
-        #   describe Thing do
+        #   RSpec.describe Thing do
         #     after(:example) { Thing.reset_count }
         #
         #     context "using let" do
@@ -379,13 +424,13 @@ EOS
         #
         # @example
         #
-        #   describe CheckingAccount, "with $50" do
+        #   RSpec.describe CheckingAccount, "with $50" do
         #     subject { CheckingAccount.new(Money.new(50, :USD)) }
         #     it { is_expected.to have_a_balance_of(Money.new(50, :USD)) }
         #     it { is_expected.not_to be_overdrawn }
         #   end
         #
-        #   describe CheckingAccount, "with a non-zero starting balance" do
+        #   RSpec.describe CheckingAccount, "with a non-zero starting balance" do
         #     subject(:account) { CheckingAccount.new(Money.new(50, :USD)) }
         #     it { is_expected.not_to be_overdrawn }
         #     it "has a balance equal to the starting balance" do
@@ -433,7 +478,7 @@ EOS
         #     end
         #   end
         #
-        #   describe Thing do
+        #   RSpec.describe Thing do
         #     after(:example) { Thing.reset_count }
         #
         #     context "using subject" do

data/lib/rspec/core/metadata.rb

@@ -7,7 +7,7 @@ module RSpec
     # In addition to metadata that is used internally, this also stores
     # user-supplied metadata, e.g.
     #
-    #     describe Something, :type => :ui do
+    #     RSpec.describe Something, :type => :ui do
     #       it "does something", :slow => true do
     #         # ...
     #       end
@@ -136,7 +136,6 @@ module RSpec
 
           populate_location_attributes
           metadata.update(user_metadata)
-          RSpec.configuration.apply_derived_metadata_to(metadata)
         end
 
       private
@@ -169,7 +168,7 @@ module RSpec
         end
 
         def description_separator(parent_part, child_part)
-          if parent_part.is_a?(Module) && child_part =~ /^(#|::|\.)/
+          if parent_part.is_a?(Module) && /^(?:#|::|\.)/.match(child_part.to_s)
             ''.freeze
           else
             ' '.freeze

data/lib/rspec/core/metadata_filter.rb

@@ -92,7 +92,7 @@ module RSpec
       #
       # This is ideal for use by a example or example group, which may
       # be updated multiple times with globally configured hooks, etc,
-      # but will not be queried frequently by other examples or examle
+      # but will not be queried frequently by other examples or example
       # groups.
       # @private
       class UpdateOptimized

data/lib/rspec/core/option_parser.rb

@@ -22,9 +22,8 @@ module RSpec::Core
       begin
         parser(options).parse!(args)
       rescue OptionParser::InvalidOption => e
-        failure = e.message
-        failure << " (defined in #{source})" if source
-        abort "#{failure}\n\nPlease use --help for a listing of valid options"
+        abort "#{e.message}#{" (defined in #{source})" if source}\n\n" \
+              "Please use --help for a listing of valid options"
       end
 
       options[:files_or_directories_to_run] = args
@@ -33,10 +32,10 @@ module RSpec::Core
 
   private
 
-    # rubocop:disable MethodLength
     # rubocop:disable Metrics/AbcSize
-    # rubocop:disable CyclomaticComplexity
-    # rubocop:disable PerceivedComplexity
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
     def parser(options)
       OptionParser.new do |parser|
         parser.summary_width = 34
@@ -58,10 +57,11 @@ module RSpec::Core
         end
 
         parser.on('--order TYPE[:SEED]', 'Run examples by the specified order type.',
-                  '  [defined] examples and groups are run in the order they are defined',
-                  '  [rand]    randomize the order of groups and examples',
-                  '  [random]  alias for rand',
-                  '  [random:SEED] e.g. --order random:123') do |o|
+                  '  [defined]           examples and groups are run in the order they are defined',
+                  '  [rand]              randomize the order of groups and examples',
+                  '  [random]            alias for rand',
+                  '  [random:SEED]       e.g. --order random:123',
+                  '  [recently-modified] run the most recently modified files first') do |o|
           options[:order] = o
         end
 
@@ -95,6 +95,11 @@ module RSpec::Core
           options[:failure_exit_code] = code
         end
 
+        parser.on('--error-exit-code CODE', Integer,
+                  'Override the exit code used when there are errors loading or running specs outside of examples.') do |code|
+          options[:error_exit_code] = code
+        end
+
         parser.on('-X', '--[no-]drb', 'Run examples via DRb.') do |use_drb|
           options[:drb] = use_drb
           options[:runner] = RSpec::Core::Invocations::DRbWithFallback.new if use_drb
@@ -111,6 +116,7 @@ module RSpec::Core
                   '  [d]ocumentation (group and example names)',
                   '  [h]tml',
                   '  [j]son',
+                  '  [f]ailures ("file:line:reason", suitable for editors integration)',
                   '  custom formatter class name') do |o|
           options[:formatters] ||= []
           options[:formatters] << [o]
@@ -178,6 +184,9 @@ module RSpec::Core
         end
 
         parser.on('-w', '--warnings', 'Enable ruby warnings') do
+          if Object.const_defined?(:Warning) && Warning.respond_to?(:[]=)
+            Warning[:deprecated] = true
+          end
           $VERBOSE = true
         end
 
@@ -226,6 +235,11 @@ FILTERING
           (options[:full_description] ||= []) << Regexp.compile(Regexp.escape(o))
         end
 
+        parser.on('-E', '--example-matches REGEX', "Run examples whose full nested names match REGEX (may be",
+                  "  used more than once)") do |o|
+          (options[:full_description] ||= []) << Regexp.compile(o)
+        end
+
         parser.on('-t', '--tag TAG[:VALUE]',
                   'Run examples with the specified tag, or exclude examples',
                   'by adding ~ before the tag.',
@@ -289,9 +303,9 @@ FILTERING
       end
     end
     # rubocop:enable Metrics/AbcSize
-    # rubocop:enable MethodLength
-    # rubocop:enable CyclomaticComplexity
-    # rubocop:enable PerceivedComplexity
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity
 
     def add_tag_filter(options, filter_type, tag_name, value=true)
       (options[filter_type] ||= {})[tag_name] = value

data/lib/rspec/core/ordering.rb

@@ -58,6 +58,14 @@ module RSpec
         MAX_32_BIT = 4_294_967_295
       end
 
+      # @private
+      # Orders items by modification time (most recent modified first).
+      class RecentlyModified
+        def order(list)
+          list.sort_by { |item| -File.mtime(item.metadata[:absolute_file_path]).to_i }
+        end
+      end
+
       # @private
       # Orders items based on a custom block.
       class Custom
@@ -77,7 +85,8 @@ module RSpec
           @configuration = configuration
           @strategies    = {}
 
-          register(:random,  Random.new(configuration))
+          register(:random, Random.new(configuration))
+          register(:recently_modified, RecentlyModified.new)
 
           identity = Identity.new
           register(:defined, identity)
@@ -132,6 +141,8 @@ module RSpec
                             :random
                           elsif order == 'defined'
                             :defined
+                          elsif order == 'recently-modified'
+                            :recently_modified
                           end
 
           register_ordering(:global, ordering_registry.fetch(ordering_name)) if ordering_name

data/lib/rspec/core/pending.rb

@@ -38,7 +38,7 @@ module RSpec
       # @param message [String] optional message to add to the summary report.
       #
       # @example
-      #     describe "an example" do
+      #     describe "some behaviour" do
       #       # reported as "Pending: no reason given"
       #       it "is pending with no message" do
       #         pending
@@ -52,21 +52,13 @@ module RSpec
       #       end
       #     end
       #
-      # @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:
-      #
-      #       it "does something", :pending => true do
-      #         # ...
-      #       end
-      #
-      #   or pass `:pending => "something else getting finished"` to add a
-      #   message to the summary report:
-      #
-      #       it "does something", :pending => "something else getting finished" do
-      #         # ...
-      #       end
+      # @note When using `pending` inside an example body using this method
+      #   hooks, such as `before(:example)`, have already be run. This means that
+      #   a failure from the code in the `before` hook will prevent the example
+      #   from being considered pending, as the example body would not be
+      #   executed. If you need to consider hooks as pending as well you can use
+      #   the pending metadata as an alternative, e.g.
+      #   `it "does something", pending: "message"`.
       def pending(message=nil)
         current_example = RSpec.current_example
 

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

@@ -12,7 +12,7 @@
 # the additional setup, and require it from the spec files that actually need
 # it.
 #
-# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+# See https://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 RSpec.configure do |config|
   # rspec-expectations config goes here. You can use an alternate
   # assertion/expectation library such as wrong or the stdlib/minitest
@@ -61,9 +61,7 @@ RSpec.configure do |config|
 
   # Limits the available syntax to the non-monkey patched syntax that is
   # recommended. For more details, see:
-  #   - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
-  #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
-  #   - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
+  # https://rspec.info/features/3-12/rspec-core/configuration/zero-monkey-patching-mode/
   config.disable_monkey_patching!
 
   # This setting enables warnings. It's recommended, but in some cases may

data/lib/rspec/core/rake_task.rb

@@ -45,6 +45,21 @@ module RSpec
       # A message to print to stderr when there are failures.
       attr_accessor :failure_message
 
+      if RUBY_VERSION < "1.9.0" || Support::Ruby.jruby?
+        # Run RSpec with a clean (empty) environment is not supported
+        def with_clean_environment=(_value)
+          raise ArgumentError, "Running in a clean environment is not supported on Ruby versions before 1.9.0"
+        end
+
+        # Run RSpec with a clean (empty) environment is not supported
+        def with_clean_environment
+          false
+        end
+      else
+        # Run RSpec with a clean (empty) environment.
+        attr_accessor :with_clean_environment
+      end
+
       # Use verbose output. If this is set to true, the task will print the
       # executed spec command to stdout. Defaults to `true`.
       attr_accessor :verbose
@@ -76,7 +91,12 @@ module RSpec
         command = spec_command
         puts command if verbose
 
-        return if system(command)
+        if with_clean_environment
+          return if system({}, command, :unsetenv_others => true)
+        else
+          return if system(command)
+        end
+
         puts failure_message if failure_message
 
         return unless fail_on_error
@@ -102,7 +122,7 @@ module RSpec
         if ENV['SPEC']
           FileList[ENV['SPEC']].sort
         elsif String === pattern && !File.exist?(pattern)
-          return if rspec_opts =~ /--pattern/
+          return if [*rspec_opts].any? { |opt| opt =~ /--pattern/ }
           "--pattern #{escape pattern}"
         else
           # Before RSpec 3.1, we used `FileList` to get the list of matched

data/lib/rspec/core/reporter.rb

@@ -30,7 +30,7 @@ module RSpec::Core
     # 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
+    # @param listener [Object] An object that wishes to be notified of reporter
     #   events
     # @param notifications [Array] Array of symbols represents the events a
     #   listener wishes to subscribe too
@@ -77,6 +77,14 @@ module RSpec::Core
       end
     end
 
+    # @param exit_code [Integer] the exit_code to be return by the reporter
+    #
+    # Reports a run that exited early without having run any examples.
+    #
+    def exit_early(exit_code)
+      report(0) { exit_code }
+    end
+
     # @private
     def start(expected_example_count, time=RSpec::Core::Time.now)
       @start = time