rspec-core 2.7.1 → 2.8.0.rc1

data/README.md

@@ -1,6 +1,6 @@
 # rspec-core
 
-RSpec Core provides the structure for writing executable examples of how your
+rspec-core provides the structure for writing executable examples of how your
 code should behave.
 
 ## Install

data/features/command_line/order.feature

@@ -0,0 +1,29 @@
+Feature: --order (new in rspec-core-2.8)
+
+  Use the `--order` option to tell RSpec how to order the files, groups, and
+  examples. Options are `default` and `rand`:
+
+  Default is:
+
+    * files are ordered based on the underlying file system's order (typically
+      case-sensitive alpha on *nix OS's and case-insenstive alpha in Windows)
+    * groups/examples are loaded in the order in which they are declared
+
+  Use `rand` to randomize the order of files, groups within files, and
+  examples within groups.*
+
+  * Nested groups are always run from top-level to bottom-level in order to avoid
+    executing `before(:all)` and `after(:all)` hooks more than once, but the order
+    of groups at each level is randomized.
+
+  You can also specify a seed
+
+  <h3>Examples</h3>
+
+      --order default
+      --order rand
+      --order rand:123
+      --seed 123 # same as --order rand:123
+
+  The `default` option is only necessary when you have `--order rand` stored in a
+  config file (e.g. `.rspec`) and you want to override it from the command line.

data/features/command_line/tag.feature

@@ -33,19 +33,19 @@ Feature: --tag option
 
   Scenario: filter examples with a simple tag
     When I run `rspec . --tag focus`
-    Then the output should contain "Run filtered including {:focus=>true}"
+    Then the output should contain "include {:focus=>true}"
     And the examples should all pass
 
   Scenario: filter examples with a simple tag and @
     When I run `rspec . --tag @focus`
-    Then the output should contain "Run filtered including {:focus=>true}"
+    Then the output should contain "include {:focus=>true}"
     Then the examples should all pass
 
   Scenario: filter examples with a name:value tag
     When I run `rspec . --tag type:special`
     Then the output should contain:
       """
-      Run filtered including {:type=>"special"}
+      include {:type=>"special"}
       """
     And the output should contain "2 examples"
     And the examples should all pass
@@ -54,25 +54,25 @@ Feature: --tag option
     When I run `rspec . --tag @type:special`
     Then the output should contain:
       """
-      Run filtered including {:type=>"special"}
+      include {:type=>"special"}
       """
     And the examples should all pass
   
   Scenario: exclude examples with a simple tag
     When I run `rspec . --tag ~skip`
-    Then the output should contain "Run filtered excluding {:skip=>true}"
+    Then the output should contain "exclude {:skip=>true}"
     Then the examples should all pass
 
   Scenario: exclude examples with a simple tag and @
     When I run `rspec . --tag ~@skip`
-    Then the output should contain "Run filtered excluding {:skip=>true}"
+    Then the output should contain "exclude {:skip=>true}"
     Then the examples should all pass
     
   Scenario: exclude examples with a name:value tag
     When I run `rspec . --tag ~speed:slow`
     Then the output should contain:
       """
-      Run filtered excluding {:speed=>"slow"}
+      exclude {:speed=>"slow"}
       """
     Then the examples should all pass
   
@@ -80,11 +80,12 @@ Feature: --tag option
     When I run `rspec . --tag ~@speed:slow`
     Then the output should contain:
       """
-      Run filtered excluding {:speed=>"slow"}
+      exclude {:speed=>"slow"}
       """
     Then the examples should all pass
 
   Scenario: filter examples with a simple tag, exclude examples with another tag
     When I run `rspec . --tag focus --tag ~skip`
-    Then the output should contain "Run filtered including {:focus=>true}, excluding {:skip=>true}"
+    Then the output should contain "include {:focus=>true}"
+    And the output should contain "exclude {:skip=>true}"
     And the examples should all pass

data/features/configuration/default_path.feature

@@ -1,7 +1,7 @@
 Feature: default_path
 
