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 multiple files and joined together with command-line switches and the SPEC_OPTS environment variable.

Precedence order (where later entries overwrite earlier entries on conflicts):

  • Global ($XDG_CONFIG_HOME/rspec/options, or ~/.rspec if it does not exist)
  • Project-specific (./.rspec)
  • Local (./.rspec-local)
  • Command-line options
  • SPEC_OPTS

For example, an option set in the local file will override an option set in your global file.

The global, project-specific and local files can all be overridden with a separate custom file using the --options command-line parameter.

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:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Build an object to store runtime configuration options and set defaults

528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
 
# File 'lib/rspec/core/configuration.rb', line 528
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?)
  @bisect_runner = RSpec::Support::RubyFeatures.fork_supported? ? :fork : :shell
  @bisect_runner_class = nil
  @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
  @error_exit_code = nil # so it can be overridden by failure exit code
  @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
  @full_cause_backtrace = false
  @world = World::Null
  @shared_context_metadata_behavior = :trigger_inclusion
  @pending_failure_output = :full
  define_built_in_hooks
end

Instance Attribute Details

#bisect_runner ⇒ Symbol

Note:

This option will only be used by --bisect if you set it in a file loaded via --require.

Determines which bisect runner implementation gets used to run subsets of the suite during a bisection. Your choices are:

  • :shell: Performs a spec run by shelling out, booting RSpec and your application environment each time. This runner is the most widely compatible runner, but is not as fast. On platforms that do not support forking, this is the default.
  • :fork: Pre-boots RSpec and your application environment in a parent process, and then forks a child process for each spec run. This runner tends to be significantly faster than the :shell runner but cannot be used in some situations. On platforms that support forking, this is the default. If you use this runner, you should ensure that all of your one-time setup logic goes in a before(:suite) hook instead of getting run at the top-level of a file loaded by --require.

Returns:

  • (Symbol) 
499
500
501
 
# File 'lib/rspec/core/configuration.rb', line 499
def bisect_runner
  @bisect_runner
end

#color ⇒ Boolean

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:

922
923
924
 
# File 'lib/rspec/core/configuration.rb', line 922
def color
  value_for(:color) { @color }
end

#color_mode ⇒ Boolean

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:

935
936
937
 
# File 'lib/rspec/core/configuration.rb', line 935
def color_mode
  value_for(:color_mode) { @color_mode }
end

#default_color ⇒ Symbol

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) 
358
 
# File 'lib/rspec/core/configuration.rb', line 358
add_setting :default_color

#default_path ⇒ String

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) 
120
 
# File 'lib/rspec/core/configuration.rb', line 120
add_read_only_setting :default_path

#detail_color ⇒ Symbol

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) 
372
 
# File 'lib/rspec/core/configuration.rb', line 372
add_setting :detail_color

#drb ⇒ Boolean

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

Returns:

  • (Boolean) 
130
 
# File 'lib/rspec/core/configuration.rb', line 130
add_setting :drb

#drb_port ⇒ void

The drb_port (default: nil).

134
 
# File 'lib/rspec/core/configuration.rb', line 134
add_setting :drb_port

#dry_run ⇒ void

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

238
 
# File 'lib/rspec/core/configuration.rb', line 238
add_setting :dry_run

#error_exit_code ⇒ Integer

The exit code to return if there are any errors outside examples (default: failure_exit_code)

Returns:

  • (Integer) 
248
 
# File 'lib/rspec/core/configuration.rb', line 248
add_setting :error_exit_code

#error_stream ⇒ void

Default: $stderr.

138
 
# File 'lib/rspec/core/configuration.rb', line 138
add_setting :error_stream

#example_status_persistence_file_path ⇒ String #example_status_persistence_file_path=(value) ⇒ void

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

Overloads:

  • #example_status_persistence_file_path ⇒ String

    Returns the file path.

    Returns:

    • (String) —

      the file path

  • #example_status_persistence_file_path=(value) ⇒ void

    Parameters:

    • value (String) —

      the file path

188
 
# File 'lib/rspec/core/configuration.rb', line 188
define_reader :example_status_persistence_file_path

#exclude_pattern ⇒ String

Exclude files matching this pattern.

Returns:

  • (String) 
300
 
# File 'lib/rspec/core/configuration.rb', line 300
define_reader :exclude_pattern

#fail_fast ⇒ void

If specified, indicates the number of failures required before cleaning up and exit (default: nil). Can also be true to fail and exit on first failure

211
 
# File 'lib/rspec/core/configuration.rb', line 211
define_reader :fail_fast

#fail_if_no_examples ⇒ Boolean

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

