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

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Hooks

#after, #around, #before, #find_hook, #hooks, #run_hook, #run_hook!, #run_hook_filtered

Methods included from MetadataHashBuilder::Common

#build_metadata_hash_from

Constructor Details

#initializeConfiguration

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_patternsObject


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

add_setting :backtrace_clean_patterns

#default_pathObject

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

#drbObject

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_portObject

The drb_port (default: `8989`).


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

add_setting :drb_port

#error_streamObject

Default: `$stderr`.


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

add_setting :error_stream

#expecting_with_rspecObject


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

add_setting :expecting_with_rspec

#fail_fastObject

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_codeObject

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

#files_to_runObject


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

add_setting :files_to_run

#filter_managerObject


169
170
171
# File 'lib/rspec/core/configuration.rb', line 169

def filter_manager
  @filter_manager
end

#include_or_extend_modulesObject


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

add_setting :include_or_extend_modules

#output_streamObject

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]

#patternObject

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_examplesObject

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_filteredObject

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_blocksObject

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_valuesObject

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

#ttyObject


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

add_setting :tty

Class Method Details

.add_setting(name, opts = {}) ⇒ Object

Invoked by the `add_setting` instance method. Use that method on a `Configuration` instance rather than this class method.


62
63
64
65
66
67
68
69
70
71
72
73
74
75
# File 'lib/rspec/core/configuration.rb', line 62

def self.add_setting(name, opts={})
  raise "Use the instance add_setting method if you want to set a default" if opts.has_key?(:default)
  if opts[:alias]
    deprecate_alias_key
    define_aliases(opts[:alias], name)
  else
    attr_writer name
    define_reader name
    define_predicate_for name
  end
  [opts[:alias_with]].flatten.compact.each do |alias_name|
    define_aliases(name, alias_name)
  end
end

.define_aliases(name, alias_name) ⇒ Object


47
48
49
50
51
# File 'lib/rspec/core/configuration.rb', line 47

def self.define_aliases(name, alias_name)
  alias_method alias_name, name
  alias_method "#{alias_name}=", "#{name}="
  define_predicate_for alias_name
end

.define_predicate_for(*names) ⇒ Object


54
55
56
# File 'lib/rspec/core/configuration.rb', line 54

def self.define_predicate_for(*names)
  names.each {|name| alias_method "#{name}?", name}
end

.define_reader(name) ⇒ Object


30
31
32
33
34
35
36
# File 'lib/rspec/core/configuration.rb', line 30

def self.define_reader(name)
  eval <<-CODE
    def #{name}
      value_for(#{name.inspect}, defined?(@#{name}) ? @#{name} : nil)
    end
  CODE
end

.deprecate_alias_keyObject


39
40
41
42
43
44
# File 'lib/rspec/core/configuration.rb', line 39

def self.deprecate_alias_key
  RSpec.warn_deprecation <<-MESSAGE
The :alias option to add_setting is deprecated. Use :alias_with on the original setting instead.
Called from #{caller(0)[5]}
MESSAGE
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 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 = (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

#colorObject 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

#configure_expectation_frameworkObject


690
691
692
693
694
# File 'lib/rspec/core/configuration.rb', line 690

def configure_expectation_framework
  expectation_frameworks.each do |framework|
    RSpec::Core::ExampleGroup.send(:include, framework)
  end
end

#configure_group(group) ⇒ Object

Used internally to extend a group with modules using `include` and/or `extend`.


677
678
679
680
681
682
# File 'lib/rspec/core/configuration.rb', line 677

def configure_group(group)
  include_or_extend_modules.each do |include_or_extend, mod, filters|
    next unless filters.empty? || group.any_apply?(filters)
    group.send(include_or_extend, mod)
  end
end

#configure_mock_frameworkObject


685
686
687
# File 'lib/rspec/core/configuration.rb', line 685

def configure_mock_framework
  RSpec::Core::ExampleGroup.send(:include, mock_framework)
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_filterObject

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


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

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.


594
595
596
# File 'lib/rspec/core/configuration.rb', line 594

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

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:


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

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

#files_or_directories_to_run=(*files) ⇒ Object


469
470
471
472
473
# File 'lib/rspec/core/configuration.rb', line 469

def files_or_directories_to_run=(*files)
  files = files.flatten
  files << default_path if command == 'rspec' && default_path && files.empty?
  self.files_to_run = get_files_to_run(files)
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:

filter_run_excluding :x => 'y'

# with treat_symbols_as_metadata_keys_with_true_values = true
filter_run_excluding :foo # results in {:foo => true}

583
584
585
# File 'lib/rspec/core/configuration.rb', line 583

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

filter_run_including :x => 'y'

# with treat_symbols_as_metadata_keys_with_true_values = true
filter_run_including :foo # results in {:foo => true}

541
542
543
# File 'lib/rspec/core/configuration.rb', line 541

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

#force(hash) ⇒ Object

Used to set higher priority option values from the command line.


199
200
201
202
203
204
205
206
# File 'lib/rspec/core/configuration.rb', line 199

def force(hash)
  if hash.has_key?(:seed)
    hash[:order], hash[:seed] = order_and_seed_from_seed(hash[:seed])
  elsif hash.has_key?(:order)
    set_order_and_seed(hash)
  end
  @preferred_options.merge!(hash)
end

#formattersObject


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:


636
637
638
# File 'lib/rspec/core/configuration.rb', line 636

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

#inclusion_filterObject Also known as: filter

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


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

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.


554
555
556
# File 'lib/rspec/core/configuration.rb', line 554

def inclusion_filter=(filter)
  filter_manager.include! ([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

#load_spec_filesObject


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

def load_spec_files
  files_to_run.uniq.map {|f| load File.expand_path(f) }
  raise_if_rspec_1_is_loaded
end

#mock_frameworkObject

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.


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

def order=(type)
  order_and_seed_from_order(type)
end

#randomize?Boolean

Returns:

  • (Boolean)

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

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

#reporterObject


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

#resetObject


209
210
211
212
# File 'lib/rspec/core/configuration.rb', line 209

def reset
  @reporter = nil
  @formatters.clear
end

#seed=(seed) ⇒ Object

Sets the seed value and sets `order='rand'`


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

def seed=(seed)
  order_and_seed_from_seed(seed)
end