Class: RSpec::Core::Configuration

Inherits:
Object
  • Object
show all
Includes:
Module.new, Hooks
Defined in:
lib/rspec/core/configuration.rb

Overview

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`).

Examples:

Standard settings

RSpec.configure do |c|
  c.drb          = true
  c.drb_port     = 1234
  c.default_path = 'behavior'
end

Hooks

RSpec.configure do |c|
  c.before(:suite)   { establish_connection }
  c.before(:example) {  :authorized }
  c.around(:example) { |ex| Database.transaction(&ex) }
end

See Also:

Defined Under Namespace

Modules: ExposeCurrentExample Classes: DeprecationReporterBuffer, MustBeConfiguredBeforeExampleGroupsError

Constant Summary collapse

Readers =

Module that holds `attr_reader` declarations. It's in a separate module to allow us to override those methods and use `super`.

Module.new
MOCKING_ADAPTERS =
{
  :rspec    => :RSpec,
  :flexmock => :Flexmock,
  :rr       => :RR,
  :mocha    => :Mocha,
  :nothing  => :Null
}
UNKNOWN_STATUS =
"unknown".freeze
FAILED_STATUS =
"failed".freeze
PASSED_STATUS =
"passed".freeze
PENDING_STATUS =
"pending".freeze
VALID_STATUSES =
[UNKNOWN_STATUS, FAILED_STATUS, PASSED_STATUS, PENDING_STATUS]
DEFAULT_FORMATTER =
lambda { |string| string }
RAISE_ERROR_WARNING_NOTIFIER =
lambda { |message| raise message }

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initializeConfiguration

Build an object to store runtime configuration options and set defaults



431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
# File 'lib/rspec/core/configuration.rb', line 431

def initialize
  # rubocop:disable Style/GlobalVars
  @start_time = $_rspec_core_load_started_at || ::RSpec::Core::Time.now
  # rubocop:enable Style/GlobalVars
  @expectation_frameworks = []
  @include_modules = FilterableItemRepository::QueryOptimized.new(:any?)
  @extend_modules  = FilterableItemRepository::QueryOptimized.new(:any?)
  @prepend_modules = FilterableItemRepository::QueryOptimized.new(:any?)

  @before_suite_hooks = []
  @after_suite_hooks  = []

  @mock_framework = nil
  @files_or_directories_to_run = []
  @loaded_spec_files = Set.new
  @color = false
  @color_mode = :automatic
  @pattern = '**{,/*/**}/*_spec.rb'
  @exclude_pattern = ''
  @failure_exit_code = 1
  @fail_if_no_examples = false
  @spec_files_loaded = false

  @backtrace_formatter = BacktraceFormatter.new

  @default_path = 'spec'
  @project_source_dirs = %w[ spec lib app ]
  @deprecation_stream = $stderr
  @output_stream = $stdout
  @reporter = nil
  @reporter_buffer = nil
  @filter_manager = FilterManager.new
  @static_config_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 = FilterableItemRepository::QueryOptimized.new(:any?)
  @threadsafe = true
  @max_displayed_failure_line_count = 10
  @world = World::Null
  @shared_context_metadata_behavior = :trigger_inclusion

  define_built_in_hooks
end

Instance Attribute Details

#backtrace_formatterObject (readonly)



426
427
428
# File 'lib/rspec/core/configuration.rb', line 426

def backtrace_formatter
  @backtrace_formatter
end

#colorBoolean

Deprecated.

No longer recommended because of complex behavior. Instead, rely on the fact that TTYs will display color by default, or set #color_mode to :on to display color on a non-TTY output.

Enables color output if the output is a TTY. As of RSpec 3.6, this is the default behavior and this option is retained only for backwards compatibility.

Returns:

  • (Boolean)

See Also:



818
819
820
# File 'lib/rspec/core/configuration.rb', line 818

def color
  value_for(:color) { @color }
end

#color_modeBoolean

The mode for determining whether to display output in color. One of:

  • :automatic - the output will be in color if the output is a TTY (the default)

  • :on - the output will be in color, whether or not the output is a TTY

  • :off - the output will not be in color

Returns:

  • (Boolean)

See Also:



831
832
833
# File 'lib/rspec/core/configuration.rb', line 831

def color_mode
  value_for(:color_mode) { @color_mode }
end

#default_colorSymbol

The default output color. Defaults to `:white` but can be set to one of the following: `[:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]`

Returns:

  • (Symbol)


313
# File 'lib/rspec/core/configuration.rb', line 313

add_setting :default_color

#default_pathString

Note:

Other scripts invoking `rspec` indirectly will ignore this setting.

Path to use if no path is provided to the `rspec` command (default: `“spec”`). Allows you to just type `rspec` instead of `rspec spec` to run all the examples in the `spec` directory.

Returns:

  • (String)


104
# File 'lib/rspec/core/configuration.rb', line 104

add_read_only_setting :default_path

#detail_colorSymbol

Color used to print details. Defaults to `:cyan` but can be set to one of the following: `[:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]`

Returns:

  • (Symbol)


327
# File 'lib/rspec/core/configuration.rb', line 327

add_setting :detail_color

#disable_monkey_patchingObject



1748
1749
1750
# File 'lib/rspec/core/configuration.rb', line 1748

def disable_monkey_patching
  @disable_monkey_patching
end

#drbBoolean

Run examples over DRb (default: `false`). RSpec doesn't supply the DRb server, but you can use tools like spork.

Returns:

  • (Boolean)


114
# File 'lib/rspec/core/configuration.rb', line 114

add_setting :drb

#drb_portObject

The drb_port (default: nil).



118
# File 'lib/rspec/core/configuration.rb', line 118

add_setting :drb_port

#dry_runObject

Prints the formatter output of your suite without running any examples or hooks.



199
# File 'lib/rspec/core/configuration.rb', line 199

add_setting :dry_run

#error_streamObject

Default: `$stderr`.



122
# File 'lib/rspec/core/configuration.rb', line 122

add_setting :error_stream

#example_status_persistence_file_pathString #example_status_persistence_file_path=(value) ⇒ Object

The file path to use for persisting example statuses. Necessary for the `–only-failures` and `–next-failure` CLI options.

Overloads:

  • #example_status_persistence_file_pathString

    Returns the file path

    Returns:

    • (String)

      the file path

  • #example_status_persistence_file_path=(value) ⇒ Object

    Parameters:

    • value (String)

      the file path



172
# File 'lib/rspec/core/configuration.rb', line 172

define_reader :example_status_persistence_file_path

#exclude_patternString

Exclude files matching this pattern.

Returns:

  • (String)


256
# File 'lib/rspec/core/configuration.rb', line 256

define_reader :exclude_pattern

#fail_fastObject

If specified, indicates the number of failures required before cleaning up and exit (default: `nil`).



194
# File 'lib/rspec/core/configuration.rb', line 194

add_setting :fail_fast

#fail_if_no_examplesBoolean

Whether or not to fail when there are no RSpec examples (default: false).

Returns:

  • (Boolean)


209
# File 'lib/rspec/core/configuration.rb', line 209

add_setting :fail_if_no_examples

#failure_colorSymbol

Color to use to indicate failure. Defaults to `:red` but can be set to one of the following: `[:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]`

Returns:

  • (Symbol)


306
# File 'lib/rspec/core/configuration.rb', line 306

add_setting :failure_color

#failure_exit_codeInteger

The exit code to return if there are any failures (default: 1).

Returns:

  • (Integer)


204
# File 'lib/rspec/core/configuration.rb', line 204

add_setting :failure_exit_code

#files_to_runArray

The spec files RSpec will run.

Returns:

  • (Array)

    specified files about to run



992
993
994
# File 'lib/rspec/core/configuration.rb', line 992

def files_to_run
  @files_to_run ||= get_files_to_run(@files_or_directories_to_run)
end

#filter_managerObject



422
423
424
# File 'lib/rspec/core/configuration.rb', line 422

def filter_manager
  @filter_manager
end

#fixed_colorSymbol

Color used when a pending example is fixed. Defaults to `:blue` but can be set to one of the following: `[:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]`

Returns:

  • (Symbol)


320
# File 'lib/rspec/core/configuration.rb', line 320

add_setting :fixed_color

#libsArray<String>

Returns dirs that have been prepended to the load path by the `-I` command line option.

Returns:

  • (Array<String>)


220
# File 'lib/rspec/core/configuration.rb', line 220

define_reader :libs

#loaded_spec_filesObject (readonly)



426
427
428
# File 'lib/rspec/core/configuration.rb', line 426

def loaded_spec_files
  @loaded_spec_files
end

#max_displayed_failure_line_countObject

Maximum count of failed source lines to display in the failure reports. (default `10`). return [Integer]



414
# File 'lib/rspec/core/configuration.rb', line 414

add_setting :max_displayed_failure_line_count

#only_failuresObject (readonly) Also known as: only_failures?

Indicates if the `–only-failures` (or `–next-failure`) flag is being used.



183
# File 'lib/rspec/core/configuration.rb', line 183

define_reader :only_failures

#ordering_managerObject (readonly)



426
427
428
# File 'lib/rspec/core/configuration.rb', line 426

def ordering_manager
  @ordering_manager
end

#output_streamIO, String

Determines where RSpec will send its output. Default: `$stdout`.

Returns:

  • (IO, String)


226
# File 'lib/rspec/core/configuration.rb', line 226

define_reader :output_stream

#patternString

Load files matching this pattern (default: `'**,/<strong>/*</strong>/*_spec.rb'`).

Returns:

  • (String)


245
# File 'lib/rspec/core/configuration.rb', line 245

define_reader :pattern

#pending_colorSymbol

Color to use to print pending examples. Defaults to `:yellow` but can be set to one of the following: `[:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]`

Returns:

  • (Symbol)


299
# File 'lib/rspec/core/configuration.rb', line 299

add_setting :pending_color

#profile_examplesObject

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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



278
# File 'lib/rspec/core/configuration.rb', line 278

add_setting :profile_examples

#project_source_dirsArray<String>

Specifies which directories contain the source code for your project. When a failure occurs, RSpec looks through the backtrace to find a a line of source to print. It first looks for a line coming from one of the project source directories so that, for example, it prints the expectation or assertion call rather than the source code from the expectation or assertion framework.

Returns:

  • (Array<String>)


272
# File 'lib/rspec/core/configuration.rb', line 272

add_setting :project_source_dirs

#requiresArray<String>

Indicates files configured to be required.

Returns:

  • (Array<String>)


214
# File 'lib/rspec/core/configuration.rb', line 214

define_reader :requires

#run_all_when_everything_filteredObject

Deprecated.

Use #filter_run_when_matching instead for the specific filters that you want to be ignored if none match.

Run all examples if none match the configured filters (default: `false`).



285
# File 'lib/rspec/core/configuration.rb', line 285

add_setting :run_all_when_everything_filtered

#shared_context_metadata_behavior:trigger_inclusion, :apply_to_host_groups #shared_context_metadata_behavior=(value) ⇒ Object

Configures how RSpec treats metadata passed as part of a shared example group definition. For example, given this shared example group definition:

RSpec.shared_context "uses DB", :db => true do
  around(:example) do |ex|
    MyORM.transaction(:rollback => true, &ex)
  end
end

…there are two ways RSpec can treat the `:db => true` metadata, each of which has a corresponding config option:

  1. `:trigger_inclusion`: this shared context will be implicitly included in any groups (or examples) that have `:db => true` metadata.

  2. `:apply_to_host_groups`: the metadata will be inherited by the metadata hash of all host groups and examples.

`:trigger_inclusion` is the legacy behavior from before RSpec 3.5 but should be considered deprecated. Instead, you can explicitly include a group with `include_context`:

RSpec.describe "My model" do
  include_context "uses DB"
end

…or you can configure RSpec to include the context based on matching metadata using an API that mirrors configured module inclusion:

RSpec.configure do |rspec|
  rspec.include_context "uses DB", :db => true
end

`:apply_to_host_groups` is a new feature of RSpec 3.5 and will be the only supported behavior in RSpec 4.

Overloads:

  • #shared_context_metadata_behavior:trigger_inclusion, :apply_to_host_groups

    Returns the configured behavior

    Returns:

    • (:trigger_inclusion, :apply_to_host_groups)

      the configured behavior

  • #shared_context_metadata_behavior=(value) ⇒ Object

    Parameters:

    • value (:trigger_inclusion, :apply_to_host_groups)

      sets the configured behavior



387
# File 'lib/rspec/core/configuration.rb', line 387

define_reader :shared_context_metadata_behavior

#silence_filter_announcementsObject

Don't print filter info i.e. “Run options: include :focus=>true” (default `false`). return [Boolean]



333
# File 'lib/rspec/core/configuration.rb', line 333

add_setting :silence_filter_announcements

#static_config_filter_managerObject



424
425
426
# File 'lib/rspec/core/configuration.rb', line 424

def static_config_filter_manager
  @static_config_filter_manager
end

#success_colorSymbol

Color to use to indicate success. Defaults to `:green` but can be set to one of the following: `[:black, :white, :red, :green, :yellow, :blue, :magenta, :cyan]`

Returns:

  • (Symbol)


292
# File 'lib/rspec/core/configuration.rb', line 292

add_setting :success_color

#threadsafeObject

Use threadsafe options where available. Currently this will place a mutex around memoized values such as let blocks. return [Boolean]



408
# File 'lib/rspec/core/configuration.rb', line 408

add_setting :threadsafe

#worldObject



422
423
424
# File 'lib/rspec/core/configuration.rb', line 422

def world
  @world
end

Class Method Details

.add_read_only_setting(name, opts = {}) ⇒ Object

As `add_setting` but only add the reader.



84
85
86
87
88
# File 'lib/rspec/core/configuration.rb', line 84

def self.add_read_only_setting(name, opts={})
  raise "Use the instance add_setting method if you want to set a default" if opts.key?(:default)
  define_reader name
  define_predicate_for name
end

.add_setting(name, opts = {}) ⇒ Object

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



71
72
73
74
75
76
77
78
79
# File 'lib/rspec/core/configuration.rb', line 71

def self.add_setting(name, opts={})
  raise "Use the instance add_setting method if you want to set a default" if opts.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) ⇒ Object



56
57
58
59
60
# File 'lib/rspec/core/configuration.rb', line 56

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) ⇒ Object



63
64
65
# File 'lib/rspec/core/configuration.rb', line 63

def self.define_predicate_for(*names)
  names.each { |name| alias_method "#{name}?", name }
end

.define_reader(name) ⇒ Object



46
47
48
49
50
51
52
53
# File 'lib/rspec/core/configuration.rb', line 46

def self.define_reader(name)
  Readers.class_eval do
    remove_method name if method_defined?(name)
    attr_reader name
  end

  define_method(name) { value_for(name) { super() } }
end

.delegate_to_ordering_manager(*methods) ⇒ Object



1539
1540
1541
1542
1543
1544
1545
# File 'lib/rspec/core/configuration.rb', line 1539

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

Instance Method Details

#add_formatter(formatter) ⇒ Object #add_formatter(formatter, output) ⇒ Object Also known as: formatter=

Adds a formatter to the set RSpec will use for this run.

Parameters:

  • formatter (Class, String, Object)

    formatter to use. Can be any of the string values supported from the CLI (`p`/`progress`, `d`/`doc`/`documentation`, `h`/`html`, or `j`/`json`), any class that implements the formatter protocol and has registered itself with RSpec as a formatter, or a formatter instance.

  • output (String, IO) (defaults to: output_wrapper)

    where the formatter will write its output. Can be an IO object or a string path to a file. If not provided, the configured `output_stream` (`$stdout`, by default) will be used.

See Also:



892
893
894
# File 'lib/rspec/core/configuration.rb', line 892

def add_formatter(formatter, output=output_wrapper)
  formatter_loader.add(formatter, output)
end

#add_setting(name) ⇒ Object #add_setting(name, opts) ⇒ Object

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.

Parameters:

  • opts (Hash) (defaults to: {})

    a customizable set of options

Options Hash (opts):

  • :default (Symbol)

    Set a default value for the generated getter and predicate methods:

    add_setting(:foo, :default => "default value")
    
  • :alias_with (Symbol)

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


555
556
557
558
559
560
561
# File 'lib/rspec/core/configuration.rb', line 555

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

#after(scope = nil, *meta, &block) ⇒ Object Also known as: prepend_after

Defines a `after` hook. See Hooks#after for full docs.

This method differs from Hooks#after in only one way: it supports the `:suite` scope. Hooks with the `:suite` scope will be run once after the last example of the entire suite is executed.



1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
# File 'lib/rspec/core/configuration.rb', line 1876

def after(scope=nil, *meta, &block)
  handle_suite_hook(scope, meta) do
    @after_suite_hooks.unshift Hooks::AfterHook.new(block, {})
  end || begin
    # defeat Ruby 2.5 lazy proc allocation to ensure
    # the methods below are passed the same proc instances
    # so `Hook` equality is preserved. For more info, see:
    # https://bugs.ruby-lang.org/issues/14045#note-5
    block.__id__

    add_hook_to_existing_matching_groups(meta, scope) { |g| g.after(scope, *meta, &block) }
    super(scope, *meta, &block)
  end
end

#alias_example_group_to(new_name, *args) ⇒ Object

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.

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

Examples:

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

See Also:



1105
1106
1107
1108
# File 'lib/rspec/core/configuration.rb', line 1105

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) ⇒ Object

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.

Creates a method that delegates to `example` including the submitted `args`. Used internally to add variants of `example` like `pending`:

Examples:

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

Parameters:

  • name (String)

    example name alias

  • args (Array<Symbol>, Hash)

    metadata for the generated example



1073
1074
1075
1076
# File 'lib/rspec/core/configuration.rb', line 1073

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 = '') ⇒ Object Also known as: alias_it_should_behave_like_to

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.

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.

Examples:

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


1136
1137
1138
# File 'lib/rspec/core/configuration.rb', line 1136

def alias_it_behaves_like_to(new_name, report_label='')
  RSpec::Core::ExampleGroup.define_nested_shared_group_method(new_name, report_label)
end

#append_after(scope = nil, *meta, &block) ⇒ Object

Adds `block` to the end of the list of `after` blocks in the same scope (`:example`, `:context`, or `:suite`), in contrast to #after, which adds the hook to the start of the list.

See Hooks#after for full `after` hook docs.

This method differs from Hooks#append_after in only one way: it supports the `:suite` scope. Hooks with the `:suite` scope will be run once after the last example of the entire suite is executed.



1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
# File 'lib/rspec/core/configuration.rb', line 1905

def append_after(scope=nil, *meta, &block)
  handle_suite_hook(scope, meta) do
    @after_suite_hooks << Hooks::AfterHook.new(block, {})
  end || begin
    # defeat Ruby 2.5 lazy proc allocation to ensure
    # the methods below are passed the same proc instances
    # so `Hook` equality is preserved. For more info, see:
    # https://bugs.ruby-lang.org/issues/14045#note-5
    block.__id__

    add_hook_to_existing_matching_groups(meta, scope) { |g| g.append_after(scope, *meta, &block) }
    super(scope, *meta, &block)
  end
end

#apply_derived_metadata_to(metadata) ⇒ Object



1808
1809
1810
1811
1812
# File 'lib/rspec/core/configuration.rb', line 1808

def ()
  @derived_metadata_blocks.items_for().each do |block|
    block.call()
  end
end

#around(scope = nil, *meta, &block) ⇒ Object

Registers `block` as an `around` hook.

See Hooks#around for full `around` hook docs.



1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
# File 'lib/rspec/core/configuration.rb', line 1923

def around(scope=nil, *meta, &block)
  # defeat Ruby 2.5 lazy proc allocation to ensure
  # the methods below are passed the same proc instances
  # so `Hook` equality is preserved. For more info, see:
  # https://bugs.ruby-lang.org/issues/14045#note-5
  block.__id__

  add_hook_to_existing_matching_groups(meta, scope) { |g| g.around(scope, *meta, &block) }
  super(scope, *meta, &block)
end

#backtrace_exclusion_patternsArray<Regexp>

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.

Returns:

  • (Array<Regexp>)


593
594
595
# File 'lib/rspec/core/configuration.rb', line 593

def backtrace_exclusion_patterns
  @backtrace_formatter.exclusion_patterns
end

#backtrace_exclusion_patterns=(patterns) ⇒ Object

Set regular expressions used to exclude lines in backtrace.

Parameters:

  • patterns (Array<Regexp>)

    set backtrace_formatter exlusion_patterns



599
600
601
# File 'lib/rspec/core/configuration.rb', line 599

def backtrace_exclusion_patterns=(patterns)
  @backtrace_formatter.exclusion_patterns = patterns
end

#backtrace_inclusion_patternsArray<Regexp>

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.

Returns:

  • (Array<Regexp>)


612
613
614
# File 'lib/rspec/core/configuration.rb', line 612

def backtrace_inclusion_patterns
  @backtrace_formatter.inclusion_patterns
end

#backtrace_inclusion_patterns=(patterns) ⇒ Object

Set regular expressions used to include lines in backtrace.



618
619
620
# File 'lib/rspec/core/configuration.rb', line 618

def backtrace_inclusion_patterns=(patterns)
  @backtrace_formatter.inclusion_patterns = patterns
end

#before(scope = nil, *meta, &block) ⇒ Object Also known as: append_before

Defines a `before` hook. See Hooks#before for full docs.

This method differs from Hooks#before in only one way: it supports the `:suite` scope. Hooks with the `:suite` scope will be run once before the first example of the entire suite is executed.



1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
# File 'lib/rspec/core/configuration.rb', line 1823

def before(scope=nil, *meta, &block)
  handle_suite_hook(scope, meta) do
    @before_suite_hooks << Hooks::BeforeHook.new(block, {})
  end || begin
    # defeat Ruby 2.5 lazy proc allocation to ensure
    # the methods below are passed the same proc instances
    # so `Hook` equality is preserved. For more info, see:
    # https://bugs.ruby-lang.org/issues/14045#note-5
    block.__id__

    add_hook_to_existing_matching_groups(meta, scope) { |g| g.before(scope, *meta, &block) }
    super(scope, *meta, &block)
  end
end

#color_enabled?(output = output_stream) ⇒ Boolean

Check if color is enabled for a particular output.

Parameters:

  • output (IO) (defaults to: output_stream)

    an output stream to use, defaults to the current `output_stream`

Returns:

  • (Boolean)


839
840
841
842
843
844
845
846
# File 'lib/rspec/core/configuration.rb', line 839

def color_enabled?(output=output_stream)
  case color_mode
  when :on then true
  when :off then false
  else # automatic
    output_to_tty?(output) || (color && tty?)
  end
end

#configure_example(example, example_hooks) ⇒ Object

Used internally to extend the singleton class of a single example's example group instance with modules using `include` and/or `extend`.



1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
# File 'lib/rspec/core/configuration.rb', line 1450

def configure_example(example, example_hooks)
  example_hooks.register_global_singleton_context_hooks(example, hooks)
  singleton_group = example.example_group_instance.singleton_class

  # We replace the metadata so that SharedExampleGroupModule#included
  # has access to the example's metadata[:location].
  singleton_group.(example.) do
    modules = @include_modules.items_for(example.)
    modules.each do |mod|
      safe_include(mod, example.example_group_instance.singleton_class)
    end

    MemoizedHelpers.define_helpers_on(singleton_group) unless modules.empty?
  end
end

#configure_expectation_frameworkObject



1490
1491
1492
1493
1494
1495
# File 'lib/rspec/core/configuration.rb', line 1490

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) ⇒ Object

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



1438
1439
1440
1441
1442
1443
1444
# File 'lib/rspec/core/configuration.rb', line 1438

def configure_group(group)
  group.hooks.register_globals(group, hooks)

  configure_group_with group, @include_modules, :safe_include
  configure_group_with group, @extend_modules,  :safe_extend
  configure_group_with group, @prepend_modules, :safe_prepend
end

#configure_mock_frameworkObject



1484
1485
1486
1487
# File 'lib/rspec/core/configuration.rb', line 1484

def configure_mock_framework
  RSpec::Core::ExampleGroup.__send__(:include, mock_framework)
  conditionally_disable_mocks_monkey_patching
end

#default_formatterObject

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



899
900
901
# File 'lib/rspec/core/configuration.rb', line 899

def default_formatter
  formatter_loader.default_formatter
end

#default_formatter=(value) ⇒ Object

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

Examples:


RSpec.configure do |rspec|
  rspec.default_formatter = 'doc'
end


910
911
912
# File 'lib/rspec/core/configuration.rb', line 910

def default_formatter=(value)
  formatter_loader.default_formatter = value
end

#define_derived_metadata(*filters) {|metadata| ... } ⇒ Object

Defines a callback that can assign derived metadata values.

Examples:

RSpec.configure do |config|
  # Tag all groups and examples in the spec/unit directory with
  # :type => :unit
  config.(:file_path => %r{/spec/unit/}) do ||
    [:type] = :unit
  end
end

Parameters:

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

Yield Parameters:

  • metadata (Hash)

    original metadata hash from an example or group. Mutate this in your block as needed.



1767
1768
1769
1770
# File 'lib/rspec/core/configuration.rb', line 1767

def (*filters, &block)
  meta = Metadata.build_hash_from(filters, :warn_about_example_group_filtering)
  @derived_metadata_blocks.append(block, meta)
end

#deprecation_streamIO, String

Determines where deprecation warnings are printed. Defaults to `$stderr`.

Returns:

  • (IO, String)

    IO or filename to write to



148
# File 'lib/rspec/core/configuration.rb', line 148

define_reader :deprecation_stream

#deprecation_stream=(value) ⇒ Object

Determines where deprecation warnings are printed.

Parameters:

  • value (IO, String)

    IO to write to or filename to write to



152
153
154
155
156
157
158
159
160
161
162
# File 'lib/rspec/core/configuration.rb', line 152

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

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.

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.

Examples:


# 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.expect_with :rspec do |expectations|
    expectations.syntax = :expect
  end
end


1740
1741
1742
1743
1744
1745
# File 'lib/rspec/core/configuration.rb', line 1740

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_filterObject

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



1265
1266
1267
# File 'lib/rspec/core/configuration.rb', line 1265

def exclusion_filter
  filter_manager.exclusions
end

#exclusion_filter=(filter) ⇒ Object

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.



1258
1259
1260
1261
# File 'lib/rspec/core/configuration.rb', line 1258

def exclusion_filter=(filter)
  meta = Metadata.build_hash_from([filter], :warn_about_example_group_filtering)
  filter_manager.exclude_only meta
end

#expect_with(*frameworks) ⇒ Object

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


754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
# File 'lib/rspec/core/configuration.rb', line 754

def expect_with(*frameworks)
  modules = frameworks.map do |framework|
    case framework
    when Module
      framework
    when :rspec
      require 'rspec/expectations'

      # Tag this exception class so our exception formatting logic knows
      # that it satisfies the `MultipleExceptionError` interface.
      ::RSpec::Expectations::MultipleExpectationsNotMetError.__send__(
        :include, MultipleExceptionError::InterfaceTag
      )

      ::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) ⇒ Object

Delegates to expect_with(framework).



727
728
729
# File 'lib/rspec/core/configuration.rb', line 727

def expectation_framework=(framework)
  expect_with(framework)
end

#expectation_frameworksObject

Returns the configured expectation framework adapter module(s)



715
716
717
718
719
720
721
722
723
724
# File 'lib/rspec/core/configuration.rb', line 715

def expectation_frameworks
  if @expectation_frameworks.empty?
    begin
      expect_with :rspec
    rescue LoadError
      expect_with Module.new
    end
  end
  @expectation_frameworks
end

#expose_current_running_example_as(method_name) ⇒ Object

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.

Examples:


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.[:type] == "foo"
  end
end

Parameters:

  • method_name (Symbol)

    the name of the helper method



1678
1679
1680
1681
1682
1683
1684
1685
# File 'lib/rspec/core/configuration.rb', line 1678

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) ⇒ Object

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



135
136
137
138
139
140
141
142
143
# File 'lib/rspec/core/configuration.rb', line 135

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

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

Returns:

  • (Boolean)


127
128
129
# File 'lib/rspec/core/configuration.rb', line 127

def expose_dsl_globally?
  Core::DSL.exposed_globally?
end

#extend(mod, *filters) ⇒ Object

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.

Examples:


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



1388
1389
1390
1391
1392
# File 'lib/rspec/core/configuration.rb', line 1388

def extend(mod, *filters)
  define_mixed_in_module(mod, filters, @extend_modules, :extend) do |group|
    safe_extend(mod, group)
  end
end

#files_or_directories_to_run=(*files) ⇒ Object



979
980
981
982
983
984
985
986
987
988
# File 'lib/rspec/core/configuration.rb', line 979

def files_or_directories_to_run=(*files)
  files = files.flatten

  if (command == 'rspec' || Runner.running_in_drb?) && default_path && files.empty?
    files << default_path
  end

  @files_or_directories_to_run = files
  @files_to_run = nil
end

#filter_gems_from_backtrace(*gem_names) ⇒ Object

Note:

The patterns this adds will match the named gems in their common locations (e.g. system gems, vendored with bundler, installed as a :git dependency with bundler, etc) but is not guaranteed to work for all possible gem locations. For example, if you have the gem source in a directory with a completely unrelated name, and use bundler's :path option, this will not filter it.

Adds #backtrace_exclusion_patterns that will filter lines from the named gems from backtraces.

Examples:

RSpec.configure do |config|
  config.filter_gems_from_backtrace "rack", "rake"
end

Parameters:

  • gem_names (Array<String>)

    Names of the gems to filter



638
639
640
641
642
# File 'lib/rspec/core/configuration.rb', line 638

def filter_gems_from_backtrace(*gem_names)
  gem_names.each do |name|
    @backtrace_formatter.filter_gem(name)
  end
end

#filter_run_excluding(*args) ⇒ Object

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`).