-  As of rspec-2.7 (not yet released), you can just type `rspec` to run all
-  specs that live in the `spec` directory.
+  As of rspec-2.7, you can just type `rspec` to run all specs that live
+  in the `spec` directory.
 
   This is supported by a `--default_path` option, which is set to `spec` by
   default. If you prefer to keep your specs in a different directory, or assign

data/features/filtering/exclusion_filters.feature

@@ -81,7 +81,7 @@ Feature: exclusion filters
       end
       """
     When I run `rspec ./spec/sample_spec.rb --format doc`
-    Then the output should match /No examples were matched. Perhaps \{.*:broken=>true.*\} is excluding everything?/
+    Then the output should match /All examples were filtered out/
     And  the examples should all pass
     And  the output should not contain "group 1"
     And  the output should not contain "group 2"

data/features/filtering/run_all_when_everything_filtered.feature

@@ -32,7 +32,7 @@ Feature: run all when everything filtered
       end
       """
     When I run `rspec spec/sample_spec.rb --format doc`
-    Then the output should contain "No examples matched {:focus=>true}"
+    Then the output should contain "All examples were filtered out; ignoring {:focus=>true}"
     And the examples should all pass
     And the output should contain:
       """

data/features/subject/attribute_of_subject.feature

@@ -65,7 +65,7 @@ Feature: attribute of subject
       Person
         with one phone number (555-1212)
           phone_numbers.first
-            should eq 555-1212
+            should eq "555-1212"
       """
 
   Scenario: specify value of an attribute of a hash

data/lib/rspec/core.rb

@@ -1,4 +1,4 @@
-$rspec_start_time ||= Time.now
+require 'rspec/core/filter_manager'
 require 'rspec/core/dsl'
 require 'rspec/core/extensions'
 require 'rspec/core/load_path'
@@ -17,37 +17,40 @@ 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_context'
 require 'rspec/core/shared_example_group'
 require 'rspec/core/example_group'
 require 'rspec/core/version'
 require 'rspec/core/errors'
 
 module RSpec
-  autoload :Matchers, 'rspec/matchers'
-
-  SharedContext = Core::SharedContext
+  autoload :Matchers,      'rspec/matchers'
+  autoload :SharedContext, 'rspec/core/shared_context'
 
+  # @api private
   # Used internally to determine what to do when a SIGINT is received
   def self.wants_to_quit
     world.wants_to_quit
   end
 
+  # @api 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
   # Internal container for global non-configuration data
   def self.world
     @world ||= RSpec::Core::World.new
   end
 
+  # @api private
   # Used internally to ensure examples get reloaded between multiple runs in
   # the same process.
   def self.reset
@@ -55,26 +58,159 @@ module RSpec
     configuration.reset
   end
 
-  # Returns the global configuration object
+  # Returns the global [Configuration](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).
+  #
+  # @example
+  #     RSpec.configuration.drb_port = 1234
+  # @see RSpec.configure
+  # @see Core::Configuration
   def self.configuration
     @configuration ||= RSpec::Core::Configuration.new
   end
 
-  # Yields the global configuration object
-  #
-  # == Examples
+  # @yield [Configuration] global configuration
   #
-  # RSpec.configure do |config|
-  #   config.format = 'documentation'
-  # end
+  # @example
+  #     RSpec.configure do |config|
+  #       config.add_formatter 'documentation'
+  #     end
+  # @see Core::Configuration
   def self.configure
     yield configuration if block_given?
   end
 
+  # @api 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'

data/lib/rspec/core/command_line.rb

@@ -18,10 +18,10 @@ module RSpec
         @configuration.load_spec_files
         @world.announce_filters
 
-        @configuration.reporter.report(@world.example_count) do |reporter|
+        @configuration.reporter.report(@world.example_count, @configuration.randomize? ? @configuration.seed : nil) do |reporter|
           begin
             @configuration.run_hook(:before, :suite)
-            @world.example_groups.map {|g| g.run(reporter)}.all? ? 0 : @configuration.failure_exit_code
+            @world.example_groups.ordered.map {|g| g.run(reporter)}.all? ? 0 : @configuration.failure_exit_code
           ensure
             @configuration.run_hook(:after, :suite)
           end