Returns:

  • (Boolean) 
253
 
# File 'lib/rspec/core/configuration.rb', line 253
add_setting :fail_if_no_examples

#failure_color ⇒ Symbol

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) 
351
 
# File 'lib/rspec/core/configuration.rb', line 351
add_setting :failure_color

#failure_exit_code ⇒ Integer

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

Returns:

  • (Integer) 
243
 
# File 'lib/rspec/core/configuration.rb', line 243
add_setting :failure_exit_code

#files_to_run ⇒ Array

The spec files RSpec will run.

Returns:

  • (Array) —

    specified files about to run

1096
1097
1098
 
# File 'lib/rspec/core/configuration.rb', line 1096
def files_to_run
  @files_to_run ||= get_files_to_run(@files_or_directories_to_run)
end

#fixed_color ⇒ Symbol

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) 
365
 
# File 'lib/rspec/core/configuration.rb', line 365
add_setting :fixed_color

#libs ⇒ Array<String>

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

Returns:

  • (Array<String>) 
264
 
# File 'lib/rspec/core/configuration.rb', line 264
define_reader :libs

#max_displayed_failure_line_count ⇒ void

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

459
 
# File 'lib/rspec/core/configuration.rb', line 459
add_setting :max_displayed_failure_line_count

#only_failures ⇒ void (readonly) Also known as: only_failures?

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

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

#output_stream ⇒ IO, String

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

Returns:

  • (IO, String) 
270
 
# File 'lib/rspec/core/configuration.rb', line 270
define_reader :output_stream

#pattern ⇒ String

Load files matching this pattern (default: '**{,/*/**}/*_spec.rb').

Returns:

  • (String) 
289
 
# File 'lib/rspec/core/configuration.rb', line 289
define_reader :pattern

#pending_color ⇒ Symbol

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) 
344
 
# File 'lib/rspec/core/configuration.rb', line 344
add_setting :pending_color

#pending_failure_output ⇒ void

Format the output for pending examples. Can be set to:

  • :full (default) - pending examples appear similarly to failures
  • :no_backtrace - same as above, but with no backtrace
  • :skip - do not show the section at all return [Symbol]

Raises:

  • (ArgumentError) 
472
 
# File 'lib/rspec/core/configuration.rb', line 472
add_read_only_setting :pending_failure_output

#profile_examples ⇒ void

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.

322
 
# File 'lib/rspec/core/configuration.rb', line 322
attr_writer :profile_examples

#project_source_dirs ⇒ Array<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>) 
316
 
# File 'lib/rspec/core/configuration.rb', line 316
add_setting :project_source_dirs

#requires ⇒ Array<String>

Indicates files configured to be required.

Returns:

  • (Array<String>) 
258
 
# File 'lib/rspec/core/configuration.rb', line 258
define_reader :requires

#run_all_when_everything_filtered ⇒ void

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

330
 
# File 'lib/rspec/core/configuration.rb', line 330
add_setting :run_all_when_everything_filtered

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

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

    Parameters:

    • value (:trigger_inclusion, :apply_to_host_groups) —

      sets the configured behavior

432
 
# File 'lib/rspec/core/configuration.rb', line 432
define_reader :shared_context_metadata_behavior

#silence_filter_announcements ⇒ void

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

378
 
# File 'lib/rspec/core/configuration.rb', line 378
add_setting :silence_filter_announcements

#success_color ⇒ Symbol

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) 
337
 
# File 'lib/rspec/core/configuration.rb', line 337
add_setting :success_color

#threadsafe ⇒ void

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

453
 
# File 'lib/rspec/core/configuration.rb', line 453
add_setting :threadsafe

Instance Method Details

#add_formatter(formatter) ⇒ void #add_formatter(formatter, output) ⇒ void 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:

996
997
998
 
# File 'lib/rspec/core/configuration.rb', line 996
def add_formatter(formatter, output=output_wrapper)
  formatter_loader.add(formatter, output)
end

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

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

659
660
661
662
663
664
665
 
# File 'lib/rspec/core/configuration.rb', line 659
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) ⇒ void 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. Conditions passed along with :suite are effectively ignored.

See Also:

2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
 
# File 'lib/rspec/core/configuration.rb', line 2029
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) ⇒ void

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:

1209
1210
1211
1212
 
# File 'lib/rspec/core/configuration.rb', line 1209
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) ⇒ void

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:

RSpec.describe Thing do
  pending "does something" do
    thing = Thing.new
  end
end
# ... which is the equivalent of

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

1177
1178
1179
1180
 
# File 'lib/rspec/core/configuration.rb', line 1177
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 = '') ⇒ void 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:

