Class: RSpec::Core::Configuration

Relationships & Source Files
Namespace Children
Modules: `ExposeCurrentExample`
Classes: `DeprecationReporterBuffer`
Exceptions: `MustBeConfiguredBeforeExampleGroupsError`
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, Module.new, `Hooks`
Inherits:	Object
Defined in:	rspec-core/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) { log_in_as :authorized }
  c.around(:example) { |ex| Database.transaction(&ex) }
end

See Also:

Constant Summary

DEFAULT_FORMATTER = Internal use only
# File 'rspec-core/lib/rspec/core/configuration.rb', line 1658
```
lambda { |string| string }
```
FAILED_STATUS = Internal use only
# File 'rspec-core/lib/rspec/core/configuration.rb', line 1133
```
"failed".freeze
```

MOCKING_ADAPTERS = Internal use only
# File 'rspec-core/lib/rspec/core/configuration.rb', line 756

{
  :rspec    => :RSpec,
  :flexmock => :Flexmock,
  :rr       => :RR,
  :mocha    => :Mocha,
  :nothing  => :Null
}

PASSED_STATUS = Internal use only
# File 'rspec-core/lib/rspec/core/configuration.rb', line 1136
```
"passed".freeze
```
PENDING_STATUS = Internal use only
# File 'rspec-core/lib/rspec/core/configuration.rb', line 1139
```
"pending".freeze
```
RAISE_ERROR_WARNING_NOTIFIER = Internal use only
# File 'rspec-core/lib/rspec/core/configuration.rb', line 1777
```
lambda { |message| raise message }
```
Readers = Internal use only

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

# File 'rspec-core/lib/rspec/core/configuration.rb', line 53
```
Module.new
```
UNKNOWN_STATUS = Internal use only
# File 'rspec-core/lib/rspec/core/configuration.rb', line 1130
```
"unknown".freeze
```
VALID_STATUSES = Internal use only
# File 'rspec-core/lib/rspec/core/configuration.rb', line 1142
```
[UNKNOWN_STATUS, FAILED_STATUS, PASSED_STATUS, PENDING_STATUS]
```

Class Method Summary

.add_read_only_setting(name, opts = {}) Internal use only Internal use only

As .add_setting but only add the reader.
.add_setting(name, opts = {}) Internal use only Internal use only

Invoked by the .add_setting instance method.
.define_alias(name, alias_name) Internal use only Internal use only
.define_predicate(name) Internal use only Internal use only
.define_reader(name) Internal use only Internal use only
.delegate_to_ordering_manager(*methods) Internal use only Internal use only
.new ⇒ Configuration constructor

Build an object to store runtime configuration options and set defaults.

Instance Attribute Summary

#backtrace_exclusion_patterns ⇒ Array<Regexp> rw

Regexps used to exclude lines from backtraces.
#backtrace_exclusion_patterns=(patterns) rw

Set regular expressions used to exclude lines in backtrace.
#backtrace_formatter readonly Internal use only Internal use only
#backtrace_inclusion_patterns ⇒ Array<Regexp> rw

Regexps used to include lines in backtraces.
#backtrace_inclusion_patterns=(patterns) rw

Set regular expressions used to include lines in backtrace.
#bisect_runner ⇒ Symbol rw

Determines which bisect runner implementation gets used to run subsets of the suite during a bisection.
#bisect_runner=(value) rw
#color ⇒ Boolean rw deprecated 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.
#color=(value) rw deprecated 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.
#color_mode ⇒ Boolean rw

The mode for determining whether to display output in color.
#color_mode=(value) rw

Set the color mode.
#default_color ⇒ Symbol rw

The default output color.
#default_formatter rw

The formatter that will be used if no formatter has been set.
#default_formatter=(value) rw

Sets a fallback formatter to use if none other has been set.
#default_path ⇒ String rw

Path to use if no path is provided to the rspec command (default: “spec”).
#default_path=(path) ⇒ String rw

Path to use if no path is provided to the rspec command (default: “spec”).
#deprecation_stream ⇒ IO, String rw

Determines where deprecation warnings are printed.
#deprecation_stream=(value) rw

Determines where deprecation warnings are printed.
#detail_color ⇒ Symbol rw

Color used to print details.
#disable_monkey_patching rw Internal use only Internal use only
#drb ⇒ Boolean rw

Run examples over DRb (default: false).
#drb_port rw

The drb_port (default: nil).
#dry_run rw

Prints the formatter output of your suite without running any examples or hooks.
#error_exit_code ⇒ Integer rw

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

Default: $stderr.
#example_status_persistence_file_path ⇒ String rw

The file path to use for persisting example statuses.
#example_status_persistence_file_path=(value) rw

Sets the file path to use for persisting example statuses.
#exclude_pattern ⇒ String rw

Exclude files matching this pattern.
#exclude_pattern=(value) rw

Set pattern to match files to exclude.
#exclusion_filter rw

Returns the #exclusion_filter.
#exclusion_filter=(filter) rw

Clears and reassigns the #exclusion_filter.
#expectation_framework=(framework) writeonly

Delegates to expect_with(framework).
#expose_dsl_globally=(value) rw

Use this to expose the core ::RSpec DSL via Module and the main object.
#expose_dsl_globally? ⇒ Boolean rw

Indicates if the DSL has been exposed off of modules and main.
#fail_fast rw

If specified, indicates the number of failures required before cleaning up and exit (default: nil).
#fail_fast=(value) rw
#fail_if_no_examples ⇒ Boolean rw

Whether or not to fail when there are no ::RSpec examples (default: false).
#failure_color ⇒ Symbol rw

Color to use to indicate failure.
#failure_exit_code ⇒ Integer rw

The exit code to return if there are any failures (default: 1).
#files_to_run ⇒ Array rw

The spec files ::RSpec will run.
#files_to_run=(value) rw Internal use only Internal use only
#filter rw

Alias for #inclusion_filter.
#filter_manager rw Internal use only Internal use only
#fixed_color ⇒ Symbol rw

Color used when a pending example is fixed.
#full_backtrace=(true_or_false) rw

Toggle full backtrace.
#full_backtrace? ⇒ Boolean rw

Check if full backtrace is enabled.
#full_description ⇒ Array rw
#full_description=(description) rw

Run examples matching on description in all files to run.
#inclusion_filter (also: #filter) rw

Returns the #inclusion_filter.
#inclusion_filter=(filter) (also: #filter=) rw

Clears and reassigns the #inclusion_filter.
#libs ⇒ Array<String> rw

Returns dirs that have been prepended to the load path by the -I command line option.
#libs=(libs) rw Internal use only Internal use only
#loaded_spec_files readonly Internal use only Internal use only
#max_displayed_failure_line_count rw

Maximum count of failed source lines to display in the failure reports (defaults to 10).
#mock_framework ⇒ Symbol rw

Returns the configured mock framework adapter module.
#mock_framework=(framework) rw

Delegates to mock_framework=(framework).
#only_failures? readonly

