rspec-core 2.8.0.rc1 → 2.8.0.rc2

data/lib/rspec/core.rb

@@ -1,56 +1,67 @@
-require 'rspec/core/filter_manager'
-require 'rspec/core/dsl'
-require 'rspec/core/extensions'
-require 'rspec/core/load_path'
-require 'rspec/core/deprecation'
-require 'rspec/core/backward_compatibility'
-require 'rspec/core/reporter'
+if defined?(require_relative)
+  # @private
+  def require_rspec(path)
+    require_relative path
+  end
+else
+  # @private
+  def require_rspec(path)
+    require "rspec/#{path}"
+  end
+end
 
-require 'rspec/core/metadata_hash_builder'
-require 'rspec/core/hooks'
-require 'rspec/core/subject'
-require 'rspec/core/let'
-require 'rspec/core/metadata'
-require 'rspec/core/pending'
+require_rspec 'core/filter_manager'
+require_rspec 'core/dsl'
+require_rspec 'core/extensions'
+require_rspec 'core/load_path'
+require_rspec 'core/deprecation'
+require_rspec 'core/backward_compatibility'
+require_rspec 'core/reporter'
 
-require 'rspec/core/world'
-require 'rspec/core/configuration'
-require 'rspec/core/command_line_configuration'
-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'
-require 'rspec/core/example_group'
-require 'rspec/core/version'
-require 'rspec/core/errors'
+require_rspec 'core/metadata_hash_builder'
+require_rspec 'core/hooks'
+require_rspec 'core/subject'
+require_rspec 'core/let'
+require_rspec 'core/metadata'
+require_rspec 'core/pending'
+
+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'
+require_rspec 'core/example_group'
+require_rspec 'core/version'
 
 module RSpec
   autoload :Matchers,      'rspec/matchers'
   autoload :SharedContext, 'rspec/core/shared_context'
 
-  # @api private
-  # Used internally to determine what to do when a SIGINT is received
+  # @private
   def self.wants_to_quit
+  # Used internally to determine what to do when a SIGINT is received
     world.wants_to_quit
   end
 
-  # @api private
+  # @private
   # Used internally to determine what to do when a SIGINT is received
   def self.wants_to_quit=(maybe)
     world.wants_to_quit=(maybe)
   end
 
-  # @api private
+  # @private
   # Internal container for global non-configuration data
   def self.world
     @world ||= RSpec::Core::World.new
   end
 
-  # @api private
+  # @private
   # Used internally to ensure examples get reloaded between multiple runs in
   # the same process.
   def self.reset
@@ -58,7 +69,7 @@ module RSpec
     configuration.reset
   end
 
-  # Returns the global [Configuration](Core/Configuration) object. While you
+  # Returns the global [Configuration](RSpec/Core/Configuration) object. While you
   # _can_ use this method to access the configuration, the more common
   # convention is to use [RSpec.configure](RSpec#configure-class_method).
   #
@@ -70,6 +81,7 @@ module RSpec
     @configuration ||= RSpec::Core::Configuration.new
   end
 
+  # Yields the global configuration to a block.
   # @yield [Configuration] global configuration
   #
   # @example
@@ -81,137 +93,15 @@ module RSpec
     yield configuration if block_given?
   end
 
-  # @api private
+  # @private
   # Used internally to clear remaining groups when fail_fast is set
   def self.clear_remaining_example_groups
     world.example_groups.clear
   end
 
