class RSpec::Core::Configuration

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(:example) { log_in_as :authorized }
  c.around(:example) { |ex| Database.transaction(&ex) }
end

@see RSpec.configure @see Hooks

Constants

DEFAULT_FORMATTER

@private

MOCKING_ADAPTERS

@private

Attributes

backtrace_formatter[R]

@private

disable_monkey_patching[RW]

@private

files_to_run[W]

@private

filter_manager[RW]

@private

ordering_manager[R]

@private

Public Class Methods

add_read_only_setting(name, opts={}) click to toggle source

@private

As `add_setting` but only add the reader

# File lib/rspec/core/configuration.rb, line 75
def self.add_read_only_setting(name, opts={})
  raise "Use the instance add_setting method if you want to set a default" if opts.has_key?(:default)
  define_reader name
  define_predicate_for name
end
add_setting(name, opts={}) click to toggle source

@private

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

# File lib/rspec/core/configuration.rb, line 62
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)
  attr_writer name
  add_read_only_setting name

  Array(opts[:alias_with]).each do |alias_name|
    define_aliases(name, alias_name)
  end
end
define_aliases(name, alias_name) click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 47
def self.define_aliases(name, alias_name)
  alias_method alias_name, name
  alias_method "#{alias_name}=", "#{name}="
  define_predicate_for alias_name
end
define_predicate_for(*names) click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 54
def self.define_predicate_for(*names)
  names.each {|name| alias_method "#{name}?", name}
end
define_reader(name) click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 39
def self.define_reader(name)
  define_method(name) do
    variable = instance_variable_defined?("@#{name}") ? instance_variable_get("@#{name}") : nil
    value_for(name, variable)
  end
end
delegate_to_ordering_manager(*methods) click to toggle source

@private @macro [attach] ::delegate_to_ordering_manager

@!method $1
# File lib/rspec/core/configuration.rb, line 1077
def self.delegate_to_ordering_manager(*methods)
  methods.each do |method|
    define_method method do |*args, &block|
      ordering_manager.__send__(method, *args, &block)
    end
  end
end
new() click to toggle source
# File lib/rspec/core/configuration.rb, line 274
def initialize
  @start_time = $_rspec_core_load_started_at || ::RSpec::Core::Time.now
  @expectation_frameworks = []
  @include_or_extend_modules = []
  @mock_framework = nil
  @files_or_directories_to_run = []
  @color = false
  @pattern = '**/*_spec.rb'
  @failure_exit_code = 1
  @spec_files_loaded = false

  @backtrace_formatter = BacktraceFormatter.new

  @default_path = 'spec'
  @deprecation_stream = $stderr
  @output_stream = $stdout
  @reporter = nil
  @reporter_buffer = nil
  @filter_manager = FilterManager.new
  @ordering_manager = Ordering::ConfigurationManager.new
  @preferred_options = {}
  @failure_color = :red
  @success_color = :green
  @pending_color = :yellow
  @default_color = :white
  @fixed_color = :blue
  @detail_color = :cyan
  @profile_examples = false
  @requires = []
  @libs = []
  @derived_metadata_blocks = []
end

Public Instance Methods

add_formatter(formatter_to_use, *paths) click to toggle source

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

# File lib/rspec/core/configuration.rb, line 622
def add_formatter(formatter_to_use, *paths)
  paths << output_stream if paths.empty?
  formatter_loader.add formatter_to_use, *paths
end
Also aliased as: formatter=
add_setting(name, opts={}) click to toggle source

@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 %x: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
# File lib/rspec/core/configuration.rb, line 357
def add_setting(name, opts={})
  default = opts.delete(:default)
  (class << self; self; end).class_exec do
    add_setting(name, opts)
  end
  __send__("#{name}=", default) if default
end
alias_example_group_to(new_name, *args) click to toggle source

Creates a method that defines an example group with the provided metadata. Can be used to define example group/metadata shortcuts.

@example

RSpec.configure do |config|
  config.alias_example_group_to :describe_model, :type => :model
end

shared_context_for "model tests", :type => :model do
  # define common model test helper methods, `let` declarations, etc
end

# This lets you do this:

RSpec.describe_model User do
end

# ... which is the equivalent of

RSpec.describe User, :type => :model do
end