Alias for #only_failures.
#only_failures_but_not_configured? ⇒ Boolean readonly Internal use only Internal use only
#ordering_manager readonly Internal use only Internal use only
#output_stream ⇒ IO, String rw

Determines where ::RSpec will send its output.
#output_stream=(value) rw

Set the output stream for reporter.
#pattern ⇒ String rw

Load files matching this pattern (default: ‘’**,//*/*_spec.rb’‘).
#pattern=(value) rw

Set pattern to match files to load.
#pending_color ⇒ Symbol rw

Color to use to print pending examples.
#pending_failure_output rw

Format the output for pending examples.
#pending_failure_output=(mode) rw

Format the output for pending examples.
#profile_examples ⇒ Boolean rw

Report the times for the slowest examples (default: false).
#profile_examples=(value) ⇒ Boolean rw

Report the times for the slowest examples (default: false).
#project_source_dirs ⇒ Array<String> rw

Specifies which directories contain the source code for your project.
#raise_on_warning=(value) writeonly

Turns RSpec warnings into errors.
#requires ⇒ Array<String> rw

Indicates files configured to be required.
#requires=(paths) rw Internal use only Internal use only
#run_all_when_everything_filtered rw deprecated Deprecated.

Use #filter_run_when_matching instead for the specific filters that you want to be ignored if none match.
#shared_context_metadata_behavior ⇒ :trigger_inclusion, :apply_to_host_groups rw

Configures how ::RSpec treats metadata passed as part of a shared example group definition.
#shared_context_metadata_behavior=(value) rw
#silence_filter_announcements rw

Don’t print filter info i.e. “Run options: include :focus=>true” (default false).
#static_config_filter_manager rw Internal use only Internal use only
#success_color ⇒ Symbol rw

Color to use to indicate success.
#threadsafe rw

Use threadsafe options where available.
#treat_symbols_as_metadata_keys_with_true_values=(_value) writeonly deprecated 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.
#warnings=(value) rw

Set Ruby warnings on or off.
#warnings? ⇒ Boolean rw
#world rw Internal use only Internal use only
#pattern_might_load_specs_from_vendored_dirs? ⇒ Boolean readonly private
#rspec_expectations_loaded? ⇒ Boolean readonly private
#rspec_mocks_loaded? ⇒ Boolean readonly private

Instance Method Summary

#add_formatter(formatter) (also: #formatter=)

Adds a formatter to the set ::RSpec will use for this run.
#add_setting(name)

Adds a custom setting to the ::RSpec.configuration object.
#after(scope = nil, *meta, &block) (also: #prepend_after)

Defines a #after hook.
#alias_example_group_to(new_name, *args)

Creates a method that defines an example group with the provided metadata.
#alias_example_to(name, *args)

Creates a method that delegates to example including the submitted args.
#alias_it_behaves_like_to(new_name, report_label = '') (also: #alias_it_should_behave_like_to)

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.
#alias_it_should_behave_like_to(new_name, report_label = '')

Alias for #alias_it_behaves_like_to.
#append_after(scope = nil, *meta, &block)

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.
#append_before(scope = nil, *meta, &block)

Alias for #before.
#apply_derived_metadata_to(metadata) Internal use only Internal use only
#around(scope = nil, *meta, &block)

Registers block as an #around hook.
#before(scope = nil, *meta, &block) (also: #append_before)

Defines a #before hook.
#bisect_runner_class Internal use only Internal use only
#color_enabled?(output = output_stream) ⇒ Boolean

Check if color is enabled for a particular output.
#configure_example(example, example_hooks) Internal use only Internal use only

Used internally to extend the singleton class of a single example’s example group instance with modules using #include and/or #extend.
#configure_expectation_framework Internal use only Internal use only
#configure_group(group) Internal use only Internal use only

Used internally to extend a group with modules using #include, #prepend and/or #extend.
#configure_mock_framework Internal use only Internal use only
#define_derived_metadata(*filters) {|metadata| ... }

Defines a callback that can assign derived metadata values.
#disable_monkey_patching!

Enables zero monkey patching mode for ::RSpec.
#expect_with(*frameworks)

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

Returns the configured expectation framework adapter module(s).
#expose_current_running_example_as(method_name)

Exposes the current running example via the named helper method.
#extend(mod, *filters)

Tells RSpec to extend example groups with mod.
#files_or_directories_to_run=(*files) Internal use only Internal use only
#filter_gems_from_backtrace(*gem_names)

Adds #backtrace_exclusion_patterns that will filter lines from the named gems from backtraces.
#filter_run(*args)

Alias for #filter_run_including.
#filter_run_excluding(*args)

Adds key/value pairs to the #exclusion_filter.
#filter_run_including(*args) (also: #filter_run)

Adds key/value pairs to the #inclusion_filter.
#filter_run_when_matching(*args)

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.
#force(hash) Internal use only Internal use only

Used to set higher priority option values from the command line.
#format_docstrings(&block)

Formats the docstring output using the block provided.
#format_docstrings_block Internal use only Internal use only
#formatter=(formatter, output = output_wrapper)

Alias for #add_formatter.
#formatter_loader Internal use only Internal use only
#formatters ⇒ Array

Returns a duplicate of the formatters currently loaded in the FormatterLoader for introspection.
#hooks Internal use only Internal use only

Holds the various registered hooks.
#in_project_source_dir_regex Internal use only Internal use only
#include(mod, *filters)

Tells RSpec to include mod in example groups.
#include_context(shared_group_name, *filters)

Tells RSpec to include the named shared example group in example groups.
#last_run_statuses Internal use only Internal use only
#load_spec_files Internal use only Internal use only
#mock_with(framework)

Sets the mock framework adapter module.
#on_example_group_definition(&block)

Invokes block before defining an example group.
#on_example_group_definition_callbacks Internal use only Internal use only

Returns an array of blocks to call before defining an example group.
#only_failures (also: #only_failures?) readonly

Indicates if the –only-failures (or –next-failure) flag is being used.
#order=(value)

Sets the default global ordering strategy.
#prepend(mod, *filters)

Tells RSpec to prepend example groups with mod.
#prepend_after(scope = nil, *meta, &block)

Alias for #after.
#prepend_before(scope = nil, *meta, &block)

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.
#raise_errors_for_deprecations!

Turns deprecation warnings into errors, in order to surface the full backtrace of the call site.
#register_ordering(name) {|list| ... }

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.
#reporter ⇒ RSpec::Core::Reporter
#reset Internal use only Internal use only
#reset_filters Internal use only Internal use only
#reset_reporter Internal use only Internal use only
#seed

Seed for random ordering (default: generated randomly each run).
#seed=(value)

Sets the seed value and sets the default global ordering to random.
#spec_files_with_failures Internal use only Internal use only
#when_first_matching_example_defined(*filters)

Defines a callback that runs after the first example with matching metadata is defined.
#with_suite_hooks Internal use only Internal use only
#absolute_pattern?(pattern) ⇒ Boolean private

:nocov:
#add_hook_to_existing_matching_groups(meta, scope, &block) private
#assert_no_example_groups_defined(config_option) private
#clear_values_derived_from_example_status_persistence_file_path private
#command private
#conditionally_disable_expectations_monkey_patching private
#conditionally_disable_mocks_monkey_patching private
#configure_group_with(group, module_list, application_method) private
#define_built_in_hooks private
#define_mixed_in_module(mod, filters, mod_list, config_method, &block) private
#extract_location(path) private
#file_glob_from(path, pattern) private
#gather_directories(path) private
#get_files_to_run(paths) private
#get_matching_files(path, pattern) private
#handle_suite_hook(scope, meta) private
#load_file_handling_errors(method, file) private
#metadata_applies_to_group?(meta, group) ⇒ Boolean private
#on_existing_matching_groups(meta) private
#output_to_tty?(output = output_stream) ⇒ Boolean private
#output_wrapper private
#paths_to_check(paths) private
#run_suite_hooks(hook_description, hooks) private
#safe_extend(mod, host) private

See additional method definition at line 2399.
#safe_include(mod, host) private

:nocov:
#safe_prepend(mod, host) private
#update_pattern_attr(name, value) private
#value_for(key) private
#windows_absolute_network_path?(pattern) ⇒ Boolean private

`Hooks` - Included

#after	Declare a block of code to be run after each example (using `:example`) or once after all examples n the context (using `:context`).
#append_after	Adds `block` to the back of the list of #after blocks in the same scope (‘:example`, `:context`, or `:suite`).
#append_before	Alias for Hooks#before.
#around	Declare a block of code, parts of which will be run before and parts after the example.
#before	Declare a block of code to be run before each example (using `:example`) or once before any example (using `:context`).
#hooks	Holds the various registered hooks.
#prepend_after	Alias for Hooks#after.
#prepend_before	Adds `block` to the front of the list of #before blocks in the same scope (‘:example`, `:context`, or `:suite`).

Constructor Details

.new ⇒ `Configuration`

Build an object to store runtime configuration options and set defaults

[ GitHub ]

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


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
  @force_line_number_for_spec_rerun = false

  define_built_in_hooks
end

Class Method Details

.add_read_only_setting(name, opts = {})

This method is for internal use only.

As .add_setting but only add the reader.

[ GitHub ]

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


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

.add_setting(name, opts = {})

This method is for internal use only.

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

[ GitHub ]

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


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_alias(name, alias_name)
  end
end

.define_alias(name, alias_name)

This method is for internal use only.

[ GitHub ]

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


def self.define_alias(name, alias_name)
  alias_method alias_name, name
  alias_method "#{alias_name}=", "#{name}="
  define_predicate alias_name
end

.define_predicate(name)

This method is for internal use only.

[ GitHub ]

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


def self.define_predicate(name)
  define_method "#{name}?" do
    !!send(name)
  end
end

.define_reader(name)

This method is for internal use only.

[ GitHub ]

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


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)

