Class: RSpec::Core::Configuration

Inherits:
Object
  • Object
show all
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).

Examples:

Standard settings

RSpec.configure do |c|
  c.drb          = true
  c.drb_port     = 1234
  c.default_path = 'behavior'
end

Hooks

RSpec.configure do |c|
  c.before(:suite) { establish_connection }
  c.before(:each)  {  :authorized }
  c.around(:each)  { |ex| Database.transaction(&ex) }
end

See Also:

Defined Under Namespace

Modules: ExposeCurrentExample Classes: MustBeConfiguredBeforeExampleGroupsError

Constant Summary collapse

NoArgument = 
"No such argument"

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Hooks

#after, #append_after, #around, #before, #prepend_before

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/rspec/core/configuration.rb', line 282

def initialize
  @expectation_frameworks = []
  @include_or_extend_modules = []
  @mock_framework = nil
  @files_to_run = []
  @color = false
  @order = nil
  @pattern = '**/*_spec.rb'
  @failure_exit_code = 1
  @spec_files_loaded = false

  @backtrace_formatter = BacktraceCleaner.new

  @default_path = 'spec'
  @deprecation_stream = $stderr
  @output_stream = $stdout
  @reporter = nil
  @filter_manager = FilterManager.new
  @preferred_options = {}
  @seed = srand % 0xFFFF
  @ordering_already_forced = false
  @failure_color = :red
  @success_color = :green
  @pending_color = :yellow
  @default_color = :white
  @fixed_color = :blue
  @detail_color = :cyan
  @profile_examples = false
  @requires = []
  @libs = []
  @show_failures_in_pending_blocks = false
end

Instance Attribute Details

#backtrace_formatter ⇒ Object (readonly)

Returns the value of attribute backtrace_formatter.



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

def backtrace_formatter
  @backtrace_formatter
end

Instance Method Details

#add_formatter(formatter) ⇒ Object 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.



738
739
740
741
 
# File 'lib/rspec/core/configuration.rb', line 738

def add_formatter(formatter_to_use, *paths)
  paths << output_stream if paths.empty?
  formatter_loader.add formatter_to_use, *paths
end

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

Adds a custom setting to the RSpec.configuration object.

RSpec.configuration.add_setting :foo

Used internally and by extension frameworks like rspec-rails, so they can add config settings that are domain specific. For example:

RSpec.configure do |c|
  c.add_setting :use_transactional_fixtures,
    :default => true,
    :alias_with => :use_transactional_examples
end

add_setting creates three methods on the configuration object, a setter, a getter, and a predicate:

RSpec.configuration.foo=(value)
RSpec.configuration.foo
RSpec.configuration.foo? # returns true if foo returns anything but nil or false

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :default (Symbol) —

    set a default value for the generated getter and predicate methods:

    add_setting(:foo, :default => "default value")
  • :alias_with (Symbol) —

    Use :alias_with to alias the setter, getter, and predicate to another name, or names:

    add_setting(:foo, :alias_with => :bar)
add_setting(:foo, :alias_with => [:bar, :baz])



370
371
372
373
374
375
376
 
# File 'lib/rspec/core/configuration.rb', line 370

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

#alias_example_to(new_name, *args) ⇒ Object

Creates a method that delegates to example including the submitted args. Used internally to add variants of example like pending:

Examples:

alias_example_to :pending, :pending => true

# This lets you do this:

describe Thing do
  pending "does something" do
    thing = Thing.new
  end
end

# ... which is the equivalent of

describe Thing do
  it "does something", :pending => true do
    thing = Thing.new
  end
end


803
804
805
806
 
# File 'lib/rspec/core/configuration.rb', line 803

def alias_example_to(new_name, *args)
  extra_options = build_metadata_hash_from(args)
  RSpec::Core::ExampleGroup.define_example_method(new_name, extra_options)
end

#alias_it_behaves_like_to(new_name, report_label = '') ⇒ Object Also known as: 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.

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



829
830
831
 
# File 'lib/rspec/core/configuration.rb', line 829

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

#backtrace_clean_patterns ⇒ Object

The patterns to discard from backtraces. Deprecated, use Configuration#backtrace_exclusion_patterns instead

Defaults to RSpec::Core::BacktraceCleaner::DEFAULT_EXCLUSION_PATTERNS

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 --backtraceon the command line, in a .rspec file, or in the rspec_options attribute of RSpec's rake task.