-  # 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:
-  #
-  #     "Describe an order."
-  #     "It sums the prices of its line items."
-  #
-  # ## Basic structure
-  #
-  #     describe Order do
-  #       it "sums the prices of its line items" do
-  #         order = Order.new
-  #         order.add_entry(LineItem.new(:item => Item.new(
-  #           :price => Money.new(1.11, :USD)
-  #         )
-  #         order.add_entry(LineItem.new(:item => Item.new(
-  #           :price => Money.new(2.22, :USD),
-  #           :quantity => 2
-  #         )
-  #         order.total.should eq(Money.new(5.55, :USD))
-  #       end
-  #     end
-  #
-  # The `describe` method creates an [ExampleGroup](Core/ExampleGroup).  Within the
-  # block passed to `describe` you can declare examples using the `it` method.
-  #
-  # Under the hood, an example group is a class in which the block passed to
-  # `describe` is evaluated. The blocks passed to `it` are evaluated in the
-  # context of an _instance_ of that class.
-  #
-  # ## Nested groups
-  #
-  # You can also declare nested nested groups using the `describe` or `context`
-  # methods:
-  #
-  #     describe Order to
-  #       context "with no items" do
-  #         it "behaves one way" do
-  #           # ...
-  #         end
-  #       end
-  #
-  #       context "with one item" do
-  #         it "behaves another way" do
-  #           # ...
-  #         end
-  #       end
-  #     end
-  #
-  # ## Aliases
-  #
-  # You can declare example groups using either `describe` or `context`, though
-  # only `describe` is available at the top level.
-  #
-  # You can declare examples within a group using any of `it`, `specify`, or
-  # `example`.
-  #
-  # ## Shared examples
-  #
-  # Declare a shared example group using `shared_examples`, and then include it
-  # in each group using `include_examples`.
-  #
-  #     shared_examples "collections" do |collection_class|
-  #       it "is empty when first created" do
-  #         collection_class.new.should be_empty
-  #       end
-  #     end
-  #
-  #     describe Array do
-  #       include_examples "collections", Array
-  #     end
-  #
-  # ## Metadata
-  #
-  # rspec-core stores a metadata hash with every example and group, which
-  # contains like their descriptions, the locations at which they were
-  # declared, etc, etc. This hash powers many of rspec-core's features,
-  # including output formatters (which access descriptions and locations),
-  # and filtering before and after hooks.
-  #
-  # Although you probably won't ever need this unless you are writing an
-  # extension, you can access it from an example like this:
-  #
-  #     it "does something" do
-  #       example.metadata[:description].should eq("does something")
-  #     end
-  #
-  # ### `described_class`
-  #
-  # When a class is passed to `describe`, you can access it from an example
-  # using the `described_class` method, which is a wrapper for
-  # `example.metadata[:described_class]`.
-  #
-  #     describe Widget do
-  #       example do
-  #         described_class.should equal(Widget)
-  #       end
-  #     end
-  #
-  # This is useful in extensions or shared example groups in which the specific
-  # class is unknown. Taking the shared examples example from above, we can
-  # clean it up a bit using `described_class`:
-  #
-  #     shared_examples "collections" do
-  #       it "is empty when first created" do
-  #         described.new.should be_empty
-  #       end
-  #     end
-  #
-  #     describe Array do
-  #       include_examples "collections"
-  #     end
-  #
-  #     describe Hash do
-  #       include_examples "collections"
-  #     end
-  #
-  # ## The `rspec` command
-  #
-  # When you install the rspec-core gem, it installs the `rspec` executable,
-  # which you'll use to run rspec. The `rspec` comes with many useful options.
-  # Run `rspec --help` to see the complete list.
   module Core
   end
 end
 
-require 'rspec/core/backward_compatibility'
-require 'rspec/monkey'
+require_rspec 'core/backward_compatibility'
+require_rspec 'monkey'

data/lib/rspec/core/backward_compatibility.rb

@@ -1,5 +1,6 @@
 module RSpec
   module Core
+    # @private
     module ConstMissing
       # Used to print deprecation warnings for Rspec and Spec constants (use
       # RSpec instead)
@@ -38,6 +39,7 @@ WARNING
     end
   end
 
+  # @private
   module Rake
     # Used to print deprecation warnings for Rake::SpecTask constant (use
     # RSpec::Core::RakeTask instead)

data/lib/rspec/core/command_line.rb

@@ -11,6 +11,10 @@ module RSpec
         @world         = world
       end
 
+      # Configures and runs a suite
+      #
+      # @param [IO] err
+      # @param [IO] out
       def run(err, out)
         @configuration.error_stream = err
         @configuration.output_stream ||= out

data/lib/rspec/core/configuration.rb

@@ -7,7 +7,9 @@ module RSpec
     #
     # @example Standard settings
     #     RSpec.configure do |c|
-    #       c.drb_port = 1234
+    #       c.drb          = true
+    #       c.drb_port     = 1234
+    #       c.default_path = 'behavior'
     #     end
     #
     # @example Hooks
@@ -24,60 +26,147 @@ module RSpec
 
       class MustBeConfiguredBeforeExampleGroupsError < StandardError; end
 
