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

Classes: MustBeConfiguredBeforeExampleGroupsError

Constant Summary

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

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.



548
549
550
551
552
553
554
555
556
 
# File 'lib/rspec/core/configuration.rb', line 548

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

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



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:

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


613
614
615
616
 
# File 'lib/rspec/core/configuration.rb', line 613

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

- (Object) alias_it_behaves_like_to(new_name, report_label = '') 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



639
640
641
 
# File 'lib/rspec/core/configuration.rb', line 639

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_exclusion_patterns

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.



312
313
314
 
# File 'lib/rspec/core/configuration.rb', line 312

def backtrace_exclusion_patterns
  @backtrace_cleaner.exclusion_patterns
end

- (Object) backtrace_exclusion_patterns=(patterns) 



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

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



294
295
296
 
# File 'lib/rspec/core/configuration.rb', line 294

def backtrace_inclusion_patterns
  @backtrace_cleaner.inclusion_patterns
end

- (Object) backtrace_inclusion_patterns=(patterns) 



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

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

- (Object) color(output = output_stream) Also known as: color_enabled 



456
457
458
459
460
461
462
 
# File 'lib/rspec/core/configuration.rb', line 456

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= 



464
465
466
467
468
469
470
471
472
473
 
# File 'lib/rspec/core/configuration.rb', line 464

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) 



495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
 
# File 'lib/rspec/core/configuration.rb', line 495

def debug=(bool)
  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

- (Boolean) debug?

Returns:

  • (Boolean) 


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

def debug?
  !!defined?(Debugger)
end

- (Object) exclusion_filter

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



751
752
753
 
# File 'lib/rspec/core/configuration.rb', line 751

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.



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

def exclusion_filter=(filter)
  filter_manager.exclude! build_metadata_hash_from([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



418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
 
# File 'lib/rspec/core/configuration.rb', line 418

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)



392
393
394
 
# File 'lib/rspec/core/configuration.rb', line 392

def expectation_framework=(framework)
  expect_with(framework)
end

- (Object) expectation_frameworks

Returns the configured expectation framework adapter module(s)



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

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.

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:



820
821
822
 
# File 'lib/rspec/core/configuration.rb', line 820

def extend(mod, *filters)
  include_or_extend_modules << [:extend, mod, build_metadata_hash_from(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).

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


734
735
736
 
# File 'lib/rspec/core/configuration.rb', line 734

def filter_run_excluding(*args)
  filter_manager.exclude_with_low_priority build_metadata_hash_from(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).

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


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

def filter_run_including(*args)
  filter_manager.include_with_low_priority build_metadata_hash_from(args)
end

- (Object) format_docstrings(&block)

Formats the docstring output using the block provided.

Examples:

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


887
888
889
 
# File 'lib/rspec/core/configuration.rb', line 887

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

- (Object) formatters 



560
561
562
 
# File 'lib/rspec/core/configuration.rb', line 560

def formatters
  @formatters ||= []
end

- (Object) full_backtrace=(true_or_false) 



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

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

- (Boolean) full_backtrace?

Returns:

  • (Boolean) 


448
449
450
 
# File 'lib/rspec/core/configuration.rb', line 448

def full_backtrace?
  @backtrace_cleaner.full_backtrace?
end

- (Object) full_description 



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

def full_description
  filter.fetch :full_description, nil
end

- (Object) full_description=(description) 



529
530
531
 
# File 'lib/rspec/core/configuration.rb', line 529

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.

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:



787
788
789
 
# File 'lib/rspec/core/configuration.rb', line 787

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

- (Object) inclusion_filter Also known as: filter

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



697
698
699
 
# File 'lib/rspec/core/configuration.rb', line 697

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.



689
690
691
 
# File 'lib/rspec/core/configuration.rb', line 689

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

- (Object) libs=(libs) 



481
482
483
484
485
486
 
# File 'lib/rspec/core/configuration.rb', line 481

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

- (Object) line_numbers 



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

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

- (Object) line_numbers=(line_numbers)

Run examples defined on line_numbers in all files to run.



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

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



349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
 
# File 'lib/rspec/core/configuration.rb', line 349

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.



906
907
908
 
# File 'lib/rspec/core/configuration.rb', line 906

def order=(type)
  order_and_seed_from_order(type)
end

- (Object) order_examples(&block)

Sets a strategy by which to order examples.

Examples:

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

See Also:



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

def order_examples(&block)
  @example_ordering_block = block
  @order = "custom" unless built_in_orderer?(block)
end

- (Object) order_groups(&block)

Sets a strategy by which to order groups.

Examples:

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

See Also:



961
962
963
964
 
# File 'lib/rspec/core/configuration.rb', line 961

def order_groups(&block)
  @group_ordering_block = block
  @order = "custom" unless built_in_orderer?(block)
end

- (Object) order_groups_and_examples(&block)

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:



984
985
986
987
 
# File 'lib/rspec/core/configuration.rb', line 984

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.



576
577
578
579
580
581
582
583
 
# File 'lib/rspec/core/configuration.rb', line 576

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

- (Boolean) randomize?

Returns:

  • (Boolean) 


910
911
912
 
# File 'lib/rspec/core/configuration.rb', line 910

def randomize?
  order.to_s.match(/rand/)
end

- (Object) reporter 



564
565
566
567
568
569
570
 
# File 'lib/rspec/core/configuration.rb', line 564

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) 



488
489
490
491
492
493
 
# File 'lib/rspec/core/configuration.rb', line 488

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) 



850
851
852
 
# File 'lib/rspec/core/configuration.rb', line 850

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'



899
900
901
 
# File 'lib/rspec/core/configuration.rb', line 899

def seed=(seed)
  order_and_seed_from_seed(seed)
end

- (Object) warnings 



994
995
996
 
# File 'lib/rspec/core/configuration.rb', line 994

def warnings
  $VERBOSE
end

- (Object) warnings=(value)

Set Ruby warnings on or off



990
991
992
 
# File 'lib/rspec/core/configuration.rb', line 990

def warnings= value
  $VERBOSE = !!value
end