Parent

Included Modules

Class Index [+]

Quicksearch

RSpec::Core::Configuration

Stores runtime configuration information.

@example Standard settings

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

@example Hooks

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

@see RSpec.configure @see Hooks

Constants

DEFAULT_BACKTRACE_PATTERNS

Attributes

filter_manager[RW]

@private

Public Class Methods

add_setting(name, opts={}) click to toggle source

@private

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

    # File lib/rspec/core/configuration.rb, line 62
62:       def self.add_setting(name, opts={})
63:         raise "Use the instance add_setting method if you want to set a default" if opts.has_key?(:default)
64:         if opts[:alias]
65:           deprecate_alias_key
66:           define_aliases(opts[:alias], name)
67:         else
68:           attr_writer name
69:           define_reader name
70:           define_predicate_for name
71:         end
72:         [opts[:alias_with]].flatten.compact.each do |alias_name|
73:           define_aliases(name, alias_name)
74:         end
75:       end
define_aliases(name, alias_name) click to toggle source

@private

    # File lib/rspec/core/configuration.rb, line 47
47:       def self.define_aliases(name, alias_name)
48:         alias_method alias_name, name
49:         alias_method "#{alias_name}=", "#{name}="
50:         define_predicate_for alias_name
51:       end
define_predicate_for(*names) click to toggle source

@private

    # File lib/rspec/core/configuration.rb, line 54
54:       def self.define_predicate_for(*names)
55:         names.each {|name| alias_method "#{name}?", name}
56:       end
define_reader(name) click to toggle source

@private

    # File lib/rspec/core/configuration.rb, line 30
30:       def self.define_reader(name)
31:         eval           def #{name}            value_for(#{name.inspect}, defined?(@#{name}) ? @#{name} : nil)          end
32:       end
deprecate_alias_key() click to toggle source

@private

    # File lib/rspec/core/configuration.rb, line 39
39:       def self.deprecate_alias_key
40:         RSpec.warn_deprecation The :alias option to add_setting is deprecated. Use :alias_with on the original setting instead.Called from #{caller(0)[5]}
41:       end
new() click to toggle source
     # File lib/rspec/core/configuration.rb, line 180
180:       def initialize
181:         @expectation_frameworks = []
182:         @include_or_extend_modules = []
183:         @mock_framework = nil
184:         @files_to_run = []
185:         @formatters = []
186:         @color = false
187:         @pattern = '**/*_spec.rb'
188:         @failure_exit_code = 1
189:         @backtrace_clean_patterns = DEFAULT_BACKTRACE_PATTERNS.dup
190:         @default_path = 'spec'
191:         @filter_manager = FilterManager.new
192:         @preferred_options = {}
193:         @seed = srand % 0xFFFF
194:       end

Public Instance Methods

add_formatter(formatter_to_use, path=nil) click to toggle source