RSpec.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
1240
1241
1242
 
# File 'lib/rspec/core/configuration.rb', line 1240
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) ⇒ void

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. Conditions passed along with :suite are effectively ignored.

See Also:

2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
 
# File 'lib/rspec/core/configuration.rb', line 2059
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

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

Registers block as an around hook.

See Hooks#around for full around hook docs.

2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
 
# File 'lib/rspec/core/configuration.rb', line 2077
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_patterns ⇒ Array<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>) 
697
698
699
 
# File 'lib/rspec/core/configuration.rb', line 697
def backtrace_exclusion_patterns
  @backtrace_formatter.exclusion_patterns
end

#backtrace_exclusion_patterns=(patterns) ⇒ void

Set regular expressions used to exclude lines in backtrace.

Parameters:

  • patterns (Array<Regexp>) —

    set backtrace_formatter exclusion_patterns

703
704
705
 
# File 'lib/rspec/core/configuration.rb', line 703
def backtrace_exclusion_patterns=(patterns)
  @backtrace_formatter.exclusion_patterns = patterns
end

#backtrace_inclusion_patterns ⇒ Array<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>) 
716
717
718
 
# File 'lib/rspec/core/configuration.rb', line 716
def backtrace_inclusion_patterns
  @backtrace_formatter.inclusion_patterns
end

#backtrace_inclusion_patterns=(patterns) ⇒ void

Set regular expressions used to include lines in backtrace.

722
723
724
 
# File 'lib/rspec/core/configuration.rb', line 722
def backtrace_inclusion_patterns=(patterns)
  @backtrace_formatter.inclusion_patterns = patterns
end

#before(scope = nil, *meta, &block) ⇒ void 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. Conditions passed along with :suite are effectively ignored.

See Also:

1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
 
# File 'lib/rspec/core/configuration.rb', line 1974
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) 
943
944
945
946
947
948
949
950
 
# File 'lib/rspec/core/configuration.rb', line 943
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

#default_formatter ⇒ void

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

1003
1004
1005
 
# File 'lib/rspec/core/configuration.rb', line 1003
def default_formatter
  formatter_loader.default_formatter
end

#default_formatter=(value) ⇒ void

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

Examples:


RSpec.configure do |rspec|
  rspec.default_formatter = 'doc'
end
1014
1015
1016
 
# File 'lib/rspec/core/configuration.rb', line 1014
def default_formatter=(value)
  formatter_loader.default_formatter = value
end

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

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.define_derived_metadata(:file_path => %r{/spec/unit/}) do |metadata|
    metadata[: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.

1898
1899
1900
1901
 
# File 'lib/rspec/core/configuration.rb', line 1898
def define_derived_metadata(*filters, &block)
  meta = Metadata.build_hash_from(filters, :warn_about_example_group_filtering)
  @derived_metadata_blocks.append(block, meta)
end

#deprecation_stream ⇒ IO, String

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

Returns:

  • (IO, String) —

    IO or filename to write to

164
 
# File 'lib/rspec/core/configuration.rb', line 164
define_reader :deprecation_stream

#deprecation_stream=(value) ⇒ void

Determines where deprecation warnings are printed.

Parameters:

  • value (IO, String) —

    IO to write to or filename to write to

168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/rspec/core/configuration.rb', line 168
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! ⇒ void

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 similar) 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
1871
1872
1873
1874
1875
1876
 
# File 'lib/rspec/core/configuration.rb', line 1871
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 ⇒ void

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

1369
1370
1371
 
# File 'lib/rspec/core/configuration.rb', line 1369
def exclusion_filter
  filter_manager.exclusions
end

#exclusion_filter=(filter) ⇒ void

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.

1362
1363
1364
1365
 
# File 'lib/rspec/core/configuration.rb', line 1362
def exclusion_filter=(filter)
  meta = Metadata.build_hash_from([filter], :warn_about_example_group_filtering)
  filter_manager.exclude_only meta
end

#expect_with(*frameworks) ⇒ void

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

858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
 
# File 'lib/rspec/core/configuration.rb', line 858
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) ⇒ void

Delegates to expect_with(framework).

831
832
833
 
# File 'lib/rspec/core/configuration.rb', line 831
def expectation_framework=(framework)
  expect_with(framework)
end

#expectation_frameworks ⇒ void

Returns the configured expectation framework adapter module(s)

819
820
821
822
823
824
825
826
827
828
 
# File 'lib/rspec/core/configuration.rb', line 819
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) ⇒ void

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
RSpec.describe MyClass do
  before do
    # `example` can be used here because of the above config.
    do_something if example.metadata[:type] == "foo"
  end