data/lib/rspec/core/configuration.rb

@@ -3,51 +3,81 @@ require 'fileutils'
 
 module RSpec
   module Core
+    # Stores runtime configuration information.
+    #
+    # @example Standard settings
+    #     RSpec.configure do |c|
+    #       c.drb_port = 1234
+    #     end
+    #
+    # @example Hooks
+    #     RSpec.configure do |c|
+    #       c.before(:suite) { establish_connection }
+    #       c.before(:each)  { log_in_as :authorized }
+    #       c.around(:each)  { |ex| Database.transaction(&ex) }
+    #     end
+    #
+    # @see RSpec.configure
+    # @see Hooks
     class Configuration
       include RSpec::Core::Hooks
 
       class MustBeConfiguredBeforeExampleGroupsError < StandardError; end
 
+      def self.define_predicate_for(*names)
+        names.each {|name| alias_method "#{name}?", name}
+      end
+
+      # @api 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]}="
-          alias_method "#{name}?", "#{opts[:alias]}?"
+          define_predicate_for name
         else
-          define_method("#{name}=") {|val| settings[name] = val}
-          define_method(name)       { settings.has_key?(name) ? settings[name] : opts[:default] }
-          define_method("#{name}?") { send name }
+          attr_writer name
+          eval <<-CODE
+            def #{name}
+              value_for(#{name.inspect}, defined?(@#{name}) ? @#{name} : nil)
+            end
+          CODE
+          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
         end
       end
 
       add_setting :error_stream
-      add_setting :output_stream
-      add_setting :output, :alias => :output_stream
-      add_setting :out, :alias => :output_stream
+      add_setting :output_stream, :alias_with => [:output, :out]
       add_setting :drb
       add_setting :drb_port
       add_setting :profile_examples
       add_setting :fail_fast
-      add_setting :failure_exit_code, :default => 1
+      add_setting :failure_exit_code
       add_setting :run_all_when_everything_filtered
-      add_setting :exclusion_filter
-      add_setting :inclusion_filter
-      add_setting :filter, :alias => :inclusion_filter
-      add_setting :pattern, :default => '**/*_spec.rb'
-      add_setting :filename_pattern, :alias => :pattern
+      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
-      add_setting :treat_symbols_as_metadata_keys_with_true_values, :default => false
+      add_setting :treat_symbols_as_metadata_keys_with_true_values
       add_setting :expecting_with_rspec
-      add_setting :default_path, :default => 'spec'
-      add_setting :show_failures_in_pending_blocks, :default => false
-
-      CONDITIONAL_FILTERS = {
-        :if     => lambda { |value, metadata| metadata.has_key?(:if) && !value },
-        :unless => lambda { |value| value }
-      }
+      add_setting :default_path
+      add_setting :show_failures_in_pending_blocks
+      add_setting :order
 
       DEFAULT_BACKTRACE_PATTERNS = [
         /\/lib\d*\/ruby\//,
@@ -59,92 +89,107 @@ module RSpec
       ]
 
       def initialize
-        @color_enabled = false
-        self.include_or_extend_modules = []
-        self.files_to_run = []
-        self.backtrace_clean_patterns = DEFAULT_BACKTRACE_PATTERNS.dup
-        self.exclusion_filter = CONDITIONAL_FILTERS.dup
+        @expectation_frameworks = []
+        @include_or_extend_modules = []
+        @mock_framework = nil
+        @files_to_run = []
+        @formatters = []
+        @color = false
+        @pattern = '**/*_spec.rb'
+        @failure_exit_code = 1
+        @backtrace_clean_patterns = DEFAULT_BACKTRACE_PATTERNS.dup
+        @default_path = 'spec'
+        @filter_manager = FilterManager.new
+        @preferred_options = {}
+        @seed = srand % 0xFFFF
+      end
+
+      attr_accessor :filter_manager
+
+      def force(hash)
+        @preferred_options.merge!(hash)
+      end
+
+      def force_include(hash)
+        filter_manager.include hash
+      end
+
+      def force_exclude(hash)
+        filter_manager.exclude hash
       end
 
       def reset
         @reporter = nil
-        @formatters.clear if @formatters
+        @formatters.clear
       end
 
-      # :call-seq:
-      #   add_setting(:name)
-      #   add_setting(:name, :default => "default_value")
-      #   add_setting(:name, :alias => :other_setting)
+      # @overload add_setting(name)
+      # @overload add_setting(name, options_hash)
       #
-      # Use this to add custom settings to the RSpec.configuration object.
+      # Adds a custom setting to the RSpec.configuration object.
       #
-      #   RSpec.configuration.add_setting :foo
+      #     RSpec.configuration.add_setting :foo
       #
-      # Creates three methods on the configuration object, a setter, a getter,
-      # and a predicate:
+      # Used internally and by extension frameworks like rspec-rails, so they
+      # can add config settings that are domain specific. For example:
+      #
+      #     RSpec.configure do |c|
+      #       c.add_setting :use_transactional_fixtures,
+      #         :default => true,
+      #         :alias_with => :use_transactional_examples
+      #     end
       #
-      #   RSpec.configuration.foo=(value)
-      #   RSpec.configuration.foo()
-      #   RSpec.configuration.foo?() # returns true if foo returns anything but nil or false
+      # `add_setting` creates three methods on the configuration object, a
+      # setter, a getter, and a predicate:
       #
-      # Intended for extension frameworks like rspec-rails, so they can add config
-      # settings that are domain specific. For example:
+      #     RSpec.configuration.foo=(value)
+      #     RSpec.configuration.foo
+      #     RSpec.configuration.foo? # returns true if foo returns anything but nil or false
       #
-      #   RSpec.configure do |c|
-      #     c.add_setting :use_transactional_fixtures, :default => true
-      #     c.add_setting :use_transactional_examples, :alias => :use_transactional_fixtures
-      #   end
+      # ### Options
       #
-      # == Options
+      # `add_setting` takes an optional hash that supports the keys `:default`
+      # and `:alias_with`.
       #
-      # +add_setting+ takes an optional hash that supports the following
-      # keys:
+      # Use `:default` to set a default value for the generated getter and
+      # predicate methods:
       #
-      #   :default => "default value"
+      #     add_setting(:foo, :default => "default value")
       #
-      # This sets the default value for the getter and the predicate (which
-      # will return +true+ as long as the value is not +false+ or +nil+).
+      # Use `:alias_with` to alias the setter, getter, and predicate to another
+      # name, or names:
       #
-      #   :alias => :other_setting
+      #     add_setting(:foo, :alias_with => :bar)
+      #     add_setting(:foo, :alias_with => [:bar, :baz])
       #
-      # Aliases its setter, getter, and predicate, to those for the
-      # +other_setting+.
       def add_setting(name, opts={})
-        self.class.add_setting(name, opts)
-      end
-
-      def puts(message)
-        output_stream.puts(message)
-      end
-
-      def settings
-        @settings ||= {}
-      end
-
-      def clear_inclusion_filter
-        self.inclusion_filter = nil
+        default = opts.delete(:default)
+        (class << self; self; end).class_eval do
+          add_setting(name, opts)
+        end
+        send("#{name}=", default) if default
       end
 
+      # Used by formatters to ask whether a backtrace line should be displayed
+      # or not, based on the line matching any `backtrace_clean_patterns`.
       def cleaned_from_backtrace?(line)
         backtrace_clean_patterns.any? { |regex| line =~ regex }
       end
 
       # Returns the configured mock framework adapter module
       def mock_framework
-        settings[:mock_framework] ||= begin
-                                        require 'rspec/core/mocking/with_rspec'
-                                        RSpec::Core::MockFrameworkAdapter
-                                      end
+        mock_with :rspec unless @mock_framework
+        @mock_framework
       end
 
       # Delegates to mock_framework=(framework)
-      def mock_with(framework)
-        self.mock_framework = framework
+      def mock_framework=(framework)
+        mock_with framework
       end
 
       # Sets the mock framework adapter module.
       #
-      # +framework+ can be a Symbol or a Module.
+      # `framework` can be a Symbol or a Module.
       #
       # Given any of :rspec, :mocha, :flexmock, or :rr, configures the named
       # framework.
@@ -164,11 +209,10 @@ module RSpec
       #
       #   teardown_mocks_for_rspec
       #     - called after verify_mocks_for_rspec (even if there are errors)
-      def mock_framework=(framework)
-        assert_no_example_groups_defined(:mock_framework)
-        case framework
+      def mock_with(framework)
+        framework_module = case framework
         when Module
-          settings[:mock_framework] = framework
+          framework
         when String, Symbol
           require case framework.to_s
                   when /rspec/i
@@ -182,72 +226,87 @@ module RSpec
                   else
                     'rspec/core/mocking/with_absolutely_nothing'
                   end
-          settings[:mock_framework] = RSpec::Core::MockFrameworkAdapter
-        else
+          RSpec::Core::MockFrameworkAdapter
+        end
+
+        new_name, old_name = [framework_module, @mock_framework].map do |mod|
+          mod.respond_to?(:framework_name) ?  mod.framework_name : :unnamed
+        end
+
+        unless new_name == old_name
+          assert_no_example_groups_defined(:mock_framework)
         end
+
+        @mock_framework = framework_module
       end
 
       # Returns the configured expectation framework adapter module(s)
       def expectation_frameworks
-        expect_with :rspec unless settings[:expectation_frameworks]
-        settings[:expectation_frameworks]
+        expect_with :rspec if @expectation_frameworks.empty?
+        @expectation_frameworks
       end
 
-      # Delegates to expect_with([framework])
+      # Delegates to expect_with(framework)
       def expectation_framework=(framework)
-        expect_with([framework])
+        expect_with(framework)
       end
 
       # Sets the expectation framework module(s).
       #
-      # +frameworks+ can be :rspec, :stdlib, or both 
+      # `frameworks` can be :rspec, :stdlib, or both
       #
       # Given :rspec, configures rspec/expectations.
       # Given :stdlib, configures test/unit/assertions
       # Given both, configures both
       def expect_with(*frameworks)
-        assert_no_example_groups_defined(:expect_with)
-        settings[:expectation_frameworks] = []
-        frameworks.each do |framework|
+        modules = frameworks.map do |framework|
           case framework
-          when Symbol
-            case framework
-            when :rspec
-              require 'rspec/core/expecting/with_rspec'
-              self.expecting_with_rspec = true
-            when :stdlib
-              require 'rspec/core/expecting/with_stdlib'
-            else
-              raise ArgumentError, "#{framework.inspect} is not supported"
-            end
-            settings[:expectation_frameworks] << RSpec::Core::ExpectationFrameworkAdapter
+          when :rspec
+            require 'rspec/expectations'
+            self.expecting_with_rspec = true
+            ::RSpec::Matchers
+          when :stdlib
+            require 'test/unit/assertions'
+            ::Test::Unit::Assertions
+          else
+            raise ArgumentError, "#{framework.inspect} is not supported"
           end
         end
-      end
 
-      def full_backtrace=(true_or_false)
-        settings[:backtrace_clean_patterns] = true_or_false ? [] : DEFAULT_BACKTRACE_PATTERNS
+        if (modules - @expectation_frameworks).any?
+          assert_no_example_groups_defined(:expect_with)
+        end
+
+        @expectation_frameworks.clear
+        @expectation_frameworks.push(*modules)
       end
 
-      def color_enabled
-        @color_enabled && output_to_tty?
+      def full_backtrace=(true_or_false)
+        @backtrace_clean_patterns = true_or_false ? [] : DEFAULT_BACKTRACE_PATTERNS
       end
 
-      def color_enabled?
-        color_enabled
+      def color
+        return false unless output_to_tty?
+        value_for(:color, @color)
       end
 
-      def color_enabled=(bool)
+      def color=(bool)
         return unless bool
-        @color_enabled = true
+        @color = true
         if bool && ::RbConfig::CONFIG['host_os'] =~ /mswin|mingw/
           unless ENV['ANSICON']
             warn "You must use ANSICON 1.31 or later (http://adoxa.110mb.com/ansicon/) to use colour on Windows"
-            @color_enabled = false
+            @color = false
           end
         end
       end
 
+      # TODO - deprecate color_enabled - probably not until the last 2.x
+      # release before 3.0
+      alias_method :color_enabled, :color
+      alias_method :color_enabled=, :color=
+      define_predicate_for :color_enabled, :color
+
       def libs=(libs)
         libs.map {|lib| $LOAD_PATH.unshift lib}
       end
@@ -277,24 +336,26 @@ EOM
         end
       end
 
-      # Run examples defined on +line_numbers+ in all files to run.
+      # Run examples defined on `line_numbers` in all files to run.
       def line_numbers=(line_numbers)
-        filter_run({ :line_numbers => line_numbers.map{|l| l.to_i} }, true)
-      end
-
-      def add_location(file_path, line_numbers)
-        # Filter locations is a hash of expanded paths to arrays of line numbers
-        # to match against.
-        #
-        filter_locations = ((self.filter || {})[:locations] ||= {})
-        (filter_locations[File.expand_path(file_path)] ||= []).push(*line_numbers)
-        filter_run({ :locations => filter_locations })
+        filter_run :line_numbers => line_numbers.map{|l| l.to_i}
       end
 
       def full_description=(description)
-        filter_run({ :full_description => /#{description}/ }, true)
+        filter_run :full_description => /#{description}/
       end
 
+      # @overload add_formatter(formatter)
+      #
+      # Adds a formatter to the formatters collection. `formatter` can be a
+      # string representing any of the built-in formatters (see
+      # `built_in_formatter`), or a custom formatter class.
+      #
+      # ### Note
+      #
+      # For internal purposes, `add_formatter` also accepts the name of a class
+      # and path to a file that contains that class definition, but you should
+      # consider that a private api that may change at any time without notice.
       def add_formatter(formatter_to_use, path=nil)
         formatter_class =
           built_in_formatter(formatter_to_use) ||
@@ -323,10 +384,12 @@ 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|
@@ -341,7 +404,7 @@ EOM
           else
             if file =~ /^(.*?)((?:\:\d+)+)$/
               path, lines = $1, $2[1..-1].split(":").map{|n| n.to_i}
-              add_location path, lines
+              filter_manager.add_location path, lines
               path
             else
               file
@@ -350,8 +413,27 @@ EOM
         end.flatten
       end
 
-      # E.g. alias_example_to :crazy_slow, :speed => 'crazy_slow' defines
-      # crazy_slow as an example variant that has the crazy_slow speed option
+      # Creates a method that delegates to `example` including the submitted
+      # `args`. Used internally to add variants of `example` like `pending`:
+      #
+      # @example
+      #     alias_example_to :pending, :pending => true
+      #
+      #     # This lets you do this:
+      #
+      #     describe Thing do
+      #       pending "does something" do
+      #         thing = Thing.new
+      #       end
+      #     end
+      #
+      #     # ... which is the equivalent of
+      #
+      #     describe Thing do
+      #       it "does something", :pending => true do
+      #         thing = Thing.new
+      #       end
+      #     end
       def alias_example_to(new_name, *args)
         extra_options = build_metadata_hash_from(args)
         RSpec::Core::ExampleGroup.alias_example_to(new_name, extra_options)
@@ -382,50 +464,82 @@ EOM
         RSpec::Core::ExampleGroup.alias_it_should_behave_like_to(new_name, report_label)
       end
 
-      undef_method :exclusion_filter=
-      def exclusion_filter=(filter)
-        settings[:exclusion_filter] = filter
+      # 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,
+      # each symbol is treated as a key in the hash with the value `true`.
+      #
+      # ### Note
+      #
+      # Filters set using this method can be overridden from the command line
+      # or config files (e.g. `.rspec`).
+      #
+      # @example
+      #     filter_run_including :x => 'y'
+      #
+      #     # 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)
       end
 
-      undef_method :exclusion_filter
-      def exclusion_filter
-        settings[:exclusion_filter] || {}
-      end
+      alias_method :filter_run, :filter_run_including
 
+      # Clears and reassigns the `inclusion_filter`. Set to `nil` if you don't
+      # want any inclusion filter at all.
+      #
+      # ### Warning
+      #
+      # This overrides any inclusion filters/tags set on the command line or in
+      # configuration files.
       def inclusion_filter=(filter)
-        settings[:inclusion_filter] = filter
+        filter_manager.include :replace, build_metadata_hash_from([filter])
       end
 
+      alias_method :filter=, :inclusion_filter=
+
+      # Returns the `inclusion_filter`. If none has been set, returns an empty
+      # hash.
       def inclusion_filter
-        settings[:inclusion_filter] || {}
+        filter_manager.inclusions
       end
 
-      def filter_run_including(*args)
-        force_overwrite = if args.last.is_a?(Hash) || args.last.is_a?(Symbol)
-          false
-        else
-          args.pop
-        end
-
-        options = build_metadata_hash_from(args)
+      alias_method :filter, :inclusion_filter
 
-        if inclusion_filter and inclusion_filter[:line_numbers] || inclusion_filter[:full_description]
-          warn "Filtering by #{options.inspect} is not possible since " \
-               "you are already filtering by #{inclusion_filter.inspect}"
-        else
-          if force_overwrite
-            self.inclusion_filter = options
-          else
-            self.inclusion_filter = (inclusion_filter || {}).merge(options)
-          end
-        end
+      # Adds key/value pairs to the `exclusion_filter`. If the
+      # `treat_symbols_as_metadata_keys_with_true_values` config option is set
+      # to true and `args` excludes any symbols that are not part of a hash,
+      # each symbol is treated as a key in the hash with the value `true`.
+      #
+      # ### Note
+      #
+      # Filters set using this method can be overridden from the command line
+      # or config files (e.g. `.rspec`).
+      #
+      # @example
+      #     filter_run_excluding :x => 'y'
+      #
+      #     # 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)
       end
 
-      alias_method :filter_run, :filter_run_including
+      # Clears and reassigns the `exclusion_filter`. Set to `nil` if you don't
+      # want any exclusion filter at all.
+      #
+      # ### Warning
+      #
+      # 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])
+      end
 
-      def filter_run_excluding(*args)
-        options = build_metadata_hash_from(args)
-        self.exclusion_filter = (exclusion_filter || {}).merge(options)
+      # Returns the `exclusion_filter`. If none has been set, returns an empty
+      # hash.
+      def exclusion_filter
+        filter_manager.exclusions
       end
 
       def include(mod, *args)
@@ -438,6 +552,10 @@ EOM
         include_or_extend_modules << [:extend, mod, filters]
       end
 
+      # @api private
+      #
+      # Used internally to extend a group with modules using `include` and/or
+      # `extend`.
       def configure_group(group)
         include_or_extend_modules.each do |include_or_extend, mod, filters|
           next unless filters.empty? || group.any_apply?(filters)
@@ -460,8 +578,35 @@ EOM
         raise_if_rspec_1_is_loaded
       end
 
+      attr_reader :seed
+
+      def seed=(seed)
+        @order = 'rand'
+        @seed = seed.to_i
+      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
+        end
+      end
+
     private
 
+      def value_for(key, default=nil)
+        @preferred_options.has_key?(key) ? @preferred_options[key] : default
+      end
+
       def assert_no_example_groups_defined(config_option)
         if RSpec.world.example_groups.any?
           raise MustBeConfiguredBeforeExampleGroupsError.new(
@@ -524,7 +669,7 @@ MESSAGE
           end
         end
       end
-      
+
       def string_const?(str)
         str.is_a?(String) && /\A[A-Z][a-zA-Z0-9_:]*\z/ =~ str
       end