400
401
402
403
404
 
# File 'lib/rspec/core/configuration.rb', line 400

def backtrace_clean_patterns
  RSpec.deprecate("RSpec::Core::Configuration#backtrace_clean_patterns",
                  :replacement => "RSpec::Core::Configuration#backtrace_exclusion_patterns")
  @backtrace_formatter.exclusion_patterns
end

#backtrace_clean_patterns=(patterns) ⇒ Object 



406
407
408
409
410
 
# File 'lib/rspec/core/configuration.rb', line 406

def backtrace_clean_patterns=(patterns)
  RSpec.deprecate("RSpec::Core::Configuration#backtrace_clean_patterns",
                  :replacement => "RSpec::Core::Configuration#backtrace_exclusion_patterns")
  @backtrace_formatter.exclusion_patterns = patterns
end

#backtrace_cleaner ⇒ Object 



276
277
278
279
280
 
# File 'lib/rspec/core/configuration.rb', line 276

def backtrace_cleaner
  RSpec.deprecate "`RSpec::Core::Configuration#backtrace_cleaner`",
                  :replacement => "`RSpec::Core::Configuration#backtrace_formatter`"
  @backtrace_formatter
end

#backtrace_exclusion_patterns ⇒ Object

The patterns to discard from backtraces.

Defaults to RSpec::Core::BacktraceCleaner::DEFAULT_EXCLUSION_PATTERNS

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 --backtraceon the command line, in a .rspec file, or in the rspec_options attribute of RSpec's rake task.



437
438
439
 
# File 'lib/rspec/core/configuration.rb', line 437

def backtrace_exclusion_patterns
  @backtrace_formatter.exclusion_patterns
end

#backtrace_exclusion_patterns=(patterns) ⇒ Object 



441
442
443
 
# File 'lib/rspec/core/configuration.rb', line 441

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

#backtrace_inclusion_patterns ⇒ Object

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



419
420
421
 
# File 'lib/rspec/core/configuration.rb', line 419

def backtrace_inclusion_patterns
  @backtrace_formatter.inclusion_patterns
end

#backtrace_inclusion_patterns=(patterns) ⇒ Object 



423
424
425
 
# File 'lib/rspec/core/configuration.rb', line 423

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

#color(output = NoArgument) ⇒ Object 



595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
 
# File 'lib/rspec/core/configuration.rb', line 595

def color(output = NoArgument)
  if output == NoArgument
    output = output_stream
    if !output_to_tty?(output) && value_for(:color, @color)
      RSpec.warn_deprecation <<-MSG.gsub(/\s+|/,'')
        | Calling `RSpec::Core::Configuration#color` in RSpec 3 will
        | return the value of the configuration setting, in RSpec 2
        | this value is `false` as your output doesn't support color.
        | Use `RSpec::Core::Configuration#color_enabled?` if you depend
        | on this behavior.
        | Called from #{CallerFilter.first_non_rspec_line}.
      MSG
    end
  else
    RSpec.deprecate '`RSpec::Core::Configuration#color(output)`',
                    :replacement => '`RSpec::Core::Configuration#color_enabled?(output)`'
  end

  color_enabled? output
end

#color=(bool) ⇒ Object 



616
617
618
619
620
621
622
623
624
625
 
# File 'lib/rspec/core/configuration.rb', line 616

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

#color?(output = output_stream) ⇒ Boolean

Returns:

  • (Boolean) 


647
648
649
650
651
 
# File 'lib/rspec/core/configuration.rb', line 647

def color?(output=output_stream)
  RSpec.deprecate "RSpec::Core::Configuration#color?",
                  :replacement => "RSpec::Core::Configuration#color_enabled?"
  color_enabled? output_stream
end

#color_enabled(output = output_stream) ⇒ Object 



631
632
633
634
635
636
637
638
639
 
# File 'lib/rspec/core/configuration.rb', line 631

def color_enabled(output=output_stream)
  RSpec.deprecate "`RSpec::Core::Configuration#color_enabled`",
    :replacement =>
      "`RSpec::Core::Configuration#color` if you want the configuration " +
      "value, or `RSpec::Core::Configuration#color_enabled?(output)` if " +
      " you want to know if color output is supported."

  color_enabled? output
end

#color_enabled=(bool) ⇒ Object 



641
642
643
644
645
 