end

Parameters:

  • method_name (Symbol) —

    the name of the helper method

1809
1810
1811
1812
1813
1814
1815
1816
 
# File 'lib/rspec/core/configuration.rb', line 1809
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) ⇒ void

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

151
152
153
154
155
156
157
158
159
 
# File 'lib/rspec/core/configuration.rb', line 151
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) 
143
144
145
 
# File 'lib/rspec/core/configuration.rb', line 143
def expose_dsl_globally?
  Core::DSL.exposed_globally?
end

#extend(mod, *filters) ⇒ void

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
module PermissionHelpers
  def define_permissions
    # ...
  end
end
RSpec.configure do |config|
  config.extend(UiHelpers, :type => :request)
  config.extend(PermissionHelpers, :with_permissions, :type => :request)
end
describe "edit profile", :with_permissions, :type => :request do
  run_in_browser
  define_permissions
  it "does stuff in the client" do
    # ...
  end
end

See Also:

1518
1519
1520
1521
1522
 
# File 'lib/rspec/core/configuration.rb', line 1518
def extend(mod, *filters)
  define_mixed_in_module(mod, filters, @extend_modules, :extend) do |group|
    safe_extend(mod, group)
  end
end

#filter_gems_from_backtrace(*gem_names) ⇒ void

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

742
743
744
745
746
 
# File 'lib/rspec/core/configuration.rb', line 742
def filter_gems_from_backtrace(*gem_names)
  gem_names.each do |name|
    @backtrace_formatter.filter_gem(name)
  end
end

#filter_run_excluding(*args) ⇒ void

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
1349
1350
1351
1352
1353
 
# File 'lib/rspec/core/configuration.rb', line 1349
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) ⇒ void 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
1275
1276
1277
1278
1279
 
# File 'lib/rspec/core/configuration.rb', line 1275
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) ⇒ void

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.

1291
1292
1293
1294
1295
 
# File 'lib/rspec/core/configuration.rb', line 1291
def filter_run_when_matching(*args)
  when_first_matching_example_defined(*args) do
    filter_run(*args)
  end
end

#format_docstrings(&block) ⇒ void

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
1659
1660
1661
 
# File 'lib/rspec/core/configuration.rb', line 1659
def format_docstrings(&block)
  @format_docstrings_block = block_given? ? block : DEFAULT_FORMATTER
end

#formatters ⇒ Array

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

1024
1025
1026
 
# File 'lib/rspec/core/configuration.rb', line 1024
def formatters
  formatter_loader.formatters.dup
end

#full_backtrace=(true_or_false) ⇒ void

Toggle full backtrace.

908
909
910
 
# File 'lib/rspec/core/configuration.rb', line 908
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

902
903
904
 
# File 'lib/rspec/core/configuration.rb', line 902
def full_backtrace?
  @backtrace_formatter.full_backtrace?
end

#full_description ⇒ Array

Returns full description filter.

Returns:

  • (Array) —

    full description filter

977
978
979
 
# File 'lib/rspec/core/configuration.rb', line 977
def full_description
  filter.fetch :full_description, nil
end

#full_description=(description) ⇒ void

Run examples matching on description in all files to run.

Parameters:

  • description (String, Regexp) —

    the pattern to filter on

972
973
974
 
# File 'lib/rspec/core/configuration.rb', line 972
def full_description=(description)
  filter_run :full_description => Regexp.union(*Array(description).map { |d| Regexp.new(d) })
end

#include(mod, *filters) ⇒ void

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 PreferencesHelpers
  def preferences(user, preferences = {})
    # ...
  end
end
module UserHelpers
  def users(username)
    # ...
  end
end
RSpec.configure do |config|
  config.include(UserHelpers) # included in all groups

  # included in examples with `:preferences` metadata
  config.include(PreferenceHelpers, :preferences)
  # included in examples with `:type => :request` metadata
  config.include(AuthenticationHelpers, :type => :request)
  # included in examples where the `:type` metadata matches a proc condition
  config.include(AuthenticationHelpers, :type => proc { |type, _metadata| [:request, :controller].include?(type) })
end
describe "edit profile", :preferences, :type => :request do
  it "can be viewed by owning user" do
     preferences(users(:jdoe), :lang => 'es')
    get "/profiles/jdoe"
    assert_select ".username", :text => 'jdoe'
  end
end

See Also:

1428
1429
1430
1431
1432
 
# File 'lib/rspec/core/configuration.rb', line 1428
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) ⇒ void

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 admin user" do
  let(:admin_user) { create_user(:admin) }
