Class: RSpec::Core::Configuration

Inherits:
Object
  • Object
show all
Includes:
Hooks
Defined in:
lib/rspec/core/configuration.rb

Overview

Stores runtime configuration information.

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.



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/rspec/core/configuration.rb', line 180

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 



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

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.



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

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.



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

add_setting :drb

#drb_port ⇒ Object

The drb_port (default: 8989).



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

add_setting :drb_port

#error_stream ⇒ Object

Default: $stderr.



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

add_setting :error_stream

#fail_fast ⇒ Object

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



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

add_setting :fail_fast

#failure_exit_code ⇒ Object

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



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

add_setting :failure_exit_code

#output_stream ⇒ Object

Default: $stdout. Also known as output and out



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

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

#pattern ⇒ Object

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



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

add_setting :pattern, :alias_with => :filename_pattern

#profile_examples ⇒ Object

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



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

add_setting :profile_examples

#run_all_when_everything_filtered ⇒ Object

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



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

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



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

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



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

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.



446
447
448
449
450
451
452
453
 
# File 'lib/rspec/core/configuration.rb', line 446

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



249
250
251
252
253
254
255
 
# File 'lib/rspec/core/configuration.rb', line 249

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


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

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

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_should_behave_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



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

def alias_it_should_behave_like_to(new_name, report_label = '')
  RSpec::Core::ExampleGroup.alias_it_should_behave_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) 


259
260
261
262
263
264
 
# File 'lib/rspec/core/configuration.rb', line 259

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 ⇒ Object Also known as: color_enabled 



375
376
377
378
 
# File 'lib/rspec/core/configuration.rb', line 375

def color
  return false unless output_to_tty?
  value_for(:color, @color)
end

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



380
381
382
383
384
385
386
387
388
389
 
# File 'lib/rspec/core/configuration.rb', line 380

def color=(bool)
  return unless bool
  @color = true
  if bool && ::RbConfig::CONFIG['host_os'] =~ /mswin|mingw/
    unless ENV['ANSICON']
      warn "You must use ANSICON 1.31 or later (http://adoxa.110mb.com/ansicon/) to use colour on Windows"
      @color = false
    end
  end
end

#debug=(bool) ⇒ Object 



405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
 
# File 'lib/rspec/core/configuration.rb', line 405

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.



632
633
634
 
# File 'lib/rspec/core/configuration.rb', line 632

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.



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

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

#expect_with(*frameworks) ⇒ Object

Sets the expectation framework module(s).

frameworks can be :rspec, :stdlib, or both

Given :rspec, configures rspec/expectations. Given :stdlib, configures test/unit/assertions Given both, configures both



348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
 
# File 'lib/rspec/core/configuration.rb', line 348

def expect_with(*frameworks)
  modules = frameworks.map do |framework|
    case 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

  @expectation_frameworks.clear
  @expectation_frameworks.push(*modules)
end

#expectation_framework=(framework) ⇒ Object

Delegates to expect_with(framework)



337
338
339
 
# File 'lib/rspec/core/configuration.rb', line 337

def expectation_framework=(framework)
  expect_with(framework)
end

#expectation_frameworks ⇒ Object

Returns the configured expectation framework adapter module(s)



331
332
333
334
 
# File 'lib/rspec/core/configuration.rb', line 331

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:



701
702
703
 
# File 'lib/rspec/core/configuration.rb', line 701

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


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

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


557
558
559
 
# File 'lib/rspec/core/configuration.rb', line 557

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

#formatters ⇒ Object 



457
458
459
 
# File 'lib/rspec/core/configuration.rb', line 457

def formatters
  @formatters ||= []
end

#full_backtrace=(true_or_false) ⇒ Object 



371
372
373
 
# File 'lib/rspec/core/configuration.rb', line 371

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

#full_description=(description) ⇒ Object 



431
432
433
 
# File 'lib/rspec/core/configuration.rb', line 431

def full_description=(description)
  filter_run :full_description => /#{description}/
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:



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

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.



578
579
580
 
# File 'lib/rspec/core/configuration.rb', line 578

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.



570
571
572
 
# File 'lib/rspec/core/configuration.rb', line 570

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

#libs=(libs) ⇒ Object 



397
398
399
 
# File 'lib/rspec/core/configuration.rb', line 397

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.



427
428
429
 
# File 'lib/rspec/core/configuration.rb', line 427

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



267
268
269
270
 
# File 'lib/rspec/core/configuration.rb', line 267

def mock_framework
  mock_with :rspec unless @mock_framework
  @mock_framework
end

#mock_framework=(framework) ⇒ Object

Delegates to mock_framework=(framework)



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

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)



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/rspec/core/configuration.rb', line 299

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

  @mock_framework = framework_module
end

#order=(type) ⇒ Object

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



760
761
762
 
# File 'lib/rspec/core/configuration.rb', line 760

def order=(type)
  order_and_seed_from_order(type)
end

#randomize? ⇒ Boolean

Returns:

  • (Boolean) 


764
765
766
 
# File 'lib/rspec/core/configuration.rb', line 764

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

#reporter ⇒ Object 



461
462
463
464
465
466
 
# File 'lib/rspec/core/configuration.rb', line 461

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

#requires=(paths) ⇒ Object 



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

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

#safe_extend(mod, host) ⇒ Object 



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

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'



753
754
755
 
# File 'lib/rspec/core/configuration.rb', line 753

def seed=(seed)
  order_and_seed_from_seed(seed)
end