# File 'lib/rspec/core/configuration.rb', line 641

def color_enabled=(bool)
  RSpec.deprecate "RSpec::Core::Configuration#color_enabled=",
                  :replacement => "RSpec::Core::Configuration#color="
  self.color = bool
end

#color_enabled?(output = output_stream) ⇒ Boolean

Returns:

  • (Boolean) 


627
628
629
 
# File 'lib/rspec/core/configuration.rb', line 627

def color_enabled?(output=output_stream)
  output_to_tty?(output) && value_for(:color, @color)
end

#debug=(bool) ⇒ Object 



667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
 
# File 'lib/rspec/core/configuration.rb', line 667

def debug=(bool)
  if bool == :cli
    RSpec.deprecate("RSpec's built-in debugger support",
                    :replacement => "a CLI option like `-rruby-debug` or `-rdebugger`",
                    :call_site => nil)
    bool = true
  elsif bool
    RSpec.deprecate("RSpec::Core::Configuration#debug=",
                    :replacement => "a CLI option like `-rruby-debug` or `-rdebugger`")
  else
    # ...but the only way to call this with a false value is to
    # call it directly, so here we mention the method name.
    # There's no replacement for it since it's a no-op, though.
    RSpec.deprecate("RSpec::Core::Configuration#debug=")
  end

  return unless bool
  begin
    require 'ruby-debug'
    Debugger.start
  rescue LoadError => e
    raise <<-EOM

#{'*'*50}
#{e.message}

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

#debug? ⇒ Boolean

Returns:

  • (Boolean) 


703
704
705
706
707
708
 
# File 'lib/rspec/core/configuration.rb', line 703

def debug?
  RSpec.deprecate("RSpec::Core::Configuration#debug?",
                  :replacement => "defined?(Debugger)")

  !!defined?(Debugger)
end

#deprecation_stream=(value) ⇒ Object 



101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/rspec/core/configuration.rb', line 101

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

#exclusion_filter ⇒ Object

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



943
944
945
 
# File 'lib/rspec/core/configuration.rb', line 943

def exclusion_filter
  filter_manager.exclusions
end

#exclusion_filter=(filter) ⇒ Object

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.



937
938
939
 
# File 'lib/rspec/core/configuration.rb', line 937

def exclusion_filter=(filter)
  filter_manager.exclude_only build_metadata_hash_from([filter])
end

#expect_with(*frameworks) ⇒ Object

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



549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
 
# File 'lib/rspec/core/configuration.rb', line 549

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
      RSpec.deprecate ':stdlib', :replacement => ":test_unit or :minitest"
      require 'test/unit/assertions'
      ::Test::Unit::Assertions
    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) ⇒ Object

Delegates to expect_with(framework)



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

def expectation_framework=(framework)
  expect_with(framework)
end

#expectation_frameworks ⇒ Object

Returns the configured expectation framework adapter module(s)



516
517
518
519
 
# File 'lib/rspec/core/configuration.rb', line 516

def expectation_frameworks
  expect_with :rspec if @expectation_frameworks.empty?
  @expectation_frameworks
end

#expose_current_running_example_as(method_name) ⇒ Object

Exposes the current running example via the named helper method. RSpec 2.x exposed this via example, but in RSpec 3.0, the example is instead exposed via an arg yielded to it, before, let, etc. However, some extension gems (such as Capybara) depend on the RSpec 2.x's example method, so this config option can be used to maintain compatibility.

Examples:


RSpec.configure do |rspec|
  rspec.expose_current_running_example_as :example
end

describe MyClass do
  before do
    # `example` can be used here because of the above config.
    do_something if example.metadata[:type] == "foo"
  end
end

Parameters:

  • method_name (Symbol) —

    the name of the helper method



1281
1282
1283
1284
1285
1286
1287
1288
 
# File 'lib/rspec/core/configuration.rb', line 1281

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

  include ExposeCurrentExample
end

#extend(mod, *filters) ⇒ Object

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

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

Examples:


module UiHelpers
  def run_in_browser
    # ...
  end
end

RSpec.configure do |config|
  config.extend(UiHelpers, :type => :request)
end

describe "edit profile", :type => :request do
  run_in_browser

  it "does stuff in the client" do
    # ...
  end
end

See Also:



1012
1013
1014
 
# File 'lib/rspec/core/configuration.rb', line 1012