This method is for internal use only.

[ GitHub ]

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


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

#backtrace_exclusion_patterns ⇒ `Array`<`Regexp`> (rw)

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.

[ GitHub ]

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


def backtrace_exclusion_patterns
  @backtrace_formatter.exclusion_patterns
end

#backtrace_exclusion_patterns=(patterns) (rw)

Set regular expressions used to exclude lines in backtrace.

Parameters:

patterns (Array<Regexp>) —

set backtrace_formatter exclusion_patterns

[ GitHub ]

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


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

#backtrace_formatter (readonly)

This method is for internal use only.

[ GitHub ]

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


attr_reader :backtrace_formatter, :ordering_manager, :loaded_spec_files

#backtrace_inclusion_patterns ⇒ `Array`<`Regexp`> (rw)

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.

[ GitHub ]

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


def backtrace_inclusion_patterns
  @backtrace_formatter.inclusion_patterns
end

#backtrace_inclusion_patterns=(patterns) (rw)

Set regular expressions used to include lines in backtrace.

[ GitHub ]

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


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

#bisect_runner ⇒ `Symbol` (rw)

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

[ GitHub ]

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


attr_reader :bisect_runner

#bisect_runner=(value) (rw)

[ GitHub ]

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


def bisect_runner=(value)
  if @bisect_runner_class && value != @bisect_runner
    raise "`config.bisect_runner = #{value.inspect}` can no longer take " \
      "effect as the #{@bisect_runner.inspect} bisect runnner is already " \
      "in use. This config setting must be set in a file loaded by a " \
      "`--require` option (passed at the CLI or in a `.rspec` file) for " \
      "it to have any effect."
  end

  @bisect_runner = value
end

#color ⇒ `Boolean` (rw)

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.

See Also:

#color_mode
#color_enabled?

[ GitHub ]

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


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

#color=(value) (rw)

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.

Toggle output color.

[ GitHub ]

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


attr_writer :color

#color_mode ⇒ `Boolean` (rw)

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

See Also:

#color_enabled?

[ GitHub ]

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


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

#color_mode=(value) (rw)

Set the color mode.

[ GitHub ]

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


attr_writer :color_mode

#default_color ⇒ `Symbol` (rw)

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

[ GitHub ]

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


add_setting :default_color

#default_formatter (rw)

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

[ GitHub ]

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


def default_formatter
  formatter_loader.default_formatter
end

#default_formatter=(value) (rw)

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

Examples:

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

[ GitHub ]

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


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

#default_path ⇒ `String` (rw)

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.

[ GitHub ]

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


add_read_only_setting :default_path

#default_path=(path) ⇒ `String` (rw)

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.

[ GitHub ]

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


add_read_only_setting :default_path

#deprecation_stream ⇒ `IO`, `String` (rw)

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

Returns:

(IO, String) —

IO or filename to write to

[ GitHub ]

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


define_reader :deprecation_stream

#deprecation_stream=(value) (rw)

Determines where deprecation warnings are printed.

Parameters:

value (IO, String) —

IO to write to or filename to write to

[ GitHub ]

# File 'rspec-core/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

#detail_color ⇒ `Symbol` (rw)

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

[ GitHub ]

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


add_setting :detail_color

#disable_monkey_patching (rw)

This method is for internal use only.

[ GitHub ]

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


attr_accessor :disable_monkey_patching

#drb ⇒ `Boolean` (rw)

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

[ GitHub ]

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


add_setting :drb

#drb_port (rw)

The drb_port (default: nil).

[ GitHub ]

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


add_setting :drb_port

#dry_run (rw)

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

[ GitHub ]

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


add_setting :dry_run

#error_exit_code ⇒ `Integer` (rw)

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

[ GitHub ]

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


add_setting :error_exit_code

#error_stream (rw)

Default: $stderr.

[ GitHub ]

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


add_setting :error_stream

#example_status_persistence_file_path ⇒ `String` (rw) #example_status_persistence_file_path=(value)

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:
- (String) —
  
  the file path