@note The defined aliased will also be added to the top level

(e.g. `main` and from within modules) if
`expose_dsl_globally` is set to true.

@see alias_example_to @see expose_dsl_globally=

# File lib/rspec/core/configuration.rb, line 787
def alias_example_group_to(new_name, *args)
  extra_options = Metadata.build_hash_from(args)
  RSpec::Core::ExampleGroup.define_example_group_method(new_name, extra_options)
end
alias_example_to(name, *args) click to toggle source

Creates a method that delegates to `example` including the submitted `args`. Used internally to add variants of `example` like `pending`: @param name [String] example name alias @param args [Array<Symbol>, Hash] metadata for the generated example

@note The specific example alias below (`pending`) is already

defined for you.

@note Use with caution. This extends the language used in your

specs, but does not add any additional documentation.  We use this
in rspec to define methods like `focus` and `xit`, but we also add
docs for those methods.

@example

RSpec.configure do |config|
  config.alias_example_to :pending, :pending => true
end

# 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
# File lib/rspec/core/configuration.rb, line 755
def alias_example_to(name, *args)
  extra_options = Metadata.build_hash_from(args)
  RSpec::Core::ExampleGroup.define_example_method(name, extra_options)
end
alias_it_behaves_like_to(new_name, report_label = '') click to toggle source

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

RSpec.configure do |config|
  config.alias_it_behaves_like_to(:it_has_behavior, 'has behavior:')
end

# 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

@note Use with caution. This extends the language used in your

specs, but does not add any additional documentation.  We use this
in rspec to define `it_should_behave_like` (for backward
compatibility), but we also add docs for that method.
# File lib/rspec/core/configuration.rb, line 818
def alias_it_behaves_like_to(new_name, report_label = '')
  RSpec::Core::ExampleGroup.define_nested_shared_group_method(new_name, report_label)
end
alias_it_should_behave_like_to(new_name, report_label = '')
apply_derived_metadata_to(metadata) click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 1262
def apply_derived_metadata_to(metadata)
  @derived_metadata_blocks.each do |filter, block|
    block.call(metadata) if filter.empty? || MetadataFilter.any_apply?(filter, metadata)
  end
end
backtrace_exclusion_patterns() click to toggle source

Regexps used to exclude lines from backtraces.

Excludes lines from ruby (and jruby) source, installed gems, anything in any “bin” directory, and any of the rspec libs (outside gem installs) by default.

You can modify the list via the getter, or replace it with the setter.

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.

# File lib/rspec/core/configuration.rb, line 387
def backtrace_exclusion_patterns
  @backtrace_formatter.exclusion_patterns
end
backtrace_exclusion_patterns=(patterns) click to toggle source

Set regular expressions used to exclude lines in backtrace @param patterns [Regexp] set the backtrace exlusion pattern

# File lib/rspec/core/configuration.rb, line 393
def backtrace_exclusion_patterns=(patterns)
  @backtrace_formatter.exclusion_patterns = patterns
end
backtrace_inclusion_patterns() click to toggle source

Regexps used to include lines in backtraces.

Defaults to [Regexp.new Dir.getwd].

Lines that match an exclusion and an inclusion pattern will be included.

You can modify the list via the getter, or replace it with the setter.

# File lib/rspec/core/configuration.rb, line 405
def backtrace_inclusion_patterns
  @backtrace_formatter.inclusion_patterns
end
backtrace_inclusion_patterns=(patterns) click to toggle source

Set regular expressions used to include lines in backtrace @attr patterns [Regexp] set #backtrace_formatter inclusion_patterns

# File lib/rspec/core/configuration.rb, line 411
def backtrace_inclusion_patterns=(patterns)
  @backtrace_formatter.inclusion_patterns = patterns
end
color() click to toggle source

Returns the configuration option for color, but should not be used to check if color is supported.

@see color_enabled? @return [Boolean]

# File lib/rspec/core/configuration.rb, line 567
def color
  value_for(:color, @color)
end
color=(true_or_false) click to toggle source

Toggle output color @attr true_or_false [Boolean] toggle color enabled