def extend(mod, *filters)
  include_or_extend_modules << [:extend, mod, build_metadata_hash_from(filters)]
end

#filename_pattern ⇒ Object 



166
167
168
169
170
 
# File 'lib/rspec/core/configuration.rb', line 166

def filename_pattern
  RSpec.deprecate "`RSpec::Core::Configuration#filename_pattern`",
                  :replacement => "`RSpec::Core::Configuration#pattern`"
  pattern
end

#filename_pattern=(value) ⇒ Object 



179
180
181
182
183
 
# File 'lib/rspec/core/configuration.rb', line 179

def filename_pattern=(value)
  RSpec.deprecate "`RSpec::Core::Configuration#filename_pattern=`",
                  :replacement => "`RSpec::Core::Configuration#pattern=`"
  self.pattern = value
end

#filter_run(*args) ⇒ Object 



870
871
872
 
# File 'lib/rspec/core/configuration.rb', line 870

def filter_run(*args)
  __filter_run(__method__, *args)
end

#filter_run_excluding(*args) ⇒ Object

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

Examples:

# given this declaration
describe "something", :foo => 'bar' do
  # ...
end

# any of the following will exclude that group
config.filter_run_excluding :foo => 'bar'
config.filter_run_excluding :foo => /^ba/
config.filter_run_excluding :foo => lambda {|v| v == 'bar'}
config.filter_run_excluding :foo => lambda {|v,m| m[:foo] == 'bar'}

# given a proc with an arity of 1, the lambda is passed the value related to the key, e.g.
config.filter_run_excluding :foo => lambda {|v| v == 'bar'}

# given a proc with an arity of 2, the lambda is passed the value related to the key,
# and the metadata itself e.g.
config.filter_run_excluding :foo => lambda {|v,m| m[:foo] == 'bar'}

# with treat_symbols_as_metadata_keys_with_true_values = true
filter_run_excluding :foo # same as filter_run_excluding :foo => true


926
927
928
 
# File 'lib/rspec/core/configuration.rb', line 926

def filter_run_excluding(*args)
  filter_manager.exclude_with_low_priority build_metadata_hash_from(args)
end

#filter_run_including(*args) ⇒ Object

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

Examples:

# given this declaration
describe "something", :foo => 'bar' do
  # ...
end

# any of the following will include that group
config.filter_run_including :foo => 'bar'
config.filter_run_including :foo => /^ba/
config.filter_run_including :foo => lambda {|v| v == 'bar'}
config.filter_run_including :foo => lambda {|v,m| m[:foo] == 'bar'}

# given a proc with an arity of 1, the lambda is passed the value related to the key, e.g.
config.filter_run_including :foo => lambda {|v| v == 'bar'}

# given a proc with an arity of 2, the lambda is passed the value related to the key,
# and the metadata itself e.g.
config.filter_run_including :foo => lambda {|v,m| m[:foo] == 'bar'}

# with treat_symbols_as_metadata_keys_with_true_values = true
filter_run_including :foo # same as filter_run_including :foo => true


866
867
868
 
# File 'lib/rspec/core/configuration.rb', line 866

def filter_run_including(*args)
  __filter_run(__method__, *args)
end

#format_docstrings(&block) ⇒ Object

Formats the docstring output using the block provided.

Examples:

# This will strip the descriptions of both examples and example groups.
RSpec.configure do |config|
  config.format_docstrings { |s| s.strip }
end


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

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

#formatters ⇒ Object 



744
745
746
 
# File 'lib/rspec/core/configuration.rb', line 744

def formatters
  DeprecatedMutableArrayProxy.new(formatter_loader.formatters)
end

#full_backtrace=(true_or_false) ⇒ Object 



590
591
592
 
# File 'lib/rspec/core/configuration.rb', line 590

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

#full_backtrace? ⇒ Boolean

Returns:

  • (Boolean) 


586
587
588
 
# File 'lib/rspec/core/configuration.rb', line 586

def full_backtrace?
  @backtrace_formatter.full_backtrace?
end

#full_description ⇒ Object 



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

def full_description
  filter.fetch :full_description, nil
end

#full_description=(description) ⇒ Object 



719
720
721
 
# File 'lib/rspec/core/configuration.rb', line 719

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

#include(mod, *filters) ⇒ Object

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.

Examples:


module AuthenticationHelpers
  def (user)
    # ...
  end