#example_status_persistence_file_path=(value)
Parameters:
- value (String) —
  
  the file path

[ GitHub ]

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


define_reader :example_status_persistence_file_path

#example_status_persistence_file_path=(value) (rw)

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

[ GitHub ]

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


def example_status_persistence_file_path=(value)
  @example_status_persistence_file_path = value
  clear_values_derived_from_example_status_persistence_file_path
end

#exclude_pattern ⇒ `String` (rw)

Exclude files matching this pattern.

[ GitHub ]

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


define_reader :exclude_pattern

#exclude_pattern=(value) (rw)

Set pattern to match files to exclude.

[ GitHub ]

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


def exclude_pattern=(value)
  update_pattern_attr :exclude_pattern, value
end

#exclusion_filter (rw)

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

[ GitHub ]

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


def exclusion_filter
  filter_manager.exclusions
end

#exclusion_filter=(filter) (rw)

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.

[ GitHub ]

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


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

#expectation_framework=(framework) (writeonly)

Delegates to expect_with(framework).

[ GitHub ]

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


def expectation_framework=(framework)
  expect_with(framework)
end

#expose_dsl_globally=(value) (rw)

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

[ GitHub ]

# File 'rspec-core/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` (rw)

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

[ GitHub ]

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


def expose_dsl_globally?
  Core::DSL.exposed_globally?
end

#fail_fast (rw)

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

[ GitHub ]

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


define_reader :fail_fast

#fail_fast=(value) (rw)

See Also:

#fail_fast

[ GitHub ]

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


def fail_fast=(value)
  case value
  when true, 'true'
    @fail_fast = true
  when false, 'false', 0
    @fail_fast = false
  when nil
    @fail_fast = nil
  else
    @fail_fast = value.to_i

    if value.to_i == 0
      # TODO: in RSpec 4, consider raising an error here.
      RSpec.warning "Cannot set `RSpec.configuration.fail_fast`" \
        " to `#{value.inspect}`. Only `true`, `false`, `nil` and integers" \
        " are valid values."
      @fail_fast = true
    end
  end
end

#fail_if_no_examples ⇒ `Boolean` (rw)

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

[ GitHub ]

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


add_setting :fail_if_no_examples

#failure_color ⇒ `Symbol` (rw)

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

[ GitHub ]

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


add_setting :failure_color

#failure_exit_code ⇒ `Integer` (rw)

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

[ GitHub ]

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


add_setting :failure_exit_code

#files_to_run ⇒ `Array` (rw)

The spec files ::RSpec will run.

Returns:

(Array) —

specified files about to run

[ GitHub ]

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


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

#files_to_run=(value) (rw)

This method is for internal use only.

[ GitHub ]

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


attr_writer :files_to_run

#filter (rw)

Alias for #inclusion_filter.

[ GitHub ]

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


alias_method :filter, :inclusion_filter

#filter_manager (rw)

This method is for internal use only.

[ GitHub ]

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


attr_accessor :filter_manager, :world

#fixed_color ⇒ `Symbol` (rw)

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

[ GitHub ]

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


add_setting :fixed_color

#full_backtrace=(true_or_false) (rw)

Toggle full backtrace.

[ GitHub ]

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


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

#full_backtrace? ⇒ `Boolean` (rw)

Check if full backtrace is enabled.

Returns:

(Boolean) —

is full backtrace enabled

[ GitHub ]

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


def full_backtrace?
  @backtrace_formatter.full_backtrace?
end

#full_description ⇒ `Array` (rw)

Returns:

(Array) —

full description filter

[ GitHub ]

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


def full_description
  filter.fetch :full_description, nil
end

#full_description=(description) (rw)

Run examples matching on description in all files to run.

Parameters:

description (String, Regexp) —

the pattern to filter on

[ GitHub ]

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


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

#inclusion_filter (rw) Also known as: #filter

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

[ GitHub ]

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


def inclusion_filter
  filter_manager.inclusions
end

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

[ GitHub ]

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


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

#libs ⇒ `Array`<`String`> (rw)

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

[ GitHub ]

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


define_reader :libs

#libs=(libs) (rw)

This method is for internal use only.

[ GitHub ]

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


def libs=(libs)
  libs.map do |lib|
    @libs.unshift lib
    $LOAD_PATH.unshift lib
  end
end

#loaded_spec_files (readonly)

This method is for internal use only.

[ GitHub ]

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


attr_reader :backtrace_formatter, :ordering_manager, :loaded_spec_files

#max_displayed_failure_line_count (rw)

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

[ GitHub ]

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


add_setting :max_displayed_failure_line_count

#mock_framework ⇒ `Symbol` (rw)

Returns the configured mock framework adapter module.

[ GitHub ]

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


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

#mock_framework=(framework) (rw)

Delegates to mock_framework=(framework).

[ GitHub ]

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


def mock_framework=(framework)
  mock_with framework
end

#only_failures? (readonly)

Alias for #only_failures.

[ GitHub ]

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


alias_method :only_failures?, :only_failures

#only_failures_but_not_configured? ⇒ `Boolean` (readonly)

This method is for internal use only.

[ GitHub ]

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


def only_failures_but_not_configured?
  only_failures? && !example_status_persistence_file_path
end

#ordering_manager (readonly)

This method is for internal use only.

[ GitHub ]

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


attr_reader :backtrace_formatter, :ordering_manager, :loaded_spec_files

#output_stream ⇒ `IO`, `String` (rw)

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

[ GitHub ]

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


define_reader :output_stream

#output_stream=(value) (rw)

Set the output stream for reporter.

See additional method definition at line 270.

[ GitHub ]

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


define_reader :output_stream

#pattern ⇒ `String` (rw)

Load files matching this pattern (default: ‘’**,//*/*_spec.rb’‘).

[ GitHub ]

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


define_reader :pattern

#pattern=(value) (rw)

Set pattern to match files to load.

[ GitHub ]

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


def pattern=(value)
  update_pattern_attr :pattern, value
end

#pattern_might_load_specs_from_vendored_dirs? ⇒ `Boolean` (readonly, private)

[ GitHub ]

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


def pattern_might_load_specs_from_vendored_dirs?
  pattern.split(File::SEPARATOR).first.include?('**')
end

#pending_color ⇒ `Symbol` (rw)

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

[ GitHub ]

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


add_setting :pending_color

#pending_failure_output (rw)

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)

[ GitHub ]

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


add_read_only_setting :pending_failure_output

#pending_failure_output=(mode) (rw)

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)

[ GitHub ]

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


add_read_only_setting :pending_failure_output

#profile_examples ⇒ `Boolean` (rw)

Report the times for the slowest examples (default: false). Use this to specify the number of examples to include in the profile.

[ GitHub ]

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


def profile_examples
  profile = value_for(:profile_examples) { @profile_examples }
  if profile && !profile.is_a?(Integer)
    10
  else
    profile
  end
end

#profile_examples=(value) ⇒ `Boolean` (rw)

