rspec-core 2.10.1 → 2.11.0

data/Changelog.md

@@ -1,3 +1,36 @@
+### 2.11.0 / 2012-07-07
+[full changelog](http://github.com/rspec/rspec-core/compare/v2.10.1...v2.11.0)
+
+Enhancements
+
+* Support multiple `--example` options. (Daniel Doubrovkine @dblock)
+* Named subject e.g. `subject(:article) { Article.new }`
+    * see [http://blog.davidchelimsky.net/2012/05/13/spec-smell-explicit-use-of-subject/](http://blog.davidchelimsky.net/2012/05/13/spec-smell-explicit-use-of-subject/)
+      for background.
+    * thanks to Bradley Schaefer for suggesting it and Avdi Grimm for almost
+      suggesting it.
+* `config.mock_with` and `config.expect_with` yield custom config object to a
+  block if given
+    * aids decoupling from rspec-core's configuation
+* `include_context` and `include_examples` support a block, which gets eval'd
+  in the current context (vs the nested context generated by `it_behaves_like`).
+* Add `config.order = 'random'` to the `spec_helper.rb` generated by `rspec
+  --init`.
+* Delay the loading of DRb (Myron Marston).
+* Limit monkey patching of `describe` onto just the objects that need it rather
+  than every object in the system (Myron Marston).
+
+Bug fixes
+
+* Support alternative path separators. For example, on Windows, you can now do
+  this: `rspec spec\subdir`. (Jarmo Pertman @jarmo)
+* When an example raises an error and an after or around hook does as
+  well, print out the hook error. Previously, the error was silenced and
+  the user got no feedback about what happened. (Myron Marston)
+* `--require` and `-I` are merged among different configuration sources (Andy
+  Lindeman)
+* Delegate to mocha methods instead of aliasing them in mocha adapter.
+
 ### 2.10.1 / 2012-05-19
 [full changelog](http://github.com/rspec/rspec-core/compare/v2.10.0...v2.10.1)
 
@@ -44,8 +77,8 @@ Bug fixes
   over DRb (using spork).
 * Ensure shared example groups are reset after a run (as example groups are).
 * Remove `rescue false` from calls to filters represented as Procs
-* Ensure described_class gets the closest constant (pyromaniac)
-* In "autorun", don't run the specs in the at_exit hook if there was an
+* Ensure `described_class` gets the closest constant (pyromaniac)
+* In "autorun", don't run the specs in the `at_exit` hook if there was an
   exception (most likely due to a SyntaxError). (sunaku)
 * Don't extend groups with modules already used to extend ancestor groups.
 * `its` correctly memoizes nil or false values (Yamada Masaki)

data/README.md

@@ -1,21 +1,22 @@
-# rspec-core
+# rspec-core [![Build Status](https://secure.travis-ci.org/rspec/rspec-core.png?branch=master)](http://travis-ci.org/rspec/rspec-core) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/rspec/rspec-core)
 
-```
-gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
-gem install rspec-core # for rspec-core only
-```
+rspec-core provides the structure for writing executable examples of how your
+code should behave, and an `rspec` command with tools to constrain which
+examples get run and taylor the output.
 
-# overview
+## install
 
-rspec-core provides the structure for writing executable examples of how
-your code should behave.  It uses the words "describe" and "it" so we can
-express concepts like a conversation:
+    gem install rspec      # for rspec-core, rspec-expectations, rspec-mocks
+    gem install rspec-core # for rspec-core only
+    rspec --help
+
+## basic structure
+
+RSpec uses the words "describe" and "it" so we can express concepts like a conversation:
 
     "Describe an order."
     "It sums the prices of its line items."
 
-## basic structure
-
 ```ruby
 describe Order do
   it "sums the prices of its line items" do
@@ -95,8 +96,8 @@ hooks, `let` declarations, and nested groups/contexts.
 
 You can also use the names `shared_context` and `include_context`. These are
 pretty much the same as `shared_examples` and `include_examples`, providing
-more accurate naming for in which you share hooks, `let` declarations, helper
-methods, etc, but no examples.
+more accurate naming when you share hooks, `let` declarations, helper methods,
+etc, but no examples.
 
 ## metadata
 

data/features/command_line/example_name_option.feature

@@ -8,6 +8,8 @@ Feature: --example option
 
   This allows you to run a single uniquely named example, all examples with
   similar names, all the examples in a uniquely named group, etc, etc.
+  
+  You can also use the option more than once to specify multiple example matches.
 
   Background:
     Given a file named "first_spec.rb" with:
@@ -84,3 +86,16 @@ Feature: --example option
   Scenario: Object#method
     When I run `rspec . --example 'Array#length'`
     Then the examples should all pass
+    
+  Scenario: Multiple applications of example name option
+    When I run `rspec . --example 'first group' --example 'second group' --format d`
+    Then the examples should all pass
+    And the output should contain all of these:
+      |first example in first group|
+      |second example in first group|
+      |first example in second group|
+      |second example in second group|
+    And the output should not contain any of these:
+      |first example in third group|
+      |nested group first example in nested group|
+      |nested group second example in nested group|

data/features/helper_methods/modules.feature

@@ -33,7 +33,7 @@ Feature: Define helper methods in a module
       end
 
       describe "an example group" do
-        it "has access the helper methods defined in the module" do
+        it "has access to the helper methods defined in the module" do
           help.should be(:available)
         end
       end
@@ -72,7 +72,7 @@ Feature: Define helper methods in a module
       end
 
       describe "an example group with matching metadata", :foo => :bar do
-        it "has access the helper methods defined in the module" do
+        it "has access to the helper methods defined in the module" do
           help.should be(:available)
         end
       end
@@ -130,7 +130,7 @@ Feature: Define helper methods in a module
       describe "an example group with matching include metadata", :include_helpers do
         puts "In a group not matching the extend filter, help is #{help rescue 'not available'}"
 
-        it "has access the helper methods defined in the module" do
+        it "has access to the helper methods defined in the module" do
           help.should be(:available)
         end
       end

data/lib/rspec/core.rb

@@ -11,6 +11,7 @@ else
 end
 
 require 'set'
+require 'rbconfig'
 require_rspec 'core/filter_manager'
 require_rspec 'core/dsl'
 require_rspec 'core/extensions'
@@ -30,10 +31,8 @@ require_rspec 'core/world'
 require_rspec 'core/configuration'
 require_rspec 'core/project_initializer'
 require_rspec 'core/option_parser'
-require_rspec 'core/drb_options'
 require_rspec 'core/configuration_options'
 require_rspec 'core/command_line'
-require_rspec 'core/drb_command_line'
 require_rspec 'core/runner'
 require_rspec 'core/example'
 require_rspec 'core/shared_example_group'
@@ -100,6 +99,11 @@ module RSpec
     world.example_groups.clear
   end
 
+  # @private
+  def self.windows_os?
+    /mswin|mingw/ === ::RbConfig::CONFIG['host_os']
+  end
+
   module Core
   end
 end

data/lib/rspec/core/configuration.rb

@@ -1,4 +1,3 @@
-require "rbconfig"
 require 'fileutils'
 
 module RSpec
@@ -278,24 +277,31 @@ MESSAGE
       #
       # `framework` can be a Symbol or a Module.
       #
-      # Given any of :rspec, :mocha, :flexmock, or :rr, configures the named
-      # framework.
+      # Given any of `:rspec`, `:mocha`, `:flexmock`, or `:rr`, configures the
+      # named framework.
       #
-      # Given :nothing, configures no framework. Use this if you don't use any
-      # mocking framework to save a little bit of overhead.
+      # Given `:nothing`, configures no framework. Use this if you don't use
+      # any mocking framework to save a little bit of overhead.
       #
       # Given a Module, includes that module in every example group. The module
       # should adhere to RSpec's mock framework adapter API:
       #
-      #   setup_mocks_for_rspec
-      #     - called before each example
+      #     setup_mocks_for_rspec
+      #       - called before each example
       #
-      #   verify_mocks_for_rspec
-      #     - called after each example. Framework should raise an exception
-      #       when expectations fail
+      #     verify_mocks_for_rspec
+      #       - called after each example. Framework should raise an exception
+      #         when expectations fail
       #
-      #   teardown_mocks_for_rspec
-      #     - called after verify_mocks_for_rspec (even if there are errors)
+      #     teardown_mocks_for_rspec
+      #       - called after verify_mocks_for_rspec (even if there are errors)
+      #
+      # If the module responds to `configuration` and `mock_with` receives a block,
+      # it will yield the configuration object to the block e.g.
+      #
+      #     config.mock_with OtherMockFrameworkAdapter do |mod_config|
+      #       mod_config.custom_setting = true
+      #     end
       def mock_with(framework)
         framework_module = case framework
         when Module
@@ -324,6 +330,11 @@ MESSAGE
           assert_no_example_groups_defined(:mock_framework)
         end
 
+        if block_given?
+          raise "#{framework_module} must respond to `configuration` so that mock_with can yield it." unless framework_module.respond_to?(:configuration)
+          yield framework_module.configuration
+        end
+
         @mock_framework = framework_module
       end
 
@@ -338,16 +349,33 @@ MESSAGE
         expect_with(framework)
       end
 
-      # Sets the expectation framework module(s).
+      # Sets the expectation framework module(s) to be included in each example
+      # group.
+      #
+      # `frameworks` can be `:rspec`, `:stdlib`, a custom module, or any
+      # combination thereof:
+      #
+      #     config.expect_with :rspec
+      #     config.expect_with :stdlib
+      #     config.expect_with :rspec, :stdlib
+      #     config.expect_with OtherExpectationFramework
       #
-      # `frameworks` can be :rspec, :stdlib, or both
+      # RSpec will translate `:rspec` and `:stdlib` into the appropriate
+      # modules.
       #
-      # Given :rspec, configures rspec/expectations.
-      # Given :stdlib, configures test/unit/assertions
-      # Given both, configures both
+      # ## Configuration
+      #
+      # If the module responds to `configuration`, `expect_with` will
+      # yield the `configuration` object if given a block:
+      #
+      #     config.expect_with OtherExpectationFramework do |custom_config|
+      #       custom_config.custom_setting = true
+      #     end
       def expect_with(*frameworks)
         modules = frameworks.map do |framework|
           case framework
+          when Module
+            framework
           when :rspec
             require 'rspec/expectations'
             self.expecting_with_rspec = true
@@ -364,7 +392,12 @@ MESSAGE
           assert_no_example_groups_defined(:expect_with)
         end
 
-        @expectation_frameworks.clear
+        if block_given?
+          raise "expect_with only accepts a block with a single argument. Call expect_with #{modules.length} times, once with each argument, instead." if modules.length > 1
+          raise "#{modules.first} must respond to `configuration` so that expect_with can yield it." unless modules.first.respond_to?(:configuration)
+          yield modules.first.configuration
+        end
+
         @expectation_frameworks.push(*modules)
       end
 
@@ -378,10 +411,9 @@ MESSAGE
       end
 
       def color=(bool)
-        return unless bool
-        @color = true
-        if bool && ::RbConfig::CONFIG['host_os'] =~ /mswin|mingw/
-          unless ENV['ANSICON']
+        if bool
+          @color = true
+          if RSpec.windows_os? and not ENV['ANSICON']
             warn "You must use ANSICON 1.31 or later (http://adoxa.110mb.com/ansicon/) to use colour on Windows"
             @color = false
           end
@@ -429,7 +461,7 @@ EOM
       end
 
       def full_description=(description)
-        filter_run :full_description => /#{description}/
+        filter_run :full_description => Regexp.union(*Array(description).map {|d| Regexp.new(d) })
       end
 
       # @overload add_formatter(formatter)
@@ -504,7 +536,7 @@ EOM
       #
       # Example:
       #
-      #     alias_it_should_behave_like_to(:it_has_behavior, 'has behavior:')
+      #     alias_it_behaves_like_to(:it_has_behavior, 'has behavior:')
       #
       # allows the user to include a shared example group like:
       #
@@ -519,10 +551,12 @@ EOM
       #     Entity
       #       has behavior: sortability
       #         # sortability examples here
-      def alias_it_should_behave_like_to(new_name, report_label = '')
-        RSpec::Core::ExampleGroup.alias_it_should_behave_like_to(new_name, report_label)
+      def alias_it_behaves_like_to(new_name, report_label = '')
+        RSpec::Core::ExampleGroup.alias_it_behaves_like_to(new_name, report_label)
       end
 
+      alias_method :alias_it_should_behave_like_to, :alias_it_behaves_like_to
+
       # Adds key/value pairs to the `inclusion_filter`. If the
       # `treat_symbols_as_metadata_keys_with_true_values` config option is set
       # to true and `args` includes any symbols that are not part of a hash,
@@ -770,6 +804,7 @@ EOM
       def get_files_to_run(paths)
         patterns = pattern.split(",")
         paths.map do |path|
+          path = path.gsub(File::ALT_SEPARATOR, File::SEPARATOR) if File::ALT_SEPARATOR
           File.directory?(path) ? gather_directories(path, patterns) : extract_location(path)
         end.flatten
       end

data/lib/rspec/core/configuration_options.rb

@@ -25,7 +25,9 @@ module RSpec
 
       def parse_options
         @options ||= extract_filters_from(*all_configs).inject do |merged, pending|
-          merged.merge(pending)
+          merged.merge(pending) { |key, oldval, newval|
+            MERGED_OPTIONS.include?(key) ? oldval + newval : newval
+          }
         end
       end
 
@@ -44,6 +46,8 @@ module RSpec
         :line_numbers, :full_description, :full_backtrace, :tty
       ].to_set
 
+      MERGED_OPTIONS = [:requires, :libs].to_set
+
       def force?(key)
         !NON_FORCED_OPTIONS.include?(key)
       end

data/lib/rspec/core/deprecation.rb

@@ -33,19 +33,4 @@ ADDITIONAL
       send :warn, message
     end
   end
-
-  # @private
-  class HashWithDeprecationNotice < Hash
-
-    def initialize(method, alternate_method=nil)
-      @method, @alternate_method = method, alternate_method
-    end
-
-    def []=(k,v)
-      RSpec.deprecate(@method, @alternate_method)
-      super(k,v)
-    end
-
-  end
-
 end

data/lib/rspec/core/drb_command_line.rb

@@ -1,3 +1,6 @@
+require 'drb/drb'
+require 'rspec/core/drb_options'
+
 module RSpec
   module Core
     class DRbCommandLine

data/lib/rspec/core/drb_options.rb

@@ -42,7 +42,9 @@ module RSpec::Core
         # into a regexp when received for the first time (see OptionParser).
         # Hence, merely grabbing the source of this regexp will retain the
         # backslashes, so we must remove them.
-        argv << "--example" << @submitted_options[:full_description].source.delete('\\')
+        @submitted_options[:full_description].each do |description|
+          argv << "--example" << description.source.delete('\\')
+        end
       end
     end
 

data/lib/rspec/core/dsl.rb

@@ -2,7 +2,7 @@ module RSpec
   module Core
     # Adds the `describe` method to the top-level namespace.
     module DSL
-      # Generates a subclass of [ExampleGroup](ExampleGroup)
+      # Generates a subclass of {ExampleGroup}
       #
       # ## Examples:
       #
@@ -21,4 +21,6 @@ module RSpec
   end
 end
 
-include RSpec::Core::DSL
+extend RSpec::Core::DSL
+Module.send(:include, RSpec::Core::DSL)
+

data/lib/rspec/core/example.rb

@@ -1,11 +1,37 @@
 module RSpec
   module Core
-    # Wrapper for an instance of a subclass of [ExampleGroup](ExampleGroup). An
-    # instance of `Example` is returned by the
-    # [example](ExampleGroup#example-instance_method) method available in
-    # examples, [before](Hooks#before-instance_method) and
-    # [after](Hooks#after-instance_method) hooks, and yielded to
-    # [around](Hooks#around-instance_method) hooks.
+    # Wrapper for an instance of a subclass of {ExampleGroup}. An instance of
+    # `Example` is returned by the {ExampleGroup#example example} method
+    # exposed to examples, {Hooks#before before} and {Hooks#after after} hooks,
+    # and yielded to {Hooks#around around} hooks.
+    #
+    # Useful for configuring logging and/or taking some action based
+    # on the state of an example's metadata.
+    #
+    # @example
+    #
+    #     RSpec.configure do |config|
+    #       config.before do
+    #         log example.description
+    #       end
+    #
+    #       config.after do
+    #         log example.description
+    #       end
+    #
+    #       config.around do |ex|
+    #         log example.description
+    #         ex.run
+    #       end
+    #     end
+    #
+    #     shared_examples "auditable" do
+    #       it "does something" do
+    #         log "#{example.full_description}: #{auditable.inspect}"
+    #         auditable.should do_something
+    #       end
+    #     end
+    #
     # @see ExampleGroup
     class Example
       # @private
@@ -70,9 +96,9 @@ module RSpec
       alias_method :pending?, :pending
 
       # @api private
+      # instance_evals the block passed to the constructor in the context of
+      # the instance of {ExampleGroup}.
       # @param example_group_instance the instance of an ExampleGroup subclass
-      # instance_evals the block submitted to the constructor in the
-      # context of the instance of ExampleGroup
       def run(example_group_instance, reporter)
         @example_group_instance = example_group_instance
         @example_group_instance.example = self
@@ -103,16 +129,16 @@ module RSpec
           @example_group_instance = nil
 
           begin
-            assign_auto_description
+            assign_generated_description
           rescue Exception => e
-            set_exception(e)
+            set_exception(e, "while assigning the example description")
           end
         end
 
         finish(reporter)
       end
 
-      # @private
+      # @api private
       #
       # Wraps the example block in a Proc so it can invoked using `run` or
       # `call` in [around](../Hooks#around-instance_method) hooks.
@@ -120,20 +146,39 @@ module RSpec
         proc.extend(Procsy).with(metadata)
       end
 
-      # @private
+      # Used to extend a `Proc` with behavior that makes it look something like
+      # an {Example} in an {Hooks#around around} hook.
+      #
+      # @note Procsy, itself, is not a public API, but we're documenting it
+      #   here to document how to interact with the object yielded to an
+      #   `around` hook.
+      #
+      # @example
+      #
+      #     RSpec.configure do |c|
+      #       c.around do |ex| # ex is a Proc extended with Procsy
+      #         if ex.metadata[:key] == :some_value && some_global_condition
+      #           raise "some message"
+      #         end
+      #         ex.run         # run delegates to ex.call
+      #       end
+      #     end
       module Procsy
+        # The `metadata` of the {Example} instance.
         attr_reader :metadata
 
-        # @private
+        # @api private
         # @param [Proc]
         # Adds a `run` method to the extended Proc, allowing it to be invoked
         # in an [around](../Hooks#around-instance_method) hook using either
         # `run` or `call`.
-        def self.extended(object)
-          def object.run; call; end
+        def self.extended(proc)
+          # @api public
+          # Foo bar
+          def proc.run; call; end
         end
 
-        # @private
+        # @api private
         def with(metadata)
           @metadata = metadata
           self
@@ -159,7 +204,20 @@ module RSpec
       #
       # Used internally to set an exception in an after hook, which
       # captures the exception but doesn't raise it.
-      def set_exception(exception)
+      def set_exception(exception, context=nil)
+        if @exception
+          # An error has already been set; we don't want to override it,
+          # but we also don't want silence the error, so let's print it.
+          msg = <<-EOS
+
+An error occurred #{context}
+  #{exception.class}: #{exception.message}
+  occurred at #{exception.backtrace.first}
+
+          EOS
+          RSpec.configuration.reporter.message(msg)
+        end
+
         @exception ||= exception
       end
 
@@ -179,8 +237,8 @@ module RSpec
       end
 
       # @private
-      def instance_eval_with_rescue(&block)
-        @example_group_instance.instance_eval_with_rescue(&block)
+      def instance_eval_with_rescue(context = nil, &block)
+        @example_group_instance.instance_eval_with_rescue(context, &block)
       end
 
       # @private
@@ -196,6 +254,8 @@ module RSpec
         else
           @example_group_class.run_around_each_hooks(self, Example.procsy(metadata, &block))
         end
+      rescue Exception => e
+        set_exception(e, "in an around(:each) hook")
       end
 
       def start(reporter)
@@ -235,18 +295,20 @@ module RSpec
       end
 
       def run_before_each
-        @example_group_instance.setup_mocks_for_rspec if @example_group_instance.respond_to?(:setup_mocks_for_rspec)
+        @example_group_instance.setup_mocks_for_rspec
         @example_group_class.run_before_each_hooks(self)
       end
 
       def run_after_each
         @example_group_class.run_after_each_hooks(self)
-        @example_group_instance.verify_mocks_for_rspec if @example_group_instance.respond_to?(:verify_mocks_for_rspec)
+        @example_group_instance.verify_mocks_for_rspec
+      rescue Exception => e
+        set_exception(e, "in an after(:each) hook")
       ensure
-        @example_group_instance.teardown_mocks_for_rspec if @example_group_instance.respond_to?(:teardown_mocks_for_rspec)
+        @example_group_instance.teardown_mocks_for_rspec
       end
 
-      def assign_auto_description
+      def assign_generated_description
         return unless RSpec.configuration.expecting_with_rspec?
         if metadata[:description].empty? and !pending?
           metadata[:description] = RSpec::Matchers.generated_description