end

module UserHelpers
  def users(username)
    # ...
  end
end

RSpec.configure do |config|
  config.include(UserHelpers) # included in all modules
  config.include(AuthenticationHelpers, :type => :request)
end

describe "edit profile", :type => :request do
  it "can be viewed by owning user" do
     users(:jdoe)
    get "/profiles/jdoe"
    assert_select ".username", :text => 'jdoe'
  end
end

See Also:



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

def include(mod, *filters)
  include_or_extend_modules << [:include, mod, build_metadata_hash_from(filters)]
end

#inclusion_filter ⇒ Object Also known as: filter

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



889
890
891
 
# File 'lib/rspec/core/configuration.rb', line 889

def inclusion_filter
  filter_manager.inclusions
end

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



881
882
883
 
# File 'lib/rspec/core/configuration.rb', line 881

def inclusion_filter=(filter)
  filter_manager.include_only build_metadata_hash_from([filter])
end

#libs=(libs) ⇒ Object 



653
654
655
656
657
658
 
# File 'lib/rspec/core/configuration.rb', line 653

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

#line_numbers ⇒ Object 



715
716
717
 
# File 'lib/rspec/core/configuration.rb', line 715

def line_numbers
  filter.fetch(:line_numbers,[])
end

#line_numbers=(line_numbers) ⇒ Object

Run examples defined on line_numbers in all files to run.



711
712
713
 
# File 'lib/rspec/core/configuration.rb', line 711

def line_numbers=(line_numbers)
  filter_run :line_numbers => line_numbers.map{|l| l.to_i}
end

#mock_framework ⇒ Object

Returns the configured mock framework adapter module



379
380
381
382
 
# File 'lib/rspec/core/configuration.rb', line 379

def mock_framework
  mock_with :rspec unless @mock_framework
  @mock_framework
end

#mock_framework=(framework) ⇒ Object

Delegates to mock_framework=(framework)



385
386
387
 
# File 'lib/rspec/core/configuration.rb', line 385

def mock_framework=(framework)
  mock_with framework
end

#mock_with(framework) ⇒ Object

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



474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
 
# File 'lib/rspec/core/configuration.rb', line 474

def mock_with(framework)
  framework_module = case framework
  when Module
    framework
  when String, Symbol
    require case framework.to_s
            when /rspec/i
              deprecate_unless_mock_adapter_name_is_exact(framework, :rspec)
              'rspec/core/mocking/with_rspec'
            when /mocha/i
              deprecate_unless_mock_adapter_name_is_exact(framework, :mocha)
              'rspec/core/mocking/with_mocha'
            when /rr/i
              deprecate_unless_mock_adapter_name_is_exact(framework, :rr)
              'rspec/core/mocking/with_rr'
            when /flexmock/i
              deprecate_unless_mock_adapter_name_is_exact(framework, :flexmock)
              'rspec/core/mocking/with_flexmock'
            else
              deprecate_unless_mock_adapter_name_is_exact(framework, :nothing)
              '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

#order ⇒ Object

Determines the order in which examples are run (default: OS standard load order for files, declaration order for groups and examples).



1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
 
# File 'lib/rspec/core/configuration.rb', line 1105

def order
  RSpec.warn_deprecation(
    "RSpec::Core::Configuration#order is deprecated with no replacement. " +
    "In RSpec 3 individal example groups can use a particular ordering, " +
    "so `order` is no longer a global property of the entire suite. " +
    "Called from #{CallerFilter.first_non_rspec_line}."
  )

  value_for(:order, @order)
end

#order=(type) ⇒ Object

Sets the order and, if order is 'rand:<seed>', also sets the seed.



1099
1100
1101
 
# File 'lib/rspec/core/configuration.rb', line 1099

def order=(type)
  order_and_seed_from_order(type)
end

#order_examples(&block) ⇒ Object

Sets a strategy by which to order examples.

Examples:

RSpec.configure do |config|
  config.order_examples do |examples|
    examples.reverse
  end
end

See Also:



1151
1152
1153
1154
1155
 
# File 'lib/rspec/core/configuration.rb', line 1151

def order_examples(&block)
  RSpec.deprecate("RSpec::Configuration#order_examples", :replacement => "RSpec::Configuration#register_ordering(:global)")
  @example_ordering_block = block
  @order = "custom" unless built_in_orderer?(block)
end

