Class: RSpec::Core::Configuration
- Inherits:
-
Object
- Object
- RSpec::Core::Configuration
- Includes:
- 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
).
Defined Under Namespace
Classes: MustBeConfiguredBeforeExampleGroupsError
Constant Summary
Constant Summary
Constants included from Hooks
Hooks::HOOK_TYPES, Hooks::SCOPES
Instance Attribute Summary (collapse)
-
- (Object) backtrace_cleaner
readonly
Returns the value of attribute backtrace_cleaner.
Instance Method Summary (collapse)
-
- (Object) add_formatter(formatter)
(also: #formatter=)
Adds a formatter to the formatters collection.
-
- (Object) add_setting(name, opts = {})
Adds a custom setting to the RSpec.configuration object.
-
- (Object) alias_example_to(new_name, *args)
Creates a method that delegates to
example
including the submittedargs
. -
- (Object) alias_it_behaves_like_to(new_name, report_label = '')
(also: #alias_it_should_behave_like_to)
Define an alias for itshouldbehavelike that allows different language (like "ithasbehavior" or "itbehaves_like") to be employed when including shared examples.
-
- (Object) backtrace_clean_patterns
The patterns to discard from backtraces.
- - (Object) backtrace_clean_patterns=(patterns)
-
- (Object) backtrace_exclusion_patterns
The patterns to discard from backtraces.
- - (Object) backtrace_exclusion_patterns=(patterns)
-
- (Object) backtrace_inclusion_patterns
The patterns to always include to backtraces.
- - (Object) backtrace_inclusion_patterns=(patterns)
- - (Object) color(output = output_stream) (also: #color_enabled)
- - (Object) color=(bool) (also: #color_enabled=)
- - (Object) debug=(bool)
- - (Boolean) debug?
-
- (Object) exclusion_filter
Returns the
exclusion_filter
. -
- (Object) exclusion_filter=(filter)
Clears and reassigns the
exclusion_filter
. -
- (Object) expect_with(*frameworks)
Sets the expectation framework module(s) to be included in each example group.
-
- (Object) expectation_framework=(framework)
Delegates to expect_with(framework).
-
- (Object) expectation_frameworks
Returns the configured expectation framework adapter module(s).
-
- (Object) extend(mod, *filters)
Tells RSpec to extend example groups with
mod
. -
- (Object) filter_run_excluding(*args)
Adds key/value pairs to the
exclusion_filter
. -
- (Object) filter_run_including(*args)
(also: #filter_run)
Adds key/value pairs to the
inclusion_filter
. -
- (Object) format_docstrings
Formats the docstring output using the block provided.
- - (Object) formatters
- - (Object) full_backtrace=(true_or_false)
- - (Boolean) full_backtrace?
- - (Object) full_description
- - (Object) full_description=(description)
-
- (Object) include(mod, *filters)
Tells RSpec to include
mod
in example groups. -
- (Object) inclusion_filter
(also: #filter)
Returns the
inclusion_filter
. -
- (Object) inclusion_filter=(filter)
(also: #filter=)
Clears and reassigns the
inclusion_filter
. -
- (Configuration) initialize
constructor
A new instance of Configuration.
- - (Object) libs=(libs)
- - (Object) line_numbers
-
- (Object) line_numbers=(line_numbers)
Run examples defined on
line_numbers
in all files to run. -
- (Object) mock_framework
Returns the configured mock framework adapter module.
-
- (Object) mock_framework=(framework)
Delegates to mock_framework=(framework).
-
- (Object) mock_with(framework)
Sets the mock framework adapter module.
-
- (Object) order=(type)
Sets the order and, if order is
'rand:<seed>'
, also sets the seed. -
- (Object) order_examples
Sets a strategy by which to order examples.
-
- (Object) order_groups
Sets a strategy by which to order groups.
-
- (Object) order_groups_and_examples
Sets a strategy by which to order groups and examples.
-
- (Object) profile_examples
private
Defaults
profile_examples
to 10 examples when@profile_examples
istrue
. - - (Boolean) randomize?
- - (Object) reporter
- - (Object) requires=(paths)
- - (Object) safe_extend(mod, host)
-
- (Object) seed=(seed)
Sets the seed value and sets
order='rand'
. - - (Object) warnings
-
- (Object) warnings=(value)
Set Ruby warnings on or off.
Methods included from Hooks
#after, #append_after, #around, #before, #prepend_before
Constructor Details
- (Configuration) initialize
A new instance of Configuration
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 |
# File 'lib/rspec/core/configuration.rb', line 186 def initialize @expectation_frameworks = [] @include_or_extend_modules = [] @mock_framework = nil @files_to_run = [] @formatters = [] @color = false @pattern = '**/*_spec.rb' @failure_exit_code = 1 @backtrace_cleaner = BacktraceCleaner.new @default_path = 'spec' @deprecation_stream = $stderr @filter_manager = FilterManager.new @preferred_options = {} @seed = srand % 0xFFFF @failure_color = :red @success_color = :green @pending_color = :yellow @default_color = :white @fixed_color = :blue @detail_color = :cyan @profile_examples = false @requires = [] @libs = [] end |
Instance Attribute Details
- (Object) backtrace_cleaner (readonly)
Returns the value of attribute backtrace_cleaner
184 185 186 |
# File 'lib/rspec/core/configuration.rb', line 184 def backtrace_cleaner @backtrace_cleaner end |
Instance Method Details
- (Object) 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.
571 572 573 574 575 576 577 578 579 |
# File 'lib/rspec/core/configuration.rb', line 571 def add_formatter(formatter_to_use, *paths) formatter_class = built_in_formatter(formatter_to_use) || custom_formatter(formatter_to_use) || (raise ArgumentError, "Formatter '#{formatter_to_use}' unknown - maybe you meant 'documentation' or 'progress'?.") paths << output if paths.empty? formatters << formatter_class.new(*paths.map {|p| String === p ? file_at(p) : p}) end |
- (Object) add_setting(name) - (Object) 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
268 269 270 271 272 273 274 |
# File 'lib/rspec/core/configuration.rb', line 268 def add_setting(name, opts={}) default = opts.delete(:default) (class << self; self; end).class_eval do add_setting(name, opts) end send("#{name}=", default) if default end |
- (Object) alias_example_to(new_name, *args)
Creates a method that delegates to example
including the submitted
args
. Used internally to add variants of example
like pending
:
636 637 638 639 |
# File 'lib/rspec/core/configuration.rb', line 636 def alias_example_to(new_name, *args) = (args) RSpec::Core::ExampleGroup.alias_example_to(new_name, ) end |
- (Object) alias_it_behaves_like_to(new_name, report_label = '') Also known as: alias_it_should_behave_like_to
Define an alias for itshouldbehavelike that allows different language (like "ithasbehavior" or "itbehaves_like") to be employed when including shared examples.
Example:
alias_it_behaves_like_to(:it_has_behavior, 'has behavior:')
allows the user to include a shared example group like:
describe Entity do
it_has_behavior 'sortability' do
let(:sortable) { Entity.new }
end
end
which is reported in the output as:
Entity
has behavior: sortability
# sortability examples here
662 663 664 |
# File 'lib/rspec/core/configuration.rb', line 662 def alias_it_behaves_like_to(new_name, report_label = '') RSpec::Core::ExampleGroup.alias_it_behaves_like_to(new_name, report_label) end |
- (Object) backtrace_clean_patterns
The patterns to discard from backtraces. Deprecated, use Configuration#backtraceexclusionpatterns instead
Defaults to RSpec::Core::BacktraceCleaner::DEFAULTEXCLUSIONPATTERNS
One can replace the list by using the setter or modify it through the getter
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.
298 299 300 301 302 |
# File 'lib/rspec/core/configuration.rb', line 298 def backtrace_clean_patterns RSpec.deprecate("RSpec::Core::Configuration#backtrace_clean_patterns", :replacement => "RSpec::Core::Configuration#backtrace_exclusion_patterns") @backtrace_cleaner.exclusion_patterns end |
- (Object) backtrace_clean_patterns=(patterns)
304 305 306 307 308 |
# File 'lib/rspec/core/configuration.rb', line 304 def backtrace_clean_patterns=(patterns) RSpec.deprecate("RSpec::Core::Configuration#backtrace_clean_patterns", :replacement => "RSpec::Core::Configuration#backtrace_exclusion_patterns") @backtrace_cleaner.exclusion_patterns = patterns end |
- (Object) backtrace_exclusion_patterns
The patterns to discard from backtraces.
Defaults to RSpec::Core::BacktraceCleaner::DEFAULTEXCLUSIONPATTERNS
One can replace the list by using the setter or modify it through the getter
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.
335 336 337 |
# File 'lib/rspec/core/configuration.rb', line 335 def backtrace_exclusion_patterns @backtrace_cleaner.exclusion_patterns end |
- (Object) backtrace_exclusion_patterns=(patterns)
339 340 341 |
# File 'lib/rspec/core/configuration.rb', line 339 def backtrace_exclusion_patterns=(patterns) @backtrace_cleaner.exclusion_patterns = patterns end |
- (Object) backtrace_inclusion_patterns
The patterns to always include to backtraces.
Defaults to [Regexp.new Dir.getwd] if the current working directory matches any of the exclusion patterns. Otherwise it defaults to empty.
One can replace the list by using the setter or modify it through the getter
317 318 319 |
# File 'lib/rspec/core/configuration.rb', line 317 def backtrace_inclusion_patterns @backtrace_cleaner.inclusion_patterns end |
- (Object) backtrace_inclusion_patterns=(patterns)
321 322 323 |
# File 'lib/rspec/core/configuration.rb', line 321 def backtrace_inclusion_patterns=(patterns) @backtrace_cleaner.inclusion_patterns = patterns end |
- (Object) color(output = output_stream) Also known as: color_enabled
479 480 481 482 483 484 485 |
# File 'lib/rspec/core/configuration.rb', line 479 def color(output=output_stream) # rspec's built-in formatters all call this with the output argument, # but defaulting to output_stream for backward compatibility with # formatters in extension libs return false unless output_to_tty?(output) value_for(:color, @color) end |
- (Object) color=(bool) Also known as: color_enabled=
487 488 489 490 491 492 493 494 495 496 |
# File 'lib/rspec/core/configuration.rb', line 487 def color=(bool) if bool if RSpec.windows_os? and not ENV['ANSICON'] warn "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 end |
- (Object) debug=(bool)
518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 |
# File 'lib/rspec/core/configuration.rb', line 518 def debug=(bool) return unless bool begin require 'ruby-debug' Debugger.start rescue LoadError => e raise <<-EOM #{'*'*50} #{e.} If you have it installed as a ruby gem, then you need to either require 'rubygems' or configure the RUBYOPT environment variable with the value 'rubygems'. #{e.backtrace.join("\n")} #{'*'*50} EOM end end |
- (Boolean) debug?
539 540 541 |
# File 'lib/rspec/core/configuration.rb', line 539 def debug? !!defined?(Debugger) end |
- (Object) exclusion_filter
Returns the exclusion_filter
. If none has been set, returns an empty
hash.
774 775 776 |
# File 'lib/rspec/core/configuration.rb', line 774 def exclusion_filter filter_manager.exclusions end |
- (Object) 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.
768 769 770 |
# File 'lib/rspec/core/configuration.rb', line 768 def exclusion_filter=(filter) filter_manager.exclude! ([filter]) end |
- (Object) expect_with(*frameworks)
Sets the expectation framework module(s) to be included in each example group.
frameworks
can be :rspec
, :stdlib
, a custom module, or any
combination thereof:
config.expect_with :rspec
config.expect_with :stdlib
config.expect_with :rspec, :stdlib
config.expect_with OtherExpectationFramework
RSpec will translate :rspec
and :stdlib
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
441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 |
# File 'lib/rspec/core/configuration.rb', line 441 def expect_with(*frameworks) modules = frameworks.map do |framework| case framework when Module framework when :rspec require 'rspec/expectations' self.expecting_with_rspec = true ::RSpec::Matchers when :stdlib require 'test/unit/assertions' ::Test::Unit::Assertions 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 |
- (Object) expectation_framework=(framework)
Delegates to expect_with(framework)
415 416 417 |
# File 'lib/rspec/core/configuration.rb', line 415 def expectation_framework=(framework) expect_with(framework) end |
- (Object) expectation_frameworks
Returns the configured expectation framework adapter module(s)
409 410 411 412 |
# File 'lib/rspec/core/configuration.rb', line 409 def expectation_frameworks expect_with :rspec if @expectation_frameworks.empty? @expectation_frameworks end |
- (Object) 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.
843 844 845 |
# File 'lib/rspec/core/configuration.rb', line 843 def extend(mod, *filters) include_or_extend_modules << [:extend, mod, (filters)] end |
- (Object) filter_run_excluding(*args)
Adds key/value pairs to the exclusion_filter
. If the
treat_symbols_as_metadata_keys_with_true_values
config option is set
to true and args
excludes any symbols that are not part of a 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
).
757 758 759 |
# File 'lib/rspec/core/configuration.rb', line 757 def filter_run_excluding(*args) filter_manager.exclude_with_low_priority (args) end |
- (Object) filter_run_including(*args) Also known as: filter_run
Adds key/value pairs to the inclusion_filter
. If the
treat_symbols_as_metadata_keys_with_true_values
config option is set
to true and args
includes any symbols that are not part of a 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
).
699 700 701 |
# File 'lib/rspec/core/configuration.rb', line 699 def filter_run_including(*args) filter_manager.include_with_low_priority (args) end |
- (Object) format_docstrings
Formats the docstring output using the block provided.
910 911 912 |
# File 'lib/rspec/core/configuration.rb', line 910 def format_docstrings(&block) @format_docstrings_block = block_given? ? block : DEFAULT_FORMATTER end |
- (Object) formatters
583 584 585 |
# File 'lib/rspec/core/configuration.rb', line 583 def formatters @formatters ||= [] end |
- (Object) full_backtrace=(true_or_false)
475 476 477 |
# File 'lib/rspec/core/configuration.rb', line 475 def full_backtrace=(true_or_false) @backtrace_cleaner.full_backtrace = true_or_false end |
- (Boolean) full_backtrace?
471 472 473 |
# File 'lib/rspec/core/configuration.rb', line 471 def full_backtrace? @backtrace_cleaner.full_backtrace? end |
- (Object) full_description
556 557 558 |
# File 'lib/rspec/core/configuration.rb', line 556 def full_description filter.fetch :full_description, nil end |
- (Object) full_description=(description)
552 553 554 |
# File 'lib/rspec/core/configuration.rb', line 552 def full_description=(description) filter_run :full_description => Regexp.union(*Array(description).map {|d| Regexp.new(d) }) end |
- (Object) include(mod, *filters)
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 in which to include the module.
810 811 812 |
# File 'lib/rspec/core/configuration.rb', line 810 def include(mod, *filters) include_or_extend_modules << [:include, mod, (filters)] end |
- (Object) inclusion_filter Also known as: filter
Returns the inclusion_filter
. If none has been set, returns an empty
hash.
720 721 722 |
# File 'lib/rspec/core/configuration.rb', line 720 def inclusion_filter filter_manager.inclusions end |
- (Object) 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.
712 713 714 |
# File 'lib/rspec/core/configuration.rb', line 712 def inclusion_filter=(filter) filter_manager.include! ([filter]) end |
- (Object) libs=(libs)
504 505 506 507 508 509 |
# File 'lib/rspec/core/configuration.rb', line 504 def libs=(libs) libs.map do |lib| @libs.unshift lib $LOAD_PATH.unshift lib end end |
- (Object) line_numbers
548 549 550 |
# File 'lib/rspec/core/configuration.rb', line 548 def line_numbers filter.fetch(:line_numbers,[]) end |
- (Object) line_numbers=(line_numbers)
Run examples defined on line_numbers
in all files to run.
544 545 546 |
# File 'lib/rspec/core/configuration.rb', line 544 def line_numbers=(line_numbers) filter_run :line_numbers => line_numbers.map{|l| l.to_i} end |
- (Object) mock_framework
Returns the configured mock framework adapter module
277 278 279 280 |
# File 'lib/rspec/core/configuration.rb', line 277 def mock_framework mock_with :rspec unless @mock_framework @mock_framework end |
- (Object) mock_framework=(framework)
Delegates to mock_framework=(framework)
283 284 285 |
# File 'lib/rspec/core/configuration.rb', line 283 def mock_framework=(framework) mock_with framework end |
- (Object) 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. 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
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 |
# File 'lib/rspec/core/configuration.rb', line 372 def mock_with(framework) framework_module = case framework when Module framework when String, Symbol require case framework.to_s when /rspec/i 'rspec/core/mocking/with_rspec' when /mocha/i 'rspec/core/mocking/with_mocha' when /rr/i 'rspec/core/mocking/with_rr' when /flexmock/i 'rspec/core/mocking/with_flexmock' else 'rspec/core/mocking/with_absolutely_nothing' end RSpec::Core::MockFrameworkAdapter 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 |
- (Object) order=(type)
Sets the order and, if order is 'rand:<seed>'
, also sets the seed.
929 930 931 |
# File 'lib/rspec/core/configuration.rb', line 929 def order=(type) order_and_seed_from_order(type) end |
- (Object) order_examples
Sets a strategy by which to order examples.
961 962 963 964 |
# File 'lib/rspec/core/configuration.rb', line 961 def order_examples(&block) @example_ordering_block = block @order = "custom" unless built_in_orderer?(block) end |
- (Object) order_groups
Sets a strategy by which to order groups.
984 985 986 987 |
# File 'lib/rspec/core/configuration.rb', line 984 def order_groups(&block) @group_ordering_block = block @order = "custom" unless built_in_orderer?(block) end |
- (Object) order_groups_and_examples
Sets a strategy by which to order groups and examples.
1007 1008 1009 1010 |
# File 'lib/rspec/core/configuration.rb', line 1007 def order_groups_and_examples(&block) order_groups(&block) order_examples(&block) end |
- (Object) 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
.
599 600 601 602 603 604 605 606 |
# File 'lib/rspec/core/configuration.rb', line 599 def profile_examples profile = value_for(:profile_examples, @profile_examples) if profile && !profile.is_a?(Integer) 10 else profile end end |
- (Boolean) randomize?
933 934 935 |
# File 'lib/rspec/core/configuration.rb', line 933 def randomize? order.to_s.match(/rand/) end |
- (Object) reporter
587 588 589 590 591 592 593 |
# File 'lib/rspec/core/configuration.rb', line 587 def reporter @reporter ||= begin add_formatter('progress') if formatters.empty? add_formatter(RSpec::Core::Formatters::DeprecationFormatter, deprecation_stream, output_stream) Reporter.new(*formatters) end end |
- (Object) requires=(paths)
511 512 513 514 515 516 |
# File 'lib/rspec/core/configuration.rb', line 511 def requires=(paths) RSpec.deprecate("RSpec::Core::Configuration#requires=(paths)", :replacement => "paths.each {|path| require path}") paths.map {|path| require path} @requires += paths end |
- (Object) safe_extend(mod, host)
873 874 875 |
# File 'lib/rspec/core/configuration.rb', line 873 def safe_extend(mod, host) host.extend(mod) unless (class << host; self; end) < mod end |
- (Object) seed=(seed)
Sets the seed value and sets order='rand'
922 923 924 |
# File 'lib/rspec/core/configuration.rb', line 922 def seed=(seed) order_and_seed_from_seed(seed) end |
- (Object) warnings
1017 1018 1019 |
# File 'lib/rspec/core/configuration.rb', line 1017 def warnings $VERBOSE end |
- (Object) warnings=(value)
Set Ruby warnings on or off
1013 1014 1015 |
# File 'lib/rspec/core/configuration.rb', line 1013 def warnings= value $VERBOSE = !!value end |