+      # @private
+      def self.define_reader(name)
+        eval <<-CODE
+          def #{name}
+            value_for(#{name.inspect}, defined?(@#{name}) ? @#{name} : nil)
+          end
+        CODE
+      end
+
+      # @private
+      def self.deprecate_alias_key
+        RSpec.warn_deprecation <<-MESSAGE
+The :alias option to add_setting is deprecated. Use :alias_with on the original setting instead.
+Called from #{caller(0)[5]}
+MESSAGE
+      end
+
+      # @private
+      def self.define_aliases(name, alias_name)
+        alias_method alias_name, name
+        alias_method "#{alias_name}=", "#{name}="
+        define_predicate_for alias_name
+      end
+
+      # @private
       def self.define_predicate_for(*names)
         names.each {|name| alias_method "#{name}?", name}
       end
 
-      # @api private
+      # @private
       #
       # Invoked by the `add_setting` instance method. Use that method on a
       # `Configuration` instance rather than this class method.
       def self.add_setting(name, opts={})
         raise "Use the instance add_setting method if you want to set a default" if opts.has_key?(:default)
         if opts[:alias]
-          RSpec.warn_deprecation <<-MESSAGE
-The :alias option to add_setting is deprecated. Use :alias_with on the original setting instead.
-Called from #{caller(0)[4]}
-MESSAGE
-          alias_method name, opts[:alias]
-          alias_method "#{name}=", "#{opts[:alias]}="
-          define_predicate_for name
+          deprecate_alias_key
+          define_aliases(opts[:alias], name)
         else
           attr_writer name
-          eval <<-CODE
-            def #{name}
-              value_for(#{name.inspect}, defined?(@#{name}) ? @#{name} : nil)
-            end
-          CODE
+          define_reader name
           define_predicate_for name
         end
-        if opts[:alias_with]
-          [opts[:alias_with]].flatten.each do |alias_name|
-            alias_method alias_name, name
-            alias_method "#{alias_name}=", "#{name}="
-            define_predicate_for alias_name
-          end
+        [opts[:alias_with]].flatten.compact.each do |alias_name|
+          define_aliases(name, alias_name)
         end
       end
 
-      add_setting :error_stream
-      add_setting :output_stream, :alias_with => [:output, :out]
+      # @macro [attach] add_setting
+      #   @attribute $1
+      # Patterns to match against lines in backtraces presented in failure
+      # messages in order to filter them out (default:
+      # DEFAULT_BACKTRACE_PATTERNS).  You can either replace this list using
+      # the setter or modify it using the getter.
+      #
+      # To override this behavior and display a full backtrace, use
+      # `--backtrace` on the command line, in a `.rspec` file, or in the
+      # `rspec_options` attribute of RSpec's rake task.
+      add_setting :backtrace_clean_patterns
+
+      # Path to use if no path is provided to the `rspec` command (default:
+      # `"spec"`). Allows you to just type `rspec` instead of `rspec spec` to
+      # run all the examples in the `spec` directory.
+      add_setting :default_path
+
+      # Run examples over DRb (default: `false`). RSpec doesn't supply the DRb
+      # server, but you can use tools like spork.
       add_setting :drb
+
+      # The drb_port (default: `8989`).
       add_setting :drb_port
-      add_setting :profile_examples
+
+      # Default: `$stderr`.
+      add_setting :error_stream
+
+      # Clean up and exit after the first failure (default: `false`).
       add_setting :fail_fast
+
+      # The exit code to return if there are any failures (default: 1).
       add_setting :failure_exit_code
-      add_setting :run_all_when_everything_filtered
+
+      # Determines the order in which examples are run (default: OS standard
+      # load order for files, declaration order for groups and examples).
+      define_reader :order
+
+      # Default: `$stdout`.
+      # Also known as `output` and `out`
+      add_setting :output_stream, :alias_with => [:output, :out]
+
+      # Load files matching this pattern (default: `'**/*_spec.rb'`)
       add_setting :pattern, :alias_with => :filename_pattern
-      add_setting :files_to_run
-      add_setting :include_or_extend_modules
-      add_setting :backtrace_clean_patterns
-      add_setting :tty
+
+      # Report the times for the 10 slowest examples (default: `false`).
+      add_setting :profile_examples
+
+      # Run all examples if none match the configured filters (default: `false`).
+      add_setting :run_all_when_everything_filtered
+
+      # Seed for random ordering (default: generated randomly each run).
+      #
+      # When you run specs with `--order random`, RSpec generates a random seed
+      # for the randomization and prints it to the `output_stream` (assuming
+      # you're using RSpec's built-in formatters). If you discover an ordering
+      # dependency (i.e. examples fail intermittently depending on order), set
+      # this (on Configuration or on the command line with `--seed`) to run
+      # using the same seed while you debug the issue.
+      #
+      # We recommend, actually, that you use the command line approach so you
+      # don't accidentally leave the seed encoded.
+      define_reader :seed
+
+      # When a block passed to pending fails (as expected), display the failure
+      # without reporting it as a failure (default: false).
+      add_setting :show_failures_in_pending_blocks
+
+      # Convert symbols to hashes with the symbol as a key with a value of
+      # `true` (default: false).
+      #
+      # This allows you to tag a group or example like this:
+      #
+      #     describe "something slow", :slow do
+      #       # ...
+      #     end
+      #
+      # ... instead of having to type:
+      #
+      #     describe "something slow", :slow => true do
+      #       # ...
+      #     end
       add_setting :treat_symbols_as_metadata_keys_with_true_values
+
+      # @private
+      add_setting :tty
+      # @private
+      add_setting :include_or_extend_modules
+      # @private
+      add_setting :files_to_run
+      # @private
       add_setting :expecting_with_rspec
-      add_setting :default_path
-      add_setting :show_failures_in_pending_blocks
-      add_setting :order
+      # @private
+      attr_accessor :filter_manager
 
       DEFAULT_BACKTRACE_PATTERNS = [
         /\/lib\d*\/ruby\//,
@@ -104,27 +193,39 @@ MESSAGE
         @seed = srand % 0xFFFF
       end
 
-      attr_accessor :filter_manager
-
+      # @private
+      #
+      # Used to set higher priority option values from the command line.
       def force(hash)
+        if hash.has_key?(:seed)
+          hash[:order], hash[:seed] = order_and_seed_from_seed(hash[:seed])
+        elsif hash.has_key?(:order)
+          set_order_and_seed(hash)
+        end
         @preferred_options.merge!(hash)
       end
 
-      def force_include(hash)
-        filter_manager.include hash
-      end
-
-      def force_exclude(hash)
-        filter_manager.exclude hash
-      end
-
+      # @api private
       def reset
         @reporter = nil
         @formatters.clear
       end
 
       # @overload add_setting(name)
-      # @overload add_setting(name, options_hash)
+      # @overload add_setting(name, opts)
+      # @option opts [Symbol] :default
+      #
+      #   set a default value for the generated getter and predicate methods:
+      #
+      #       add_setting(:foo, :default => "default value")
+      #
+      # @option opts [Symbol] :alias_with
+      #
+      #   Use `:alias_with` to alias the setter, getter, and predicate to another
+      #   name, or names:
+      #
+      #       add_setting(:foo, :alias_with => :bar)
+      #       add_setting(:foo, :alias_with => [:bar, :baz])
       #
       # Adds a custom setting to the RSpec.configuration object.
       #
@@ -145,23 +246,6 @@ MESSAGE
       #     RSpec.configuration.foo=(value)
       #     RSpec.configuration.foo
       #     RSpec.configuration.foo? # returns true if foo returns anything but nil or false
-      #
-      # ### Options
-      #
-      # `add_setting` takes an optional hash that supports the keys `:default`
-      # and `:alias_with`.
-      #
-      # Use `:default` to set a default value for the generated getter and
-      # predicate methods:
-      #
-      #     add_setting(:foo, :default => "default value")
-      #
-      # Use `:alias_with` to alias the setter, getter, and predicate to another
-      # name, or names:
-      #
-      #     add_setting(:foo, :alias_with => :bar)
-      #     add_setting(:foo, :alias_with => [:bar, :baz])
-      #
       def add_setting(name, opts={})
         default = opts.delete(:default)
         (class << self; self; end).class_eval do
@@ -384,35 +468,6 @@ EOM
         self.files_to_run = get_files_to_run(files)
       end
 
-      # @api private
-      def command
-        $0.split(File::SEPARATOR).last
-      end
-
-      # @api private
-      def get_files_to_run(files)
-        patterns = pattern.split(",")
-        files.map do |file|
-          if File.directory?(file)
-            patterns.map do |pattern|
-              if pattern =~ /^#{file}/
-                Dir[pattern.strip]
-              else
-                Dir["#{file}/{#{pattern.strip}}"]
-              end
-            end
-          else
-            if file =~ /^(.*?)((?:\:\d+)+)$/
-              path, lines = $1, $2[1..-1].split(":").map{|n| n.to_i}
-              filter_manager.add_location path, lines
-              path
-            else
-              file
-            end
-          end
-        end.flatten
-      end
-
       # Creates a method that delegates to `example` including the submitted
       # `args`. Used internally to add variants of `example` like `pending`:
       #
@@ -480,7 +535,7 @@ EOM
       #     # with treat_symbols_as_metadata_keys_with_true_values = true
       #     filter_run_including :foo # results in {:foo => true}
       def filter_run_including(*args)
-        filter_manager.include :low_priority, build_metadata_hash_from(args)
+        filter_manager.include_with_low_priority build_metadata_hash_from(args)
       end
 
       alias_method :filter_run, :filter_run_including
@@ -493,7 +548,7 @@ EOM
       # This overrides any inclusion filters/tags set on the command line or in
       # configuration files.
       def inclusion_filter=(filter)
-        filter_manager.include :replace, build_metadata_hash_from([filter])
+        filter_manager.include! build_metadata_hash_from([filter])
       end
 
       alias_method :filter=, :inclusion_filter=
@@ -522,7 +577,7 @@ EOM
       #     # with treat_symbols_as_metadata_keys_with_true_values = true
       #     filter_run_excluding :foo # results in {:foo => true}
       def filter_run_excluding(*args)
-        filter_manager.exclude :low_priority, build_metadata_hash_from(args)
+        filter_manager.exclude_with_low_priority build_metadata_hash_from(args)
       end
 
       # Clears and reassigns the `exclusion_filter`. Set to `nil` if you don't
@@ -533,7 +588,7 @@ EOM
       # This overrides any exclusion filters/tags set on the command line or in
       # configuration files.
       def exclusion_filter=(filter)
-        filter_manager.exclude :replace, build_metadata_hash_from([filter])
+        filter_manager.exclude! build_metadata_hash_from([filter])
       end
 
       # Returns the `exclusion_filter`. If none has been set, returns an empty
@@ -563,45 +618,68 @@ EOM
         end
       end
 
+      # @api private
       def configure_mock_framework
         RSpec::Core::ExampleGroup.send(:include, mock_framework)
       end
 
+      # @api private
       def configure_expectation_framework
         expectation_frameworks.each do |framework|
           RSpec::Core::ExampleGroup.send(:include, framework)
         end
       end
 
+      # @api private
       def load_spec_files
         files_to_run.map {|f| load File.expand_path(f) }
         raise_if_rspec_1_is_loaded
       end
 
-      attr_reader :seed
-
+      # @api
+      #
+      # Sets the seed value and sets `order='rand'`
       def seed=(seed)
-        @order = 'rand'
-        @seed = seed.to_i
+        order_and_seed_from_seed(seed)
+      end
+
+      # @api
+      #
+      # Sets the order and, if order is `'rand:<seed>'`, also sets the seed.
+      def order=(type)
+        order_and_seed_from_order(type)
       end
 
       def randomize?
         order.to_s.match(/rand/)
       end
 
-      remove_method :order=
-      def order=(type)
-        order, seed = type.to_s.split(':')
-        if order == 'default'
-          @order = nil
-          @seed = nil
-        else
-          @order = order
-          @seed = seed.to_i if seed
+    private
+
+      def get_files_to_run(paths)
+        patterns = pattern.split(",")
+        paths.map do |path|
+          File.directory?(path) ? gather_directories(path, patterns) : extract_location(path)
+        end.flatten
+      end
+
+      def gather_directories(path, patterns)
+        patterns.map do |pattern|
+          pattern =~ /^#{path}/ ? Dir[pattern.strip] : Dir["#{path}/{#{pattern.strip}}"]
         end
       end
 
-    private
+      def extract_location(path)
+        if path =~ /^(.*?)((?:\:\d+)+)$/
+          path, lines = $1, $2[1..-1].split(":").map{|n| n.to_i}
+          filter_manager.add_location path, lines
+        end
+        path
+      end
+
+      def command
+        $0.split(File::SEPARATOR).last
+      end
 
       def value_for(key, default=nil)
         @preferred_options.has_key?(key) ? @preferred_options[key] : default
@@ -698,6 +776,23 @@ MESSAGE
         File.new(path, 'w')
       end
 
+      def order_and_seed_from_seed(value)
+        @order, @seed = 'rand', value.to_i
+      end
+
+      def set_order_and_seed(hash)
+        hash[:order], seed = order_and_seed_from_order(hash[:order])
+        hash[:seed] = seed if seed
+      end
+
+      def order_and_seed_from_order(type)
+        order, seed = type.to_s.split(':')
+        @order = order
+        @seed  = seed = seed.to_i if seed
+        @order, @seed = nil, nil if order == 'default'
+        return order, seed
+      end
+
     end
   end
 end