#order_groups(&block) ⇒ Object

Sets a strategy by which to order groups.

Examples:

RSpec.configure do |config|
  config.order_groups do |groups|
    groups.reverse
  end
end

See Also:



1175
1176
1177
1178
1179
 
# File 'lib/rspec/core/configuration.rb', line 1175

def order_groups(&block)
  RSpec.deprecate("RSpec::Configuration#order_groups", :replacement => "RSpec::Configuration#register_ordering(:global)")
  @group_ordering_block = block
  @order = "custom" unless built_in_orderer?(block)
end

#order_groups_and_examples(&block) ⇒ Object

Sets a strategy by which to order groups and examples.

Examples:

RSpec.configure do |config|
  config.order_groups_and_examples do |groups_or_examples|
    groups_or_examples.reverse
  end
end

See Also:



1199
1200
1201
1202
 
# File 'lib/rspec/core/configuration.rb', line 1199

def order_groups_and_examples(&block)
  order_groups(&block)
  order_examples(&block)
end

#out ⇒ Object

Deprecated.

use RSpec::Core::Configuration#output_stream instead.



152
153
154
155
 
# File 'lib/rspec/core/configuration.rb', line 152

def out
  RSpec.deprecate("RSpec::Core::Configuration#out", :replacement => "RSpec::Core::Configuration#output_stream")
  output_stream
end

#out=(value) ⇒ Object

Deprecated.

use RSpec::Core::Configuration#output_stream= instead.



158
159
160
161
 
# File 'lib/rspec/core/configuration.rb', line 158

def out=(value)
  RSpec.deprecate("RSpec::Core::Configuration#out=", :replacement => "RSpec::Core::Configuration#output_stream=")
  self.output_stream = value
end

#output ⇒ Object

Deprecated.

use RSpec::Core::Configuration#output_stream instead.



140
141
142
143
 
# File 'lib/rspec/core/configuration.rb', line 140

def output
  RSpec.deprecate("RSpec::Core::Configuration#output", :replacement => "RSpec::Core::Configuration#output_stream")
  output_stream
end

#output=(value) ⇒ Object

Deprecated.

use RSpec::Core::Configuration#output_stream= instead.



146
147
148
149
 
# File 'lib/rspec/core/configuration.rb', line 146

def output=(value)
  RSpec.deprecate("RSpec::Core::Configuration#output=", :replacement => "RSpec::Core::Configuration#output_stream=")
  self.output_stream = value
end

#output_stream=(value) ⇒ Object 



128
129
130
131
132
133
134
135
136
137
 
# File 'lib/rspec/core/configuration.rb', line 128

def output_stream=(value)
  if @reporter && !value.equal?(@output_stream)
    warn "RSpec's reporter has already been initialized with " +
      "#{output_stream.inspect} as the output stream, so your change to "+
      "`output_stream` will be ignored. You should configure it earlier for " +
      "it to take effect. (Called from #{CallerFilter.first_non_rspec_line})"
  else
    @output_stream = value
  end
end

#pattern=(value) ⇒ Object 



172
173
174
175
176
177
 
# File 'lib/rspec/core/configuration.rb', line 172

def pattern= value
  if @spec_files_loaded
    Kernel.warn "WARNING: Configuring `pattern` to #{value} has no effect since RSpec has already loaded the spec files. Called from #{CallerFilter.first_non_rspec_line}"
  end
  @pattern = value
end

#profile_examples ⇒ Object

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.



766
767
768
769
770
771
772
773
 
# File 'lib/rspec/core/configuration.rb', line 766

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

#raise_errors_for_deprecations! ⇒ Object

Turns deprecation warnings into errors, in order to surface the full backtrace of the call site. This can be useful when you need more context to address a deprecation than the single-line call site normally provided.

Examples:


RSpec.configure do |rspec|
  rspec.raise_errors_for_deprecations!
end


1302
1303
1304
 
# File 'lib/rspec/core/configuration.rb', line 1302

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

#randomize? ⇒ Boolean

Returns:

  • (Boolean) 


1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
 
# File 'lib/rspec/core/configuration.rb', line 1116

def randomize?
  RSpec.warn_deprecation(
    "RSpec::Core::Configuration#randomize? is deprecated with no replacement. " +
    "In RSpec 3 individal example groups can use a particular ordering, " +
    "so `randomize?` is no longer a binary property of the entire suite. " +
    "Called from #{CallerFilter.first_non_rspec_line}."
  )

  value_for(:order, @order).to_s.match(/rand/)