Report the times for the slowest examples (default: false). Use this to specify the number of examples to include in the profile.

[ GitHub ]

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


attr_writer :profile_examples

#project_source_dirs ⇒ `Array`<`String`> (rw)

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.

[ GitHub ]

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


add_setting :project_source_dirs

#raise_on_warning=(value) (writeonly)

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

[ GitHub ]

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


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

#requires ⇒ `Array`<`String`> (rw)

Indicates files configured to be required.

[ GitHub ]

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


define_reader :requires

#requires=(paths) (rw)

This method is for internal use only.

[ GitHub ]

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


def requires=(paths)
  directories = ['lib', default_path].select { |p| File.directory? p }
  RSpec::Core::RubyProject.add_to_load_path(*directories)
  paths.each { |path|
    load_file_handling_errors(:require, path)
    @requires << path
  }
end

#rspec_expectations_loaded? ⇒ `Boolean` (readonly, private)

[ GitHub ]

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


def rspec_expectations_loaded?
  defined?(RSpec::Expectations.configuration)
end

#rspec_mocks_loaded? ⇒ `Boolean` (readonly, private)

[ GitHub ]

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


def rspec_mocks_loaded?
  defined?(RSpec::Mocks.configuration)
end

#run_all_when_everything_filtered (rw)

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

[ GitHub ]

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


add_setting :run_all_when_everything_filtered

#shared_context_metadata_behavior ⇒ `:trigger_inclusion`, `:apply_to_host_groups` (rw) #shared_context_metadata_behavior=(value)

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:

:trigger_inclusion: this shared context will be implicitly included in any groups (or examples) that have ‘:db => true` metadata.
: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:
- (:trigger_inclusion, :apply_to_host_groups) —
  
  the configured behavior
#shared_context_metadata_behavior=(value)
Parameters:
- value (:trigger_inclusion, :apply_to_host_groups) —
  
  sets the configured behavior

[ GitHub ]

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


define_reader :shared_context_metadata_behavior

#shared_context_metadata_behavior=(value) (rw)

See Also:

#shared_context_metadata_behavior

[ GitHub ]

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


def shared_context_metadata_behavior=(value)
  case value
  when :trigger_inclusion, :apply_to_host_groups
    @shared_context_metadata_behavior = value
  else
    raise ArgumentError, "Cannot set `RSpec.configuration." \
      "shared_context_metadata_behavior` to `#{value.inspect}`. Only " \
      "`:trigger_inclusion` and `:apply_to_host_groups` are valid values."
  end
end

#silence_filter_announcements (rw)

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

[ GitHub ]

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


add_setting :silence_filter_announcements

#static_config_filter_manager (rw)

This method is for internal use only.

[ GitHub ]

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


attr_accessor :static_config_filter_manager

#success_color ⇒ `Symbol` (rw)

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

[ GitHub ]

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


add_setting :success_color

#threadsafe (rw)

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

[ GitHub ]

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


add_setting :threadsafe

#treat_symbols_as_metadata_keys_with_true_values=(_value) (writeonly)

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.

[ GitHub ]

# File 'rspec-core/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) (rw)

Set Ruby warnings on or off.

[ GitHub ]

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


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

#warnings? ⇒ `Boolean` (rw)

Returns:

(Boolean) —

Whether or not ruby warnings are enabled.

[ GitHub ]

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


def warnings?
  $VERBOSE
end

#world (rw)

This method is for internal use only.

[ GitHub ]

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


attr_accessor :filter_manager, :world

Instance Method Details

#absolute_pattern?(pattern) ⇒ `Boolean` (private)

:nocov:

See additional method definition at line 2251.

[ GitHub ]

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


def absolute_pattern?(pattern)
  pattern =~ /\A[A-Z]:\\/ || windows_absolute_network_path?(pattern)
end

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

Formatters::Protocol

[ GitHub ]

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


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

#add_hook_to_existing_matching_groups(meta, scope, &block) (private)

[ GitHub ]

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


def add_hook_to_existing_matching_groups(meta, scope, &block)
  # For example hooks, we have to apply it to each of the top level
  # groups, even if the groups do not match. When we apply it, we
  # apply it with the metadata, so it will only apply to examples
  # in the group that match the metadata.
  # #2280 for background and discussion.
  if scope == :example || scope == :each || scope.nil?
    world.example_groups.each(&block)
  else
    meta = Metadata.build_hash_from(meta.dup)
    on_existing_matching_groups(meta, &block)
  end
end

#add_setting(name) #add_setting(name, opts)

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

[ GitHub ]

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


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

#append_after
#before
#prepend_before

[ GitHub ]

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


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)

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:

#alias_example_to
#expose_dsl_globally=

[ GitHub ]

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


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)

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

[ GitHub ]

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


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

[ GitHub ]

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


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

#alias_it_should_behave_like_to(new_name, report_label = '')

Alias for #alias_it_behaves_like_to.

[ GitHub ]

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


alias_method :alias_it_should_behave_like_to, :alias_it_behaves_like_to

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

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:

#append_after
#before
#prepend_before

[ GitHub ]

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


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

#append_before(scope = nil, *meta, &block)

Alias for #before.

[ GitHub ]

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


alias_method :append_before, :before

#apply_derived_metadata_to(metadata)

This method is for internal use only.

Raises:

(SystemStackError)

[ GitHub ]

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


def apply_derived_metadata_to(metadata)
  already_run_blocks = Set.new

  # We loop and attempt to re-apply metadata blocks to support cascades
  # (e.g. where a derived bit of metadata triggers the application of
  # another piece of derived metadata, etc)
  #
  # We limit our looping to 200 times as a way to detect infinitely recursing derived metadata blocks.
  # It's hard to imagine a valid use case for a derived metadata cascade greater than 200 iterations.
  200.times do
    return if @derived_metadata_blocks.items_for(metadata).all? do |block|
      already_run_blocks.include?(block).tap do |skip_block|
        block.call(metadata) unless skip_block
        already_run_blocks << block
      end
    end
  end

  # If we got here, then `@derived_metadata_blocks.items_for(metadata).all?` never returned
  # `true` above and we treat this as an attempt to recurse infinitely. It's better to fail
  # with a clear # error than hang indefinitely, which is what would happen if we didn't limit
  # the looping above.
  raise SystemStackError, "Attempted to recursively derive metadata indefinitely."
end

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

Registers block as an around hook.

See Hooks#around for full around hook docs.

[ GitHub ]

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


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

#assert_no_example_groups_defined(config_option) (private)

Raises:

(MustBeConfiguredBeforeExampleGroupsError)

[ GitHub ]

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


def assert_no_example_groups_defined(config_option)
  return unless world.example_groups.any?

  raise MustBeConfiguredBeforeExampleGroupsError.new(
    "RSpec's #{config_option} configuration option must be configured before " \
    "any example groups are defined, but you have already defined a group."
  )
end

#before(scope = nil, *meta, &block) 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:

