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 ~/.rspec
, .rspec
,
.rspec-local
, command line switches, and the SPEC_OPTS
environment
variable (listed in lowest to highest precedence; for example, an option
in ~/.rspec
can be overridden by an option in .rspec-local
).
Constant Summary
Instance Attribute Summary (collapse)
-
- (void) default_color
The default output color.
-
- (void) default_path
Path to use if no path is provided to the
rspec
command (default:"spec"
). -
- (void) detail_color
Color used to print details.
-
- (void) drb
Run examples over DRb (default:
false
). -
- (void) drb_port
The drb_port (default: nil).
-
- (void) dry_run
Prints the formatter output of your suite without running any examples or hooks.
-
- (void) error_stream
Default:
$stderr
. -
- (void) exclude_pattern
Exclude files matching this pattern.
-
- (void) fail_fast
Clean up and exit after the first failure (default:
false
). -
- (void) failure_color
Color to use to indicate failure.
-
- (void) failure_exit_code
The exit code to return if there are any failures (default: 1).
-
- (Array) files_to_run
readonly
The spec files RSpec will run.
-
- (void) fixed_color
Color used when a pending example is fixed.
-
- (void) libs
readonly
Returns dirs that have been prepended to the load path by the
-I
command line option. -
- (void) output_stream
Determines where RSpec will send its output.
-
- (void) pattern
Load files matching this pattern (default:
'**{,/*/**}/*_spec.rb'
). -
- (void) pending_color
Color to use to print pending examples.
-
- (void) profile_examples
private
Defaults
profile_examples
to 10 examples when@profile_examples
istrue
. -
- (void) requires
readonly
Indicates files configured to be required.
-
- (void) run_all_when_everything_filtered
Run all examples if none match the configured filters (default:
false
). -
- (void) success_color
Color to use to indicate success.
Instance Method Summary (collapse)
-
- (void) add_formatter(formatter)
(also: #formatter=)
Adds a formatter to the formatters collection.
-
- (void) add_setting(name, opts = {})
Adds a custom setting to the RSpec.configuration object.
-
- (void) after(*args, &block)
(also: #prepend_after)
Defines a
after
hook. -
- (void) alias_example_group_to(new_name, *args)
Creates a method that defines an example group with the provided metadata.
-
- (void) alias_example_to(name, *args)
Creates a method that delegates to
example
including the submittedargs
. -
- (void) 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.
-
- (void) append_after(*args, &block)
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. -
- (void) backtrace_exclusion_patterns
Regexps used to exclude lines from backtraces.
-
- (void) backtrace_exclusion_patterns=(patterns)
Set regular expressions used to exclude lines in backtrace.
-
- (void) backtrace_inclusion_patterns
Regexps used to include lines in backtraces.
-
- (void) backtrace_inclusion_patterns=(patterns)
Set regular expressions used to include lines in backtrace.
-
- (void) before(*args, &block)
(also: #append_before)
Defines a
before
hook. -
- (Boolean) color
Returns the configuration option for color, but should not be used to check if color is supported.
-
- (void) color=(true_or_false)
Toggle output color.
-
- (Boolean) color_enabled?(output = output_stream)
Check if color is enabled for a particular output.
-
- (void) default_formatter
The formatter that will be used if no formatter has been set.
-
- (void) default_formatter=(value)
Sets a fallback formatter to use if none other has been set.
-
- (void) define_derived_metadata(*filters) {|metadata| ... }
Defines a callback that can assign derived metadata values.
-
- (IO, String) deprecation_stream
Determines where deprecation warnings are printed.
-
- (void) deprecation_stream=(value)
Determines where deprecation warnings are printed.
-
- (void) disable_monkey_patching!
Enables zero monkey patching mode for RSpec.
-
- (void) exclusion_filter
Returns the
exclusion_filter
. -
- (void) exclusion_filter=(filter)
Clears and reassigns the
exclusion_filter
. -
- (void) expect_with(*frameworks)
Sets the expectation framework module(s) to be included in each example group.
-
- (void) expectation_framework=(framework)
Delegates to expect_with(framework).
-
- (void) expectation_frameworks
Returns the configured expectation framework adapter module(s).
-
- (void) expose_current_running_example_as(method_name)
Exposes the current running example via the named helper method.
-
- (void) expose_dsl_globally=(value)
Use this to expose the core RSpec DSL via
Module
and themain
object. -
- (Boolean) expose_dsl_globally?
Indicates if the DSL has been exposed off of modules and
main
. -
- (void) extend(mod, *filters)
Tells RSpec to extend example groups with
mod
. -
- (void) filter_gems_from_backtrace(*gem_names)
Adds #backtrace_exclusion_patterns that will filter lines from the named gems from backtraces.
-
- (void) filter_run_excluding(*args)
Adds key/value pairs to the
exclusion_filter
. -
- (void) filter_run_including(*args)
(also: #filter_run)
Adds key/value pairs to the
inclusion_filter
. -
- (void) format_docstrings(&block)
Formats the docstring output using the block provided.
-
- (Array) formatters
Returns a duplicate of the formatters currently loaded in the
FormatterLoader
for introspection. -
- (void) full_backtrace=(true_or_false)
Toggle full backtrace.
-
- (Boolean) full_backtrace?
Check if full backtrace is enabled.
-
- (Array) full_description
Full description filter.
-
- (void) full_description=(description)
Run examples matching on
description
in all files to run. -
- (void) include(mod, *filters)
Tells RSpec to include
mod
in example groups. -
- (void) inclusion_filter
(also: #filter)
Returns the
inclusion_filter
. -
- (void) inclusion_filter=(filter)
(also: #filter=)
Clears and reassigns the
inclusion_filter
. -
- (Configuration) initialize
constructor
A new instance of Configuration.
-
- (void) mock_framework
Returns the configured mock framework adapter module.
-
- (void) mock_framework=(framework)
Delegates to mock_framework=(framework).
-
- (void) mock_with(framework)
Sets the mock framework adapter module.
-
- (void) order=
Sets the default global order and, if order is
'rand:'
, also sets the seed. -
- (void) prepend(mod, *filters)
Tells RSpec to prepend example groups with
mod
. -
- (void) prepend_before(*args, &block)
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. -
- (void) raise_errors_for_deprecations!
Turns deprecation warnings into errors, in order to surface the full backtrace of the call site.
-
- (void) register_ordering {|list| ... }
Registers a named ordering strategy that can later be used to order an example group's subgroups by adding
:order =>
metadata to the example group. -
- (void) seed
Seed for random ordering (default: generated randomly each run).
-
- (void) seed=
Sets the seed value and sets the default global ordering to random.
-
- (void) treat_symbols_as_metadata_keys_with_true_values=(_value)
Deprecated.
-
- (void) warnings=(value)
Set Ruby warnings on or off.
-
- (Boolean) warnings?
Whether or not ruby warnings are enabled.
Methods included from Hooks
Constructor Details
- (Configuration) initialize
Returns a new instance of Configuration
295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 |
# File 'lib/rspec/core/configuration.rb', line 295 def initialize # rubocop:disable Style/GlobalVars @start_time = $_rspec_core_load_started_at || ::RSpec::Core::Time.now # rubocop:enable Style/GlobalVars @expectation_frameworks = [] @include_modules = FilterableItemRepository::QueryOptimized.new(:any?) @extend_modules = FilterableItemRepository::QueryOptimized.new(:any?) @prepend_modules = FilterableItemRepository::QueryOptimized.new(:any?) @before_suite_hooks = [] @after_suite_hooks = [] @mock_framework = nil @files_or_directories_to_run = [] @loaded_spec_files = Set.new @color = false @pattern = '**{,/*/**}/*_spec.rb' @exclude_pattern = '' @failure_exit_code = 1 @spec_files_loaded = false @backtrace_formatter = BacktraceFormatter.new @default_path = 'spec' @deprecation_stream = $stderr @output_stream = $stdout @reporter = nil @reporter_buffer = nil @filter_manager = FilterManager.new @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?) end |
Instance Attribute Details
- (void) default_color
The default output color.
253 |
# File 'lib/rspec/core/configuration.rb', line 253 add_setting :default_color |
- (void) default_path
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.
103 |
# File 'lib/rspec/core/configuration.rb', line 103 add_setting :default_path |
- (void) detail_color
Color used to print details.
267 |
# File 'lib/rspec/core/configuration.rb', line 267 add_setting :detail_color |
- (void) drb
Run examples over DRb (default: false
). RSpec doesn't supply the DRb
server, but you can use tools like spork.
108 |
# File 'lib/rspec/core/configuration.rb', line 108 add_setting :drb |
- (void) drb_port
The drb_port (default: nil).
112 |
# File 'lib/rspec/core/configuration.rb', line 112 add_setting :drb_port |
- (void) dry_run
Prints the formatter output of your suite without running any examples or hooks.
164 |
# File 'lib/rspec/core/configuration.rb', line 164 add_setting :dry_run |
- (void) error_stream
Default: $stderr
.
116 |
# File 'lib/rspec/core/configuration.rb', line 116 add_setting :error_stream |
- (void) exclude_pattern
Exclude files matching this pattern.
209 |
# File 'lib/rspec/core/configuration.rb', line 209 define_reader :exclude_pattern |
- (void) fail_fast
Clean up and exit after the first failure (default: false
).
159 |
# File 'lib/rspec/core/configuration.rb', line 159 add_setting :fail_fast |
- (void) failure_color
Color to use to indicate failure.
246 |
# File 'lib/rspec/core/configuration.rb', line 246 add_setting :failure_color |
- (void) failure_exit_code
The exit code to return if there are any failures (default: 1).
168 |
# File 'lib/rspec/core/configuration.rb', line 168 add_setting :failure_exit_code |
- (Array) files_to_run
The spec files RSpec will run.
802 803 804 |
# File 'lib/rspec/core/configuration.rb', line 802 def files_to_run @files_to_run ||= get_files_to_run(@files_or_directories_to_run) end |
- (void) fixed_color
Color used when a pending example is fixed.
260 |
# File 'lib/rspec/core/configuration.rb', line 260 add_setting :fixed_color |
- (void) libs
Returns dirs that have been prepended to the load path by the -I
command line option.
177 |
# File 'lib/rspec/core/configuration.rb', line 177 define_reader :libs |
- (void) output_stream
Determines where RSpec will send its output.
Default: $stdout
.
182 |
# File 'lib/rspec/core/configuration.rb', line 182 define_reader :output_stream |
- (void) pattern
Load files matching this pattern (default: '**{,/*/**}/*_spec.rb'
).
199 |
# File 'lib/rspec/core/configuration.rb', line 199 define_reader :pattern |
- (void) pending_color
Color to use to print pending examples.
239 |
# File 'lib/rspec/core/configuration.rb', line 239 add_setting :pending_color |
- (void) profile_examples
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
.
220 |
# File 'lib/rspec/core/configuration.rb', line 220 add_setting :profile_examples |
- (void) requires
Indicates files configured to be required.
172 |
# File 'lib/rspec/core/configuration.rb', line 172 define_reader :requires |
- (void) run_all_when_everything_filtered
Run all examples if none match the configured filters
(default: false
).
225 |
# File 'lib/rspec/core/configuration.rb', line 225 add_setting :run_all_when_everything_filtered |
- (void) success_color
Color to use to indicate success.
232 |
# File 'lib/rspec/core/configuration.rb', line 232 add_setting :success_color |
Instance Method Details
- (void) add_formatter(formatter) Also known as: formatter=
Adds a formatter to the formatters collection. formatter
can be a
string representing any of the built-in formatters (see
built_in_formatter
), or a custom formatter class.
Note
For internal purposes, add_formatter
also accepts the name of a class
and paths to use for output streams, but you should consider that a
private api that may change at any time without notice.
705 706 707 708 |
# File 'lib/rspec/core/configuration.rb', line 705 def add_formatter(formatter_to_use, *paths) paths << output_stream if paths.empty? formatter_loader.add formatter_to_use, *paths end |
- (void) add_setting(name) - (void) 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.
400 401 402 403 404 405 406 |
# File 'lib/rspec/core/configuration.rb', line 400 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 |
- (void) after(*args, &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.
1495 1496 1497 1498 |
# File 'lib/rspec/core/configuration.rb', line 1495 def after(*args, &block) handle_suite_hook(args, @after_suite_hooks, :unshift, Hooks::AfterHook, block) || super(*args, &block) end |
- (void) alias_example_group_to(new_name, *args)
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.
870 871 872 873 |
# File 'lib/rspec/core/configuration.rb', line 870 def alias_example_group_to(new_name, *args) = Metadata.build_hash_from(args) RSpec::Core::ExampleGroup.define_example_group_method(new_name, ) end |
- (void) alias_example_to(name, *args)
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
:
838 839 840 841 |
# File 'lib/rspec/core/configuration.rb', line 838 def alias_example_to(name, *args) = Metadata.build_hash_from(args) RSpec::Core::ExampleGroup.define_example_method(name, ) end |
- (void) alias_it_behaves_like_to(new_name, report_label = '') 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.
901 902 903 |
# File 'lib/rspec/core/configuration.rb', line 901 def alias_it_behaves_like_to(new_name, report_label='') RSpec::Core::ExampleGroup.define_nested_shared_group_method(new_name, report_label) end |
- (void) append_after(*args, &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.
1514 1515 1516 1517 |
# File 'lib/rspec/core/configuration.rb', line 1514 def append_after(*args, &block) handle_suite_hook(args, @after_suite_hooks, :push, Hooks::AfterHook, block) || super(*args, &block) end |
- (void) backtrace_exclusion_patterns
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.
436 437 438 |
# File 'lib/rspec/core/configuration.rb', line 436 def backtrace_exclusion_patterns @backtrace_formatter.exclusion_patterns end |
- (void) backtrace_exclusion_patterns=(patterns)
Set regular expressions used to exclude lines in backtrace.
442 443 444 |
# File 'lib/rspec/core/configuration.rb', line 442 def backtrace_exclusion_patterns=(patterns) @backtrace_formatter.exclusion_patterns = patterns end |
- (void) backtrace_inclusion_patterns
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.
454 455 456 |
# File 'lib/rspec/core/configuration.rb', line 454 def backtrace_inclusion_patterns @backtrace_formatter.inclusion_patterns end |
- (void) backtrace_inclusion_patterns=(patterns)
Set regular expressions used to include lines in backtrace.
460 461 462 |
# File 'lib/rspec/core/configuration.rb', line 460 def backtrace_inclusion_patterns=(patterns) @backtrace_formatter.inclusion_patterns = patterns end |
- (void) before(*args, &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.
1462 1463 1464 1465 |
# File 'lib/rspec/core/configuration.rb', line 1462 def before(*args, &block) handle_suite_hook(args, @before_suite_hooks, :push, Hooks::BeforeHook, block) || super(*args, &block) end |
- (Boolean) color
Returns the configuration option for color, but should not be used to check if color is supported.
648 649 650 |
# File 'lib/rspec/core/configuration.rb', line 648 def color value_for(:color) { @color } end |
- (void) color=(true_or_false)
Toggle output color.
662 663 664 665 666 667 668 669 670 671 672 673 |
# File 'lib/rspec/core/configuration.rb', line 662 def color=(true_or_false) return unless true_or_false if RSpec::Support::OS.windows? && !ENV['ANSICON'] RSpec.warning "You must use ANSICON 1.31 or later " \ "(http://adoxa.3eeweb.com/ansicon/) to use colour " \ "on Windows" @color = false else @color = true end end |
- (Boolean) color_enabled?(output = output_stream)
Check if color is enabled for a particular output.
656 657 658 |
# File 'lib/rspec/core/configuration.rb', line 656 def color_enabled?(output=output_stream) output_to_tty?(output) && color end |
- (void) default_formatter
The formatter that will be used if no formatter has been set. Defaults to 'progress'.
713 714 715 |
# File 'lib/rspec/core/configuration.rb', line 713 def default_formatter formatter_loader.default_formatter end |
- (void) default_formatter=(value)
Sets a fallback formatter to use if none other has been set.
724 725 726 |
# File 'lib/rspec/core/configuration.rb', line 724 def default_formatter=(value) formatter_loader.default_formatter = value end |
- (void) define_derived_metadata(*filters) {|metadata| ... }
Defines a callback that can assign derived metadata values.
1441 1442 1443 1444 |
# File 'lib/rspec/core/configuration.rb', line 1441 def (*filters, &block) = Metadata.build_hash_from(filters, :warn_about_example_group_filtering) @derived_metadata_blocks.append(block, ) end |
- (IO, String) deprecation_stream
Determines where deprecation warnings are printed.
Defaults to $stderr
.
141 |
# File 'lib/rspec/core/configuration.rb', line 141 define_reader :deprecation_stream |
- (void) deprecation_stream=(value)
Determines where deprecation warnings are printed.
145 146 147 148 149 150 151 152 153 154 155 |
# File 'lib/rspec/core/configuration.rb', line 145 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 |
- (void) disable_monkey_patching!
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.
1414 1415 1416 1417 1418 1419 |
# File 'lib/rspec/core/configuration.rb', line 1414 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 |
- (void) exclusion_filter
Returns the exclusion_filter
. If none has been set, returns an empty
hash.
1016 1017 1018 |
# File 'lib/rspec/core/configuration.rb', line 1016 def exclusion_filter filter_manager.exclusions end |
- (void) exclusion_filter=(filter)
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.
1009 1010 1011 1012 |
# File 'lib/rspec/core/configuration.rb', line 1009 def exclusion_filter=(filter) = Metadata.build_hash_from([filter], :warn_about_example_group_filtering) filter_manager.exclude_only end |
- (void) 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 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
596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 |
# File 'lib/rspec/core/configuration.rb', line 596 def expect_with(*frameworks) modules = frameworks.map do |framework| case framework when Module framework when :rspec require 'rspec/expectations' ::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 |
- (void) expectation_framework=(framework)
Delegates to expect_with(framework).
569 570 571 |
# File 'lib/rspec/core/configuration.rb', line 569 def expectation_framework=(framework) expect_with(framework) end |
- (void) expectation_frameworks
Returns the configured expectation framework adapter module(s)
557 558 559 560 561 562 563 564 565 566 |
# File 'lib/rspec/core/configuration.rb', line 557 def expectation_frameworks if @expectation_frameworks.empty? begin expect_with :rspec rescue LoadError expect_with Module.new end end @expectation_frameworks end |
- (void) 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.
1352 1353 1354 1355 1356 1357 1358 1359 |
# File 'lib/rspec/core/configuration.rb', line 1352 def expose_current_running_example_as(method_name) ExposeCurrentExample.module_exec do extend RSpec::SharedContext let(method_name) { |ex| ex } end include ExposeCurrentExample end |
- (void) expose_dsl_globally=(value)
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
128 129 130 131 132 133 134 135 136 |
# File 'lib/rspec/core/configuration.rb', line 128 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 |
- (Boolean) expose_dsl_globally?
Indicates if the DSL has been exposed off of modules and main
.
Default: true
120 121 122 |
# File 'lib/rspec/core/configuration.rb', line 120 def expose_dsl_globally? Core::DSL.exposed_globally? end |
- (void) 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.
1095 1096 1097 1098 |
# File 'lib/rspec/core/configuration.rb', line 1095 def extend(mod, *filters) = Metadata.build_hash_from(filters, :warn_about_example_group_filtering) @extend_modules.append(mod, ) end |
- (void) filter_gems_from_backtrace(*gem_names)
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.
480 481 482 483 484 |
# File 'lib/rspec/core/configuration.rb', line 480 def filter_gems_from_backtrace(*gem_names) gem_names.each do |name| @backtrace_formatter.filter_gem(name) end end |
- (void) 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
).
996 997 998 999 1000 |
# File 'lib/rspec/core/configuration.rb', line 996 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 |
- (void) 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
).
936 937 938 939 940 |
# File 'lib/rspec/core/configuration.rb', line 936 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 |
- (void) format_docstrings(&block)
Formats the docstring output using the block provided.
1244 1245 1246 |
# File 'lib/rspec/core/configuration.rb', line 1244 def format_docstrings(&block) @format_docstrings_block = block_given? ? block : DEFAULT_FORMATTER end |
- (Array) formatters
Returns a duplicate of the formatters currently loaded in
the FormatterLoader
for introspection.
Note as this is a duplicate, any mutations will be disregarded.
734 735 736 |
# File 'lib/rspec/core/configuration.rb', line 734 def formatters formatter_loader.formatters.dup end |
- (void) full_backtrace=(true_or_false)
Toggle full backtrace.
639 640 641 |
# File 'lib/rspec/core/configuration.rb', line 639 def full_backtrace=(true_or_false) @backtrace_formatter.full_backtrace = true_or_false end |
- (Boolean) full_backtrace?
Check if full backtrace is enabled.
633 634 635 |
# File 'lib/rspec/core/configuration.rb', line 633 def full_backtrace? @backtrace_formatter.full_backtrace? end |
- (Array) full_description
Returns full description filter
690 691 692 |
# File 'lib/rspec/core/configuration.rb', line 690 def full_description filter.fetch :full_description, nil end |
- (void) full_description=(description)
Run examples matching on description
in all files to run.
685 686 687 |
# File 'lib/rspec/core/configuration.rb', line 685 def full_description=(description) filter_run :full_description => Regexp.union(*Array(description).map { |d| Regexp.new(d) }) end |
- (void) include(mod, *filters)
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.
1060 1061 1062 1063 |
# File 'lib/rspec/core/configuration.rb', line 1060 def include(mod, *filters) = Metadata.build_hash_from(filters, :warn_about_example_group_filtering) @include_modules.append(mod, ) end |
- (void) inclusion_filter Also known as: filter
Returns the inclusion_filter
. If none has been set, returns an empty
hash.
960 961 962 |
# File 'lib/rspec/core/configuration.rb', line 960 def inclusion_filter filter_manager.inclusions end |
- (void) inclusion_filter=(filter) 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.
951 952 953 954 |
# File 'lib/rspec/core/configuration.rb', line 951 def inclusion_filter=(filter) = Metadata.build_hash_from([filter], :warn_about_example_group_filtering) filter_manager.include_only end |
- (void) mock_framework
Returns the configured mock framework adapter module.
409 410 411 412 413 414 415 416 417 418 |
# File 'lib/rspec/core/configuration.rb', line 409 def mock_framework if @mock_framework.nil? begin mock_with :rspec rescue LoadError mock_with :nothing end end @mock_framework end |
- (void) mock_framework=(framework)
Delegates to mock_framework=(framework).
421 422 423 |
# File 'lib/rspec/core/configuration.rb', line 421 def mock_framework=(framework) mock_with framework end |
- (void) 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 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
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 |
# File 'lib/rspec/core/configuration.rb', line 524 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 |
- (void) order=
Sets the default global order and, if order is 'rand:<seed>'
, also
sets the seed.
1287 |
# File 'lib/rspec/core/configuration.rb', line 1287 delegate_to_ordering_manager :order= |
- (void) 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.
1133 1134 1135 1136 |
# File 'lib/rspec/core/configuration.rb', line 1133 def prepend(mod, *filters) = Metadata.build_hash_from(filters, :warn_about_example_group_filtering) @prepend_modules.append(mod, ) end |
- (void) prepend_before(*args, &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.
1481 1482 1483 1484 |
# File 'lib/rspec/core/configuration.rb', line 1481 def prepend_before(*args, &block) handle_suite_hook(args, @before_suite_hooks, :unshift, Hooks::BeforeHook, block) || super(*args, &block) end |
- (void) 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.
1374 1375 1376 |
# File 'lib/rspec/core/configuration.rb', line 1374 def raise_errors_for_deprecations! self.deprecation_stream = Formatters::DeprecationFormatter::RaiseErrorStream.new end |
- (void) register_ordering {|list| ... }
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.
1315 |
# File 'lib/rspec/core/configuration.rb', line 1315 delegate_to_ordering_manager :register_ordering |
- (void) 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.
1281 |
# File 'lib/rspec/core/configuration.rb', line 1281 delegate_to_ordering_manager :seed |
- (void) seed=
Sets the seed value and sets the default global ordering to random.
1267 |
# File 'lib/rspec/core/configuration.rb', line 1267 delegate_to_ordering_manager :seed= |
- (void) treat_symbols_as_metadata_keys_with_true_values=(_value)
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.
272 273 274 275 276 277 278 279 |
# File 'lib/rspec/core/configuration.rb', line 272 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 |
- (void) warnings=(value)
Set Ruby warnings on or off.
1321 1322 1323 |
# File 'lib/rspec/core/configuration.rb', line 1321 def warnings=(value) $VERBOSE = !!value end |
- (Boolean) warnings?
Returns Whether or not ruby warnings are enabled.
1326 1327 1328 |
# File 'lib/rspec/core/configuration.rb', line 1326 def warnings? $VERBOSE end |