# File lib/rspec/core/configuration.rb, line 581
def color=(true_or_false)
  if true_or_false
    if RSpec.world.windows_os? and not ENV['ANSICON']
      RSpec.warning "You must use ANSICON 1.31 or later (http://adoxa.3eeweb.com/ansicon/) to use colour on Windows"
      @color = false
    else
      @color = true
    end
  end
end
color_enabled?(output = output_stream) click to toggle source

Check if color is enabled for a particular output @param output [IO] an output stream to use, defaults to the current

`output_stream`

@return [Boolean]

# File lib/rspec/core/configuration.rb, line 575
def color_enabled?(output = output_stream)
  output_to_tty?(output) && color
end
configure_expectation_framework() click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 1042
def configure_expectation_framework
  expectation_frameworks.each do |framework|
    RSpec::Core::ExampleGroup.__send__(:include, framework)
  end
  conditionally_disable_expectations_monkey_patching
end
configure_group(group) click to toggle source

@private

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

# File lib/rspec/core/configuration.rb, line 1002
def configure_group(group)
  include_or_extend_modules.each do |include_or_extend, mod, filters|
    next unless filters.empty? || group.any_apply?(filters)
    __send__("safe_#{include_or_extend}", mod, group)
  end
end
configure_mock_framework() click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 1036
def configure_mock_framework
  RSpec::Core::ExampleGroup.__send__(:include, mock_framework)
  conditionally_disable_mocks_monkey_patching
end
default_formatter() click to toggle source

The formatter that will be used if no formatter has been set. Defaults to 'progress'.

# File lib/rspec/core/configuration.rb, line 630
def default_formatter
  formatter_loader.default_formatter
end
default_formatter=(value) click to toggle source

Sets a fallback formatter to use if none other has been set.

@example

RSpec.configure do |rspec|
  rspec.default_formatter = 'doc'
end
# File lib/rspec/core/configuration.rb, line 641
def default_formatter=(value)
  formatter_loader.default_formatter = value
end
define_derived_metadata(*filters, &block) click to toggle source

Defines a callback that can assign derived metadata values.

@param filters [Array<Symbol>, Hash] metadata filters that determine which example

or group metadata hashes the callback will be triggered for. If none are given,
the callback will be run against the metadata hashes of all groups and examples.

@yieldparam metadata [Hash] original metadata hash from an example or group. Mutate this in

your block as needed.

@example

RSpec.configure do |config|
  # Tag all groups and examples in the spec/unit directory with :type => :unit
  config.define_derived_metadata(:file_path => %r{/spec/unit/}) do |metadata|
    metadata[:type] = :unit
  end
end
# File lib/rspec/core/configuration.rb, line 1257
def define_derived_metadata(*filters, &block)
  @derived_metadata_blocks << [Metadata.build_hash_from(filters), block]
end
deprecation_stream=(value) click to toggle source

Determines where deprecation warnings are printed. @param value [IO, String] IO to write to or filename to write to

# File lib/rspec/core/configuration.rb, line 134
def deprecation_stream=(value)
  if @reporter && !value.equal?(@deprecation_stream)
    warn "RSpec's reporter has already been initialized with " +
      "#{deprecation_stream.inspect} as the deprecation stream, so your change to "+
      "`deprecation_stream` will be ignored. You should configure it earlier for " +
      "it to take effect, or use the `--deprecation-out` CLI option. " +
      "(Called from #{CallerFilter.first_non_rspec_line})"
  else
    @deprecation_stream = value
  end
end
disable_monkey_patching!() click to toggle source

Enables zero monkey patching mode for RSpec. It removes monkey patching of the top-level DSL methods (`describe`, `shared_examples_for`, etc) onto `main` and `Module`, instead requiring you to prefix these methods with `RSpec.`. It enables expect-only syntax for rspec-mocks and rspec-expectations. It simply disables monkey patching on whatever pieces of rspec the user is using.

@note It configures rspec-mocks and rspec-expectations only

if the user is using those (either explicitly or implicitly
by not setting `mock_with` or `expect_with` to anything else).

@note If the user uses this options with `mock_with :mocha`

(or similiar) they will still have monkey patching active
in their test environment from mocha.

@example

# It disables all monkey patching
RSpec.configure do |config|
  config.disable_monkey_patching!
end