#prepend_before
#after
#append_after

[ GitHub ]

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


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

#bisect_runner_class

This method is for internal use only.

[ GitHub ]

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


def bisect_runner_class
  @bisect_runner_class ||= begin
    case bisect_runner
    when :fork
      RSpec::Support.require_rspec_core 'bisect/fork_runner'
      Bisect::ForkRunner
    when :shell
      RSpec::Support.require_rspec_core 'bisect/shell_runner'
      Bisect::ShellRunner
    else
      raise "Unsupported value for `bisect_runner` (#{bisect_runner.inspect}). " \
            "Only `:fork` and `:shell` are supported."
    end
  end
end

#clear_values_derived_from_example_status_persistence_file_path (private)

[ GitHub ]

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


def clear_values_derived_from_example_status_persistence_file_path
  @last_run_statuses = nil
  @spec_files_with_failures = nil
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

[ GitHub ]

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


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

#command (private)

[ GitHub ]

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


def command
  $0.split(File::SEPARATOR).last
end

#conditionally_disable_expectations_monkey_patching (private)

[ GitHub ]

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


def conditionally_disable_expectations_monkey_patching
  return unless disable_monkey_patching && rspec_expectations_loaded?

  RSpec::Expectations.configuration.syntax = :expect
end

#conditionally_disable_mocks_monkey_patching (private)

[ GitHub ]

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


def conditionally_disable_mocks_monkey_patching
  return unless disable_monkey_patching && rspec_mocks_loaded?

  RSpec::Mocks.configuration.tap do |config|
    config.syntax = :expect
    config.patch_marshal_to_support_partial_doubles = false
  end
end

#configure_example(example, example_hooks)

This method is for internal use only.

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

[ GitHub ]

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


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.with_replaced_metadata(example.metadata) do
    modules = @include_modules.items_for(example.metadata)
    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_framework

This method is for internal use only.

[ GitHub ]

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


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)

This method is for internal use only.

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

[ GitHub ]

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


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_group_with(group, module_list, application_method) (private)

[ GitHub ]

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


def configure_group_with(group, module_list, application_method)
  module_list.items_for(group.metadata).each do |mod|
    __send__(application_method, mod, group)
  end
end

#configure_mock_framework

This method is for internal use only.

[ GitHub ]

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


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

#define_built_in_hooks (private)

[ GitHub ]

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


def define_built_in_hooks
  around(:example, :aggregate_failures => true) do |procsy|
    begin
      aggregate_failures(nil, :hide_backtrace => true, &procsy)
    rescue Support::AllExceptionsExceptOnesWeMustNotRescue => exception
      procsy.example.set_aggregate_failures_exception(exception)
    end
  end
end

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

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.

[ GitHub ]

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


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

#define_mixed_in_module(mod, filters, mod_list, config_method, &block) (private)

[ GitHub ]

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


def define_mixed_in_module(mod, filters, mod_list, config_method, &block)
  unless Module === mod
    raise TypeError, "`RSpec.configuration.#{config_method}` expects a module but got: #{mod.inspect}"
  end

  meta = Metadata.build_hash_from(filters, :warn_about_example_group_filtering)
  mod_list.append(mod, meta)
  on_existing_matching_groups(meta, &block)
end

#disable_monkey_patching!

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

[ GitHub ]

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


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

#expect_with(*frameworks)

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 RSpec.configuration, expect_with will yield the RSpec.configuration object if given a block:

config.expect_with OtherExpectationFramework do |custom_config|
  custom_config.custom_setting = true
end

[ GitHub ]

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


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_frameworks

Returns the configured expectation framework adapter module(s)

[ GitHub ]

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


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)

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

[ GitHub ]

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


def expose_current_running_example_as(method_name)
  ExposeCurrentExample.module_exec do
    extend RSpec::SharedContext
    let(method_name) { |ex| ex }
  end

  include ExposeCurrentExample
end

#extend(mod, *filters)

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

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

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:

#include
#prepend

[ GitHub ]

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


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

#extract_location(path) (private)

[ GitHub ]

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


def extract_location(path)
  match = /^(.*?)((?:\:\d+)+)$/.match(path)

  if match
    captures = match.captures
    path = captures[0]
    lines = captures[1][1..-1].split(":").map(&:to_i)
    filter_manager.add_location path, lines
  else
    path, scoped_ids = Example.parse_id(path)
    filter_manager.add_ids(path, scoped_ids.split(/\s*,\s*/)) if scoped_ids
  end

  return [] if path == default_path
  File.expand_path(path)
end

#file_glob_from(path, pattern) (private)

[ GitHub ]

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


def file_glob_from(path, pattern)
  stripped = "{#{pattern.gsub(/\s*,\s*/, ',')}}"
  return stripped if pattern =~ /^(\.\/)?#{Regexp.escape path}/ || absolute_pattern?(pattern)
  File.join(path, stripped)
end

#files_or_directories_to_run=(*files)

This method is for internal use only.

[ GitHub ]

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


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)

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

[ GitHub ]

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


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

#filter_run(*args)

Alias for #filter_run_including.

[ GitHub ]

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


alias_method :filter_run, :filter_run_including

#filter_run_excluding(*args)

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

[ GitHub ]

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


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

[ GitHub ]

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


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)

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.

[ GitHub ]

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


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

#force(hash)

This method is for internal use only.

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

[ GitHub ]

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


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)

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

[ GitHub ]

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


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

#format_docstrings_block

This method is for internal use only.

[ GitHub ]

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


def format_docstrings_block
  @format_docstrings_block ||= DEFAULT_FORMATTER
end

#formatter=(formatter, output = output_wrapper)

Alias for #add_formatter.

[ GitHub ]

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


alias_method :formatter=, :add_formatter

#formatter_loader

This method is for internal use only.

[ GitHub ]

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


def formatter_loader
  @formatter_loader ||= Formatters::Loader.new(Reporter.new(self))
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

[ GitHub ]

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


def formatters
  formatter_loader.formatters.dup
end

#gather_directories(path) (private)

[ GitHub ]

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


def gather_directories(path)
  include_files = get_matching_files(path, pattern)
  exclude_files = get_matching_files(path, exclude_pattern)
  (include_files - exclude_files).uniq
end

#get_files_to_run(paths) (private)

[ GitHub ]

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


def get_files_to_run(paths)
  files = FlatMap.flat_map(paths_to_check(paths)) do |path|
    path = path.gsub(File::ALT_SEPARATOR, File::SEPARATOR) if File::ALT_SEPARATOR
    File.directory?(path) ? gather_directories(path) : extract_location(path)
  end.uniq

  return files unless only_failures?
  relative_files = files.map { |f| Metadata.relative_path(File.expand_path f) }
  intersection = (relative_files & spec_files_with_failures.to_a)
  intersection.empty? ? files : intersection
end

#get_matching_files(path, pattern) (private)

[ GitHub ]

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


