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

Stores runtime configuration information.

Configuration options are loaded from `~/.rspec`, `.rspec`, `.rspec-local`, command line switches, and the `SPEC_OPTS` environment variable (listed in lowest to highest precedence; for example, an option in `~/.rspec` can be overridden by an option in `.rspec-local`).

@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

add_formatter   add_setting   add_setting   alias_example_to   alias_it_behaves_like_to   alias_it_should_behave_like_to   backtrace_clean_patterns   backtrace_clean_patterns=   backtrace_exclusion_patterns   backtrace_exclusion_patterns=   backtrace_inclusion_patterns   backtrace_inclusion_patterns=   color   color=   color_enabled   color_enabled=   configure_expectation_framework   configure_group   configure_mock_framework   debug=   debug?   define_aliases   define_predicate_for   define_reader   deprecate_alias_key   exclusion_filter   exclusion_filter=   expect_with   expectation_framework=   expectation_frameworks   extend   files_or_directories_to_run=   filter   filter=   filter_run   filter_run_excluding   filter_run_including   force   format_docstrings   format_docstrings_block   formatter=   formatters   full_backtrace=   full_backtrace?   full_description   full_description=   include   inclusion_filter   inclusion_filter=   libs=   line_numbers   line_numbers=   load_spec_files   mock_framework   mock_framework=   mock_with   new   order=   profile_examples   randomize?   reporter   requires=   reset   safe_extend   safe_extend   safe_include   seed=   setup_load_path_and_require  

Included Modules

RSpec::Core::Hooks

Classes and Modules

Class RSpec::Core::Configuration::MustBeConfiguredBeforeExampleGroupsError

Constants

DEFAULT_FORMATTER = lambda { |string| string }   @private
DEFAULT_ORDERING = lambda { |list| list }   @private
RANDOM_ORDERING = lambda do |list| Kernel.srand RSpec.configuration.seed   @private

Attributes

backtrace_cleaner  [R] 
filter_manager  [RW]  @private

Public Class methods

add_setting(name, opts={})

@private

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

Public Instance methods

add_formatter(formatter_to_use, *paths)

@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 paths to use for output streams, but you should consider that a private api that may change at any time without notice.

add_setting(name, opts={})

@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
alias_example_to(new_name, *args)

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
alias_it_behaves_like_to(new_name, report_label = '')

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 = '')

Alias for alias_it_behaves_like_to

backtrace_clean_patterns()

The patterns to discard from backtraces. Deprecated, use Configuration#backtrace_exclusion_patterns instead

Defaults to RSpec::Core::BacktraceCleaner::DEFAULT_EXCLUSION_PATTERNS

One can replace the list by using the setter or modify it through the getter

To override this behaviour 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.

backtrace_exclusion_patterns()

The patterns to discard from backtraces.

Defaults to RSpec::Core::BacktraceCleaner::DEFAULT_EXCLUSION_PATTERNS

One can replace the list by using the setter or modify it through the getter

To override this behaviour 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.

backtrace_inclusion_patterns()

The patterns to always include to backtraces.

Defaults to [Regexp.new Dir.getwd] if the current working directory matches any of the exclusion patterns. Otherwise it defaults to empty.

One can replace the list by using the setter or modify it through the getter

color_enabled(output=output_stream)

Alias for color

color_enabled=(bool)

Alias for color=

configure_group(group)

@private

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

exclusion_filter()

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

exclusion_filter=(filter)

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.

expect_with(*frameworks) {|modules.first.configuration| ...}

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
expectation_frameworks()

Returns the configured expectation framework adapter module(s)

extend(mod, *filters)

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)

Alias for filter_run_including

filter_run_excluding(*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
filter_run_including(*args)

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
force(hash)

@private

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

format_docstrings(&block)

Formats the docstring output using the block provided.

@example 

  # This will strip the descriptions of both examples and example groups.
  RSpec.configure do |config|
    config.format_docstrings { |s| s.strip }
  end
formatter=(formatter_to_use, *paths)

Alias for add_formatter

include(mod, *filters)

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

inclusion_filter()

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

inclusion_filter=(filter)

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.

line_numbers=(line_numbers)

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

mock_framework()

Returns the configured mock framework adapter module

mock_with(framework) {|framework_module.configuration| ...}

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
order=(type)

@api

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

profile_examples()

@api private

Defaults `profile_examples` to 10 examples when `@profile_examples` is `true`.

reset()

@private

seed=(seed)

@api

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

[Validate]