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 collapse

DEFAULT_BACKTRACE_PATTERNS = 
[
  /\/lib\d*\/ruby\//,
  /org\/jruby\//,
  /bin\//,
  /gems/,
  /spec\/spec_helper\.rb/,
  /lib\/rspec\/(core|expectations|matchers|mocks)/
]

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.



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/rspec/core/configuration.rb', line 184

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_clean_patterns = DEFAULT_BACKTRACE_PATTERNS.dup
  @default_path = 'spec'
  @filter_manager = FilterManager.new
  @preferred_options = {}
  @seed = srand % 0xFFFF
end

Instance Attribute Details

#backtrace_clean_patterns ⇒ Object 



91
 
# File 'lib/rspec/core/configuration.rb', line 91

add_setting :backtrace_clean_patterns

#default_path ⇒ Object

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.



96
 
# File 'lib/rspec/core/configuration.rb', line 96

add_setting :default_path

#drb ⇒ Object

Run examples over DRb (default: false). RSpec doesn't supply the DRb server, but you can use tools like spork.



100
 
# File 'lib/rspec/core/configuration.rb', line 100

add_setting :drb

#drb_port ⇒ Object

The drb_port (default: 8989).



103
 
# File 'lib/rspec/core/configuration.rb', line 103

add_setting :drb_port

#error_stream ⇒ Object

Default: $stderr.



106
 
# File 'lib/rspec/core/configuration.rb', line 106

add_setting :error_stream

#fail_fast ⇒ Object

Clean up and exit after the first failure (default: false).



109
 
# File 'lib/rspec/core/configuration.rb', line 109

add_setting :fail_fast

#failure_exit_code ⇒ Object

The exit code to return if there are any failures (default: 1).



112
 
# File 'lib/rspec/core/configuration.rb', line 112

add_setting :failure_exit_code

#output_stream ⇒ Object

Default: $stdout. Also known as output and out



120
 
# File 'lib/rspec/core/configuration.rb', line 120

add_setting :output_stream, :alias_with => [:output, :out]

#pattern ⇒ Object

Load files matching this pattern (default: '**/*_spec.rb')



123
 
# File 'lib/rspec/core/configuration.rb', line 123

add_setting :pattern, :alias_with => :filename_pattern

#profile_examples ⇒ Object

Report the times for the 10 slowest examples (default: false).



126
 
# File 'lib/rspec/core/configuration.rb', line 126

add_setting :profile_examples

#run_all_when_everything_filtered ⇒ Object

Run all examples if none match the configured filters (default: false).



129
 
# File 'lib/rspec/core/configuration.rb', line 129

add_setting :run_all_when_everything_filtered

#show_failures_in_pending_blocks ⇒ Object

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



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

add_setting :show_failures_in_pending_blocks

#treat_symbols_as_metadata_keys_with_true_values ⇒ Object

Convert symbols to hashes with the symbol as a key with a value of true (default: false).

This allows you to tag a group or example like this:

describe "something slow", :slow do
  # ...
end

... instead of having to type:

describe "something slow", :slow => true do
  # ...
end



162
 
# File 'lib/rspec/core/configuration.rb', line 162

add_setting :treat_symbols_as_metadata_keys_with_true_values

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 path to a file that contains that class definition, but you should consider that a private api that may change at any time without notice.



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

def add_formatter(formatter_to_use, path=nil)
  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'?.")

  formatters << formatter_class.new(path ? file_at(path) : output)
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])



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

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


537
538
539
540
 
# File 'lib/rspec/core/configuration.rb', line 537

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

#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



563
564
565
 
# File 'lib/rspec/core/configuration.rb', line 563

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

#cleaned_from_backtrace?(line) ⇒ Boolean

Used by formatters to ask whether a backtrace line should be displayed or not, based on the line matching any backtrace_clean_patterns.

Returns:

  • (Boolean) 


263
264
265
266
267
268
 
# File 'lib/rspec/core/configuration.rb', line 263

def cleaned_from_backtrace?(line)
  # TODO (David 2011-12-25) why are we asking the configuration to do
  # stuff? Either use the patterns directly or enapsulate the filtering
  # in a BacktraceCleaner object.
  backtrace_clean_patterns.any? { |regex| line =~ regex }