def get_matching_files(path, pattern)
  raw_files = Dir[file_glob_from(path, pattern)]
  raw_files.map { |file| File.expand_path(file) }.sort
end

#handle_suite_hook(scope, meta) (private)

[ GitHub ]

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


def handle_suite_hook(scope, meta)
  return nil unless scope == :suite

  unless meta.empty?
    # TODO: in RSpec 4, consider raising an error here.
    # We warn only for backwards compatibility.
    RSpec.warn_with "WARNING: `:suite` hooks do not support metadata since " \
                    "they apply to the suite as a whole rather than " \
                    "any individual example or example group that has metadata. " \
                    "The metadata you have provided (#{meta.inspect}) will be ignored."
  end

  yield
end

#hooks

This method is for internal use only.

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

[ GitHub ]

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


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

#in_project_source_dir_regex

This method is for internal use only.

[ GitHub ]

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


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)

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 login_as(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
    login_as preferences(users(:jdoe), :lang => 'es')
    get "/profiles/jdoe"
    assert_select ".username", :text => 'jdoe'
  end
end

See Also:

#include_context
#extend
#prepend

[ GitHub ]

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


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)

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
    login_with admin_user
    get "/admin"
    expect(response).to be_ok
  end

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

See Also:

#include

[ GitHub ]

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


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

#last_run_statuses

This method is for internal use only.

[ GitHub ]

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


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_file_handling_errors(method, file) (private)

[ GitHub ]

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


def load_file_handling_errors(method, file)
  __send__(method, file)
rescue LoadError => ex
  relative_file = Metadata.relative_path(file)
  suggestions = DidYouMean.new(relative_file).call
  reporter.notify_non_example_exception(ex, "An error occurred while loading #{relative_file}.#{suggestions}")
  RSpec.world.wants_to_quit = true
rescue SyntaxError => ex
  relative_file = Metadata.relative_path(file)
  reporter.notify_non_example_exception(
    ex,
    "While loading #{relative_file} a `raise SyntaxError` occurred, RSpec will now quit."
  )
  RSpec.world.rspec_is_quitting = true
rescue Support::AllExceptionsExceptOnesWeMustNotRescue => ex
  relative_file = Metadata.relative_path(file)
  reporter.notify_non_example_exception(ex, "An error occurred while loading #{relative_file}.")
  RSpec.world.wants_to_quit = true
rescue SystemExit => ex
  relative_file = Metadata.relative_path(file)
  reporter.notify_non_example_exception(
    ex,
    "While loading #{relative_file} an `exit` / `raise SystemExit` occurred, RSpec will now quit."
  )
  RSpec.world.rspec_is_quitting = true
  raise ex
end

#load_spec_files

This method is for internal use only.

[ GitHub ]

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


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

#metadata_applies_to_group?(meta, group) ⇒ `Boolean` (private)

[ GitHub ]

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


def metadata_applies_to_group?(meta, group)
  meta.empty? || MetadataFilter.apply?(:any?, meta, group.metadata)
end

#mock_with(framework)

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

[ GitHub ]

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


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)

Invokes block before defining an example group

[ GitHub ]

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


def on_example_group_definition(&block)
  on_example_group_definition_callbacks << block
end

#on_example_group_definition_callbacks

This method is for internal use only.

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

[ GitHub ]

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


def on_example_group_definition_callbacks
  @on_example_group_definition_callbacks ||= []
end

#on_existing_matching_groups(meta) (private)

[ GitHub ]

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


def on_existing_matching_groups(meta)
  world.traverse_example_group_trees_until do |group|
    metadata_applies_to_group?(meta, group).tap do |applies|
      yield group if applies
    end
  end
end

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

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

[ GitHub ]

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


define_reader :only_failures

#order=(value)

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:’, the seed will also be set.

See Also:

#register_ordering

[ GitHub ]

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


delegate_to_ordering_manager :order=

#output_to_tty?(output = output_stream) ⇒ `Boolean` (private)

[ GitHub ]

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


def output_to_tty?(output=output_stream)
  output.respond_to?(:tty?) && output.tty?
end

#output_wrapper (private)

[ GitHub ]

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


def output_wrapper
  @output_wrapper ||= OutputWrapper.new(output_stream)
end

#paths_to_check(paths) (private)

[ GitHub ]

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


def paths_to_check(paths)
  return paths if pattern_might_load_specs_from_vendored_dirs?
  paths + [Dir.getwd]
end

#prepend(mod, *filters)

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:

#include
#extend

[ GitHub ]

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


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

#prepend_after(scope = nil, *meta, &block)

Alias for #after.

[ GitHub ]

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


alias_method :prepend_after, :after

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

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:

#before
#after
#append_after

[ GitHub ]

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


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!

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

[ GitHub ]

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


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

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

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:

list (Array<RSpec::Core::Example>, Array<RSpec::Core::ExampleGroup>) —

The examples or groups to order

Yield Returns:

(Array<RSpec::Core::Example>, Array<RSpec::Core::ExampleGroup>) —

The re-ordered examples or groups

[ GitHub ]

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


delegate_to_ordering_manager :register_ordering

#reporter ⇒ RSpec::Core::Reporter

Returns:

(RSpec::Core::Reporter) —

the currently configured reporter

[ GitHub ]

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


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

#reset

This method is for internal use only.

[ GitHub ]

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


def reset
  @spec_files_loaded = false
  reset_reporter
end

#reset_filters

This method is for internal use only.

[ GitHub ]

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


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_reporter

This method is for internal use only.

[ GitHub ]

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


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

#run_suite_hooks(hook_description, hooks) (private)

[ GitHub ]

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


def run_suite_hooks(hook_description, hooks)
  context = SuiteHookContext.new(hook_description, reporter)

  hooks.each do |hook|
    begin
      hook.run(context)
    rescue Support::AllExceptionsExceptOnesWeMustNotRescue => ex
      context.set_exception(ex)

      # Do not run subsequent `before` hooks if one fails.
      # But for `after` hooks, we run them all so that all
      # cleanup bits get a chance to complete, minimizing the
      # chance that resources get left behind.
      break if hooks.equal?(@before_suite_hooks)
    end
  end
end

#safe_extend(mod, host) (private)

See additional method definition at line 2399.

[ GitHub ]

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


def safe_extend(mod, host)
  host.extend(mod) unless host.singleton_class < mod
end

#safe_include(mod, host) (private)

:nocov:

[ GitHub ]

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


def safe_include(mod, host)
  host.__send__(:include, mod) unless host < mod
end

#safe_prepend(mod, host) (private)

[ GitHub ]

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


def safe_prepend(mod, host)
  host.__send__(:prepend, mod) unless host < mod
end

#seed

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.

[ GitHub ]

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


delegate_to_ordering_manager :seed

#seed=(value)

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

[ GitHub ]

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


delegate_to_ordering_manager :seed=

#spec_files_with_failures

This method is for internal use only.

[ GitHub ]

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


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

#update_pattern_attr(name, value) (private)

[ GitHub ]

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


