Class RSpec::Core::Configuration
In: lib/rspec/core/configuration.rb
Parent: Object

Stores runtime configuration information.

@example Standard settings

    RSpec.configure do |c|
      c.drb          = true
      c.drb_port     = 1234
      c.default_path = 'behavior'
    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

Methods

Included Modules

RSpec::Core::Hooks

Classes and Modules

Class RSpec::Core::Configuration::MustBeConfiguredBeforeExampleGroupsError

Constants

DEFAULT_BACKTRACE_PATTERNS = [ /\/lib\d*\/ruby\//, /org\/jruby\//, /bin\//, /gems/, /spec\/spec_helper\.rb/, /lib\/rspec\/(core|expectations|matchers|mocks)/

Attributes

filter_manager  [RW]  @private

Public Class methods

@private

Invoked by the `add_setting` instance method. Use that method on a `Configuration` instance rather than this class method.

Public Instance methods

@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.

@overload add_setting(name) @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.

    RSpec.configuration.add_setting :foo

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

`add_setting` creates three methods on the configuration object, a setter, a getter, and a predicate:

    RSpec.configuration.foo=(value)
    RSpec.configuration.foo
    RSpec.configuration.foo? # returns true if foo returns anything but nil or false

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

Define an alias for it_should_behave_like that allows different language (like "it_has_behavior" or "it_behaves_like") to be employed when including shared examples.

Example:

    alias_it_behaves_like_to(:it_has_behavior, 'has behavior:')

allows the user to include a shared example group like:

    describe Entity do
      it_has_behavior 'sortability' do
        let(:sortable) { Entity.new }
      end
    end

which is reported in the output as:

    Entity
      has behavior: sortability
        # sortability examples here
alias_it_should_behave_like_to(new_name, report_label = '')

Used by formatters to ask whether a backtrace line should be displayed or not, based on the line matching any `backtrace_clean_patterns`.

color_enabled()

Alias for color

color_enabled=(bool)

Alias for color=

@private

Used internally to extend a group with modules using `include` and/or `extend`.

Returns the `exclusion_filter`. If none has been set, returns an empty hash.

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.

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

RSpec will translate `:rspec` and `:stdlib` into the appropriate modules.

## 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

Returns the configured expectation framework adapter module(s)

Tells RSpec to extend example groups with `mod`. Methods defined in `mod` are exposed to example groups (not examples). Use `filters` to constrain the groups to extend.

Similar to `include`, but behavior is added to example groups, which are classes, rather than the examples, which are instances of those classes.

@example

    module UiHelpers
      def run_in_browser
        # ...
      end
    end

    RSpec.configure do |config|
      config.extend(UiHelpers, :type => :request)
    end

    describe "edit profile", :type => :request do
      run_in_browser

      it "does stuff in the client" do
        # ...
      end
    end

@see include

filter()

Alias for inclusion_filter

filter=(filter)

Alias for inclusion_filter=

filter_run(*args)

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

    # given this declaration
    describe "something", :foo => 'bar' do
      # ...
    end

    # any of the following will exclude that group
    config.filter_run_excluding :foo => 'bar'
    config.filter_run_excluding :foo => /^ba/
    config.filter_run_excluding :foo => lambda {|v| v == 'bar'}
    config.filter_run_excluding :foo => lambda {|v,m| m[:foo] == 'bar'}

    # given a proc with an arity of 1, the lambda is passed the value related to the key, e.g.
    config.filter_run_excluding :foo => lambda {|v| v == 'bar'}

    # given a proc with an arity of 2, the lambda is passed the value related to the key,
    # and the metadata itself e.g.
    config.filter_run_excluding :foo => lambda {|v,m| m[:foo] == 'bar'}

    # with treat_symbols_as_metadata_keys_with_true_values = true
    filter_run_excluding :foo # same as filter_run_excluding :foo => true

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

    # given this declaration
    describe "something", :foo => 'bar' do
      # ...
    end

    # any of the following will include that group
    config.filter_run_including :foo => 'bar'
    config.filter_run_including :foo => /^ba/
    config.filter_run_including :foo => lambda {|v| v == 'bar'}
    config.filter_run_including :foo => lambda {|v,m| m[:foo] == 'bar'}

    # given a proc with an arity of 1, the lambda is passed the value related to the key, e.g.
    config.filter_run_including :foo => lambda {|v| v == 'bar'}

    # given a proc with an arity of 2, the lambda is passed the value related to the key,
    # and the metadata itself e.g.
    config.filter_run_including :foo => lambda {|v,m| m[:foo] == 'bar'}

    # with treat_symbols_as_metadata_keys_with_true_values = true
    filter_run_including :foo # same as filter_run_including :foo => true

@private

Used to set higher priority option values from the command line.

formatter=(formatter_to_use, path=nil)

Alias for add_formatter

Tells RSpec to include `mod` in example groups. Methods defined in `mod` are exposed to examples (not example groups). Use `filters` to constrain the groups in which to include the module.

@example

    module AuthenticationHelpers
      def login_as(user)
        # ...
      end
    end

    module UserHelpers
      def users(username)
        # ...
      end
    end

    RSpec.configure do |config|
      config.include(UserHelpers) # included in all modules
      config.include(AuthenticationHelpers, :type => :request)
    end

    describe "edit profile", :type => :request do
      it "can be viewed by owning user" do
        login_as users(:jdoe)
        get "/profiles/jdoe"
        assert_select ".username", :text => 'jdoe'
      end
    end

@see extend

Returns the `inclusion_filter`. If none has been set, returns an empty hash.

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.

Run examples defined on `line_numbers` in all files to run.

Returns the configured mock framework adapter module

Sets the mock framework adapter module.

`framework` can be a Symbol or a Module.

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 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

    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)

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

@api

Sets the order and, if order is `’rand:<seed>’`, also sets the seed.

@private

@api

Sets the seed value and sets `order=‘rand’`

[Validate]