Examples:

# 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


1245
1246
1247
1248
1249
# File 'lib/rspec/core/configuration.rb', line 1245

def filter_run_excluding(*args)
  meta = Metadata.build_hash_from(args, :warn_about_example_group_filtering)
  filter_manager.exclude_with_low_priority meta
  static_config_filter_manager.exclude_with_low_priority Metadata.deep_hash_dup(meta)
end

#filter_run_including(*args) ⇒ Object Also known as: filter_run

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`).

Examples:

# 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


1171
1172
1173
1174
1175
# File 'lib/rspec/core/configuration.rb', line 1171

def filter_run_including(*args)
  meta = Metadata.build_hash_from(args, :warn_about_example_group_filtering)
  filter_manager.include_with_low_priority meta
  static_config_filter_manager.include_with_low_priority Metadata.deep_hash_dup(meta)
end

#filter_run_when_matching(*args) ⇒ Object

Applies the provided filter only if any of examples match, in constrast to #filter_run, which always applies even if no examples match, in which case no examples will be run. This allows you to leave configured filters in place that are intended only for temporary use. The most common example is focus filtering: `config.filter_run_when_matching :focus`. With that configured, you can temporarily focus an example or group by tagging it with `:focus` metadata, or prefixing it with an `f` (as in `fdescribe`, `fcontext` and `fit`) since those are aliases for `describe`/`context`/`it` with `:focus` metadata.



1187
1188
1189
1190
1191
# File 'lib/rspec/core/configuration.rb', line 1187

def filter_run_when_matching(*args)
  when_first_matching_example_defined(*args) do
    filter_run(*args)
  end
end

#force(hash) ⇒ Object

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



488
489
490
491
492
493
494
# File 'lib/rspec/core/configuration.rb', line 488

def force(hash)
  ordering_manager.force(hash)
  @preferred_options.merge!(hash)

  return unless hash.key?(:example_status_persistence_file_path)
  clear_values_derived_from_example_status_persistence_file_path
end

#format_docstrings(&block) ⇒ Object

Formats the docstring output using the block provided.

Examples:

# This will strip the descriptions of both examples and example
# groups.
RSpec.configure do |config|
  config.format_docstrings { |s| s.strip }
end


1529
1530
1531
# File 'lib/rspec/core/configuration.rb', line 1529

def format_docstrings(&block)
  @format_docstrings_block = block_given? ? block : DEFAULT_FORMATTER
end

#format_docstrings_blockObject



1534
1535
1536
# File 'lib/rspec/core/configuration.rb', line 1534

def format_docstrings_block
  @format_docstrings_block ||= DEFAULT_FORMATTER
end

#formatter_loaderObject



925
926
927
# File 'lib/rspec/core/configuration.rb', line 925

def formatter_loader
  @formatter_loader ||= Formatters::Loader.new(Reporter.new(self))
end

#formattersArray

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

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

Returns:

  • (Array)

    the formatters currently loaded



920
921
922
# File 'lib/rspec/core/configuration.rb', line 920

def formatters
  formatter_loader.formatters.dup
end

#full_backtrace=(true_or_false) ⇒ Object

Toggle full backtrace.



804
805
806
# File 'lib/rspec/core/configuration.rb', line 804

def full_backtrace=(true_or_false)
  @backtrace_formatter.full_backtrace = true_or_false
end

#full_backtrace?Boolean

Check if full backtrace is enabled.

Returns:

  • (Boolean)

    is full backtrace enabled



798
799
800
# File 'lib/rspec/core/configuration.rb', line 798

def full_backtrace?
  @backtrace_formatter.full_backtrace?
end

#full_descriptionArray

Returns full description filter

Returns:

  • (Array)

    full description filter



873
874
875
# File 'lib/rspec/core/configuration.rb', line 873

def full_description
  filter.fetch :full_description, nil
end

#full_description=(description) ⇒ Object

Run examples matching on `description` in all files to run.

Parameters:

  • description (String, Regexp)

    the pattern to filter on



868
869
870
# File 'lib/rspec/core/configuration.rb', line 868

def full_description=(description)
  filter_run :full_description => Regexp.union(*Array(description).map { |d| Regexp.new(d) })
end

#hooksObject

Holds the various registered hooks. Here we use a FilterableItemRepository implementation that is specifically optimized for the read/write patterns of the config object.



1950
1951
1952
# File 'lib/rspec/core/configuration.rb', line 1950

def hooks
  @hooks ||= HookCollections.new(self, FilterableItemRepository::QueryOptimized)
end

#in_project_source_dir_regexObject



1475
1476
1477
1478
1479
1480
1481
# File 'lib/rspec/core/configuration.rb', line 1475

def in_project_source_dir_regex
  regexes = project_source_dirs.map do |dir|
    /\A#{Regexp.escape(File.expand_path(dir))}\//
  end

  Regexp.union(regexes)
end

#include(mod, *filters) ⇒ Object

Note:

Filtered module inclusions can also be applied to individual examples that have matching metadata. Just like Ruby's object model is that every object has a singleton class which has only a single instance, RSpec's model is that every example has a singleton example group containing just the one example.

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 or examples in which to include the module.

Examples:


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

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

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

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

See Also:



1310
1311
1312
1313
1314
# File 'lib/rspec/core/configuration.rb', line 1310

def include(mod, *filters)
  define_mixed_in_module(mod, filters, @include_modules, :include) do |group|
    safe_include(mod, group)
  end
end

#include_context(shared_group_name, *filters) ⇒ Object

Note:

Filtered context inclusions can also be applied to individual examples that have matching metadata. Just like Ruby's object model is that every object has a singleton class which has only a single instance, RSpec's model is that every example has a singleton example group containing just the one example.

Tells RSpec to include the named shared example group in example groups. Use `filters` to constrain the groups or examples in which to include the example group.

Examples:


RSpec.shared_context "example users" do
  let(:admin_user) { create_user(:admin) }
  let(:guest_user) { create_user(:guest) }
end

RSpec.configure do |config|
  config.include_context "example users", :type => :request
end

RSpec.describe "The admin page", :type => :request do
  it "can be viewed by admins" do
     admin_user
    get "/admin"
    expect(response).to be_ok
  end

  it "cannot be viewed by guests" do
     guest_user
    get "/admin"
    expect(response).to be_forbidden
  end
end

See Also:



1353
1354
1355
1356
# File 'lib/rspec/core/configuration.rb', line 1353

def include_context(shared_group_name, *filters)
  shared_module = world.shared_example_group_registry.find([:main], shared_group_name)
  include shared_module, *filters
end

#inclusion_filterObject Also known as: filter

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



1209
1210
1211
# File 'lib/rspec/core/configuration.rb', line 1209

def inclusion_filter
  filter_manager.inclusions
end

#inclusion_filter=(filter) ⇒ Object Also known as: 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.



1200
1201
1202
1203
# File 'lib/rspec/core/configuration.rb', line 1200

def inclusion_filter=(filter)
  meta = Metadata.build_hash_from([filter], :warn_about_example_group_filtering)
  filter_manager.include_only meta
end

#last_run_statusesObject



997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
# File 'lib/rspec/core/configuration.rb', line 997

def last_run_statuses
  @last_run_statuses ||= Hash.new(UNKNOWN_STATUS).tap do |statuses|
    if (path = example_status_persistence_file_path)
      begin
        ExampleStatusPersister.load_from(path).inject(statuses) do |hash, example|
          status = example[:status]
          status = UNKNOWN_STATUS unless VALID_STATUSES.include?(status)
          hash[example.fetch(:example_id)] = status
          hash
        end
      rescue SystemCallError => e
        RSpec.warning "Could not read from #{path.inspect} (configured as " \
                      "`config.example_status_persistence_file_path`) due " \
                      "to a system error: #{e.inspect}. Please check that " \
                      "the config option is set to an accessible, valid " \
                      "file path", :call_site => nil
      end
    end
  end
end

#load_spec_filesObject



1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
# File 'lib/rspec/core/configuration.rb', line 1498

def load_spec_files
  # Note which spec files world is already aware of.
  # This is generally only needed for when the user runs
  # `ruby path/to/spec.rb` (and loads `rspec/autorun`) --
  # in that case, the spec file was loaded by `ruby` and
  # isn't loaded by us here so we only know about it because
  # of an example group being registered in it.
  world.registered_example_group_files.each do |f|
    loaded_spec_files << f # the registered files are already expended absolute paths
  end

  files_to_run.uniq.each do |f|
    file = File.expand_path(f)
    load_file_handling_errors(:load, file)
    loaded_spec_files << file
  end

  @spec_files_loaded = true
end

#mock_frameworkSymbol

Returns the configured mock framework adapter module.

Returns:

  • (Symbol)


565
566
567
568
569
570
571
572
573
574
# File 'lib/rspec/core/configuration.rb', line 565

def mock_framework
  if @mock_framework.nil?
    begin
      mock_with :rspec
    rescue LoadError
      mock_with :nothing
    end
  end
  @mock_framework
end

#mock_framework=(framework) ⇒ Object

Delegates to mock_framework=(framework).



577
578
579
# File 'lib/rspec/core/configuration.rb', line 577

def mock_framework=(framework)
  mock_with framework
end

#mock_with(framework) ⇒ Object

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


682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
# File 'lib/rspec/core/configuration.rb', line 682

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

#on_example_group_definition(&block) ⇒ Object

Invokes block before defining an example group



1955
1956
1957
# File 'lib/rspec/core/configuration.rb', line 1955

def on_example_group_definition(&block)
  on_example_group_definition_callbacks << block
end

#on_example_group_definition_callbacksObject

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns an array of blocks to call before defining an example group



1961
1962
1963
# File 'lib/rspec/core/configuration.rb', line 1961

def on_example_group_definition_callbacks
  @on_example_group_definition_callbacks ||= []
end

#only_failures_but_not_configured?Boolean

Returns:

  • (Boolean)


187
188
189
# File 'lib/rspec/core/configuration.rb', line 187

def only_failures_but_not_configured?
  only_failures? && !example_status_persistence_file_path
end

#order=(value) ⇒ Object

Sets the default global ordering strategy. By default this can be one of `:defined`, `:random`, but is customizable through the `register_ordering` API. If order is set to `'rand:<seed>'`, the seed will also be set.

See Also:



1574
# File 'lib/rspec/core/configuration.rb', line 1574

delegate_to_ordering_manager :order=

#prepend(mod, *filters) ⇒ Object

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

Similar to `include`, but module is included before the example group's class in the ancestor chain.

Examples:


module OverrideMod
  def override_me
    "overridden"
  end
end

RSpec.configure do |config|
  config.prepend(OverrideMod, :method => :prepend)
end

describe "overriding example's class", :method => :prepend do
  it "finds the user" do
    self.class.class_eval do
      def override_me
      end
    end
    override_me # => "overridden"
    # ...
  end
end

See Also:



1427
1428
1429
1430
1431
# File 'lib/rspec/core/configuration.rb', line 1427

def prepend(mod, *filters)
  define_mixed_in_module(mod, filters, @prepend_modules, :prepend) do |group|
    safe_prepend(mod, group)
  end
end

#prepend_before(scope = nil, *meta, &block) ⇒ Object

Adds `block` to the start of the list of `before` blocks in the same scope (`:example`, `:context`, or `:suite`), in contrast to #before, which adds the hook to the end of the list.

See Hooks#before for full `before` hook docs.

This method differs from Hooks#prepend_before in only one way: it supports the `:suite` scope. Hooks with the `:suite` scope will be run once before the first example of the entire suite is executed.



1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
# File 'lib/rspec/core/configuration.rb', line 1852

def prepend_before(scope=nil, *meta, &block)
  handle_suite_hook(scope, meta) do
    @before_suite_hooks.unshift Hooks::BeforeHook.new(block, {})
  end || begin
    # defeat Ruby 2.5 lazy proc allocation to ensure
    # the methods below are passed the same proc instances
    # so `Hook` equality is preserved. For more info, see:
    # https://bugs.ruby-lang.org/issues/14045#note-5
    block.__id__

    add_hook_to_existing_matching_groups(meta, scope) { |g| g.prepend_before(scope, *meta, &block) }
    super(scope, *meta, &block)
  end
end

#raise_errors_for_deprecations!Object

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.

Examples:


RSpec.configure do |rspec|
  rspec.raise_errors_for_deprecations!
end


1700
1701
1702
# File 'lib/rspec/core/configuration.rb', line 1700

def raise_errors_for_deprecations!
  self.deprecation_stream = Formatters::DeprecationFormatter::RaiseErrorStream.new
end

#raise_on_warning=(value) ⇒ Object

Turns warnings into errors. This can be useful when you want RSpec to run in a 'strict' no warning situation.

Examples:


RSpec.configure do |rspec|
  rspec.raise_on_warning = true
end


1648
1649
1650
1651
1652
1653
1654
# File 'lib/rspec/core/configuration.rb', line 1648

def raise_on_warning=(value)
  if value
    RSpec::Support.warning_notifier = RAISE_ERROR_WARNING_NOTIFIER
  else
    RSpec::Support.warning_notifier = RSpec::Support::DEFAULT_WARNING_NOTIFIER
  end
end

#register_ordering(name) {|list| ... } ⇒ Object

Note:

Pass the symbol `:global` to set the ordering strategy that will be used to order the top-level example groups and any example groups that do not have declared `:order` metadata.

Registers a named ordering strategy that can later be used to order an example group's subgroups by adding `:order => <name>` metadata to the example group.

Examples:

RSpec.configure do |rspec|
  rspec.register_ordering :reverse do |list|
    list.reverse
  end
end

RSpec.describe 'MyClass', :order => :reverse do
  # ...
end
RSpec.configure do |rspec|
  rspec.register_ordering :global do |examples|
    acceptance, other = examples.partition do |example|
      example.[:type] == :acceptance
    end
    other + acceptance
  end
end

RSpec.describe 'MyClass', :type => :acceptance do
  # will run last
end

RSpec.describe 'MyClass' do
  # will run first
end

Parameters:

  • name (Symbol)

    The name of the ordering.

Yields:

  • Block that will order the given examples or example groups

Yield Parameters:

Yield Returns:



1622
# File 'lib/rspec/core/configuration.rb', line 1622

delegate_to_ordering_manager :register_ordering

#reporterRSpec::Core::Reporter

Returns the currently configured reporter

Returns:



952
953
954
955
956
957
958
959
960
961
962
963
# File 'lib/rspec/core/configuration.rb', line 952

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.prepare_default output_wrapper, deprecation_stream
      @reporter_buffer.play_onto(formatter_loader.reporter)
      @reporter_buffer = nil
      formatter_loader.reporter
    end
end

#resetObject



497
498
499
500
# File 'lib/rspec/core/configuration.rb', line 497

def reset
  @spec_files_loaded = false
  reset_reporter
end

#reset_filtersObject



510
511
512
513
514
515
516
517
518
# File 'lib/rspec/core/configuration.rb', line 510

def reset_filters
  self.filter_manager = FilterManager.new
  filter_manager.include_only(
    Metadata.deep_hash_dup(static_config_filter_manager.inclusions.rules)
  )
  filter_manager.exclude_only(
    Metadata.deep_hash_dup(static_config_filter_manager.exclusions.rules)
  )
end

#reset_reporterObject



503
504
505
506
507
# File 'lib/rspec/core/configuration.rb', line 503

def reset_reporter
  @reporter = nil
  @formatter_loader = nil
  @output_wrapper = nil
end

#seedObject

Seed for random ordering (default: generated randomly each run).

When you run specs with `–order random`, RSpec generates a random seed for the randomization and prints it to the `output_stream` (assuming you're using RSpec's built-in formatters). If you discover an ordering dependency (i.e. examples fail intermittently depending on order), set this (on Configuration or on the command line with `–seed`) to run using the same seed while you debug the issue.

We recommend, actually, that you use the command line approach so you don't accidentally leave the seed encoded.



1564
# File 'lib/rspec/core/configuration.rb', line 1564

delegate_to_ordering_manager :seed

#seed=(value) ⇒ Object

Sets the seed value and sets the default global ordering to random.



1550
# File 'lib/rspec/core/configuration.rb', line 1550

delegate_to_ordering_manager :seed=

#spec_files_with_failuresObject



1034
1035
1036
1037
1038
1039
# File 'lib/rspec/core/configuration.rb', line 1034

def spec_files_with_failures
  @spec_files_with_failures ||= last_run_statuses.inject(Set.new) do |files, (id, status)|
    files << Example.parse_id(id).first if status == FAILED_STATUS
    files
  end.to_a
end

#treat_symbols_as_metadata_keys_with_true_values=(_value) ⇒ Object

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.



338
339
340
341
342
343
344
345
# File 'lib/rspec/core/configuration.rb', line 338

def (_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) ⇒ Object

Set Ruby warnings on or off.



1628
1629
1630
# File 'lib/rspec/core/configuration.rb', line 1628

def warnings=(value)
  $VERBOSE = !!value
end

#warnings?Boolean

Returns Whether or not ruby warnings are enabled.

Returns:

  • (Boolean)

    Whether or not ruby warnings are enabled.



1633
1634
1635
# File 'lib/rspec/core/configuration.rb', line 1633

def warnings?
  $VERBOSE
end

#when_first_matching_example_defined(*filters) ⇒ Object

Defines a callback that runs after the first example with matching metadata is defined. If no examples are defined with matching metadata, it will not get called at all.

This can be used to ensure some setup is performed (such as bootstrapping a DB or loading a specific file that adds significantly to the boot time) if needed (as indicated by the presence of an example with matching metadata) but avoided otherwise.

Examples:

RSpec.configure do |config|
  config.when_first_matching_example_defined(:db) do
    # Load a support file that does some heavyweight setup,
    # including bootstrapping the DB, but only if we have loaded
    # any examples tagged with `:db`.
    require 'support/db'
  end
end


1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
# File 'lib/rspec/core/configuration.rb', line 1790

def when_first_matching_example_defined(*filters)
  specified_meta = Metadata.build_hash_from(filters, :warn_about_example_group_filtering)

  callback = lambda do |example_or_group_meta|
    # Example groups do not have `:example_group` metadata
    # (instead they have `:parent_example_group` metadata).
    return unless example_or_group_meta.key?(:example_group)

    # Ensure the callback only fires once.
    @derived_metadata_blocks.delete(callback, specified_meta)

    yield
  end

  @derived_metadata_blocks.append(callback, specified_meta)
end

#with_suite_hooksObject



1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
# File 'lib/rspec/core/configuration.rb', line 1935

def with_suite_hooks
  return yield if dry_run?

  begin
    run_suite_hooks("a `before(:suite)` hook", @before_suite_hooks)
    yield
  ensure
    run_suite_hooks("an `after(:suite)` hook", @after_suite_hooks)
  end
end