# Is an equivalent to
RSpec.configure do |config|
  config.expose_dsl_globally = false

  config.mock_with :rspec do |mocks|
    mocks.syntax = :expect
    mocks.patch_marshal_to_support_partial_doubles = false
  end

  config.mock_with :rspec do |expectations|
    expectations.syntax = :expect
  end
end
# File lib/rspec/core/configuration.rb, line 1232
def disable_monkey_patching!
  self.expose_dsl_globally = false
  self.disable_monkey_patching = true
  conditionally_disable_mocks_monkey_patching
  conditionally_disable_expectations_monkey_patching
end
exclusion_filter() click to toggle source

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

# File lib/rspec/core/configuration.rb, line 925
def exclusion_filter
  filter_manager.exclusions
end
exclusion_filter=(filter) click to toggle source

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.

# File lib/rspec/core/configuration.rb, line 919
def exclusion_filter=(filter)
  filter_manager.exclude_only Metadata.build_hash_from([filter])
end
expect_with(*frameworks) { |first.configuration| ... } click to toggle source

Sets the expectation framework module(s) to be included in each example group.

`frameworks` can be `:rspec`, `:test_unit`, `:minitest`, a custom module, or any combination thereof:

config.expect_with :rspec
config.expect_with :test_unit
config.expect_with :minitest
config.expect_with :rspec, :minitest
config.expect_with OtherExpectationFramework

RSpec will translate `:rspec`, `:minitest`, and `:test_unit` 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
# File lib/rspec/core/configuration.rb, line 517
def expect_with(*frameworks)
  modules = frameworks.map do |framework|
    case framework
    when Module
      framework
    when :rspec
      require 'rspec/expectations'
      self.expecting_with_rspec = true
      ::RSpec::Matchers
    when :test_unit
      require 'rspec/core/test_unit_assertions_adapter'
      ::RSpec::Core::TestUnitAssertionsAdapter
    when :minitest
      require 'rspec/core/minitest_assertions_adapter'
      ::RSpec::Core::MinitestAssertionsAdapter
    else
      raise ArgumentError, "#{framework.inspect} is not supported"
    end
  end

  if (modules - @expectation_frameworks).any?
    assert_no_example_groups_defined(:expect_with)
  end

  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
expectation_framework=(framework) click to toggle source

Delegates to #expect_with(framework)

# File lib/rspec/core/configuration.rb, line 490
def expectation_framework=(framework)
  expect_with(framework)
end
expectation_frameworks() click to toggle source

Returns the configured expectation framework adapter module(s)

# File lib/rspec/core/configuration.rb, line 484
def expectation_frameworks
  expect_with :rspec if @expectation_frameworks.empty?
  @expectation_frameworks
end
expose_current_running_example_as(method_name) click to toggle source

Exposes the current running example via the named helper method. RSpec 2.x exposed this via `example`, but in RSpec 3.0, the example is instead exposed via an arg yielded to `it`, `before`, `let`, etc. However, some extension gems (such as Capybara) depend on the RSpec 2.x's `example` method, so this config option can be used to maintain compatibility.

@param method_name [Symbol] the name of the helper method

@example

RSpec.configure do |rspec|
  rspec.expose_current_running_example_as :example
end

describe MyClass do
  before do
    # `example` can be used here because of the above config.
    do_something if example.metadata[:type] == "foo"
  end
end
# File lib/rspec/core/configuration.rb, line 1170
def expose_current_running_example_as(method_name)
  ExposeCurrentExample.module_exec do
    extend RSpec::SharedContext
    let(method_name) { |ex| ex }
  end

  include ExposeCurrentExample
end
expose_dsl_globally=(value) click to toggle source

Use this to expose the core RSpec DSL via `Module` and the `main` object. It will be set automatically but you can override it to remove the DSL. Default: true

# File lib/rspec/core/configuration.rb, line 117
def expose_dsl_globally=(value)
  if value
    Core::DSL.expose_globally!
    Core::SharedExampleGroup::TopLevelDSL.expose_globally!
  else
    Core::DSL.remove_globally!
    Core::SharedExampleGroup::TopLevelDSL.remove_globally!
  end
end
expose_dsl_globally?() click to toggle source

Indicates if the DSL has been exposed off of modules and `main`. Default: true