end
RSpec.shared_context "example guest user" do
  let(:guest_user) { create_user(:guest) }
end
RSpec.configure do |config|
  config.include_context "example guest user", :type => :request
  config.include_context "example admin user", :admin, :type => :request
end
RSpec.describe "The admin page", :type => :request do
  it "can be viewed by admins", :admin 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:

1475
1476
1477
1478
 
# File 'lib/rspec/core/configuration.rb', line 1475
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_filter ⇒ void Also known as: filter

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

1313
1314
1315
 
# File 'lib/rspec/core/configuration.rb', line 1313
def inclusion_filter
  filter_manager.inclusions
end

#inclusion_filter=(filter) ⇒ void 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.

1304
1305
1306
1307
 
# File 'lib/rspec/core/configuration.rb', line 1304
def inclusion_filter=(filter)
  meta = Metadata.build_hash_from([filter], :warn_about_example_group_filtering)
  filter_manager.include_only meta
end

#mock_framework ⇒ Symbol

Returns the configured mock framework adapter module.

Returns:

  • (Symbol) 
669
670
671
672
673
674
675
676
677
678
 
# File 'lib/rspec/core/configuration.rb', line 669
def mock_framework
  if @mock_framework.nil?
    begin
      mock_with :rspec
    rescue LoadError
      mock_with :nothing
    end
  end
  @mock_framework
end

#mock_framework=(framework) ⇒ void

Delegates to mock_framework=(framework).

681
682
683
 
# File 'lib/rspec/core/configuration.rb', line 681
def mock_framework=(framework)
  mock_with framework
end

#mock_with(framework) ⇒ void

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

786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
 
# File 'lib/rspec/core/configuration.rb', line 786
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) ⇒ void

Invokes block before defining an example group

2112
2113
2114
 
# File 'lib/rspec/core/configuration.rb', line 2112
def on_example_group_definition(&block)
  on_example_group_definition_callbacks << block
end

#on_example_group_definition_callbacks ⇒ void

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

2118
2119
2120
 
# File 'lib/rspec/core/configuration.rb', line 2118
def on_example_group_definition_callbacks
  @on_example_group_definition_callbacks ||= []
end

#order=(value) ⇒ void

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:

1704
 
# File 'lib/rspec/core/configuration.rb', line 1704
delegate_to_ordering_manager :order=

#prepend(mod, *filters) ⇒ void

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:

1557
1558
1559
1560
1561
 
# File 'lib/rspec/core/configuration.rb', line 1557
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) ⇒ void

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. Conditions passed along with :suite are effectively ignored.

See Also:

2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
 
# File 'lib/rspec/core/configuration.rb', line 2004
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! ⇒ void

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
1831
1832
1833
 
# File 'lib/rspec/core/configuration.rb', line 1831
def raise_errors_for_deprecations!
  self.deprecation_stream = Formatters::DeprecationFormatter::RaiseErrorStream.new
end

#raise_on_warning=(value) ⇒ void

Turns RSpec warnings into errors. This can be useful when you want RSpec to run in a 'strict' no warning situation. (Note this does not capture or raise on Ruby warnings).

Examples:


RSpec.configure do |rspec|
  rspec.raise_on_warning = true
end
1779
1780
1781
1782
1783
1784
1785
 
# File 'lib/rspec/core/configuration.rb', line 1779
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| ... } ⇒ void

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.metadata[: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:

1752
 
# File 'lib/rspec/core/configuration.rb', line 1752
delegate_to_ordering_manager :register_ordering

#reporter ⇒ RSpec::Core::Reporter

Returns the currently configured reporter.

Returns:

1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
 
# File 'lib/rspec/core/configuration.rb', line 1056
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

#seed ⇒ void

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.

1694
 
# File 'lib/rspec/core/configuration.rb', line 1694
delegate_to_ordering_manager :seed

#seed=(value) ⇒ void

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

1680
 
# File 'lib/rspec/core/configuration.rb', line 1680
delegate_to_ordering_manager :seed=

#treat_symbols_as_metadata_keys_with_true_values=(_value) ⇒ void

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.

383
384
385
386
387
388
389
390
 
# File 'lib/rspec/core/configuration.rb', line 383
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) ⇒ void

Set Ruby warnings on or off.

1758
1759
1760
 
# File 'lib/rspec/core/configuration.rb', line 1758
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.

1763
1764
1765
 
# File 'lib/rspec/core/configuration.rb', line 1763
def warnings?
  $VERBOSE
end

#when_first_matching_example_defined(*filters) ⇒ void

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
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
 
# File 'lib/rspec/core/configuration.rb', line 1921
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