def update_pattern_attr(name, value)
  if @spec_files_loaded
    RSpec.warning "Configuring `#{name}` to #{value} has no effect since " \
                  "RSpec has already loaded the spec files."
  end

  instance_variable_set(:"@#{name}", value)
  @files_to_run = nil
end

#value_for(key) (private)

[ GitHub ]

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


def value_for(key)
  @preferred_options.fetch(key) { yield }
end

#when_first_matching_example_defined(*filters)

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

[ GitHub ]

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


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

#windows_absolute_network_path?(pattern) ⇒ `Boolean` (private)

[ GitHub ]

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


def windows_absolute_network_path?(pattern)
  return false unless ::File::ALT_SEPARATOR
  pattern.start_with?(::File::ALT_SEPARATOR + ::File::ALT_SEPARATOR)
end

#with_suite_hooks

This method is for internal use only.

[ GitHub ]

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


def with_suite_hooks
  return yield if dry_run?

  begin
    RSpec.current_scope = :before_suite_hook
    run_suite_hooks("a `before(:suite)` hook", @before_suite_hooks)
    yield
  ensure
    RSpec.current_scope = :after_suite_hook
    run_suite_hooks("an `after(:suite)` hook", @after_suite_hooks)
    RSpec.current_scope = :suite
  end
end

Class: RSpec::Core::Configuration

Overview

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Hooks - Included

Constructor Details

.new ⇒ Configuration

Class Method Details

.add_read_only_setting(name, opts = {})

.add_setting(name, opts = {})

.define_alias(name, alias_name)

.define_predicate(name)

.define_reader(name)

.delegate_to_ordering_manager(*methods)

Instance Attribute Details

#backtrace_exclusion_patterns ⇒ Array<Regexp> (rw)

#backtrace_exclusion_patterns=(patterns) (rw)

#backtrace_formatter (readonly)

#backtrace_inclusion_patterns ⇒ Array<Regexp> (rw)

#backtrace_inclusion_patterns=(patterns) (rw)

#bisect_runner ⇒ Symbol (rw)

#bisect_runner=(value) (rw)

#color ⇒ Boolean (rw)

#color=(value) (rw)

#color_mode ⇒ Boolean (rw)

#color_mode=(value) (rw)

#default_color ⇒ Symbol (rw)

#default_formatter (rw)

#default_formatter=(value) (rw)

#default_path ⇒ String (rw)

#default_path=(path) ⇒ String (rw)

#deprecation_stream ⇒ IO, String (rw)

#deprecation_stream=(value) (rw)

#detail_color ⇒ Symbol (rw)

#disable_monkey_patching (rw)

#drb ⇒ Boolean (rw)

#drb_port (rw)

#dry_run (rw)

#error_exit_code ⇒ Integer (rw)

#error_stream (rw)

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

#example_status_persistence_file_path=(value) (rw)

#exclude_pattern ⇒ String (rw)

#exclude_pattern=(value) (rw)

#exclusion_filter (rw)

#exclusion_filter=(filter) (rw)

Warning

#expectation_framework=(framework) (writeonly)

#expose_dsl_globally=(value) (rw)

#expose_dsl_globally? ⇒ Boolean (rw)

#fail_fast (rw)

#fail_fast=(value) (rw)

#fail_if_no_examples ⇒ Boolean (rw)

#failure_color ⇒ Symbol (rw)

#failure_exit_code ⇒ Integer (rw)

#files_to_run ⇒ Array (rw)

#files_to_run=(value) (rw)

#filter (rw)

#filter_manager (rw)

#fixed_color ⇒ Symbol (rw)

#full_backtrace=(true_or_false) (rw)

#full_backtrace? ⇒ Boolean (rw)

#full_description ⇒ Array (rw)

#full_description=(description) (rw)

#inclusion_filter (rw) Also known as: #filter

#inclusion_filter=(filter) (rw) Also known as: #filter=

Warning

#libs ⇒ Array<String> (rw)

#libs=(libs) (rw)

#loaded_spec_files (readonly)

#max_displayed_failure_line_count (rw)

#mock_framework ⇒ Symbol (rw)

#mock_framework=(framework) (rw)

#only_failures? (readonly)

#only_failures_but_not_configured? ⇒ Boolean (readonly)

#ordering_manager (readonly)

#output_stream ⇒ IO, String (rw)

#output_stream=(value) (rw)

`Hooks` - Included

.new ⇒ `Configuration`

#backtrace_exclusion_patterns ⇒ `Array`<`Regexp`> (rw)

#backtrace_inclusion_patterns ⇒ `Array`<`Regexp`> (rw)

#bisect_runner ⇒ `Symbol` (rw)

#color ⇒ `Boolean` (rw)

#color_mode ⇒ `Boolean` (rw)

#default_color ⇒ `Symbol` (rw)

#default_path ⇒ `String` (rw)

#default_path=(path) ⇒ `String` (rw)

#deprecation_stream ⇒ `IO`, `String` (rw)

#detail_color ⇒ `Symbol` (rw)

#drb ⇒ `Boolean` (rw)

#error_exit_code ⇒ `Integer` (rw)

#example_status_persistence_file_path ⇒ `String` (rw) #example_status_persistence_file_path=(value)

#exclude_pattern ⇒ `String` (rw)

#expose_dsl_globally? ⇒ `Boolean` (rw)

#fail_if_no_examples ⇒ `Boolean` (rw)

#failure_color ⇒ `Symbol` (rw)

#failure_exit_code ⇒ `Integer` (rw)

#files_to_run ⇒ `Array` (rw)

#fixed_color ⇒ `Symbol` (rw)

#full_backtrace? ⇒ `Boolean` (rw)

#full_description ⇒ `Array` (rw)

#libs ⇒ `Array`<`String`> (rw)

#mock_framework ⇒ `Symbol` (rw)

#only_failures_but_not_configured? ⇒ `Boolean` (readonly)

#output_stream ⇒ `IO`, `String` (rw)

#pattern ⇒ `String` (rw)

#pattern_might_load_specs_from_vendored_dirs? ⇒ `Boolean` (readonly, private)

#pending_color ⇒ `Symbol` (rw)

#profile_examples ⇒ `Boolean` (rw)

#profile_examples=(value) ⇒ `Boolean` (rw)

#project_source_dirs ⇒ `Array`<`String`> (rw)

#requires ⇒ `Array`<`String`> (rw)

#rspec_expectations_loaded? ⇒ `Boolean` (readonly, private)

#rspec_mocks_loaded? ⇒ `Boolean` (readonly, private)

#shared_context_metadata_behavior ⇒ `:trigger_inclusion`, `:apply_to_host_groups` (rw) #shared_context_metadata_behavior=(value)

#success_color ⇒ `Symbol` (rw)

#warnings? ⇒ `Boolean` (rw)

#absolute_pattern?(pattern) ⇒ `Boolean` (private)

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

#color_enabled?(output = output_stream) ⇒ `Boolean`