# File lib/rspec/core/configuration.rb, line 109
def expose_dsl_globally?
  Core::DSL.exposed_globally?
end
extend(mod, *filters) click to toggle source

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

# File lib/rspec/core/configuration.rb, line 994
def extend(mod, *filters)
  include_or_extend_modules << [:extend, mod, Metadata.build_hash_from(filters)]
end
files_or_directories_to_run=(*files) click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 710
def files_or_directories_to_run=(*files)
  files = files.flatten
  files << default_path if (command == 'rspec' || Runner.running_in_drb?) && default_path && files.empty?
  @files_or_directories_to_run = files
  @files_to_run = nil
end
files_to_run() click to toggle source

The spec files RSpec will run @return [Array] specified files about to run

# File lib/rspec/core/configuration.rb, line 719
def files_to_run
  @files_to_run ||= get_files_to_run(@files_or_directories_to_run)
end
filter()
Alias for: inclusion_filter
filter=(filter)
Alias for: inclusion_filter=
filter_run(*args)
filter_run_excluding(*args) click to toggle source

Adds key/value pairs to the `exclusion_filter`. If `args` includes any symbols that are not part of the 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'}

filter_run_excluding :foo # same as filter_run_excluding :foo => true
# File lib/rspec/core/configuration.rb, line 908
def filter_run_excluding(*args)
  filter_manager.exclude_with_low_priority Metadata.build_hash_from(args)
end
filter_run_including(*args) click to toggle source

Adds key/value pairs to the `inclusion_filter`. If `args` includes any symbols that are not part of the 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'}

filter_run_including :foo # same as filter_run_including :foo => true
# File lib/rspec/core/configuration.rb, line 852
def filter_run_including(*args)
  filter_manager.include_with_low_priority Metadata.build_hash_from(args)
end
Also aliased as: filter_run
force(hash) click to toggle source

@private

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

# File lib/rspec/core/configuration.rb, line 310
def force(hash)
  ordering_manager.force(hash)
  @preferred_options.merge!(hash)
end
format_docstrings(&block) click to toggle source

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
# File lib/rspec/core/configuration.rb, line 1065
def format_docstrings(&block)
  @format_docstrings_block = block_given? ? block : DEFAULT_FORMATTER
end
format_docstrings_block() click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 1070
def format_docstrings_block
  @format_docstrings_block ||= DEFAULT_FORMATTER
end
formatter=(formatter_to_use, *paths)
Alias for: add_formatter
formatter_loader() click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 656
def formatter_loader
  @formatter_loader ||= Formatters::Loader.new(Reporter.new(self))
end
formatters() click to toggle source

Returns a duplicate of the formatters currently loaded in the `FormatterLoader` for introspection.

Note as this is a duplicate, any mutations will be disregarded.

@return [Array] the formatters currently loaded

# File lib/rspec/core/configuration.rb, line 651
def formatters
  formatter_loader.formatters.dup
end
full_backtrace=(true_or_false) click to toggle source

Toggle full backtrace @attr true_or_false [Boolean] toggle full backtrace display

# File lib/rspec/core/configuration.rb, line 558
def full_backtrace=(true_or_false)
  @backtrace_formatter.full_backtrace = true_or_false
end
full_backtrace?() click to toggle source

Check if full backtrace is enabled @return [Boolean] is full backtrace enabled

# File lib/rspec/core/configuration.rb, line 552
def full_backtrace?
  @backtrace_formatter.full_backtrace?
end
full_description() click to toggle source

@return [Array] full description filter

# File lib/rspec/core/configuration.rb, line 607
def full_description
  filter.fetch :full_description, nil
end
full_description=(description) click to toggle source

Run examples matching on `description` in all files to run. @param description [String, Regexp] the pattern to filter on

# File lib/rspec/core/configuration.rb, line 602
def full_description=(description)
  filter_run :full_description => Regexp.union(*Array(description).map {|d| Regexp.new(d) })
end
include(mod, *filters) click to toggle source

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

# File lib/rspec/core/configuration.rb, line 961
def include(mod, *filters)
  include_or_extend_modules << [:include, mod, Metadata.build_hash_from(filters)]
end
inclusion_filter() click to toggle source

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

