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
@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 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
@private
# 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
@private
# File lib/rspec/core/configuration.rb, line 54 def self.define_predicate_for(*names) names.each {|name| alias_method "#{name}?", name} end
@private
# File lib/rspec/core/configuration.rb, line 30 def self.define_reader(name) eval " def #{name} value_for(#{name.inspect}, defined?(@#{name}) ? @#{name} : nil) end " end
@private
# File lib/rspec/core/configuration.rb, line 39 def self.deprecate_alias_key RSpec.warn_deprecation "The :alias option to add_setting is deprecated. Use :alias_with on the original setting instead. Called from #{caller(0)[5]} " end
# 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
@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 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
@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 %x: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 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
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 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
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 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
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 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
# File lib/rspec/core/configuration.rb, line 375 def color return false unless output_to_tty? value_for(:color, @color) end
# File lib/rspec/core/configuration.rb, line 380 def color=(bool) return unless bool @color = true if bool && ::RbConfig::CONFIG['host_os'] =~ %rmswin|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
TODO - deprecate #color_enabled - probably not until the last 2.x release before 3.0
@private
# 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
@private
Used internally to extend a group with modules using `include` and/or `extend`.
# 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
@private
# File lib/rspec/core/configuration.rb, line 685 def configure_mock_framework RSpec::Core::ExampleGroup.send(:include, mock_framework) end
# File lib/rspec/core/configuration.rb, line 405 def debug=(bool) return unless bool begin require 'ruby-debug' Debugger.start rescue LoadError => e 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} " end end
Returns the `#exclusion_filter`. If none has been set, returns an empty hash.
# File lib/rspec/core/configuration.rb, line 600 def exclusion_filter filter_manager.exclusions 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 594 def exclusion_filter=(filter) filter_manager.exclude! build_metadata_hash_from([filter]) 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 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
Delegates to #expect_with(framework)
# File lib/rspec/core/configuration.rb, line 337 def expectation_framework=(framework) expect_with(framework) end
Returns the configured expectation framework adapter module(s)
# File lib/rspec/core/configuration.rb, line 331 def expectation_frameworks expect_with :rspec if @expectation_frameworks.empty? @expectation_frameworks 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 include
# File lib/rspec/core/configuration.rb, line 669 def extend(mod, *filters) include_or_extend_modules << [:extend, mod, build_metadata_hash_from(filters)] end
@private
# 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
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
filter_run_excluding :x => 'y' # with treat_symbols_as_metadata_keys_with_true_values = true filter_run_excluding :foo # results in {:foo => true}
# File lib/rspec/core/configuration.rb, line 583 def filter_run_excluding(*args) filter_manager.exclude_with_low_priority build_metadata_hash_from(args) 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
filter_run_including :x => 'y' # with treat_symbols_as_metadata_keys_with_true_values = true filter_run_including :foo # results in {:foo => true}
# File lib/rspec/core/configuration.rb, line 541 def filter_run_including(*args) filter_manager.include_with_low_priority build_metadata_hash_from(args) end
@private
Used to set higher priority option values from the command line.
# 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
# File lib/rspec/core/configuration.rb, line 457 def formatters @formatters ||= [] end
# File lib/rspec/core/configuration.rb, line 371 def full_backtrace=(true_or_false) @backtrace_clean_patterns = true_or_false ? [] : DEFAULT_BACKTRACE_PATTERNS end
# File lib/rspec/core/configuration.rb, line 431 def full_description=(description) filter_run :full_description => %r#{description}/ 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 extend
# File lib/rspec/core/configuration.rb, line 636 def include(mod, *filters) include_or_extend_modules << [:include, mod, build_metadata_hash_from(filters)] end
Returns the `#inclusion_filter`. If none has been set, returns an empty hash.
# File lib/rspec/core/configuration.rb, line 562 def inclusion_filter filter_manager.inclusions 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 554 def inclusion_filter=(filter) filter_manager.include! build_metadata_hash_from([filter]) end
# File lib/rspec/core/configuration.rb, line 397 def libs=(libs) libs.map {|lib| $LOAD_PATH.unshift lib} end
Run examples defined on `line_numbers` in all files to run.
# 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
@private
# 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
Returns the configured mock framework adapter module
# File lib/rspec/core/configuration.rb, line 267 def mock_framework mock_with :rspec unless @mock_framework @mock_framework end
Delegates to #mock_framework=(framework)
# File lib/rspec/core/configuration.rb, line 273 def mock_framework=(framework) mock_with framework 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 def mock_with(framework) framework_module = case framework when Module framework when String, Symbol require case framework.to_s when %rrspec/ 'rspec/core/mocking/with_rspec' when %rmocha/ 'rspec/core/mocking/with_mocha' when %rrr/ 'rspec/core/mocking/with_rr' when %rflexmock/ '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
@api
Sets the order and, if order is `'rand:<seed>'`, also sets the seed.
# File lib/rspec/core/configuration.rb, line 712 def order=(type) order_and_seed_from_order(type) end
# File lib/rspec/core/configuration.rb, line 716 def randomize? order.to_s.match(%rrand/) end
# File lib/rspec/core/configuration.rb, line 461 def reporter @reporter ||= begin add_formatter('progress') if formatters.empty? Reporter.new(*formatters) end end
# File lib/rspec/core/configuration.rb, line 401 def requires=(paths) paths.map {|path| require path} end
@private
# File lib/rspec/core/configuration.rb, line 209 def reset @reporter = nil @formatters.clear end
@api
Sets the seed value and sets `order='rand'`
# File lib/rspec/core/configuration.rb, line 705 def seed=(seed) order_and_seed_from_seed(seed) end