end

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



413
414
415
416
417
418
419
 
# File 'lib/rspec/core/configuration.rb', line 413

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

#color=(bool) ⇒ Object Also known as: color_enabled= 



421
422
423
424
425
426
427
428
429
430
 
# File 'lib/rspec/core/configuration.rb', line 421

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

#debug=(bool) ⇒ Object 



446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
 
# File 'lib/rspec/core/configuration.rb', line 446

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

#exclusion_filter ⇒ Object

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



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

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.



669
670
671
 
# File 'lib/rspec/core/configuration.rb', line 669

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



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
407
 
# File 'lib/rspec/core/configuration.rb', line 379

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

#expectation_framework=(framework) ⇒ Object

Delegates to expect_with(framework)



353
354
355
 
# File 'lib/rspec/core/configuration.rb', line 353

def expectation_framework=(framework)
  expect_with(framework)
end

#expectation_frameworks ⇒ Object

Returns the configured expectation framework adapter module(s)



347
348
349
350
 
# File 'lib/rspec/core/configuration.rb', line 347

def expectation_frameworks
  expect_with :rspec if @expectation_frameworks.empty?
  @expectation_frameworks
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:



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

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


658
659
660
 
# File 'lib/rspec/core/configuration.rb', line 658

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

#filter_run_including(*args) ⇒ Object 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


600
601
602
 
# File 'lib/rspec/core/configuration.rb', line 600

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


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

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

#formatters ⇒ Object 



498
499
500
 
# File 'lib/rspec/core/configuration.rb', line 498

def formatters
  @formatters ||= []
end

#full_backtrace=(true_or_false) ⇒ Object 



409
410
411
 
# File 'lib/rspec/core/configuration.rb', line 409

def full_backtrace=(true_or_false)
  @backtrace_clean_patterns = true_or_false ? [] : DEFAULT_BACKTRACE_PATTERNS
end

#full_description=(description) ⇒ Object 



472
473
474
 
# File 'lib/rspec/core/configuration.rb', line 472

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:



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

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.



621
622
623
 
# File 'lib/rspec/core/configuration.rb', line 621

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.



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

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

#libs=(libs) ⇒ Object 



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

def libs=(libs)
  libs.map {|lib| $LOAD_PATH.unshift lib}
end

#line_numbers=(line_numbers) ⇒ Object

Run examples defined on line_numbers in all files to run.



468
469
470
 
# File 'lib/rspec/core/configuration.rb', line 468

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



271
272
273
274
 
# File 'lib/rspec/core/configuration.rb', line 271

def mock_framework
  mock_with :rspec unless @mock_framework
  @mock_framework
end

#mock_framework=(framework) ⇒ Object

Delegates to mock_framework=(framework)



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

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



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
338
339
340
341
342
343
344
 
# File 'lib/rspec/core/configuration.rb', line 310

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

#order=(type) ⇒ Object

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



822
823
824
 
# File 'lib/rspec/core/configuration.rb', line 822

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:



852
853
854
855
 
# File 'lib/rspec/core/configuration.rb', line 852

def order_examples(&block)
  @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:



875
876
877
878
 
# File 'lib/rspec/core/configuration.rb', line 875

def order_groups(&block)
  @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:



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

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

#randomize? ⇒ Boolean

Returns:

  • (Boolean) 


826
827
828
 
# File 'lib/rspec/core/configuration.rb', line 826

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

#reporter ⇒ Object 



502
503
504
505
506
507
 
# File 'lib/rspec/core/configuration.rb', line 502

def reporter
  @reporter ||= begin
                  add_formatter('progress') if formatters.empty?
                  Reporter.new(*formatters)
                end
end

#requires=(paths) ⇒ Object 



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

def requires=(paths)
  paths.map {|path| require path}
end

#safe_extend(mod, host) ⇒ Object 



766
767
768
 
# File 'lib/rspec/core/configuration.rb', line 766

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'



815
816
817
 
# File 'lib/rspec/core/configuration.rb', line 815

def seed=(seed)
  order_and_seed_from_seed(seed)
end