# File lib/rspec/core/configuration.rb, line 873
def inclusion_filter
  filter_manager.inclusions
end
Also aliased as: filter
inclusion_filter=(filter) click to toggle source

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.

# File lib/rspec/core/configuration.rb, line 865
def inclusion_filter=(filter)
  filter_manager.include_only Metadata.build_hash_from([filter])
end
Also aliased as: filter=
libs=(libs) click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 593
def libs=(libs)
  libs.map do |lib|
    @libs.unshift lib
    $LOAD_PATH.unshift lib
  end
end
load_spec_files() click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 1050
def load_spec_files
  files_to_run.uniq.each {|f| load File.expand_path(f) }
  @spec_files_loaded = true
end
mock_framework() click to toggle source

Returns the configured mock framework adapter module

# File lib/rspec/core/configuration.rb, line 366
def mock_framework
  mock_with :rspec unless @mock_framework
  @mock_framework
end
mock_framework=(framework) click to toggle source

Delegates to #mock_framework=(framework)

# File lib/rspec/core/configuration.rb, line 372
def mock_framework=(framework)
  mock_with framework
end
mock_with(framework) { |configuration| ... } click to toggle source

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 if the example hasn't yet failed.
    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
# File lib/rspec/core/configuration.rb, line 453
def mock_with(framework)
  framework_module = if framework.is_a?(Module)
     framework
  else
    const_name = MOCKING_ADAPTERS.fetch(framework) do
      raise ArgumentError,
        "Unknown mocking framework: #{framework.inspect}. " +
        "Pass a module or one of #{MOCKING_ADAPTERS.keys.inspect}"
    end

    RSpec::Support.require_rspec_core "mocking_adapters/#{const_name.to_s.downcase}"
    RSpec::Core::MockingAdapters.const_get(const_name)
  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

  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
output_stream=(value) click to toggle source

Set the output stream for reporter @attr value [IO] value for output, defaults to $stdout

# File lib/rspec/core/configuration.rb, line 174
def output_stream=(value)
  if @reporter && !value.equal?(@output_stream)
    warn "RSpec's reporter has already been initialized with " +
      "#{output_stream.inspect} as the output stream, so your change to "+
      "`output_stream` will be ignored. You should configure it earlier for " +
      "it to take effect. (Called from #{CallerFilter.first_non_rspec_line})"
  else
    @output_stream = value
  end
end
pattern=(value) click to toggle source

Set pattern to match files to load @attr value [String] the filename pattern to filter spec files by

# File lib/rspec/core/configuration.rb, line 191
def pattern=(value)
  if @spec_files_loaded
    RSpec.warning "Configuring `pattern` to #{value} has no effect since RSpec has already loaded the spec files."
  end
  @pattern = value
end
profile_examples() click to toggle source

@api private

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

# File lib/rspec/core/configuration.rb, line 700
def profile_examples
  profile = value_for(:profile_examples, @profile_examples)
  if profile && !profile.is_a?(Integer)
    10
  else
    profile
  end
end
raise_errors_for_deprecations!() click to toggle source

Turns deprecation warnings into errors, in order to surface the full backtrace of the call site. This can be useful when you need more context to address a deprecation than the single-line call site normally provided.

@example

RSpec.configure do |rspec|
  rspec.raise_errors_for_deprecations!
end
# File lib/rspec/core/configuration.rb, line 1192
def raise_errors_for_deprecations!
  self.deprecation_stream = Formatters::DeprecationFormatter::RaiseErrorStream.new
end
reporter() click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 683
def reporter
  # @reporter_buffer should only ever be set in this method to cover
  # initialization of @reporter.
  @reporter_buffer || @reporter ||=
    begin
      @reporter_buffer = DeprecationReporterBuffer.new
      formatter_loader.setup_default output_stream, deprecation_stream
      @reporter_buffer.play_onto(formatter_loader.reporter)
      @reporter_buffer = nil
      formatter_loader.reporter
    end
end
requires=(paths) click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 1015
def requires=(paths)
  directories = ['lib', default_path].select { |p| File.directory? p }
  RSpec::Core::RubyProject.add_to_load_path(*directories)
  paths.each {|path| require path}
  @requires += paths
end
reset() click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 316
def reset
  @spec_files_loaded = false
  @reporter = nil
  @formatter_loader = nil
