Class: RSpec::Core::Configuration
- Inherits:
-
Object
- Object
- RSpec::Core::Configuration
- Includes:
- Module.new, Hooks
- Defined in:
- lib/rspec/core/configuration.rb
Overview
Stores runtime configuration information.
Configuration options are loaded from multiple files and joined together
with command-line switches and the SPEC_OPTS
environment variable.
Precedence order (where later entries overwrite earlier entries on conflicts):
- Global (
$XDG_CONFIG_HOME/rspec/options
, or~/.rspec
if it does not exist) - Project-specific (
./.rspec
) - Local (
./.rspec-local
) - Command-line options
SPEC_OPTS
For example, an option set in the local file will override an option set in your global file.
The global, project-specific and local files can all be overridden with a separate custom file using the --options command-line parameter.
Instance Attribute Summary collapse
-
#bisect_runner ⇒ Symbol
Determines which bisect runner implementation gets used to run subsets of the suite during a bisection.
-
#color ⇒ Boolean
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
The mode for determining whether to display output in color.
-
#default_color ⇒ Symbol
The default output color.
-
#default_path ⇒ String
Path to use if no path is provided to the
rspec
command (default:"spec"
). -
#detail_color ⇒ Symbol
Color used to print details.
-
#drb ⇒ Boolean
Run examples over DRb (default:
false
). -
#drb_port ⇒ void
The drb_port (default: nil).
-
#dry_run ⇒ void
Prints the formatter output of your suite without running any examples or hooks.
-
#error_exit_code ⇒ Integer
The exit code to return if there are any errors outside examples (default: failure_exit_code).
-
#error_stream ⇒ void
Default:
$stderr
. -
#example_status_persistence_file_path ⇒ void
The file path to use for persisting example statuses.
-
#exclude_pattern ⇒ String
Exclude files matching this pattern.
-
#fail_fast ⇒ void
If specified, indicates the number of failures required before cleaning up and exit (default:
nil
). -
#fail_if_no_examples ⇒ Boolean
Whether or not to fail when there are no RSpec examples (default: false).
-
#failure_color ⇒ Symbol
Color to use to indicate failure.
-
#failure_exit_code ⇒ Integer
The exit code to return if there are any failures (default: 1).
-
#files_to_run ⇒ Array
readonly
The spec files RSpec will run.
-
#fixed_color ⇒ Symbol
Color used when a pending example is fixed.
-
#libs ⇒ Array<String>
readonly
Returns dirs that have been prepended to the load path by the
-I
command line option. -
#max_displayed_failure_line_count ⇒ void
Maximum count of failed source lines to display in the failure reports.
-
#only_failures ⇒ void
(also: #only_failures?)
readonly
Indicates if the
--only-failures
(or--next-failure
) flag is being used. -
#output_stream ⇒ IO, String
Determines where RSpec will send its output.
-
#pattern ⇒ String
Load files matching this pattern (default:
'**{,/*/**}/*_spec.rb'
). -
#pending_color ⇒ Symbol
Color to use to print pending examples.
-
#profile_examples ⇒ void
private
Defaults
profile_examples
to 10 examples when@profile_examples
istrue
. -
#project_source_dirs ⇒ Array<String>
Specifies which directories contain the source code for your project.
-
#requires ⇒ Array<String>
readonly
Indicates files configured to be required.
-
#run_all_when_everything_filtered ⇒ void
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 ⇒ void
Configures how RSpec treats metadata passed as part of a shared example group definition.
-
#silence_filter_announcements ⇒ void
Don't print filter info i.e.
-
#success_color ⇒ Symbol
Color to use to indicate success.
-
#threadsafe ⇒ void
Use threadsafe options where available.
Instance Method Summary collapse
-
#add_formatter(formatter, output = output_wrapper) ⇒ void
(also: #formatter=)
Adds a formatter to the set RSpec will use for this run.
-
#add_setting(name, opts = {}) ⇒ void
Adds a custom setting to the RSpec.configuration object.
-
#after(scope = nil, *meta, &block) ⇒ void
(also: #prepend_after)
Defines a
after
hook. -
#alias_example_group_to(new_name, *args) ⇒ void
Creates a method that defines an example group with the provided metadata.
-
#alias_example_to(name, *args) ⇒ void
Creates a method that delegates to
example
including the submittedargs
. -
#alias_it_behaves_like_to(new_name, report_label = '') ⇒ void
(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.
-
#append_after(scope = nil, *meta, &block) ⇒ void
Adds
block
to the end of the list ofafter
blocks in the same scope (:example
,:context
, or:suite
), in contrast to #after, which adds the hook to the start of the list. -
#around(scope = nil, *meta, &block) ⇒ void
Registers
block
as anaround
hook. -
#backtrace_exclusion_patterns ⇒ Array<Regexp>
Regexps used to exclude lines from backtraces.
-
#backtrace_exclusion_patterns=(patterns) ⇒ void
Set regular expressions used to exclude lines in backtrace.
-
#backtrace_inclusion_patterns ⇒ Array<Regexp>
Regexps used to include lines in backtraces.
-
#backtrace_inclusion_patterns=(patterns) ⇒ void
Set regular expressions used to include lines in backtrace.
-
#before(scope = nil, *meta, &block) ⇒ void
(also: #append_before)
Defines a
before
hook. -
#color_enabled?(output = output_stream) ⇒ Boolean
Check if color is enabled for a particular output.
-
#default_formatter ⇒ void
The formatter that will be used if no formatter has been set.
-
#default_formatter=(value) ⇒ void
Sets a fallback formatter to use if none other has been set.
-
#define_derived_metadata(*filters) {|metadata| ... } ⇒ void
Defines a callback that can assign derived metadata values.
-
#deprecation_stream ⇒ IO, String
Determines where deprecation warnings are printed.
-
#deprecation_stream=(value) ⇒ void
Determines where deprecation warnings are printed.
-
#disable_monkey_patching! ⇒ void
Enables zero monkey patching mode for RSpec.
-
#exclusion_filter ⇒ void
Returns the
exclusion_filter
. -
#exclusion_filter=(filter) ⇒ void
Clears and reassigns the
exclusion_filter
. -
#expect_with(*frameworks) ⇒ void
Sets the expectation framework module(s) to be included in each example group.
-
#expectation_framework=(framework) ⇒ void
Delegates to expect_with(framework).
-
#expectation_frameworks ⇒ void
Returns the configured expectation framework adapter module(s).
-
#expose_current_running_example_as(method_name) ⇒ void
Exposes the current running example via the named helper method.
-
#expose_dsl_globally=(value) ⇒ void
Use this to expose the core RSpec DSL via
Module
and themain
object. -
#expose_dsl_globally? ⇒ Boolean
Indicates if the DSL has been exposed off of modules and
main
. -
#extend(mod, *filters) ⇒ void
Tells RSpec to extend example groups with
mod
. -
#filter_gems_from_backtrace(*gem_names) ⇒ void
Adds #backtrace_exclusion_patterns that will filter lines from the named gems from backtraces.
-
#filter_run_excluding(*args) ⇒ void
Adds key/value pairs to the
exclusion_filter
. -
#filter_run_including(*args) ⇒ void
(also: #filter_run)
Adds key/value pairs to the
inclusion_filter
. -
#filter_run_when_matching(*args) ⇒ void
Applies the provided filter only if any of examples match, in constrast to #filter_run, which always applies even if no examples match, in which case no examples will be run.
-
#format_docstrings(&block) ⇒ void
Formats the docstring output using the block provided.
-
#formatters ⇒ Array
Returns a duplicate of the formatters currently loaded in the
FormatterLoader
for introspection. -
#full_backtrace=(true_or_false) ⇒ void
Toggle full backtrace.
-
#full_backtrace? ⇒ Boolean
Check if full backtrace is enabled.
-
#full_description ⇒ Array
Full description filter.
-
#full_description=(description) ⇒ void
Run examples matching on
description
in all files to run. -
#include(mod, *filters) ⇒ void
Tells RSpec to include
mod
in example groups. -
#include_context(shared_group_name, *filters) ⇒ void
Tells RSpec to include the named shared example group in example groups.
-
#inclusion_filter ⇒ void
(also: #filter)
Returns the
inclusion_filter
. -
#inclusion_filter=(filter) ⇒ void
(also: #filter=)
Clears and reassigns the
inclusion_filter
. -
#initialize ⇒ Configuration
constructor
Build an object to store runtime configuration options and set defaults.
-
#mock_framework ⇒ Symbol
Returns the configured mock framework adapter module.
-
#mock_framework=(framework) ⇒ void
Delegates to mock_framework=(framework).
-
#mock_with(framework) ⇒ void
Sets the mock framework adapter module.
-
#on_example_group_definition(&block) ⇒ void
Invokes block before defining an example group.
-
#on_example_group_definition_callbacks ⇒ void
private
Returns an array of blocks to call before defining an example group.
-
#order=(value) ⇒ void
Sets the default global ordering strategy.
-
#prepend(mod, *filters) ⇒ void
Tells RSpec to prepend example groups with
mod
. -
#prepend_before(scope = nil, *meta, &block) ⇒ void
Adds
block
to the start of the list ofbefore
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! ⇒ void
Turns deprecation warnings into errors, in order to surface the full backtrace of the call site.
-
#raise_on_warning=(value) ⇒ void
Turns warnings into errors.
-
#register_ordering(name) {|list| ... } ⇒ void
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
The currently configured reporter.
-
#seed ⇒ void
Seed for random ordering (default: generated randomly each run).
-
#seed=(value) ⇒ void
Sets the seed value and sets the default global ordering to random.
-
#treat_symbols_as_metadata_keys_with_true_values=(_value) ⇒ void
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) ⇒ void
Set Ruby warnings on or off.
-
#warnings? ⇒ Boolean
Whether or not ruby warnings are enabled.
-
#when_first_matching_example_defined(*filters) ⇒ void
Defines a callback that runs after the first example with matching metadata is defined.
Constructor Details
#initialize ⇒ Configuration
Build an object to store runtime configuration options and set defaults
508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 |
# File 'lib/rspec/core/configuration.rb', line 508 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 @world = World::Null @shared_context_metadata_behavior = :trigger_inclusion define_built_in_hooks end |
Instance Attribute Details
#bisect_runner ⇒ Symbol
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 abefore(:suite)
hook instead of getting run at the top-level of a file loaded by--require
.
480 481 482 |
# File 'lib/rspec/core/configuration.rb', line 480 def bisect_runner @bisect_runner end |
#color ⇒ Boolean
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.
899 900 901 |
# File 'lib/rspec/core/configuration.rb', line 899 def color value_for(:color) { @color } end |
#color_mode ⇒ Boolean
The mode for determining whether to display output in color. One of:
- :automatic - the output will be in color if the output is a TTY (the default)
- :on - the output will be in color, whether or not the output is a TTY
- :off - the output will not be in color
912 913 914 |
# File 'lib/rspec/core/configuration.rb', line 912 def color_mode value_for(:color_mode) { @color_mode } end |
#default_color ⇒ Symbol
The default output color. Defaults to :white
but can be set to one of
the following: [:black, :white, :red, :green, :yellow, :blue,
:magenta, :cyan]
358 |
# File 'lib/rspec/core/configuration.rb', line 358 add_setting :default_color |
#default_path ⇒ String
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.
120 |
# File 'lib/rspec/core/configuration.rb', line 120 add_read_only_setting :default_path |
#detail_color ⇒ Symbol
Color used to print details. Defaults to :cyan
but can be set to one
of the following: [:black, :white, :red, :green, :yellow, :blue,
:magenta, :cyan]
372 |
# File 'lib/rspec/core/configuration.rb', line 372 add_setting :detail_color |
#drb ⇒ Boolean
Run examples over DRb (default: false
). RSpec doesn't supply the DRb
server, but you can use tools like spork.
130 |
# File 'lib/rspec/core/configuration.rb', line 130 add_setting :drb |
#drb_port ⇒ void
The drb_port (default: nil).
134 |
# File 'lib/rspec/core/configuration.rb', line 134 add_setting :drb_port |
#dry_run ⇒ void
Prints the formatter output of your suite without running any examples or hooks.
238 |
# File 'lib/rspec/core/configuration.rb', line 238 add_setting :dry_run |
#error_exit_code ⇒ Integer
The exit code to return if there are any errors outside examples (default: failure_exit_code)
248 |
# File 'lib/rspec/core/configuration.rb', line 248 add_setting :error_exit_code |
#error_stream ⇒ void
Default: $stderr
.
138 |
# File 'lib/rspec/core/configuration.rb', line 138 add_setting :error_stream |
#example_status_persistence_file_path ⇒ String #example_status_persistence_file_path=(value) ⇒ void
The file path to use for persisting example statuses. Necessary for the
--only-failures
and --next-failure
CLI options.
188 |
# File 'lib/rspec/core/configuration.rb', line 188 define_reader :example_status_persistence_file_path |
#exclude_pattern ⇒ String
Exclude files matching this pattern.
300 |
# File 'lib/rspec/core/configuration.rb', line 300 define_reader :exclude_pattern |
#fail_fast ⇒ void
If specified, indicates the number of failures required before cleaning
up and exit (default: nil
). Can also be true
to fail and exit on first
failure
211 |
# File 'lib/rspec/core/configuration.rb', line 211 define_reader :fail_fast |
#fail_if_no_examples ⇒ Boolean
Whether or not to fail when there are no RSpec examples (default: false).
253 |
# File 'lib/rspec/core/configuration.rb', line 253 add_setting :fail_if_no_examples |
#failure_color ⇒ Symbol
Color to use to indicate failure. Defaults to :red
but can be set to
one of the following: [:black, :white, :red, :green, :yellow, :blue,
:magenta, :cyan]
351 |
# File 'lib/rspec/core/configuration.rb', line 351 add_setting :failure_color |
#failure_exit_code ⇒ Integer
The exit code to return if there are any failures (default: 1).
243 |
# File 'lib/rspec/core/configuration.rb', line 243 add_setting :failure_exit_code |
#files_to_run ⇒ Array
The spec files RSpec will run.
1073 1074 1075 |
# File 'lib/rspec/core/configuration.rb', line 1073 def files_to_run @files_to_run ||= get_files_to_run(@files_or_directories_to_run) end |
#fixed_color ⇒ Symbol
Color used when a pending example is fixed. Defaults to :blue
but can
be set to one of the following: [:black, :white, :red, :green,
:yellow, :blue, :magenta, :cyan]
365 |
# File 'lib/rspec/core/configuration.rb', line 365 add_setting :fixed_color |
#libs ⇒ Array<String>
Returns dirs that have been prepended to the load path by the -I
command line option.
264 |
# File 'lib/rspec/core/configuration.rb', line 264 define_reader :libs |
#max_displayed_failure_line_count ⇒ void
Maximum count of failed source lines to display in the failure reports.
(default 10
).
return [Integer]
459 |
# File 'lib/rspec/core/configuration.rb', line 459 add_setting :max_displayed_failure_line_count |
#only_failures ⇒ void (readonly) Also known as: only_failures?
Indicates if the --only-failures
(or --next-failure
) flag is being used.
199 |
# File 'lib/rspec/core/configuration.rb', line 199 define_reader :only_failures |
#output_stream ⇒ IO, String
Determines where RSpec will send its output.
Default: $stdout
.
270 |
# File 'lib/rspec/core/configuration.rb', line 270 define_reader :output_stream |
#pattern ⇒ String
Load files matching this pattern (default: '**{,/*/**}/*_spec.rb'
).
289 |
# File 'lib/rspec/core/configuration.rb', line 289 define_reader :pattern |
#pending_color ⇒ Symbol
Color to use to print pending examples. Defaults to :yellow
but can
be set to one of the following: [:black, :white, :red, :green,
:yellow, :blue, :magenta, :cyan]
344 |
# File 'lib/rspec/core/configuration.rb', line 344 add_setting :pending_color |
#profile_examples ⇒ void
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Defaults profile_examples
to 10 examples when @profile_examples
is
true
.
322 |
# File 'lib/rspec/core/configuration.rb', line 322 attr_writer :profile_examples |
#project_source_dirs ⇒ Array<String>
Specifies which directories contain the source code for your project. When a failure occurs, RSpec looks through the backtrace to find a a line of source to print. It first looks for a line coming from one of the project source directories so that, for example, it prints the expectation or assertion call rather than the source code from the expectation or assertion framework.
316 |
# File 'lib/rspec/core/configuration.rb', line 316 add_setting :project_source_dirs |
#requires ⇒ Array<String>
Indicates files configured to be required.
258 |
# File 'lib/rspec/core/configuration.rb', line 258 define_reader :requires |
#run_all_when_everything_filtered ⇒ void
Use #filter_run_when_matching instead for the specific filters that you want to be ignored if none match.
Run all examples if none match the configured filters
(default: false
).
330 |
# File 'lib/rspec/core/configuration.rb', line 330 add_setting :run_all_when_everything_filtered |
#shared_context_metadata_behavior ⇒ :trigger_inclusion, :apply_to_host_groups #shared_context_metadata_behavior=(value) ⇒ void
Configures how RSpec treats metadata passed as part of a shared example group definition. For example, given this shared example group definition:
RSpec.shared_context "uses DB", :db => true do
around(:example) do |ex|
MyORM.transaction(:rollback => true, &ex)
end
end
...there are two ways RSpec can treat the :db => true
metadata, each
of which has a corresponding config option:
: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.
432 |
# File 'lib/rspec/core/configuration.rb', line 432 define_reader :shared_context_metadata_behavior |
#silence_filter_announcements ⇒ void
Don't print filter info i.e. "Run options: include :focus=>true"
(default false
).
return [Boolean]
378 |
# File 'lib/rspec/core/configuration.rb', line 378 add_setting :silence_filter_announcements |
#success_color ⇒ Symbol
Color to use to indicate success. Defaults to :green
but can be set
to one of the following: [:black, :white, :red, :green, :yellow,
:blue, :magenta, :cyan]
337 |
# File 'lib/rspec/core/configuration.rb', line 337 add_setting :success_color |
#threadsafe ⇒ void
Use threadsafe options where available. Currently this will place a mutex around memoized values such as let blocks. return [Boolean]
453 |
# File 'lib/rspec/core/configuration.rb', line 453 add_setting :threadsafe |
Instance Method Details
#add_formatter(formatter) ⇒ void #add_formatter(formatter, output) ⇒ void Also known as: formatter=
Adds a formatter to the set RSpec will use for this run.
973 974 975 |
# File 'lib/rspec/core/configuration.rb', line 973 def add_formatter(formatter, output=output_wrapper) formatter_loader.add(formatter, output) end |
#add_setting(name) ⇒ void #add_setting(name, opts) ⇒ void
Adds a custom setting to the RSpec.configuration object.
RSpec.configuration.add_setting :foo
Used internally and by extension frameworks like rspec-rails, so they can add config settings that are domain specific. For example:
RSpec.configure do |c|
c.add_setting :use_transactional_fixtures,
:default => true,
:alias_with => :use_transactional_examples
end
add_setting
creates three methods on the configuration object, a
setter, a getter, and a predicate:
RSpec.configuration.foo=(value)
RSpec.configuration.foo
RSpec.configuration.foo? # Returns true if foo returns anything but nil or false.
636 637 638 639 640 641 642 |
# File 'lib/rspec/core/configuration.rb', line 636 def add_setting(name, opts={}) default = opts.delete(:default) (class << self; self; end).class_exec do add_setting(name, opts) end __send__("#{name}=", default) if default end |
#after(scope = nil, *meta, &block) ⇒ void Also known as: prepend_after
Defines a after
hook. See Hooks#after for full docs.
This method differs from Hooks#after in only one way: it supports
the :suite
scope. Hooks with the :suite
scope will be run once after
the last example of the entire suite is executed. Conditions passed along
with :suite
are effectively ignored.
2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 |
# File 'lib/rspec/core/configuration.rb', line 2002 def after(scope=nil, *, &block) handle_suite_hook(scope, ) 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(, scope) { |g| g.after(scope, *, &block) } super(scope, *, &block) end end |
#alias_example_group_to(new_name, *args) ⇒ void
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.
1186 1187 1188 1189 |
# File 'lib/rspec/core/configuration.rb', line 1186 def alias_example_group_to(new_name, *args) = Metadata.build_hash_from(args) RSpec::Core::ExampleGroup.define_example_group_method(new_name, ) end |
#alias_example_to(name, *args) ⇒ void
The specific example alias below (pending
) is already
defined for you.
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
:
1154 1155 1156 1157 |
# File 'lib/rspec/core/configuration.rb', line 1154 def alias_example_to(name, *args) = Metadata.build_hash_from(args) RSpec::Core::ExampleGroup.define_example_method(name, ) end |
#alias_it_behaves_like_to(new_name, report_label = '') ⇒ void Also known as: alias_it_should_behave_like_to
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.
1217 1218 1219 |
# File 'lib/rspec/core/configuration.rb', line 1217 def alias_it_behaves_like_to(new_name, report_label='') RSpec::Core::ExampleGroup.define_nested_shared_group_method(new_name, report_label) end |
#append_after(scope = nil, *meta, &block) ⇒ void
Adds block
to the end of the list of after
blocks in the same
scope (:example
, :context
, or :suite
), in contrast to #after,
which adds the hook to the start of the list.
See Hooks#after for full after
hook docs.
This method differs from Hooks#append_after in only one way: it supports
the :suite
scope. Hooks with the :suite
scope will be run once after
the last example of the entire suite is executed. Conditions passed along
with :suite
are effectively ignored.
2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 |
# File 'lib/rspec/core/configuration.rb', line 2032 def append_after(scope=nil, *, &block) handle_suite_hook(scope, ) 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(, scope) { |g| g.append_after(scope, *, &block) } super(scope, *, &block) end end |
#around(scope = nil, *meta, &block) ⇒ void
Registers block
as an around
hook.
See Hooks#around for full around
hook docs.
2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 |
# File 'lib/rspec/core/configuration.rb', line 2050 def around(scope=nil, *, &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(, scope) { |g| g.around(scope, *, &block) } super(scope, *, &block) end |
#backtrace_exclusion_patterns ⇒ Array<Regexp>
Regexps used to exclude lines from backtraces.
Excludes lines from ruby (and jruby) source, installed gems, anything in any "bin" directory, and any of the RSpec libs (outside gem installs) by default.
You can modify the list via the getter, or replace it with the setter.
To override this behaviour and display a full backtrace, use
--backtrace
on the command line, in a .rspec
file, or in the
rspec_options
attribute of RSpec's rake task.
674 675 676 |
# File 'lib/rspec/core/configuration.rb', line 674 def backtrace_exclusion_patterns @backtrace_formatter.exclusion_patterns end |
#backtrace_exclusion_patterns=(patterns) ⇒ void
Set regular expressions used to exclude lines in backtrace.
680 681 682 |
# File 'lib/rspec/core/configuration.rb', line 680 def backtrace_exclusion_patterns=(patterns) @backtrace_formatter.exclusion_patterns = patterns end |
#backtrace_inclusion_patterns ⇒ Array<Regexp>
Regexps used to include lines in backtraces.
Defaults to [Regexp.new Dir.getwd].
Lines that match an exclusion and an inclusion pattern will be included.
You can modify the list via the getter, or replace it with the setter.
693 694 695 |
# File 'lib/rspec/core/configuration.rb', line 693 def backtrace_inclusion_patterns @backtrace_formatter.inclusion_patterns end |
#backtrace_inclusion_patterns=(patterns) ⇒ void
Set regular expressions used to include lines in backtrace.
699 700 701 |
# File 'lib/rspec/core/configuration.rb', line 699 def backtrace_inclusion_patterns=(patterns) @backtrace_formatter.inclusion_patterns = patterns end |
#before(scope = nil, *meta, &block) ⇒ void Also known as: append_before
Defines a before
hook. See Hooks#before for full docs.
This method differs from Hooks#before in only one way: it supports
the :suite
scope. Hooks with the :suite
scope will be run once before
the first example of the entire suite is executed. Conditions passed along
with :suite
are effectively ignored.
1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 |
# File 'lib/rspec/core/configuration.rb', line 1947 def before(scope=nil, *, &block) handle_suite_hook(scope, ) 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(, scope) { |g| g.before(scope, *, &block) } super(scope, *, &block) end end |
#color_enabled?(output = output_stream) ⇒ Boolean
Check if color is enabled for a particular output.
920 921 922 923 924 925 926 927 |
# File 'lib/rspec/core/configuration.rb', line 920 def color_enabled?(output=output_stream) case color_mode when :on then true when :off then false else # automatic output_to_tty?(output) || (color && tty?) end end |
#default_formatter ⇒ void
The formatter that will be used if no formatter has been set. Defaults to 'progress'.
980 981 982 |
# File 'lib/rspec/core/configuration.rb', line 980 def default_formatter formatter_loader.default_formatter end |
#default_formatter=(value) ⇒ void
Sets a fallback formatter to use if none other has been set.
991 992 993 |
# File 'lib/rspec/core/configuration.rb', line 991 def default_formatter=(value) formatter_loader.default_formatter = value end |
#define_derived_metadata(*filters) {|metadata| ... } ⇒ void
Defines a callback that can assign derived metadata values.
1871 1872 1873 1874 |
# File 'lib/rspec/core/configuration.rb', line 1871 def (*filters, &block) = Metadata.build_hash_from(filters, :warn_about_example_group_filtering) @derived_metadata_blocks.append(block, ) end |
#deprecation_stream ⇒ IO, String
Determines where deprecation warnings are printed.
Defaults to $stderr
.
164 |
# File 'lib/rspec/core/configuration.rb', line 164 define_reader :deprecation_stream |
#deprecation_stream=(value) ⇒ void
Determines where deprecation warnings are printed.
168 169 170 171 172 173 174 175 176 177 178 |
# File 'lib/rspec/core/configuration.rb', line 168 def deprecation_stream=(value) if @reporter && !value.equal?(@deprecation_stream) warn "RSpec's reporter has already been initialized with " \ "#{deprecation_stream.inspect} as the deprecation stream, so your change to "\ "`deprecation_stream` will be ignored. You should configure it earlier for " \ "it to take effect, or use the `--deprecation-out` CLI option. " \ "(Called from #{CallerFilter.first_non_rspec_line})" else @deprecation_stream = value end end |
#disable_monkey_patching! ⇒ void
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).
If the user uses this options with mock_with :mocha
(or similiar) they will still have monkey patching active
in their test environment from mocha.
Enables zero monkey patching mode for RSpec. It removes monkey
patching of the top-level DSL methods (describe
,
shared_examples_for
, etc) onto main
and Module
, instead
requiring you to prefix these methods with RSpec.
. It enables
expect-only syntax for rspec-mocks and rspec-expectations. It
simply disables monkey patching on whatever pieces of RSpec
the user is using.
1844 1845 1846 1847 1848 1849 |
# File 'lib/rspec/core/configuration.rb', line 1844 def disable_monkey_patching! self.expose_dsl_globally = false self.disable_monkey_patching = true conditionally_disable_mocks_monkey_patching conditionally_disable_expectations_monkey_patching end |
#exclusion_filter ⇒ void
Returns the exclusion_filter
. If none has been set, returns an empty
hash.
1346 1347 1348 |
# File 'lib/rspec/core/configuration.rb', line 1346 def exclusion_filter filter_manager.exclusions end |
#exclusion_filter=(filter) ⇒ void
Clears and reassigns the exclusion_filter
. Set to nil
if you don't
want any exclusion filter at all.
Warning
This overrides any exclusion filters/tags set on the command line or in configuration files.
1339 1340 1341 1342 |
# File 'lib/rspec/core/configuration.rb', line 1339 def exclusion_filter=(filter) = Metadata.build_hash_from([filter], :warn_about_example_group_filtering) filter_manager.exclude_only end |
#expect_with(*frameworks) ⇒ void
Sets the expectation framework module(s) to be included in each example group.
frameworks
can be :rspec
, :test_unit
, :minitest
, a custom
module, or any combination thereof:
config.expect_with :rspec
config.expect_with :test_unit
config.expect_with :minitest
config.expect_with :rspec, :minitest
config.expect_with OtherExpectationFramework
RSpec will translate :rspec
, :minitest
, and :test_unit
into the
appropriate modules.
Configuration
If the module responds to configuration
, expect_with
will
yield the configuration
object if given a block:
config.expect_with OtherExpectationFramework do |custom_config|
custom_config.custom_setting = true
end
835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 |
# File 'lib/rspec/core/configuration.rb', line 835 def expect_with(*frameworks) modules = frameworks.map do |framework| case framework when Module framework when :rspec require 'rspec/expectations' # Tag this exception class so our exception formatting logic knows # that it satisfies the `MultipleExceptionError` interface. ::RSpec::Expectations::MultipleExpectationsNotMetError.__send__( :include, MultipleExceptionError::InterfaceTag ) ::RSpec::Matchers when :test_unit require 'rspec/core/test_unit_assertions_adapter' ::RSpec::Core::TestUnitAssertionsAdapter when :minitest require 'rspec/core/minitest_assertions_adapter' ::RSpec::Core::MinitestAssertionsAdapter else raise ArgumentError, "#{framework.inspect} is not supported" end end if (modules - @expectation_frameworks).any? assert_no_example_groups_defined(:expect_with) end if block_given? raise "expect_with only accepts a block with a single argument. " \ "Call expect_with #{modules.length} times, " \ "once with each argument, instead." if modules.length > 1 raise "#{modules.first} must respond to `configuration` so that " \ "expect_with can yield it." unless modules.first.respond_to?(:configuration) yield modules.first.configuration end @expectation_frameworks.push(*modules) end |
#expectation_framework=(framework) ⇒ void
Delegates to expect_with(framework).
808 809 810 |
# File 'lib/rspec/core/configuration.rb', line 808 def expectation_framework=(framework) expect_with(framework) end |
#expectation_frameworks ⇒ void
Returns the configured expectation framework adapter module(s)
796 797 798 799 800 801 802 803 804 805 |
# File 'lib/rspec/core/configuration.rb', line 796 def expectation_frameworks if @expectation_frameworks.empty? begin expect_with :rspec rescue LoadError expect_with Module.new end end @expectation_frameworks end |
#expose_current_running_example_as(method_name) ⇒ void
Exposes the current running example via the named
helper method. RSpec 2.x exposed this via example
,
but in RSpec 3.0, the example is instead exposed via
an arg yielded to it
, before
, let
, etc. However,
some extension gems (such as Capybara) depend on the
RSpec 2.x's example
method, so this config option
can be used to maintain compatibility.
1782 1783 1784 1785 1786 1787 1788 1789 |
# File 'lib/rspec/core/configuration.rb', line 1782 def expose_current_running_example_as(method_name) ExposeCurrentExample.module_exec do extend RSpec::SharedContext let(method_name) { |ex| ex } end include ExposeCurrentExample end |
#expose_dsl_globally=(value) ⇒ void
Use this to expose the core RSpec DSL via Module
and the main
object. It will be set automatically but you can override it to
remove the DSL.
Default: true
151 152 153 154 155 156 157 158 159 |
# File 'lib/rspec/core/configuration.rb', line 151 def expose_dsl_globally=(value) if value Core::DSL.expose_globally! Core::SharedExampleGroup::TopLevelDSL.expose_globally! else Core::DSL.remove_globally! Core::SharedExampleGroup::TopLevelDSL.remove_globally! end end |
#expose_dsl_globally? ⇒ Boolean
Indicates if the DSL has been exposed off of modules and main
.
Default: true
143 144 145 |
# File 'lib/rspec/core/configuration.rb', line 143 def expose_dsl_globally? Core::DSL.exposed_globally? end |
#extend(mod, *filters) ⇒ void
Tells RSpec to extend example groups with mod
. Methods defined in
mod
are exposed to example groups (not examples). Use filters
to
constrain the groups to extend.
Similar to include
, but behavior is added to example groups, which
are classes, rather than the examples, which are instances of those
classes.
1492 1493 1494 1495 1496 |
# File 'lib/rspec/core/configuration.rb', line 1492 def extend(mod, *filters) define_mixed_in_module(mod, filters, @extend_modules, :extend) do |group| safe_extend(mod, group) end end |
#filter_gems_from_backtrace(*gem_names) ⇒ void
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.
719 720 721 722 723 |
# File 'lib/rspec/core/configuration.rb', line 719 def filter_gems_from_backtrace(*gem_names) gem_names.each do |name| @backtrace_formatter.filter_gem(name) end end |
#filter_run_excluding(*args) ⇒ void
Adds key/value pairs to the exclusion_filter
. If args
includes any symbols that are not part of the hash, each symbol
is treated as a key in the hash with the value true
.
Note
Filters set using this method can be overridden from the command line
or config files (e.g. .rspec
).
1326 1327 1328 1329 1330 |
# File 'lib/rspec/core/configuration.rb', line 1326 def filter_run_excluding(*args) = Metadata.build_hash_from(args, :warn_about_example_group_filtering) filter_manager.exclude_with_low_priority static_config_filter_manager.exclude_with_low_priority Metadata.deep_hash_dup() end |
#filter_run_including(*args) ⇒ void Also known as: filter_run
Adds key/value pairs to the inclusion_filter
. If args
includes any symbols that are not part of the hash, each symbol
is treated as a key in the hash with the value true
.
Note
Filters set using this method can be overridden from the command line
or config files (e.g. .rspec
).
1252 1253 1254 1255 1256 |
# File 'lib/rspec/core/configuration.rb', line 1252 def filter_run_including(*args) = Metadata.build_hash_from(args, :warn_about_example_group_filtering) filter_manager.include_with_low_priority static_config_filter_manager.include_with_low_priority Metadata.deep_hash_dup() end |
#filter_run_when_matching(*args) ⇒ void
Applies the provided filter only if any of examples match, in constrast
to #filter_run, which always applies even if no examples match, in
which case no examples will be run. This allows you to leave configured
filters in place that are intended only for temporary use. The most common
example is focus filtering: config.filter_run_when_matching :focus
.
With that configured, you can temporarily focus an example or group
by tagging it with :focus
metadata, or prefixing it with an f
(as in fdescribe
, fcontext
and fit
) since those are aliases for
describe
/context
/it
with :focus
metadata.
1268 1269 1270 1271 1272 |
# File 'lib/rspec/core/configuration.rb', line 1268 def filter_run_when_matching(*args) when_first_matching_example_defined(*args) do filter_run(*args) end end |
#format_docstrings(&block) ⇒ void
Formats the docstring output using the block provided.
1633 1634 1635 |
# File 'lib/rspec/core/configuration.rb', line 1633 def format_docstrings(&block) @format_docstrings_block = block_given? ? block : DEFAULT_FORMATTER end |
#formatters ⇒ Array
Returns a duplicate of the formatters currently loaded in
the FormatterLoader
for introspection.
Note as this is a duplicate, any mutations will be disregarded.
1001 1002 1003 |
# File 'lib/rspec/core/configuration.rb', line 1001 def formatters formatter_loader.formatters.dup end |
#full_backtrace=(true_or_false) ⇒ void
Toggle full backtrace.
885 886 887 |
# File 'lib/rspec/core/configuration.rb', line 885 def full_backtrace=(true_or_false) @backtrace_formatter.full_backtrace = true_or_false end |
#full_backtrace? ⇒ Boolean
Check if full backtrace is enabled.
879 880 881 |
# File 'lib/rspec/core/configuration.rb', line 879 def full_backtrace? @backtrace_formatter.full_backtrace? end |
#full_description ⇒ Array
Returns full description filter.
954 955 956 |
# File 'lib/rspec/core/configuration.rb', line 954 def full_description filter.fetch :full_description, nil end |
#full_description=(description) ⇒ void
Run examples matching on description
in all files to run.
949 950 951 |
# File 'lib/rspec/core/configuration.rb', line 949 def full_description=(description) filter_run :full_description => Regexp.union(*Array(description).map { |d| Regexp.new(d) }) end |
#include(mod, *filters) ⇒ void
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.
1402 1403 1404 1405 1406 |
# File 'lib/rspec/core/configuration.rb', line 1402 def include(mod, *filters) define_mixed_in_module(mod, filters, @include_modules, :include) do |group| safe_include(mod, group) end end |
#include_context(shared_group_name, *filters) ⇒ void
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.
1449 1450 1451 1452 |
# File 'lib/rspec/core/configuration.rb', line 1449 def include_context(shared_group_name, *filters) shared_module = world.shared_example_group_registry.find([:main], shared_group_name) include shared_module, *filters end |
#inclusion_filter ⇒ void Also known as: filter
Returns the inclusion_filter
. If none has been set, returns an empty
hash.
1290 1291 1292 |
# File 'lib/rspec/core/configuration.rb', line 1290 def inclusion_filter filter_manager.inclusions end |
#inclusion_filter=(filter) ⇒ void Also known as: filter=
Clears and reassigns the inclusion_filter
. Set to nil
if you don't
want any inclusion filter at all.
Warning
This overrides any inclusion filters/tags set on the command line or in configuration files.
1281 1282 1283 1284 |
# File 'lib/rspec/core/configuration.rb', line 1281 def inclusion_filter=(filter) = Metadata.build_hash_from([filter], :warn_about_example_group_filtering) filter_manager.include_only end |
#mock_framework ⇒ Symbol
Returns the configured mock framework adapter module.
646 647 648 649 650 651 652 653 654 655 |
# File 'lib/rspec/core/configuration.rb', line 646 def mock_framework if @mock_framework.nil? begin mock_with :rspec rescue LoadError mock_with :nothing end end @mock_framework end |
#mock_framework=(framework) ⇒ void
Delegates to mock_framework=(framework).
658 659 660 |
# File 'lib/rspec/core/configuration.rb', line 658 def mock_framework=(framework) mock_with framework end |
#mock_with(framework) ⇒ void
Sets the mock framework adapter module.
framework
can be a Symbol or a Module.
Given any of :rspec
, :mocha
, :flexmock
, or :rr
, configures the
named framework.
Given :nothing
, configures no framework. Use this if you don't use
any mocking framework to save a little bit of overhead.
Given a Module, includes that module in every example group. The module should adhere to RSpec's mock framework adapter API:
setup_mocks_for_rspec
- called before each example
verify_mocks_for_rspec
- called after each example if the example hasn't yet failed.
Framework should raise an exception when expectations fail
teardown_mocks_for_rspec
- called after verify_mocks_for_rspec (even if there are errors)
If the module responds to configuration
and mock_with
receives a
block, it will yield the configuration object to the block e.g.
config.mock_with OtherMockFrameworkAdapter do |mod_config|
mod_config.custom_setting = true
end
763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 |
# File 'lib/rspec/core/configuration.rb', line 763 def mock_with(framework) framework_module = if framework.is_a?(Module) framework else const_name = MOCKING_ADAPTERS.fetch(framework) do raise ArgumentError, "Unknown mocking framework: #{framework.inspect}. " \ "Pass a module or one of #{MOCKING_ADAPTERS.keys.inspect}" end RSpec::Support.require_rspec_core "mocking_adapters/#{const_name.to_s.downcase}" RSpec::Core::MockingAdapters.const_get(const_name) end new_name, old_name = [framework_module, @mock_framework].map do |mod| mod.respond_to?(:framework_name) ? mod.framework_name : :unnamed end unless new_name == old_name assert_no_example_groups_defined(:mock_framework) end if block_given? raise "#{framework_module} must respond to `configuration` so that " \ "mock_with can yield it." unless framework_module.respond_to?(:configuration) yield framework_module.configuration end @mock_framework = framework_module end |
#on_example_group_definition(&block) ⇒ void
Invokes block before defining an example group
2085 2086 2087 |
# File 'lib/rspec/core/configuration.rb', line 2085 def on_example_group_definition(&block) on_example_group_definition_callbacks << block end |
#on_example_group_definition_callbacks ⇒ void
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Returns an array of blocks to call before defining an example group
2091 2092 2093 |
# File 'lib/rspec/core/configuration.rb', line 2091 def on_example_group_definition_callbacks @on_example_group_definition_callbacks ||= [] end |
#order=(value) ⇒ void
Sets the default global ordering strategy. By default this can be one
of :defined
, :random
, but is customizable through the
register_ordering
API. If order is set to 'rand:<seed>'
,
the seed will also be set.
1678 |
# File 'lib/rspec/core/configuration.rb', line 1678 delegate_to_ordering_manager :order= |
#prepend(mod, *filters) ⇒ void
Tells RSpec to prepend example groups with mod
. Methods defined in
mod
are exposed to examples (not example groups). Use filters
to
constrain the groups in which to prepend the module.
Similar to include
, but module is included before the example group's class
in the ancestor chain.
1531 1532 1533 1534 1535 |
# File 'lib/rspec/core/configuration.rb', line 1531 def prepend(mod, *filters) define_mixed_in_module(mod, filters, @prepend_modules, :prepend) do |group| safe_prepend(mod, group) end end |
#prepend_before(scope = nil, *meta, &block) ⇒ void
Adds block
to the start of the list of before
blocks in the same
scope (:example
, :context
, or :suite
), in contrast to #before,
which adds the hook to the end of the list.
See Hooks#before for full before
hook docs.
This method differs from Hooks#prepend_before in only one way: it supports
the :suite
scope. Hooks with the :suite
scope will be run once before
the first example of the entire suite is executed. Conditions passed along
with :suite
are effectively ignored.
1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 |
# File 'lib/rspec/core/configuration.rb', line 1977 def prepend_before(scope=nil, *, &block) handle_suite_hook(scope, ) 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(, scope) { |g| g.prepend_before(scope, *, &block) } super(scope, *, &block) end end |
#raise_errors_for_deprecations! ⇒ void
Turns deprecation warnings into errors, in order to surface the full backtrace of the call site. This can be useful when you need more context to address a deprecation than the single-line call site normally provided.
1804 1805 1806 |
# File 'lib/rspec/core/configuration.rb', line 1804 def raise_errors_for_deprecations! self.deprecation_stream = Formatters::DeprecationFormatter::RaiseErrorStream.new end |
#raise_on_warning=(value) ⇒ void
Turns warnings into errors. This can be useful when you want RSpec to run in a 'strict' no warning situation.
1752 1753 1754 1755 1756 1757 1758 |
# File 'lib/rspec/core/configuration.rb', line 1752 def raise_on_warning=(value) if value RSpec::Support.warning_notifier = RAISE_ERROR_WARNING_NOTIFIER else RSpec::Support.warning_notifier = RSpec::Support::DEFAULT_WARNING_NOTIFIER end end |
#register_ordering(name) {|list| ... } ⇒ void
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.
1726 |
# File 'lib/rspec/core/configuration.rb', line 1726 delegate_to_ordering_manager :register_ordering |
#reporter ⇒ RSpec::Core::Reporter
Returns the currently configured reporter.
1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 |
# File 'lib/rspec/core/configuration.rb', line 1033 def reporter # @reporter_buffer should only ever be set in this method to cover # initialization of @reporter. @reporter_buffer || @reporter ||= begin @reporter_buffer = DeprecationReporterBuffer.new formatter_loader.prepare_default output_wrapper, deprecation_stream @reporter_buffer.play_onto(formatter_loader.reporter) @reporter_buffer = nil formatter_loader.reporter end end |
#seed ⇒ void
Seed for random ordering (default: generated randomly each run).
When you run specs with --order random
, RSpec generates a random seed
for the randomization and prints it to the output_stream
(assuming
you're using RSpec's built-in formatters). If you discover an ordering
dependency (i.e. examples fail intermittently depending on order), set
this (on Configuration or on the command line with --seed
) to run
using the same seed while you debug the issue.
We recommend, actually, that you use the command line approach so you don't accidentally leave the seed encoded.
1668 |
# File 'lib/rspec/core/configuration.rb', line 1668 delegate_to_ordering_manager :seed |
#seed=(value) ⇒ void
Sets the seed value and sets the default global ordering to random.
1654 |
# File 'lib/rspec/core/configuration.rb', line 1654 delegate_to_ordering_manager :seed= |
#treat_symbols_as_metadata_keys_with_true_values=(_value) ⇒ void
This config option was added in RSpec 2 to pave the way for this being the default behavior in RSpec 3. Now this option is a no-op.
383 384 385 386 387 388 389 390 |
# File 'lib/rspec/core/configuration.rb', line 383 def (_value) RSpec.deprecate( "RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values=", :message => "RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values= " \ "is deprecated, it is now set to true as default and " \ "setting it to false has no effect." ) end |
#warnings=(value) ⇒ void
Set Ruby warnings on or off.
1732 1733 1734 |
# File 'lib/rspec/core/configuration.rb', line 1732 def warnings=(value) $VERBOSE = !!value end |
#warnings? ⇒ Boolean
Returns Whether or not ruby warnings are enabled.
1737 1738 1739 |
# File 'lib/rspec/core/configuration.rb', line 1737 def warnings? $VERBOSE end |
#when_first_matching_example_defined(*filters) ⇒ void
Defines a callback that runs after the first example with matching metadata is defined. If no examples are defined with matching metadata, it will not get called at all.
This can be used to ensure some setup is performed (such as bootstrapping a DB or loading a specific file that adds significantly to the boot time) if needed (as indicated by the presence of an example with matching metadata) but avoided otherwise.
1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 |
# File 'lib/rspec/core/configuration.rb', line 1894 def when_first_matching_example_defined(*filters) = Metadata.build_hash_from(filters, :warn_about_example_group_filtering) callback = lambda do || # Example groups do not have `:example_group` metadata # (instead they have `:parent_example_group` metadata). return unless .key?(:example_group) # Ensure the callback only fires once. @derived_metadata_blocks.delete(callback, ) yield end @derived_metadata_blocks.append(callback, ) end |