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
@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
@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
@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
@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
@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
# 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
@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
@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
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
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
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
# 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
# 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
TODO - deprecate color_enabled - probably not until the last 2.x release before 3.0
@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
# 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
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
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
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
Delegates to expect_with(framework)
# File lib/rspec/core/configuration.rb, line 337 337: def expectation_framework=(framework) 338: expect_with(framework) 339: end
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
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
@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
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
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
@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
# File lib/rspec/core/configuration.rb, line 457 457: def formatters 458: @formatters ||= [] 459: end
# 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
# File lib/rspec/core/configuration.rb, line 431 431: def full_description=(description) 432: filter_run :full_description => /#{description}/ 433: end
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
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
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
# File lib/rspec/core/configuration.rb, line 397 397: def libs=(libs) 398: libs.map {|lib| $LOAD_PATH.unshift lib} 399: end
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
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
Delegates to mock_framework=(framework)
# File lib/rspec/core/configuration.rb, line 273 273: def mock_framework=(framework) 274: mock_with framework 275: end
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
# 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
# File lib/rspec/core/configuration.rb, line 401 401: def requires=(paths) 402: paths.map {|path| require path} 403: end
@private
# File lib/rspec/core/configuration.rb, line 209 209: def reset 210: @reporter = nil 211: @formatters.clear 212: end
# File lib/rspec/core/configuration.rb, line 723 723: def safe_extend(mod, host) 724: host.extend(mod) unless (class << host; self; end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.