end

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

Note:

Pass the symbol :global to set the ordering strategy that will be used to order the top-level example groups and any example groups that do not have declared :order metadata.

In RSpec 3, this 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.

In RSpec 2.99, only register_ordering(:global) is supported, to set the global ordering.

Examples:

RSpec.configure do |rspec|
  rspec.register_ordering :reverse do |list|
    list.reverse
  end
end

describe MyClass, :order => :reverse do
  # ...
end

Parameters:

  • name (Symbol) —

    The name of the ordering.

Yields:

  • Block that will order the given examples or example groups

Yield Parameters:

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

    The examples or groups to order

Yield Returns:



1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
 
# File 'lib/rspec/core/configuration.rb', line 1230

def register_ordering(name, &block)
  unless name == :global
    raise ArgumentError,
      "Ordering name `#{name.inspect}` given, `:global` expected. " +
      "RSpec 3 will support named orderings (that can be used for " +
      "individual example groups) but 2.99 only supports using this " +
      "to set the global order."
  end

  @group_ordering_block = block
  @example_ordering_block = block
  @order = "custom"
end

#requires=(paths) ⇒ Object 



660
661
662
663
664
665
 
# File 'lib/rspec/core/configuration.rb', line 660

def requires=(paths)
  RSpec.deprecate("RSpec::Core::Configuration#requires=(paths)",
                  :replacement => "paths.each {|path| require path}")
  paths.map {|path| require path}
  @requires += paths
end

#safe_extend(mod, host) ⇒ Object 



1042
1043
1044
 
# File 'lib/rspec/core/configuration.rb', line 1042

def safe_extend(mod, host)
  host.extend(mod) unless (class << host; self; end) < mod
end

#seed=(seed) ⇒ Object

Sets the seed value and sets order='rand'



1092
1093
1094
 
# File 'lib/rspec/core/configuration.rb', line 1092

def seed=(seed)
  order_and_seed_from_seed(seed)
end

#show_failures_in_pending_blocks ⇒ Object 



226
227
228
229
230
231
232
233
 
# File 'lib/rspec/core/configuration.rb', line 226

def show_failures_in_pending_blocks
  RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''))
    |RSpec.configuration.show_failures_in_pending_blocks is being removed
    |with no replacement. Called from #{CallerFilter.first_non_rspec_line}.
  EOS

  @show_failures_in_pending_blocks
end

#show_failures_in_pending_blocks=(value) ⇒ Object

When a block passed to pending fails (as expected), display the failure without reporting it as a failure (default: false).



217
218
219
220
221
222
223
224
 
# File 'lib/rspec/core/configuration.rb', line 217

def show_failures_in_pending_blocks=(value)
  RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''))
    |RSpec.configuration.show_failures_in_pending_blocks is being removed
    |with no replacement. Called from #{CallerFilter.first_non_rspec_line}.
  EOS

  @show_failures_in_pending_blocks = value
end

#show_failures_in_pending_blocks? ⇒ Boolean

Returns:

  • (Boolean) 


235
236
237
 
# File 'lib/rspec/core/configuration.rb', line 235

def show_failures_in_pending_blocks?
  !!show_failures_in_pending_blocks
end

#treat_symbols_as_metadata_keys_with_true_values=(value) ⇒ Object 



255
256
257
258
259
260
261
 
# File 'lib/rspec/core/configuration.rb', line 255

def treat_symbols_as_metadata_keys_with_true_values=(value)
  unless value
    RSpec.deprecate("RSpec.configuration.treat_symbols_as_metadata_keys_with_true_values = false")
  end

  @treat_symbols_as_metadata_keys_with_true_values = value
end

#warnings ⇒ Object 



1253
1254
1255
1256
1257
 
# File 'lib/rspec/core/configuration.rb', line 1253

def warnings
  RSpec.deprecate("`RSpec::Core::Configuration#warnings`",
                  :replacement => "`RSpec::Core::Configuration#warnings?`")
  warnings?
end

#warnings=(value) ⇒ Object

Set Ruby warnings on or off



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

def warnings= value
  $VERBOSE = !!value
end

#warnings? ⇒ Boolean

Returns:

  • (Boolean) 


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

def warnings?
  $VERBOSE
end