@overload add_formatter(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.

     # File lib/rspec/core/configuration.rb, line 446
446:       def add_formatter(formatter_to_use, path=nil)
447:         formatter_class =
448:           built_in_formatter(formatter_to_use) ||
449:           custom_formatter(formatter_to_use) ||
450:           (raise ArgumentError, "Formatter '#{formatter_to_use}' unknown - maybe you meant 'documentation' or 'progress'?.")
451: 
452:         formatters << formatter_class.new(path ? file_at(path) : output)
453:       end
Also aliased as: formatter=
add_setting(name, opts={}) click to toggle source

@overload add_setting(name) @overload add_setting(name, opts) @option opts [Symbol] :default

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

      add_setting(:foo, :default => "default value")

@option opts [Symbol] :alias_with

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

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
     # File lib/rspec/core/configuration.rb, line 249
249:       def add_setting(name, opts={})
250:         default = opts.delete(:default)
251:         (class << self; self; end).class_eval do
252:           add_setting(name, opts)
253:         end
254:         send("#{name}=", default) if default
255:       end
alias_example_to(new_name, *args) click to toggle source

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

@example

    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
     # File lib/rspec/core/configuration.rb, line 496
496:       def alias_example_to(new_name, *args)
497:         extra_options = build_metadata_hash_from(args)
498:         RSpec::Core::ExampleGroup.alias_example_to(new_name, extra_options)
499:       end
alias_it_should_behave_like_to(new_name, report_label = '') click to toggle source

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
     # File lib/rspec/core/configuration.rb, line 522
522:       def alias_it_should_behave_like_to(new_name, report_label = '')
523:         RSpec::Core::ExampleGroup.alias_it_should_behave_like_to(new_name, report_label)
524:       end
cleaned_from_backtrace?(line) click to toggle source

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

     # File lib/rspec/core/configuration.rb, line 259
259:       def cleaned_from_backtrace?(line)
260:         # TODO (David 2011-12-25) why are we asking the configuration to do
261:         # stuff? Either use the patterns directly or enapsulate the filtering
262:         # in a BacktraceCleaner object.
263:         backtrace_clean_patterns.any? { |regex| line =~ regex }
264:       end
color() click to toggle source
     # File lib/rspec/core/configuration.rb, line 375
375:       def color
376:         return false unless output_to_tty?
377:         value_for(:color, @color)
378:       end
Also aliased as: color_enabled
color=(bool) click to toggle source
     # File lib/rspec/core/configuration.rb, line 380
380:       def color=(bool)
381:         return unless bool
382:         @color = true
383:         if bool && ::RbConfig::CONFIG['host_os'] =~ /mswin|mingw/
384:           unless ENV['ANSICON']
385:             warn "You must use ANSICON 1.31 or later (http://adoxa.110mb.com/ansicon/) to use colour on Windows"
386:             @color = false
387:           end
388:         end
389:       end
Also aliased as: color_enabled=
color_enabled() click to toggle source

TODO - deprecate color_enabled - probably not until the last 2.x release before 3.0

Alias for: color
color_enabled=(bool) click to toggle source
Alias for: color=
configure_group(group) click to toggle source

@private

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

     # File lib/rspec/core/configuration.rb, line 709
709:       def configure_group(group)
710:         include_or_extend_modules.each do |include_or_extend, mod, filters|
711:           next unless filters.empty? || group.any_apply?(filters)
712:           send("safe_#{include_or_extend}", mod, group)
713:         end
714:       end
debug=(bool) click to toggle source
     # File lib/rspec/core/configuration.rb, line 405
405:       def debug=(bool)
406:         return unless bool
407:         begin
408:           require 'ruby-debug'
409:           Debugger.start
410:         rescue LoadError => e
411:           raise #{'*'*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}
412:         end
413:       end
exclusion_filter() click to toggle source

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

     # File lib/rspec/core/configuration.rb, line 632
632:       def exclusion_filter
633:         filter_manager.exclusions
634:       end
exclusion_filter=(filter) click to toggle source

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.

     # File lib/rspec/core/configuration.rb, line 626
626:       def exclusion_filter=(filter)
627:         filter_manager.exclude! build_metadata_hash_from([filter])
628:       end
expect_with(*frameworks) click to toggle source

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

     # File lib/rspec/core/configuration.rb, line 348
348:       def expect_with(*frameworks)
349:         modules = frameworks.map do |framework|
350:           case framework
351:           when :rspec
352:             require 'rspec/expectations'
353:             self.expecting_with_rspec = true
354:             ::RSpec::Matchers
355:           when :stdlib
356:             require 'test/unit/assertions'
357:             ::Test::Unit::Assertions
358:           else
359:             raise ArgumentError, "#{framework.inspect} is not supported"
360:           end
361:         end
362: 
363:         if (modules - @expectation_frameworks).any?
364:           assert_no_example_groups_defined(:expect_with)
365:         end
366: 
367:         @expectation_frameworks.clear
368:         @expectation_frameworks.push(*modules)
369:       end
expectation_framework=(framework) click to toggle source

Delegates to expect_with(framework)

     # File lib/rspec/core/configuration.rb, line 337
337:       def expectation_framework=(framework)
338:         expect_with(framework)
339:       end
expectation_frameworks() click to toggle source

Returns the configured expectation framework adapter module(s)

     # File lib/rspec/core/configuration.rb, line 331
331:       def expectation_frameworks
332:         expect_with :rspec if @expectation_frameworks.empty?
333:         @expectation_frameworks
334:       end
extend(mod, *filters) click to toggle source

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.

@example

    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 #

     # File lib/rspec/core/configuration.rb, line 701
701:       def extend(mod, *filters)
702:         include_or_extend_modules << [:extend, mod, build_metadata_hash_from(filters)]
703:       end
files_or_directories_to_run=(*files) click to toggle source

@private

     # File lib/rspec/core/configuration.rb, line 469
469:       def files_or_directories_to_run=(*files)
470:         files = files.flatten
471:         files << default_path if command == 'rspec' && default_path && files.empty?
472:         self.files_to_run = get_files_to_run(files)
473:       end
filter() click to toggle source
Alias for: inclusion_filter
filter=(filter) click to toggle source
Alias for: inclusion_filter=
filter_run(*args) click to toggle source
filter_run_excluding(*args) click to toggle source

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

@example

    # 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
     # File lib/rspec/core/configuration.rb, line 615
615:       def filter_run_excluding(*args)
616:         filter_manager.exclude_with_low_priority build_metadata_hash_from(args)
617:       end
filter_run_including(*args) click to toggle source

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

@example

    # 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
     # File lib/rspec/core/configuration.rb, line 557
557:       def filter_run_including(*args)
558:         filter_manager.include_with_low_priority build_metadata_hash_from(args)
559:       end
Also aliased as: filter_run
force(hash) click to toggle source

@private

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

     # File lib/rspec/core/configuration.rb, line 199
199:       def force(hash)
200:         if hash.has_key?(:seed)
201:           hash[:order], hash[:seed] = order_and_seed_from_seed(hash[:seed])
202:         elsif hash.has_key?(:order)
203:           set_order_and_seed(hash)
204:         end
205:         @preferred_options.merge!(hash)
206:       end
formatter=(formatter_to_use, path=nil) click to toggle source
Alias for: add_formatter
formatters() click to toggle source
     # File lib/rspec/core/configuration.rb, line 457
457:       def formatters
458:         @formatters ||= []
459:       end
full_backtrace=(true_or_false) click to toggle source
     # File lib/rspec/core/configuration.rb, line 371
371:       def full_backtrace=(true_or_false)
372:         @backtrace_clean_patterns = true_or_false ? [] : DEFAULT_BACKTRACE_PATTERNS
373:       end
full_description=(description) click to toggle source
     # File lib/rspec/core/configuration.rb, line 431
431:       def full_description=(description)
432:         filter_run :full_description => /#{description}/
433:       end
include(mod, *filters) click to toggle source

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.

@example

    module AuthenticationHelpers
      def login_as(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
        login_as users(:jdoe)
        get "/profiles/jdoe"
        assert_select ".username", :text => 'jdoe'
      end
    end

@see #

     # File lib/rspec/core/configuration.rb, line 668
668:       def include(mod, *filters)
669:         include_or_extend_modules << [:include, mod, build_metadata_hash_from(filters)]
670:       end
inclusion_filter() click to toggle source

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

     # File lib/rspec/core/configuration.rb, line 578
578:       def inclusion_filter
579:         filter_manager.inclusions
580:       end
Also aliased as: filter
inclusion_filter=(filter) click to toggle source

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.

     # File lib/rspec/core/configuration.rb, line 570
570:       def inclusion_filter=(filter)
571:         filter_manager.include! build_metadata_hash_from([filter])
572:       end
Also aliased as: filter=
libs=(libs) click to toggle source
     # File lib/rspec/core/configuration.rb, line 397
397:       def libs=(libs)
398:         libs.map {|lib| $LOAD_PATH.unshift lib}
399:       end
line_numbers=(line_numbers) click to toggle source

Run examples defined on `line_numbers` in all files to run.

     # File lib/rspec/core/configuration.rb, line 427
427:       def line_numbers=(line_numbers)
428:         filter_run :line_numbers => line_numbers.map{|l| l.to_i}
429:       end
mock_framework() click to toggle source

Returns the configured mock framework adapter module

     # File lib/rspec/core/configuration.rb, line 267
267:       def mock_framework
268:         mock_with :rspec unless @mock_framework
269:         @mock_framework
270:       end
mock_framework=(framework) click to toggle source

Delegates to mock_framework=(framework)

     # File lib/rspec/core/configuration.rb, line 273
273:       def mock_framework=(framework)
274:         mock_with framework
275:       end
mock_with(framework) click to toggle source

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)
     # File lib/rspec/core/configuration.rb, line 299
299:       def mock_with(framework)
300:         framework_module = case framework
301:         when Module
302:           framework
303:         when String, Symbol
304:           require case framework.to_s
305:                   when /rspec/
306:                     'rspec/core/mocking/with_rspec'
307:                   when /mocha/
308:                     'rspec/core/mocking/with_mocha'
309:                   when /rr/
310:                     'rspec/core/mocking/with_rr'
311:                   when /flexmock/
312:                     'rspec/core/mocking/with_flexmock'
313:                   else
314:                     'rspec/core/mocking/with_absolutely_nothing'
315:                   end
316:           RSpec::Core::MockFrameworkAdapter
317:         end
318: 
319:         new_name, old_name = [framework_module, @mock_framework].map do |mod|
320:           mod.respond_to?(:framework_name) ?  mod.framework_name : :unnamed
321:         end
322: 
323:         unless new_name == old_name
324:           assert_no_example_groups_defined(:mock_framework)
325:         end
326: 
327:         @mock_framework = framework_module
328:       end
reporter() click to toggle source
     # File lib/rspec/core/configuration.rb, line 461
461:       def reporter
462:         @reporter ||= begin
463:                         add_formatter('progress') if formatters.empty?
464:                         Reporter.new(*formatters)
465:                       end
466:       end
requires=(paths) click to toggle source
     # File lib/rspec/core/configuration.rb, line 401
401:       def requires=(paths)
402:         paths.map {|path| require path}
403:       end
reset() click to toggle source

@private

     # File lib/rspec/core/configuration.rb, line 209
209:       def reset
210:         @reporter = nil
211:         @formatters.clear
212:       end
safe_extend(mod, host) click to toggle source
     # File lib/rspec/core/configuration.rb, line 723
723:         def safe_extend(mod, host)
724:           host.extend(mod) unless (class << host; self; end
safe_extend(mod, host) click to toggle source
     # File lib/rspec/core/configuration.rb, line 727
727:         def safe_extend(mod, host)
728:           host.extend(mod) unless (class << host; self; end
safe_include(mod, host) click to toggle source

@private

     # File lib/rspec/core/configuration.rb, line 717
717:       def safe_include(mod, host)
718:         host.send(:include,mod) unless host < mod
719:       end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.