end
safe_extend(mod, host) click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 1025
def safe_extend(mod, host)
  host.extend(mod) unless host.singleton_class < mod
end
safe_include(mod, host) click to toggle source

@private

# File lib/rspec/core/configuration.rb, line 1010
def safe_include(mod, host)
  host.__send__(:include, mod) unless host < mod
end
treat_symbols_as_metadata_keys_with_true_values=(value) click to toggle source

Deprecated. This config option was added in RSpec 2 to pave the way for this being the default behavior in RSpec 3. Now this option is a no-op.

# File lib/rspec/core/configuration.rb, line 252
def treat_symbols_as_metadata_keys_with_true_values=(value)
  RSpec.deprecate("RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values=",
                  :message => "RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values= " +
                              "is deprecated, it is now set to true as default and setting it to false has no effect.")
end
warnings=(value) click to toggle source

Set Ruby warnings on or off

# File lib/rspec/core/configuration.rb, line 1139
def warnings=(value)
  $VERBOSE = !!value
end
warnings?() click to toggle source

@return [Boolean] Whether or not ruby warnings are enabled.

# File lib/rspec/core/configuration.rb, line 1144
def warnings?
  $VERBOSE
end

Private Instance Methods

assert_no_example_groups_defined(config_option) click to toggle source
# File lib/rspec/core/configuration.rb, line 1299
def assert_no_example_groups_defined(config_option)
  if RSpec.world.example_groups.any?
    raise MustBeConfiguredBeforeExampleGroupsError.new(
      "RSpec's #{config_option} configuration option must be configured before " +
      "any example groups are defined, but you have already defined a group."
    )
  end
end
command() click to toggle source
# File lib/rspec/core/configuration.rb, line 1291
def command
  $0.split(File::SEPARATOR).last
end
conditionally_disable_expectations_monkey_patching() click to toggle source
# File lib/rspec/core/configuration.rb, line 1321
def conditionally_disable_expectations_monkey_patching
  return unless disable_monkey_patching && rspec_expectations_loaded?

  RSpec::Expectations.configuration.syntax = :expect
end
conditionally_disable_mocks_monkey_patching() click to toggle source
# File lib/rspec/core/configuration.rb, line 1312
def conditionally_disable_mocks_monkey_patching
  return unless disable_monkey_patching && rspec_mocks_loaded?

  RSpec::Mocks.configuration.tap do |config|
    config.syntax = :expect
    config.patch_marshal_to_support_partial_doubles = false
  end
end
extract_location(path) click to toggle source
# File lib/rspec/core/configuration.rb, line 1283
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
gather_directories(path) click to toggle source
# File lib/rspec/core/configuration.rb, line 1277
def gather_directories(path)
  stripped = "{#{pattern.gsub(/\s*,\s*/, ',')}}"
  files    = pattern =~ /^#{Regexp.escape path}/ ? Dir[stripped] : Dir["#{path}/#{stripped}"]
  files.sort
end
get_files_to_run(paths) click to toggle source
# File lib/rspec/core/configuration.rb, line 1270
def get_files_to_run(paths)
  FlatMap.flat_map(paths) do |path|
    path = path.gsub(File::ALT_SEPARATOR, File::SEPARATOR) if File::ALT_SEPARATOR
    File.directory?(path) ? gather_directories(path) : extract_location(path)
  end.sort
end
output_to_tty?(output=output_stream) click to toggle source
# File lib/rspec/core/configuration.rb, line 1308
def output_to_tty?(output=output_stream)
  tty? || (output.respond_to?(:tty?) && output.tty?)
end
rspec_expectations_loaded?() click to toggle source
# File lib/rspec/core/configuration.rb, line 1331
def rspec_expectations_loaded?
  defined?(RSpec::Expectations.configuration)
end
rspec_mocks_loaded?() click to toggle source
# File lib/rspec/core/configuration.rb, line 1327
def rspec_mocks_loaded?
  defined?(RSpec::Mocks.configuration)
end
value_for(key, default=nil) click to toggle source
# File lib/rspec/core/configuration.rb, line 1295
def value_for(key, default=nil)
  @preferred_options.has_key?(key) ? @preferred_options[key] : default
end