Class | RSpec::Core::Configuration |
In: |
lib/rspec/core/configuration.rb
|
Parent: | Object |
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
DEFAULT_BACKTRACE_PATTERNS | = | [ /\/lib\d*\/ruby\//, /org\/jruby\//, /bin\//, /gems/, /spec\/spec_helper\.rb/, /lib\/rspec\/(core|expectations|matchers|mocks)/ |
filter_manager | [RW] | @private |
@private
Invoked by the `add_setting` instance method. Use that method on a `Configuration` instance rather than this class method.
@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.
@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
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
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.
alias_it_behaves_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
Used by formatters to ask whether a backtrace line should be displayed or not, based on the line matching any `backtrace_clean_patterns`.
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.
Sets the expectation framework module(s) to be included in each example group.
`frameworks` can be `:rspec`, `:stdlib`, a custom module, or any combination thereof:
config.expect_with :rspec config.expect_with :stdlib config.expect_with :rspec, :stdlib config.expect_with OtherExpectationFramework
RSpec will translate `:rspec` and `:stdlib` into the appropriate modules.
If the module responds to `configuration`, `expect_with` will yield the `configuration` object if given a block:
config.expect_with OtherExpectationFramework do |custom_config| custom_config.custom_setting = true 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
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
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
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
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.
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)
If the module responds to `configuration` and `mock_with` receives a block, it will yield the configuration object to the block e.g.
config.mock_with OtherMockFrameworkAdapter do |mod_config| mod_config.custom_setting = true end