Used to ensure examples get reloaded between multiple runs in the same
+process.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Class Method Details
+
+
+
+
+
+ + (void) configuration
+
+
+
+
+
+
+
+
+
Returns the global Configuration
+object. While you can use this method to access the configuration,
+the more common convention is to use RSpec.configure.
# File 'lib/rspec/core.rb', line 78
+
+defself.configure
+ yieldconfigurationifblock_given?
+end
+
+
+
+
+
+
+
+
+ + (void) current_example
+
+
+
+
+
+
+
+
+
The example being executed.
+
+
The primary audience for this method is library authors who need access to
+the example currently being executed and also want to support all versions
+of RSpec 2 and 3.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|c|
+ # context.example is deprecated, but RSpec.current_example is not
+# available until RSpec 3.0.
+fetch_current_example=RSpec.respond_to?(:current_example)?
+ proc{RSpec.current_example}:proc{|context|context.example}
+
+ c.before(:example)do
+ example=fetch_current_example.call(self)
+
+ # ...
+end
+end
+
+
+
+
+
+
+
+
+
+
+103
+104
+105
+
+
+
# File 'lib/rspec/core.rb', line 103
+
+defself.current_example
+ thread_local_metadata[:current_example]
+end
Configuration options are loaded from ~/.rspec,
+.rspec, .rspec-local, command line switches, and
+the SPEC_OPTS environment variable (listed in lowest to
+highest precedence; for example, an option in ~/.rspec can be
+overridden by an option in .rspec-local).
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.
defaults to :white but can be set to one of the
+following:[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+234
+
+
+
# File 'lib/rspec/core/configuration.rb', line 234
+
+add_setting:default_color
+
+
+
+
+
+
+
+
+
+
+ - (void) default_path
+
+
+
+
+
+
+
+
+
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
+
+
+
+
+
+
+
+
+
+
+ - (void) detail_color
+
+
+
+
+
+
+
+
+
Color used to print details.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ color
+
+
+ (Symbol)
+
+
+
+ —
+
+
defaults to :cyan but can be set to one of the following:
+[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+248
+
+
+
# File 'lib/rspec/core/configuration.rb', line 248
+
+add_setting:detail_color
+
+
+
+
+
+
+
+
+
+
+ - (void) drb
+
+
+
+
+
+
+
+
+
Run examples over DRb (default: false). RSpec doesn't
+supply the DRb server, but you can use tools like spork.
+
+
+
+
+
+
+
+
+
+
+
+
+
+97
+
+
+
# File 'lib/rspec/core/configuration.rb', line 97
+
+add_setting:drb
+
+
+
+
+
+
+
+
+
+
+ - (void) drb_port
+
+
+
+
+
+
+
+
+
The drb_port (default: nil).
+
+
+
+
+
+
+
+
+
+
+
+
+
+101
+
+
+
# File 'lib/rspec/core/configuration.rb', line 101
+
+add_setting:drb_port
+
+
+
+
+
+
+
+
+
+
+ - (void) dry_run
+
+
+
+
+
+
+
+
+
Prints the formatter output of your suite without running any examples or
+hooks.
+
+
+
+
+
+
+
+
+
+
+
+
+
+153
+
+
+
# File 'lib/rspec/core/configuration.rb', line 153
+
+add_setting:dry_run
+
+
+
+
+
+
+
+
+
+
+ - (void) error_stream
+
+
+
+
+
+
+
+
+
Default: $stderr.
+
+
+
+
+
+
+
+
+
+
+
+
+
+105
+
+
+
# File 'lib/rspec/core/configuration.rb', line 105
+
+add_setting:error_stream
+
+
+
+
+
+
+
+
+
+
+ - (void) fail_fast
+
+
+
+
+
+
+
+
+
Clean up and exit after the first failure (default: false).
+
+
+
+
+
+
+
+
+
+
+
+
+
+148
+
+
+
# File 'lib/rspec/core/configuration.rb', line 148
+
+add_setting:fail_fast
+
+
+
+
+
+
+
+
+
+
+ - (void) failure_color
+
+
+
+
+
+
+
+
+
Color to use to indicate failure.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ color
+
+
+ (Symbol)
+
+
+
+ —
+
+
defaults to :red but can be set to one of the following:
+[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+227
+
+
+
# File 'lib/rspec/core/configuration.rb', line 227
+
+add_setting:failure_color
+
+
+
+
+
+
+
+
+
+
+ - (void) failure_exit_code
+
+
+
+
+
+
+
+
+
The exit code to return if there are any failures (default: 1).
+
+
+
+
+
+
+
+
+
+
+
+
+
+157
+
+
+
# File 'lib/rspec/core/configuration.rb', line 157
+
+add_setting:failure_exit_code
+
+
+
+
+
+
+
+
+
+
+ - (Array) files_to_run
+
+
+
+
+
+
+
+
+
The spec files RSpec will run
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Array)
+
+
+
+ —
+
+
specified files about to run
+
+
+
+
+
+
+
+
+
+
+
+
+720
+721
+722
+
+
+
# File 'lib/rspec/core/configuration.rb', line 720
+
+deffiles_to_run
+ @files_to_run||=get_files_to_run(@files_or_directories_to_run)
+end
+
+
+
+
+
+
+
+
+
+
+ - (void) fixed_color
+
+
+
+
+
+
+
+
+
Color used when a pending example is fixed.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ color
+
+
+ (Symbol)
+
+
+
+ —
+
+
defaults to :blue but can be set to one of the following:
+[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+241
+
+
+
# File 'lib/rspec/core/configuration.rb', line 241
+
+add_setting:fixed_color
+
+
+
+
+
+
+
+
+
+
+ - (void) libs
+
+
+
+
+
+
+
+
+
Returns dirs that have been prepended to the load path by the
+-I command line option
+
+
+
+
+
+
+
+
+
+
+
+
+
+165
+
+
+
# File 'lib/rspec/core/configuration.rb', line 165
+
+define_reader:libs
+
+
+
+
+
+
+
+
+
+
+ - (void) output_stream
+
+
+
+
+
+
+
+
+
Determines where RSpec will send its output. Default: $stdout.
+
+
+
+
+
+
+
+
+
+
+
+
+
+170
+
+
+
# File 'lib/rspec/core/configuration.rb', line 170
+
+define_reader:output_stream
+
+
+
+
+
+
+
+
+
+
+ - (void) pattern
+
+
+
+
+
+
+
+
+
Load files matching this pattern (default:
+'**/*_spec.rb')
+
+
+
+
+
+
+
+
+
+
+
+
+
+187
+
+
+
# File 'lib/rspec/core/configuration.rb', line 187
+
+define_reader:pattern
+
+
+
+
+
+
+
+
+
+
+ - (void) pending_color
+
+
+
+
+
+
+
+
+
Color to use to print pending examples.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ color
+
+
+ (Symbol)
+
+
+
+ —
+
+
defaults to :yellow but can be set to one of the following:
+[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+220
+
+
+
# File 'lib/rspec/core/configuration.rb', line 220
+
+add_setting:pending_color
+
+
+
+
+
+
+
+
+
+
+ - (void) profile_examples
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
Defaults profile_examples to 10 examples when
+@profile_examples is true.
+
+
+
+
+
+
+
+
+
+
+
+
+
+202
+
+
+
# File 'lib/rspec/core/configuration.rb', line 202
+
+add_setting:profile_examples
+
+
+
+
+
+
+
+
+
+
+ - (void) requires
+
+
+
+
+
+
+
+
+
Indicates files configured to be required
+
+
+
+
+
+
+
+
+
+
+
+
+
+161
+
+
+
# File 'lib/rspec/core/configuration.rb', line 161
+
+define_reader:requires
Run all examples if none match the configured filters (default:
+false).
+
+
+
+
+
+
+
+
+
+
+
+
+
+206
+
+
+
# File 'lib/rspec/core/configuration.rb', line 206
+
+add_setting:run_all_when_everything_filtered
+
+
+
+
+
+
+
+
+
+
+ - (void) success_color
+
+
+
+
+
+
+
+
+
Color to use to indicate success.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ color
+
+
+ (Symbol)
+
+
+
+ —
+
+
defaults to :green but can be set to one of the following:
+[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+213
+
+
+
# File 'lib/rspec/core/configuration.rb', line 213
+
+add_setting:success_color
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (void) add_formatter(formatter)
+
+
+
+ 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 paths to use for output streams, but you should consider that a
+private api that may change at any time without notice.
The defined aliased will also be added to the top level (e.g.
+main and from within modules) if
+expose_dsl_globally is set to true.
+
+
+
+
+
Creates a method that defines an example group with the provided metadata.
+Can be used to define example group/metadata shortcuts.
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.configuredo|config|
+ config.alias_example_group_to:describe_model,:type=>:model
+end
+
+shared_context_for"model tests",:type=>:modeldo
+ # define common model test helper methods, `let` declarations, etc
+end
+
+# This lets you do this:
+
+RSpec.describe_modelUserdo
+end
+
+# ... which is the equivalent of
+
+RSpec.describeUser,:type=>:modeldo
+end
The specific example alias below (pending) is already defined
+for you.
+
+
+
+
+ Note:
+
+
Use with caution. This extends the language used in your specs, but does
+not add any additional documentation. We use this in rspec to define
+methods like focus and xit, but we also add docs
+for those methods.
+
+
+
+
+
Creates a method that delegates to example including the
+submitted args. Used internally to add variants of
+example like pending:
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.configuredo|config|
+ config.alias_example_to:pending,:pending=>true
+end
+
+# This lets you do this:
+
+describeThingdo
+ pending"does something"do
+ thing=Thing.new
+ end
+end
+
+# ... which is the equivalent of
+
+describeThingdo
+ it"does something",:pending=>truedo
+ thing=Thing.new
+ end
+end
Use with caution. This extends the language used in your specs, but does
+not add any additional documentation. We use this in rspec to define
+it_should_behave_like (for backward compatibility), but we
+also add docs for that method.
+
+
+
+
+
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.
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.configuredo|config|
+ config.alias_it_behaves_like_to(:it_has_behavior,'has behavior:')
+end
+
+# allows the user to include a shared example group like:
+
+describeEntitydo
+ 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
+
+
+
+
+
+
+
+
+
+
+819
+820
+821
+
+
+
# File 'lib/rspec/core/configuration.rb', line 819
+
+defalias_it_behaves_like_to(new_name,report_label='')
+ RSpec::Core::ExampleGroup.define_nested_shared_group_method(new_name,report_label)
+end
Excludes lines from ruby (and jruby) source, installed gems, anything in
+any “bin” directory, and any of the rspec libs (outside gem installs) by
+default.
+
+
You can modify the list via the getter, or replace it with the setter.
+
+
To override this behaviour and display a full backtrace, use
+--backtraceon the command line, in a .rspec file,
+or in the rspec_options attribute of RSpec's rake task.
+
+
+
+
+
+
+
+
+
+
+
+
+
+388
+389
+390
+
+
+
# File 'lib/rspec/core/configuration.rb', line 388
+
+defbacktrace_exclusion_patterns
+ @backtrace_formatter.exclusion_patterns
+end
# File 'lib/rspec/core/configuration.rb', line 582
+
+defcolor=(true_or_false)
+ iftrue_or_false
+ ifRSpec.world.windows_os?andnotENV['ANSICON']
+ RSpec.warning"You must use ANSICON 1.31 or later (http://adoxa.3eeweb.com/ansicon/) to use colour on Windows"
+ @color=false
+ else
+ @color=true
+ end
+ end
+end
Defines a callback that can assign derived metadata values.
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.configuredo|config|
+ # Tag all groups and examples in the spec/unit directory with :type => :unit
+config.define_derived_metadata(:file_path=>%r{/spec/unit/})do|metadata|
+ metadata[:type]=:unit
+ end
+end
metadata filters that determine which example or group metadata hashes the
+callback will be triggered for. If none are given, the callback will be run
+against the metadata hashes of all groups and examples.
+
+
+
+
+
+
+
Yield Parameters:
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
original metadata hash from an example or group. Mutate this in your block
+as needed.
# File 'lib/rspec/core/configuration.rb', line 134
+
+defdeprecation_stream=(value)
+ if@reporter&&!value.equal?(@deprecation_stream)
+ warn"RSpec's reporter has already been initialized with "+
+ "#{deprecation_stream.inspect} as the deprecation stream, so your change to "+
+ "`deprecation_stream` will be ignored. You should configure it earlier for "+
+ "it to take effect, or use the `--deprecation-out` CLI option. "+
+ "(Called from #{CallerFilter.first_non_rspec_line})"
+ else
+ @deprecation_stream=value
+ end
+end
+
+
+
+
+
+
+
+
+ - (void) disable_monkey_patching!
+
+
+
+
+
+
+
+
+
+ Note:
+
+
It configures rspec-mocks and rspec-expectations only if the user is using
+those (either explicitly or implicitly by not setting
+mock_with or expect_with to anything else).
+
+
+
+
+ Note:
+
+
If the user uses this options with mock_with :mocha (or
+similiar) they will still have monkey patching active in their test
+environment from mocha.
+
+
+
+
+
Enables zero monkey patching mode for RSpec. It removes monkey patching of
+the top-level DSL methods (describe,
+shared_examples_for, etc) onto main and
+Module, instead requiring you to prefix these methods with
+RSpec.. It enables expect-only syntax for rspec-mocks and
+rspec-expectations. It simply disables monkey patching on whatever pieces
+of rspec the user is using.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+# It disables all monkey patching
+RSpec.configuredo|config|
+ config.disable_monkey_patching!
+end
+
+# Is an equivalent to
+RSpec.configuredo|config|
+ config.expose_dsl_globally=false
+
+ config.mock_with:rspecdo|mocks|
+ mocks.syntax=:expect
+ mocks.patch_marshal_to_support_partial_doubles=false
+ end
+
+ config.mock_with:rspecdo|expectations|
+ expectations.syntax=:expect
+ end
+end
# File 'lib/rspec/core/configuration.rb', line 518
+
+defexpect_with(*frameworks)
+ modules=frameworks.mapdo|framework|
+ caseframework
+ whenModule
+ framework
+ when:rspec
+ require'rspec/expectations'
+ self.expecting_with_rspec=true
+ ::RSpec::Matchers
+ when:test_unit
+ require'rspec/core/test_unit_assertions_adapter'
+ ::RSpec::Core::TestUnitAssertionsAdapter
+ when:minitest
+ require'rspec/core/minitest_assertions_adapter'
+ ::RSpec::Core::MinitestAssertionsAdapter
+ else
+ raiseArgumentError,"#{framework.inspect} is not supported"
+ end
+ end
+
+ if(modules-@expectation_frameworks).any?
+ assert_no_example_groups_defined(:expect_with)
+ end
+
+ ifblock_given?
+ raise"expect_with only accepts a block with a single argument. Call expect_with #{modules.length} times, once with each argument, instead."ifmodules.length>1
+ raise"#{modules.first} must respond to `configuration` so that expect_with can yield it."unlessmodules.first.respond_to?(:configuration)
+ yieldmodules.first.configuration
+ end
+
+ @expectation_frameworks.push(*modules)
+end
Exposes the current running example via the named helper method. RSpec 2.x
+exposed this via example, but in RSpec 3.0, the example is
+instead exposed via an arg yielded to it, before,
+let, etc. However, some extension gems (such as Capybara)
+depend on the RSpec 2.x's example method, so this config
+option can be used to maintain compatibility.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|rspec|
+ rspec.expose_current_running_example_as:example
+end
+
+describeMyClassdo
+ beforedo
+ # `example` can be used here because of the above config.
+do_somethingifexample.metadata[:type]=="foo"
+ end
+end
Use this to expose the core RSpec DSL via Module and the
+main object. It will be set automatically but you can override
+it to remove the DSL. Default: true
Indicates if the DSL has been exposed off of modules and main.
+Default: true
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+109
+110
+111
+
+
+
# File 'lib/rspec/core/configuration.rb', line 109
+
+defexpose_dsl_globally?
+ Core::DSL.exposed_globally?
+end
+
+
+
+
+
+
+
+
+ - (void) extend(mod, *filters)
+
+
+
+
+
+
+
+
+
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.
Adds key/value pairs to the exclusion_filter. If
+args includes any symbols that are not part of the 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:
+
+
+
# 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'}
+
+filter_run_excluding:foo# same as filter_run_excluding :foo => true
+
+ - (void) filter_run_including(*args)
+
+
+
+ Also known as:
+ filter_run
+
+
+
+
+
+
+
+
Adds key/value pairs to the inclusion_filter. If
+args includes any symbols that are not part of the 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:
+
+
+
# 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'}
+
+filter_run_including:foo# same as filter_run_including :foo => true
# File 'lib/rspec/core/configuration.rb', line 603
+
+deffull_description=(description)
+ filter_run:full_description=>Regexp.union(*Array(description).map{|d|Regexp.new(d)})
+end
+
+
+
+
+
+
+
+
+ - (void) include(mod, *filters)
+
+
+
+
+
+
+
+
+
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:
+
+
+
+moduleAuthenticationHelpers
+ deflogin_as(user)
+ # ...
+end
+end
+
+moduleUserHelpers
+ defusers(username)
+ # ...
+end
+end
+
+RSpec.configuredo|config|
+ config.include(UserHelpers)# included in all modules
+config.include(AuthenticationHelpers,:type=>:request)
+end
+
+describe"edit profile",:type=>:requestdo
+ it"can be viewed by owning user"do
+ login_asusers(:jdoe)
+ get"/profiles/jdoe"
+ assert_select".username",:text=>'jdoe'
+ end
+end
# File 'lib/rspec/core/configuration.rb', line 373
+
+defmock_framework=(framework)
+ mock_withframework
+end
+
+
+
+
+
+
+
+
+ - (void) mock_with(framework)
+
+
+
+
+
+
+
+
+
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 if the example hasn't yet failed.
+ 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.
Turns deprecation warnings into errors, in order to surface the full
+backtrace of the call site. This can be useful when you need more context
+to address a deprecation than the single-line call site normally provided.
Pass the symbol :global to set the ordering strategy that will
+be used to order the top-level example groups and any example groups that
+do not have declared :order metadata.
+
+
+
+
+
Registers a named ordering strategy that can later be used to order an
+example group's subgroups by adding :order =>
+<name> metadata to the example group.
# File 'lib/rspec/core/configuration.rb', line 1140
+
+delegate_to_ordering_manager:register_ordering
+
+
+
+
+
+
+
+
+ - (void) seed
+
+
+
+
+
+
+
+
+
Seed for random ordering (default: generated randomly each run).
+
+
When you run specs with --order random, RSpec generates a
+random seed for the randomization and prints it to the
+output_stream (assuming you're using RSpec's built-in
+formatters). If you discover an ordering dependency (i.e. examples fail
+intermittently depending on order), set this (on Configuration or on the
+command line with --seed) to run using the same seed while you
+debug the issue.
+
+
We recommend, actually, that you use the command line approach so you
+don't accidentally leave the seed encoded.
+
+
+
+
+
+
+
+
+
+
+
+
+
+1109
+
+
+
# File 'lib/rspec/core/configuration.rb', line 1109
+
+delegate_to_ordering_manager:seed
+
+
+
+
+
+
+
+
+ - (void) seed=
+
+
+
+
+
+
+
+
+
Sets the seed value and sets the default global ordering to random.
+
+
+
+
+
+
+
+
+
+
+
+
+
+1095
+
+
+
# File 'lib/rspec/core/configuration.rb', line 1095
+
+delegate_to_ordering_manager:seed=
Deprecated. This config option was added in RSpec 2 to pave the way for
+this being the default behavior in RSpec 3. Now this option is a no-op.
+
+
+
+
+
+
+
+
+
+
+
+
+
+253
+254
+255
+256
+257
+
+
+
# File 'lib/rspec/core/configuration.rb', line 253
+
+deftreat_symbols_as_metadata_keys_with_true_values=(value)
+ RSpec.deprecate("RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values=",
+ :message=>"RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values= "+
+ "is deprecated, it is now set to true as default and setting it to false has no effect.")
+end
+
+
+
+
+
+
+
+
+ - (void) warnings=(value)
+
+
+
+
+
+
+
+
+
Set Ruby warnings on or off
+
+
+
+
+
+
+
+
+
+
+
+
+
+1146
+1147
+1148
+
+
+
# File 'lib/rspec/core/configuration.rb', line 1146
+
+defwarnings=(value)
+ $VERBOSE=!!value
+end
+
+
+
+
+
+
+
+
+ - (Boolean) warnings?
+
+
+
+
+
+
+
+
+
Returns Whether or not ruby warnings are enabled.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
+
Whether or not ruby warnings are enabled.
+
+
+
+
+
+
+
+
+
+
+
+
+1151
+1152
+1153
+
+
+
# File 'lib/rspec/core/configuration.rb', line 1151
+
+defwarnings?
+ $VERBOSE
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-core/RSpec/Core/ConfigurationOptions.html b/source/documentation/3.0/rspec-core/RSpec/Core/ConfigurationOptions.html
new file mode 100644
index 000000000..512463314
--- /dev/null
+++ b/source/documentation/3.0/rspec-core/RSpec/Core/ConfigurationOptions.html
@@ -0,0 +1,530 @@
+
+
+
+
+
+ Class: RSpec::Core::ConfigurationOptions
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Responsible for utilizing externally provided configuration options,
+whether via the command line, .rspec, ~/.rspec,
+.rspec-local or a custom options file.
DSL defines methods to group examples, most notably describe,
+and exposes them as class methods of RSpec. They can also be exposed
+globally (on main and instances of Module)
+through the Configuration option expose_dsl_globally.
+
+
By default the methods describe, context and
+example_group are exposed. These methods define a named
+context for one or more examples. The given block is evaluated in the
+context of a generated subclass of ExampleGroup
+
+
Examples:
+
+
RSpec.describe"something"do
+ context"when something is a certain way"do
+ it"does something"do
+ # example code goes here
+end
+ end
+end
Example blocks are evaluated in the context of an instance of an
+ExampleGroup, not in the context of an instance of
+Example.
+
+
+
+
+
Wrapper for an instance of a subclass of ExampleGroup. An instance of
+RSpec::Core::Example is returned by example definition methods
+such as it and is yielded to the it,
+before, after, around,
+let and
+subject blocks.
+
+
This allows us to provide rich metadata about each individual example
+without adding tons of methods directly to the ExampleGroup that users may
+inadvertantly redefine.
+
+
Useful for configuring logging and/or taking some action based on the state
+of an example's metadata.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|config|
+ config.beforedo|example|
+ logexample.description
+ end
+
+ config.afterdo|example|
+ logexample.description
+ end
+
+ config.arounddo|example|
+ logexample.description
+ example.run
+ end
+end
+
+shared_examples"auditable"do
+ it"does something"do
+ log"#{example.full_description}: #{auditable.inspect}"
+ auditable.shoulddo_something
+ end
+end
Returns the first exception raised in the context of running this example
+(nil if no exception is raised)
+
+
+
+
+
+
+
+
+
+
+
+
+
+86
+87
+88
+
+
+
# File 'lib/rspec/core/example.rb', line 86
+
+defexception
+ @exception
+end
+
+
+
+
+
+
+
+
+
+
+ - (void) metadata(readonly)
+
+
+
+
+
+
+
+
+
Returns the metadata object associated with this example.
+
+
+
+
+
+
+
+
+
+
+
+
+
+91
+92
+93
+
+
+
# File 'lib/rspec/core/example.rb', line 91
+
+defmetadata
+ @metadata
+end
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (void) description
+
+
+
+
+
+
+
+
+
Returns the string submitted to example or its aliases (e.g.
+specify, it, etc). If no string is submitted
+(e.g. it { is_expected.to do_something }) it returns the
+message generated by the matcher if there is one, otherwise returns a
+message including the location of the example.
+
+
+
+
+
+
+
+
+
+
+
+
+
+75
+76
+77
+78
+79
+80
+
+
+
# File 'lib/rspec/core/example.rb', line 75
+
+defdescription
+ description=metadata[:description].to_s.empty??
+ "example at #{location}":
+ metadata[:description]
+ RSpec.configuration.format_docstrings_block.call(description)
+end
+
+
+
+
+
+
+
+
+ - (void) example_group
+
+
+
+
+
+
+
+
+
Returns the example group class that provides the context for running this
+example.
+
+
+
+
+
+
+
+
+
+
+
+
+
+124
+125
+126
+
+
+
# File 'lib/rspec/core/example.rb', line 124
+
+defexample_group
+ @example_group_class
+end
# File 'lib/rspec/core/example.rb', line 53
+
+delegate_to_metadata:execution_result
+
+
+
+
+
+
+
+
+ - (String) file_path
+
+
+
+
+
+
+
+
+
Returns the relative path to the file where this example was defined.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
+
the relative path to the file where this example was defined.
+
+
+
+
+
+
+
+
+
+
+
+
+55
+
+
+
# File 'lib/rspec/core/example.rb', line 55
+
+delegate_to_metadata:file_path
+
+
+
+
+
+
+
+
+ - (String) full_description
+
+
+
+
+
+
+
+
+
Returns the full description (including the docstrings of all parent
+example groups).
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
+
the full description (including the docstrings of all parent example
+groups).
+
+
+
+
+
+
+
+
+
+
+
+
+58
+
+
+
# File 'lib/rspec/core/example.rb', line 58
+
+delegate_to_metadata:full_description
+
+
+
+
+
+
+
+
+ - (String) location
+
+
+
+
+
+
+
+
+
Returns the exact source location of this example in a form like
+./path/to/spec.rb:17
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
+
the exact source location of this example in a form like
+./path/to/spec.rb:17
+
+
+
+
+
+
+
+
+
+
+
+
+61
+
+
+
# File 'lib/rspec/core/example.rb', line 61
+
+delegate_to_metadata:location
+
+
+
+
+
+
+
+
+ - (Boolean) pending
+
+
+
+ Also known as:
+ pending?
+
+
+
+
+
+
+
+
Returns flag that indicates that the example is not expected to pass. It
+will be run and will either have a pending result (if a failure occurs) or
+a failed result (if no failure occurs).
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
+
flag that indicates that the example is not expected to pass. It will be
+run and will either have a pending result (if a failure occurs) or a failed
+result (if no failure occurs).
+
+
+
+
+
+
+
+
+
+
+
+
+65
+
+
+
# File 'lib/rspec/core/example.rb', line 65
+
+delegate_to_metadata:pending
# File 'lib/rspec/core/example.rb', line 396
+
+defexception
+ @exception
+end
+
+
+
+
+
+
+
+
+
+
+ - (Time) finished_at
+
+
+
+
+
+
+
+
+
Returns When the example finished.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Time)
+
+
+
+ —
+
+
When the example finished.
+
+
+
+
+
+
+
+
+
+
+
+
+402
+403
+404
+
+
+
# File 'lib/rspec/core/example.rb', line 402
+
+deffinished_at
+ @finished_at
+end
+
+
+
+
+
+
+
+
+
+
+ - (Exception?) pending_exception
+
+
+
+
+
+
+
+
+
Returns The exception triggered while executing the pending example. If no
+exception was triggered it would no longer get a status of
+:pending unless it was tagged with :skip.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Exception, nil)
+
+
+
+ —
+
+
The exception triggered while executing the pending example. If no
+exception was triggered it would no longer get a status of
+:pending unless it was tagged with :skip.
+
+
+
+
+
+
+
+
+
+
+
+
+415
+416
+417
+
+
+
# File 'lib/rspec/core/example.rb', line 415
+
+defpending_exception
+ @pending_exception
+end
+
+
+
+
+
+
+
+
+
+
+ - (Boolean) pending_fixed
+
+
+
+ Also known as:
+ pending_fixed?
+
+
+
+
+
+
+
+
Returns For examples tagged with :pending, this indicates
+whether or not it now passes.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
+
For examples tagged with :pending, this indicates whether or
+not it now passes.
+
+
+
+
+
+
+
+
+
+
+
+
+419
+420
+421
+
+
+
# File 'lib/rspec/core/example.rb', line 419
+
+defpending_fixed
+ @pending_fixed
+end
+
+
+
+
+
+
+
+
+
+
+ - (String?) pending_message
+
+
+
+
+
+
+
+
+
Returns The reason the example was pending, or nil if the example was not
+pending.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String, nil)
+
+
+
+ —
+
+
The reason the example was pending, or nil if the example was not pending.
+
+
+
+
+
+
+
+
+
+
+
+
+409
+410
+411
+
+
+
# File 'lib/rspec/core/example.rb', line 409
+
+defpending_message
+ @pending_message
+end
+
+
+
+
+
+
+
+
+
+
+ - (Float) run_time
+
+
+
+
+
+
+
+
+
Returns How long the example took in seconds.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Float)
+
+
+
+ —
+
+
How long the example took in seconds.
+
+
+
+
+
+
+
+
+
+
+
+
+405
+406
+407
+
+
+
# File 'lib/rspec/core/example.rb', line 405
+
+defrun_time
+ @run_time
+end
+
+
+
+
+
+
+
+
+
+
+ - (Time) started_at
+
+
+
+
+
+
+
+
+
Returns When the example started.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Time)
+
+
+
+ —
+
+
When the example started.
+
+
+
+
+
+
+
+
+
+
+
+
+399
+400
+401
+
+
+
# File 'lib/rspec/core/example.rb', line 399
+
+defstarted_at
+ @started_at
+end
+
+
+
+
+
+
+
+
+
+
+ - (Symbol) status
+
+
+
+
+
+
+
+
+
Returns :passed, :failed or
+:pending.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Symbol)
+
+
+
+ —
+
+
:passed, :failed or :pending.
+
+
+
+
+
+
+
+
+
+
+
+
+393
+394
+395
+
+
+
# File 'lib/rspec/core/example.rb', line 393
+
+defstatus
+ @status
+end
Wraps both a Proc and an RSpec::Core::Example for use in around hooks. In around hooks we need to yield this special kind of object
+(rather than the raw RSpec::Core::Example) because when there are multiple
+around hooks we have to wrap them recursively.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|c|
+ c.arounddo|ex|# Procsy which wraps the example
+ifex.metadata[:key]==:some_value&&some_global_condition
+ raise"some message"
+ end
+ ex.run# run delegates to ex.call
+end
+end
ExampleGroup and Example are the main structural elements of rspec-core.
+Consider this example:
+
+
describeThingdo
+ it"does something"do
+ end
+end
+
+
The object returned by describe Thing is a subclass of
+ExampleGroup. The object returned by it "does
+something" is an instance of Example, which serves as a wrapper
+for an instance of the ExampleGroup in which it is declared.
+
+
Example group bodies (e.g. describe or context
+blocks) are evaluated in the context of a new subclass of ExampleGroup.
+Individual examples are evalutaed in the context of an instance of the
+specific ExampleGroup subclass to which they belong.
An alias of example_group. Generally used when grouping
+examples contextually (e.g. “with xyz”, “when xyz” or “if xyz”). Generates
+a subclass of this example group which inherits everything except the
+examples themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ context"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
# File 'lib/rspec/core/example_group.rb', line 249
+
+define_example_group_method:context
+
+
+
+
+
+
+
+
+ + (void) describe { ... }
+
+
+
+
+
+
+
+
+
An alias of example_group. Generally used when grouping
+examples by a thing you are describing (e.g. an object, class or method).
+Generates a subclass of this example group which inherits everything except
+the examples themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ describe"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
exampledo
+end
+
+example"does something"do
+end
+
+example"does something",:with=>'additional metadata'do
+end
+
+example"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 131
+
+define_example_method:example
+
+
+
+
+
+
+
+
+ + (void) example_group { ... }
+
+
+
+
+
+
+
+
+
Generates a subclass of this example group which inherits everything except
+the examples themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ example_group"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+
+
+
+
+
+
+
The example group definition
+
+
+
+
+
+
+
+
+
+
+
+
+239
+
+
+
# File 'lib/rspec/core/example_group.rb', line 239
+
+define_example_group_method:example_group
+
+
+
+
+
+
+
+
+ + (void) fcontext { ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example group with :focus => true.
+Generates a subclass of this example group which inherits everything except
+the examples themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ fcontext"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
# File 'lib/rspec/core/example_group.rb', line 265
+
+define_example_group_method:fcontext,:focus=>true
+
+
+
+
+
+
+
+
+ + (void) fdescribe { ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example group with :focus => true.
+Generates a subclass of this example group which inherits everything except
+the examples themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ fdescribe"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
fexampledo
+end
+
+fexample"does something"do
+end
+
+fexample"does something",:with=>'additional metadata'do
+end
+
+fexample"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 150
+
+define_example_method:fexample,:focus=>true
+
+
+
+
+
+
+
+
+ + (void) fit {|Example| ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example with :focus => true
+
+
+
+
+
+
+
+
Examples:
+
+
+
fitdo
+end
+
+fit"does something"do
+end
+
+fit"does something",:with=>'additional metadata'do
+end
+
+fit"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 153
+
+define_example_method:fit,:focus=>true
+
+
+
+
+
+
+
+
+ + (void) focus {|Example| ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example with :focus => true
+
+
+
+
+
+
+
+
Examples:
+
+
+
focusdo
+end
+
+focus"does something"do
+end
+
+focus"does something",:with=>'additional metadata'do
+end
+
+focus"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
fspecifydo
+end
+
+fspecify"does something"do
+end
+
+fspecify"does something",:with=>'additional metadata'do
+end
+
+fspecify"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
Includes shared content mapped to name directly in the group
+in which it is declared, as opposed to it_behaves_like, which
+creates a nested group. If given a block, that block is also eval'd in
+the current context.
Includes shared content mapped to name directly in the group
+in which it is declared, as opposed to it_behaves_like, which
+creates a nested group. If given a block, that block is also eval'd in
+the current context.
# File 'lib/rspec/core/example_group.rb', line 310
+
+defself.include_examples(name,*args,&block)
+ find_and_eval_shared("examples",name,*args,&block)
+end
+
+
+
+
+
+
+
+
+ + (void) it {|Example| ... }
+
+
+
+
+
+
+
+
+
Defines an example within a group. This is the primary API to define a code
+example.
+
+
+
+
+
+
+
+
Examples:
+
+
+
itdo
+end
+
+it"does something"do
+end
+
+it"does something",:with=>'additional metadata'do
+end
+
+it"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 44
+
+defself.metadata
+ @metadataifdefined?(@metadata)
+end
+
+
+
+
+
+
+
+
+ + (void) pending {|Example| ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example with :pending => true
+
+
+
+
+
+
+
+
Examples:
+
+
+
pendingdo
+end
+
+pending"does something"do
+end
+
+pending"does something",:with=>'additional metadata'do
+end
+
+pending"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
skipdo
+end
+
+skip"does something"do
+end
+
+skip"does something",:with=>'additional metadata'do
+end
+
+skip"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 168
+
+define_example_method:skip,:skip=>true
+
+
+
+
+
+
+
+
+ + (void) specify {|Example| ... }
+
+
+
+
+
+
+
+
+
Defines an example within a group. Useful for when your docstring does not
+read well off of it.
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.describeMyClassdo
+ specify"#do_something is deprecated"do
+ # ...
+end
+end
+
+
+
specifydo
+end
+
+specify"does something"do
+end
+
+specify"does something",:with=>'additional metadata'do
+end
+
+specify"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 143
+
+define_example_method:specify
+
+
+
+
+
+
+
+
+ + (void) xcontext { ... }
+
+
+
+
+
+
+
+
+
Shortcut to temporarily make an example group skipped. Generates a subclass
+of this example group which inherits everything except the examples
+themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ xcontext"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
# File 'lib/rspec/core/example_group.rb', line 257
+
+define_example_group_method:xcontext,:skip=>"Temporarily skipped with xcontext"
+
+
+
+
+
+
+
+
+ + (void) xdescribe { ... }
+
+
+
+
+
+
+
+
+
Shortcut to temporarily make an example group skipped. Generates a subclass
+of this example group which inherits everything except the examples
+themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ xdescribe"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
Shortcut to define an example with :skip => 'Temporarily
+skipped with xexample'
+
+
+
+
+
+
+
+
Examples:
+
+
+
xexampledo
+end
+
+xexample"does something"do
+end
+
+xexample"does something",:with=>'additional metadata'do
+end
+
+xexample"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 159
+
+define_example_method:xexample,:skip=>'Temporarily skipped with xexample'
+
+
+
+
+
+
+
+
+ + (void) xit {|Example| ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example with :skip => 'Temporarily
+skipped with xit'
+
+
+
+
+
+
+
+
Examples:
+
+
+
xitdo
+end
+
+xit"does something"do
+end
+
+xit"does something",:with=>'additional metadata'do
+end
+
+xit"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
Shortcut to define an example with :skip => 'Temporarily
+skipped with xspecify'
+
+
+
+
+
+
+
+
Examples:
+
+
+
xspecifydo
+end
+
+xspecify"does something"do
+end
+
+xspecify"does something",:with=>'additional metadata'do
+end
+
+xspecify"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
progress (default) - prints dots for passing examples, F for
+failures, * for pending
+
+
documentation - prints the docstrings passed to describe and
+it methods (and their aliases)
+
+
html
+
+
json - useful for archiving data for subsequent analysis
+
+
+
The progress formatter is the default, but you can choose any one or more
+of the other formatters by passing with the --format (or
+-f for short) command-line option, e.g.
+
+
rspec --format documentation
+
+
You can also send the output of multiple formatters to different streams,
+e.g.
+
+
rspec --format documentation --format html --out results.html
+
+
This example sends the output of the documentation formatter to
+$stdout, and the output of the html formatter to results.html.
+
+
Custom Formatters
+
+
You can tell RSpec to use a custom formatter by passing its path and name
+to the rspec commmand. For example, if you define
+MyCustomFormatter in path/to/my_custom_formatter.rb, you would type this
+command:
The reporter calls every formatter with this protocol:
+
+
To start
+
+
start(StartNotification)
+
+
Once per example group
+
+
example_group_started(GroupNotification)
+
+
Once per example
+
+
example_started(ExampleNotification)
+
+
One of these per example, depending on outcome
+
+
example_passed(ExampleNotification)
+
+
example_failed(FailedExampleNotification)
+
+
example_pending(ExampleNotification)
+
+
Optionally at any time
+
+
message(MessageNotification)
+
+
At the end of the suite
+
+
stop(ExamplesNotification)
+
+
start_dump(NullNotification)
+
+
dump_pending(ExamplesNotification)
+
+
dump_failures(ExamplesNotification)
+
+
dump_summary(SummaryNotification)
+
+
seed(SeedNotification)
+
+
close(NullNotification)
+
+
+
Only the notifications to which you subscribe your formatter will be called
+on your formatter. To subscribe your formatter use:
+RSpec::Core::Formatters#register e.g.
We recommend you implement the methods yourself; for simplicity we provide
+the default formatter output via our notification objects but if you prefer
+you can subclass RSpec::Core::Formatters::BaseTextFormatter
+and override the methods you wish to enhance.
RSpec's built-in formatters are all subclasses of
+RSpec::Core::Formatters::BaseTextFormatter, but the BaseTextFormatter
+documents all of the notifications implemented as part of the standard
+interface. The reporter will issue these during a normal test suite run,
+but a formatter will only receive those notifications it has registered
+itself to receive.
# File 'lib/rspec/core/formatters/base_formatter.rb', line 89
+
+
+
+
+
+
+
+
+
+
+ - (void) start(notification)
+
+
+
+
+
+
+
+
+
This method is invoked before any examples are run, right after they have
+all been collected. This can be useful for special formatters that need to
+provide progress on feedback (graphical ones).
+
+
This will only be invoked once, and the next one to be invoked is
+#example_group_started.
This method is invoked after all of the examples have executed. The next
+method to be invoked after this one is #dump_failures (BaseTextFormatter
+then calls #dump_failure once for each failed example.)
+
+
+
+
+
+
Parameters:
+
+
+
+
+ notification
+
+
+ (NullNotification)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/core/formatters/base_formatter.rb', line 103
+
+
+
+
+
+
+
+
+
+
+ - (void) stop
+
+
+
+
+
+
+
+
+
Invoked after all examples have executed, before dumping post-run reports.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ notification
+
+
+ (NullNotification)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/core/formatters/base_formatter.rb', line 96
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-core/RSpec/Core/Formatters/BaseTextFormatter.html b/source/documentation/3.0/rspec-core/RSpec/Core/Formatters/BaseTextFormatter.html
new file mode 100644
index 000000000..59e8d9444
--- /dev/null
+++ b/source/documentation/3.0/rspec-core/RSpec/Core/Formatters/BaseTextFormatter.html
@@ -0,0 +1,524 @@
+
+
+
+
+
+ Class: RSpec::Core::Formatters::BaseTextFormatter
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Base for all of RSpec's built-in formatters. See
+RSpec::Core::Formatters::BaseFormatter to learn more about all of the
+methods called by the reporter.
Formats seconds to have 5 digits of precision with trailing zeros removed
+if the number is less than 1 or with 2 digits of precision if the number is
+greater than zero.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
Formats seconds to have 5 digits of precision with trailing zeros removed
+if the number is less than 1 or with 2 digits of precision if the number is
+greater than zero.
+
+
The precision used is set in SUB_SECOND_PRECISION and
+DEFAULT_PRECISION.
+ This class is part of a private API.
+ You should avoid using this class if possible, as it may be removed or be changed in the future.
+
+
+
RSpec::Core::Formatters::Loader is an internal class for
+managing formatters used by a particular configuration. It is not expected
+to be used directly, but only through the configuration interface.
Provides before, after and around
+hooks as a means of supporting common setup and teardown. This module is
+extended onto ExampleGroup, making the methods available from any
+describe or context block and included in
+Configuration, making them available off of the configuration object to
+define global setup or teardown logic.
The :example and :context scopes are also
+available as :each and :all, respectively. Use
+whichever you prefer.
+
+
+
+
+
Declare a block of code to be run after each example (using
+:example) or once after all examples n the context (using
+:context). See #before for more information about ordering.
+
+
Exceptions
+
+
after hooks are guaranteed to run even when there are
+exceptions in before hooks or examples. When an exception is
+raised in an after block, the exception is captured for later reporting,
+and subsequent after blocks are run.
+
+
Order
+
+
after hooks are stored in three scopes, which are run in
+order: :example, :context, and
+:suite. They can also be declared in several different places:
+RSpec.configure, a parent group, the current group. They are
+run in the following order:
+
+
after(:example)# declared in the current group
+after(:example)# declared in a parent group
+after(:example)# declared in RSpec.configure
+after(:context)# declared in the current group
+after(:context)# declared in a parent group
+after(:context)# declared in RSpec.configure
+after(:suite)# declared in RSpec.configure
+
+
This is the reverse of the order in which before hooks are
+run. Similarly, if more than one after is declared within any
+one scope, they are run in reverse order of that in which they are
+declared.
+
+
+
+
+
+
+
Overloads:
+
+
+
+
+
+ - (void) after(scope, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ scope
+
+
+ (Symbol)
+
+
+
+ —
+
+
:example, :context, or :suite
+(defaults to :example)
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) after(scope, conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ scope
+
+
+ (Symbol)
+
+
+
+ —
+
+
:example, :context, or :suite
+(defaults to :example)
+
+
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+after(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) after(conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+after(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
the syntax of around is similar to that of before
+and after but the semantics are quite different.
+before and after hooks are run in the context of
+of the examples with which they are associated, whereas around
+hooks are actually responsible for running the examples. Consequently,
+around hooks do not have direct access to resources that are
+made available within the examples and their associated before
+and after hooks.
+
+
+
+
+ Note:
+
+
:example/:each is the only supported scope.
+
+
+
+
+
Declare a block of code, parts of which will be run before and parts after
+the example. It is your responsibility to run the example:
+
+
around(:example)do|ex|
+ # do some stuff before
+ex.run
+ # do some stuff after
+end
+
+
+
The yielded example aliases run with call, which
+lets you treat it like a Proc. This is especially handy when
+working with libaries that manage their own setup and teardown using a
+block or proc syntax, e.g.
:example (defaults to :example) present for
+syntax parity with before and after, but
+:example/:each is the only supported value.
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) around(scope, conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ scope
+
+
+ (Symbol)
+
+
+
+ —
+
+
:example (defaults to :example) present for
+syntax parity with before and after, but
+:example/:each is the only supported value.
+
+
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+around(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) around(conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+around(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
The :example and :context scopes are also
+available as :each and :all, respectively. Use
+whichever you prefer.
+
+
+
+
+
Declare a block of code to be run before each example (using
+:example) or once before any example (using
+:context). These are usually declared directly in the
+ExampleGroup to which they apply, but they can also be shared across
+multiple groups.
+
+
You can also use before(:suite) to run a block of code before
+any example groups are run. This should be declared in RSpec.configure
+
+
Instance variables declared in before(:example) or
+before(:context) are accessible within each example.
+
+
Order
+
+
before hooks are stored in three scopes, which are run in
+order: :suite, :context, and
+:example. They can also be declared in several different
+places: RSpec.configure, a parent group, the current group.
+They are run in the following order:
+
+
before(:suite)# declared in RSpec.configure
+before(:context)# declared in RSpec.configure
+before(:context)# declared in a parent group
+before(:context)# declared in the current group
+before(:example)# declared in RSpec.configure
+before(:example)# declared in a parent group
+before(:example)# declared in the current group
+
+
If more than one before is declared within any one scope, they
+are run in the order in which they are declared.
+
+
Conditions
+
+
When you add a conditions hash to before(:example) or
+before(:context), RSpec will only apply that hook to groups or
+examples that match the conditions. e.g.
+
+
RSpec.configuredo|config|
+ config.before(:example,:authorized=>true)do
+ log_in_as:authorized_user
+ end
+end
+
+describeSomething,:authorized=>truedo
+ # the before hook will run in before each example in this group
+end
+
+describeSomethingElsedo
+ it"does something",:authorized=>truedo
+ # the before hook will run before this example
+end
+
+ it"does something else"do
+ # the hook will not run before this example
+end
+end
+
+
+
Warning: before(:suite, :with => :conditions)
+
+
The conditions hash is used to match against specific examples. Since
+before(:suite) is not run in relation to any specific example
+or group, conditions passed along with :suite are effectively
+ignored.
+
+
Exceptions
+
+
When an exception is raised in a before block, RSpec skips any
+subsequent before blocks and the example, but runs all of the
+after(:example) and after(:context) hooks.
+
+
Warning: implicit before blocks
+
+
before hooks can also be declared in shared contexts which get
+included implicitly either by you or by extension libraries. Since RSpec
+runs these in the order in which they are declared within each scope, load
+order matters, and can lead to confusing results when one before block
+depends on state that is prepared in another before block that gets run
+later.
+
+
Warning: before(:context)
+
+
It is very tempting to use before(:context) to speed things
+up, but we recommend that you avoid this as there are a number of gotchas,
+as well as things that simply don't work.
+
+
context
+
+
before(:context) is run in an example that is generated to
+provide group context for the block.
+
+
instance variables
+
+
Instance variables declared in before(:context) are shared
+across all the examples in the group. This means that each example can
+change the state of a shared object, resulting in an ordering dependency
+that can make it difficult to reason about failures.
+
+
unsupported rspec constructs
+
+
RSpec has several constructs that reset state between each example
+automatically. These are not intended for use from within
+before(:context):
+
+
let declarations
+
+
subject declarations
+
+
Any mocking, stubbing or test double declaration
+
+
+
other frameworks
+
+
Mock object frameworks and database transaction managers (like
+ActiveRecord) are typically designed around the idea of setting up before
+an example, running that one example, and then tearing down. This means
+that mocks and stubs can (sometimes) be declared in
+before(:context), but get torn down before the first real
+example is ever run.
+
+
You can create database-backed model objects in a
+before(:context) in rspec-rails, but it will not be wrapped in
+a transaction for you, so you are on your own to clean up in an
+after(:context) block.
+describeParserdo
+ before(:context)do
+ File.open(file_to_parse,'w')do|f|
+ f.write<<-CONTENT
+ stuff in the file
+ CONTENT
+end
+ end
+
+ it"parses the file"do
+ Parser.parse(file_to_parse)
+ end
+
+ after(:context)do
+ File.delete(file_to_parse)
+ end
+end
+
+
+
+
Overloads:
+
+
+
+
+
+ - (void) before(scope, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ scope
+
+
+ (Symbol)
+
+
+
+ —
+
+
:example, :context, or :suite
+(defaults to :example)
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) before(scope, conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ scope
+
+
+ (Symbol)
+
+
+
+ —
+
+
:example, :context, or :suite
+(defaults to :example)
+
+
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+before(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) before(conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+before(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
This only works if you are using rspec-expectations.
+
+
+
+
+ Note:
+
+
If you are using RSpec's newer expect-based syntax you may want to use
+is_expected.to instead of should.
+
+
+
+
+
When should is called with no explicit receiver, the call is
+delegated to the object returned by subject. Combined with an
+implicit subject this supports very concise expressions.
# File 'lib/rspec/core/memoized_helpers.rb', line 99
+
+defshould_not(matcher=nil,message=nil)
+ RSpec::Expectations::NegativeExpectationHandler.handle_matcher(subject,matcher,message)
+end
+
+
+
+
+
+
+
+
+ - (void) subject
+
+
+
+
+
+
+
+
+
+ Note:
+
+
subject was contributed by Joe Ferris to support the one-liner
+syntax embraced by shoulda matchers:
+
+
describeWidgetdo
+ it{is_expected.tovalidate_presence_of(:name)}
+ # or
+it{shouldvalidate_presence_of(:name)}
+end
+
+
While the examples below demonstrate how to use subject
+explicitly in examples, we recommend that you define a method with an
+intention revealing name instead.
+
+
+
+
+ Note:
+
+
Because subject is designed to create state that is reset
+between each example, and before(:context) is designed to
+setup state that is shared across all examples in an example
+group, subject is not intended to be used in a
+before(:context) hook.
+
+
+
+
+
+
+
+
+
+
+
Examples:
+
+
+
+# explicit declaration of subject
+describePersondo
+ subject{Person.new(:birthdate=>19.years.ago)}
+ it"should be eligible to vote"do
+ subject.shouldbe_eligible_to_vote
+ # ^ ^ explicit reference to subject not recommended
+end
+end
+
+# implicit subject => { Person.new }
+describePersondo
+ it"should be eligible to vote"do
+ subject.shouldbe_eligible_to_vote
+ # ^ ^ explicit reference to subject not recommended
+end
+end
+
+# one-liner syntax - expectation is set on the subject
+describePersondo
+ it{is_expected.tobe_eligible_to_vote}
+ # or
+it{shouldbe_eligible_to_vote}
+end
This module is extended onto ExampleGroup, making the methods available
+to be called from within example group blocks. You can think of them as
+being analagous to class macros.
Declares a subject for an example group which can then be
+wrapped with expect using is_expected to make it
+the target of an expectation in a concise, one-line example.
Just like subject, except the block is invoked by an implicit
+before hook.
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (void) let(name, &block)
+
+
+
+
+
+
+
+
+
+ Note:
+
+
letcan enhance readability when used sparingly (1,2,
+or maybe 3 declarations) in any given example group, but that can quickly
+degrade with overuse. YMMV.
+
+
+
+
+ Note:
+
+
let uses an ||= conditional that has the
+potential to behave in surprising ways in examples that spawn separate
+threads, though we have yet to see this in practice. You've been
+warned.
+
+
+
+
+ Note:
+
+
Because let is designed to create state that is reset between
+each example, and before(:context) is designed to setup state
+that is shared across all examples in an example group,
+let is not intended to be used in a
+before(:context) hook.
+
+
+
+
+
Generates a method whose return value is memoized after the first call.
+Useful for reducing duplication between examples that assign values to the
+same local variable.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+describeThingdo
+ let(:thing){Thing.new}
+
+ it"does something"do
+ # first invocation, executes block, memoizes and returns result
+thing.do_something
+
+ # second invocation, returns the memoized value
+thing.shouldbe_something
+ end
+end
# File 'lib/rspec/core/memoized_helpers.rb', line 231
+
+deflet(name,&block)
+ # We have to pass the block directly to `define_method` to
+# allow it to use method constructs like `super` and `return`.
+raise"#let or #subject called without a block"ifblock.nil?
+ MemoizedHelpers.module_for(self).__send__(:define_method,name,&block)
+
+ # Apply the memoization. The method has been defined in an ancestor
+# module so we can use `super` here to get the value.
+ifblock.arity==1
+ define_method(name){__memoized.fetch(name){|k|__memoized[k]=super(RSpec.current_example,&nil)}}
+ else
+ define_method(name){__memoized.fetch(name){|k|__memoized[k]=super(&nil)}}
+ end
+end
+
+
+
+
+
+
+
+
+ - (void) let!(name, &block)
+
+
+
+
+
+
+
+
+
Just like let, except the block is invoked by an implicit
+before hook. This serves a dual purpose of setting up state
+and providing a memoized reference to that state.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+classThing
+ defself.count
+ @count||=0
+ end
+
+ defself.count=(val)
+ @count+=val
+ end
+
+ defself.reset_count
+ @count=0
+ end
+
+ definitialize
+ self.class.count+=1
+ end
+end
+
+describeThingdo
+ after(:example){Thing.reset_count}
+
+ context"using let"do
+ let(:thing){Thing.new}
+
+ it"is not invoked implicitly"do
+ Thing.count.shouldeq(0)
+ end
+
+ it"can be invoked explicitly"do
+ thing
+ Thing.count.shouldeq(1)
+ end
+ end
+
+ context"using let!"do
+ let!(:thing){Thing.new}
+
+ it"is invoked implicitly"do
+ Thing.count.shouldeq(1)
+ end
+
+ it"returns memoized version on first invocation"do
+ thing
+ Thing.count.shouldeq(1)
+ end
+ end
+end
Declares a subject for an example group which can then be
+wrapped with expect using is_expected to make it
+the target of an expectation in a concise, one-line example.
+
+
Given a name, defines a method with that name which returns
+the subject. This lets you declare the subject once and access
+it implicitly in one-liners and explicitly using an intention revealing
+name.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+describeCheckingAccount,"with $50"do
+ subject{CheckingAccount.new(Money.new(50,:USD))}
+ it{is_expected.tohave_a_balance_of(Money.new(50,:USD))}
+ it{is_expected.not_tobe_overdrawn}
+end
+
+describeCheckingAccount,"with a non-zero starting balance"do
+ subject(:account){CheckingAccount.new(Money.new(50,:USD))}
+ it{is_expected.not_tobe_overdrawn}
+ it"has a balance equal to the starting balance"do
+ account.balance.shouldeq(Money.new(50,:USD))
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String, Symbol)
+
+
+ (defaults to: nil)
+
+
+ —
+
+
used to define an accessor with an intention revealing name
+
+
+
+
+
+
+ block
+
+
+
+
+
+
+ —
+
+
defines the value to be returned by subject in examples
# File 'lib/rspec/core/memoized_helpers.rb', line 336
+
+defsubject(name=nil,&block)
+ ifname
+ let(name,&block)
+ alias_method:subject,name
+
+ self::NamedSubjectPreventSuper.__send__(:define_method,name)do
+ raiseNotImplementedError,"`super` in named subjects is not supported"
+ end
+ else
+ let(:subject,&block)
+ end
+end
Just like subject, except the block is invoked by an implicit
+before hook. This serves a dual purpose of setting up state
+and providing a memoized reference to that state.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+classThing
+ defself.count
+ @count||=0
+ end
+
+ defself.count=(val)
+ @count+=val
+ end
+
+ defself.reset_count
+ @count=0
+ end
+
+ definitialize
+ self.class.count+=1
+ end
+end
+
+describeThingdo
+ after(:example){Thing.reset_count}
+
+ context"using subject"do
+ subject{Thing.new}
+
+ it"is not invoked implicitly"do
+ Thing.count.shouldeq(0)
+ end
+
+ it"can be invoked explicitly"do
+ subject
+ Thing.count.shouldeq(1)
+ end
+ end
+
+ context"using subject!"do
+ subject!(:thing){Thing.new}
+
+ it"is invoked implicitly"do
+ Thing.count.shouldeq(1)
+ end
+
+ it"returns memoized version on first invocation"do
+ subject
+ Thing.count.shouldeq(1)
+ end
+ end
+end
Each ExampleGroup class and Example instance owns an instance of Metadata,
+which is Hash extended to support lazy evaluation of values associated with
+keys that may or may not be used by any example or group.
+
+
In addition to metadata that is used internally, this also stores
+user-supplied metadata, e.g.
:type => :ui is stored in the Metadata owned by the example
+group, and :slow => true is stored in the Metadata owned by
+the example. These can then be used to select which examples are run using
+the --tag option on the command line, or several methods on
+Configuration used to filter a run (e.g.
+filter_run_including, filter_run_excluding, etc).
Contains metadata filtering logic. This has been extracted from the
+metadata classes because it operates ON a metadata hash but does not manage
+any of the state in the hash. We're moving towards having metadata be a
+raw hash (not a custom subclass), so externalizing this filtering logic
+helps us move in that direction.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-core/RSpec/Core/Notifications.html b/source/documentation/3.0/rspec-core/RSpec/Core/Notifications.html
new file mode 100644
index 000000000..f47ffe8ed
--- /dev/null
+++ b/source/documentation/3.0/rspec-core/RSpec/Core/Notifications.html
@@ -0,0 +1,127 @@
+
+
+
+
+
+ Module: RSpec::Core::Notifications
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
The DeprecationNotification is issued by the reporter when a
+deprecated part of RSpec is encountered. It represents information about
+the deprecated call site.
The ExampleNotification represents notifications sent by the
+reporter which contain information about the current (or soon to be)
+example. It is used by formatters to access information about that example.
+
+
+
+
+
+
+
+
Examples:
+
+
+
defexample_started(notification)
+ puts"Hey I started #{notification.example.description}"
+end
The GroupNotification represents notifications sent by the
+reporter which contain information about the currently running (or soon to
+be) example group It is used by formatters to access information about that
+group.
+
+
+
+
+
+
+
+
Examples:
+
+
+
defexample_group_started(notification)
+ puts"Hey I started #{notification.group.description}"
+end
Returns the message generated for this failure line by line.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Array(String))
+
+
+
+ —
+
+
The example failure message
+
+
+
+
+
+
+
+
+
+
+
+
+307
+308
+309
+
+
+
# File 'lib/rspec/core/notifications.rb', line 307
+
+defmessage_lines
+ ["Expected pending '#{example.execution_result.pending_message}' to fail. No Error was raised."]
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-core/RSpec/Core/Notifications/ProfileNotification.html b/source/documentation/3.0/rspec-core/RSpec/Core/Notifications/ProfileNotification.html
new file mode 100644
index 000000000..013962764
--- /dev/null
+++ b/source/documentation/3.0/rspec-core/RSpec/Core/Notifications/ProfileNotification.html
@@ -0,0 +1,410 @@
+
+
+
+
+
+ Class: RSpec::Core::Notifications::ProfileNotification
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
The ProfileNotification holds information about the results of
+running a test suite when profiling is enabled. It is used by formatters to
+provide information at the end of the test run for profiling information.
The StartNotification represents a notification sent by the
+reporter when the suite is started. It contains the expected amount of
+examples to be executed, and the load time of RSpec.
The SummaryNotification holds information about the results of
+running a test suite. It is used by formatters to provide information at
+the end of the test run.
before(:example) hooks are eval'd when you use the
+pending method within an example. If you want to declare an
+example pending and bypass the before hooks as
+well, you can pass :pending => true to the it
+method:
Marks an example as pending. The rest of the example will still be
+executed, and if it passes the example will fail to indicate that the
+pending can be removed.
+
+
+
+
+
+
+
+
Examples:
+
+
+
describe"an example"do
+ # reported as "Pending: no reason given"
+it"is pending with no message"do
+ pending
+ raise"broken"
+ end
+
+ # reported as "Pending: something else getting finished"
+it"is pending with a custom message"do
+ pending("something else getting finished")
+ raise"broken"
+ end
+end
# File 'lib/rspec/core/pending.rb', line 68
+
+defpending(message=nil)
+ current_example=RSpec.current_example
+
+ ifblock_given?
+ raiseArgumentError,<<-EOS.gsub(/^\s+\|/,'')
+ |The semantics of `RSpec::Core::Pending#pending` have changed in
+ |RSpec 3. In RSpec 2.x, it caused the example to be skipped. In
+ |RSpec 3, the rest of the example is still run but is expected to
+ |fail, and will be marked as a failure (rather than as pending) if
+ |the example passes.
+ |
+ |Passing a block within an example is now deprecated. Marking the
+ |example as pending provides the same behavior in RSpec 3 which was
+ |provided only by the block in RSpec 2.x.
+ |
+ |Move the code in the block provided to `pending` into the rest of
+ |the example body.
+ |
+ |Called from #{CallerFilter.first_non_rspec_line}.
+ |
+ EOS
+elsifcurrent_example
+ Pending.mark_pending!current_example,message
+ else
+ raise"`pending` may not be used outside of examples, such as in "+
+ "before(:context). Maybe you want `skip`?"
+ end
+end
describe"an example"do
+ # reported as "Pending: no reason given"
+it"is skipped with no message"do
+ skip
+ end
+
+ # reported as "Pending: something else getting finished"
+it"is skipped with a custom message"do
+ skip"something else getting finished"
+ end
+end
Initializes the report run and yields itself for further reporting. The
+block is required, so that the reporter can manage cleaning up after the
+run.
This is not generally needed. The rspec command takes care of
+running examples for you without involving an at_exit hook.
+This is only needed if you are running specs using the ruby
+command, and even then, the normal way to invoke this is by requiring
+rspec/autorun.
+
+
+
+
+
Register an at_exit hook that runs the suite when the process
+exits.
# File 'lib/rspec/core/runner.rb', line 13
+
+defself.autorun
+ ifautorun_disabled?
+ RSpec.deprecate("Requiring `rspec/autorun` when running RSpec via the `rspec` command")
+ return
+ elsifinstalled_at_exit?||running_in_drb?
+ return
+ end
+
+ at_exitdo
+ # Don't bother running any specs and just let the program terminate
+# if we got here due to an unrescued exception (anything other than
+# SystemExit, which is raised when somebody calls Kernel#exit).
+nextunless$!.nil?||$!.kind_of?(SystemExit)
+
+ # We got here because either the end of the program was reached or
+# somebody called Kernel#exit. Run the specs and then override any
+# existing exit status with RSpec's exit status if any specs failed.
+invoke
+ end
+ @installed_at_exit=true
+end
+
+
+
+
+
+
+
+
+ + (void) invoke
+
+
+
+
+
+
+
+
+
Runs the suite of specs and exits the process with an appropriate exit
+code.
This is used internally by RSpec to run a suite, but is available for use
+by any other automation tool.
+
+
If you want to run this multiple times in the same process, and you want
+files like spec_helper.rb to be reloaded, be sure to load
+load instead of require.
# File 'lib/rspec/core/runner.rb', line 57
+
+defself.run(args,err=$stderr,out=$stdout)
+ trap_interrupt
+ options=ConfigurationOptions.new(args)
+
+ ifoptions.options[:drb]
+ require'rspec/core/drb'
+ begin
+ DRbRunner.new(options).run(err,out)
+ rescueDRb::DRbConnError
+ err.puts"No DRb server is running. Running in local process instead ..."
+ new(options).run(err,out)
+ end
+ else
+ new(options).run(err,out)
+ end
+end
Shared example groups let you define common context and/or common examples
+that you wish to use in multiple example groups.
+
+
When defined, the shared group block is stored for later evaluation. It can
+later be included in an example group either explicitly (using
+include_examples, include_context or
+it_behaves_like) or implicitly (via matching metadata).
+
+
Named shared example groups are scoped based on where they are defined.
+Shared groups defined in an example group are available for inclusion in
+that example group or any child example groups, but not in any parent or
+sibling example groups. Shared example groups defined at the top level can
+be included from any example group.
Stores the block for later use. The block will be evaluated in the context
+of an example group via include_examples,
+include_context, or it_behaves_like.
+
+
+
+
+
+
+
+
Examples:
+
+
+
shared_examples"auditable"do
+ it"stores an audit record on save!"do
+ expect{auditable.save!}.tochange(Audit,:count).by(1)
+ end
+end
+
+describeAccountdo
+ it_behaves_like"auditable"do
+ let(:auditable){Account.new}
+ end
+end
# File 'lib/rspec/core/shared_example_group.rb', line 50
+
+defshared_examples(name,*args,&block)
+ top_level=self==ExampleGroup
+ iftop_level&&RSpec.thread_local_metadata[:in_example_group]
+ raise"Creating isolated shared examples from within a context is "+
+ "not allowed. Remove `RSpec.` prefix or move this to a "+
+ "top-level scope."
+ end
+
+ RSpec.world.shared_example_group_registry.add(self,name,*args,&block)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-core/RSpec/Core/SharedExampleGroup/TopLevelDSL.html b/source/documentation/3.0/rspec-core/RSpec/Core/SharedExampleGroup/TopLevelDSL.html
new file mode 100644
index 000000000..d63d2a6ea
--- /dev/null
+++ b/source/documentation/3.0/rspec-core/RSpec/Core/SharedExampleGroup/TopLevelDSL.html
@@ -0,0 +1,295 @@
+
+
+
+
+
+ Module: RSpec::Core::SharedExampleGroup::TopLevelDSL
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Fix processing order of CLI options so that if
+config.files_to_run is accessed from a file loaded by
+--require, --pattern is still applied. (Myron
+Marston, #1652)
+
+
Fix config.pattern= so that it still takes affect even if
+config.files_to_run has already been accessed. (Myron Marston,
+#1652)
Fix regression in CLI option handling that prevented --tag
+slow passed at the command line from overriding --tag
+~slow in .rspec. (Colin Jones, #1602)
+
+
Fix metadata :example_group deprecation warning so that it
+gets issued at the call site of the configuration that specified it as a
+filter rather than later when an example group is defined. (Myron Marston,
+#1562)
+
+
Make the line that is printed when a shared example group fails indicating
+where the concrete example group is white, separating it from the stack
+trace that is produced for the failure. (Sam Phippen, Jon Rowe, #1606)
Fix BaseTextFormatter so that it does not re-close a closed
+output stream. (Myron Marston)
+
+
Fix regression in metadata that caused the metadata hash of a top-level
+example group to have a :parent_example_group key even though
+it has no parent example group. (Myron Marston)
+
+
+
Enhancements:
+
+
Alter the default spec_helper.rb to no longer recommend
+config.full_backtrace = true see #1536 for discussion. (Jon
+Rowe)
Change described_class so that in a nested group like
+describe MyClass, it returns MyClass rather
+than the outer group's described class. (Myron Marston)
+
+
Refactor filter manager so that it no longer subclasses Hash and has a
+tighter, more domain-specific interface. (Sergey Pchelincev)
+
+
Remove legacy colours definitions from BaseTextFormatter. (Jon
+Rowe)
+
+
Remove console color definitions from BaseTextFormatter. (Jon
+Rowe)
+
+
Restructure example group metadata so that the computed keys are exposed
+directly off of the metadata hash rather than being on a nested
+:example_group subhash. In addition, the parent example group
+metadata is now available as [:parent_example_group] rather
+than [:example_group][:example_group]. Deprecated access via
+the old key structure is still provided. (Myron Marston)
+
+
Remove :describes metadata key. It duplicates
+:described_class for no good reason. Deprecated access via
+:describes is still provided. (Myron Marston)
+
+
Rename :example_group_block metadata key to
+:block. (Myron Marston)
Move BaseTextFormatter#colorize_summary to
+SummaryNotification#colorize_with (Jon Rowe).
+
+
describe some_hash treated some_hash as metadata
+in RSpec 2.x but will treat it as the described object in RSpec 3.0.
+Metadata must always come after the description args. (Myron Marston)
+
+
Remove deprecated display_name alias of
+ExampleGroup.description. (Myron Marston)
+
+
Remove deprecated describes alias of
+ExampleGroup.described_class. (Myron Marston)
+
+
Remove deprecated
+RSpec::Core::ExampleGroup.alias_it_behaves_like_to. Use
+RSpec::Core::Configuration#alias_it_behaves_like_to instead.
+(Myron Marston)
Removed focused example alias and change example/group aliases
+fit, focus, fcontext and
+fdescribe to no longer include :focused =>
+true metadata. They only contain :focus => true
+metadata now. This means that you will need to filter them with
+filter_run :focus, not filter_run :focused.
+(Myron Marston)
+
+
Remove --line-number filtering. It's semantically dubious
+since it's a global filter (potentially applied to multiple files) but
+there's no meaningful connection between the same line number in
+multiple files. Instead use the rspec path/to/spec.rb:23:46
+form, which is terser and makes more sense as it is scoped to a file.
+(Myron Marston)
+
+
Remove --default_path as an alias for
+--default-path. (Jon Rowe)
+
+
Remove deprecated share_examples_for. There's still
+shared_examples and shared_examples_for. (Myron
+Marston)
+
+
Rename RSpec::Core::Configuration#warnings to
+RSpec::Core::Configuration#warnings? since it's a boolean
+flag. (Myron Marston)
+
+
RSpec's global state is no longer reset after a spec run. This gives
+more flexibility to alternate runners to decide when and if they want the
+state reset. Alternate runners are now responsible for calling this (or
+doing a similar reset) if they are going to run the spec suite multiple
+times in the same process. (Sam Phippen)
+
+
Merge RSpec::Core::CommandLine (never formally declared
+public) into RSpec::Core::Runner. (Myron Marston)
+
+
Remove color_enabled as an alias of color. (Jon
+Rowe)
+
+
Remove backtrace_cleaner as an alias of
+backtrace_formatter. (Jon Rowe)
+
+
Remove filename_pattern as an alias of pattern.
+(Jon Rowe)
+
+
Extract support for legacy formatters to
+rspec-legacy_formatters. (Jon Rowe)
+
+
RSpec::Configuration#formatters now returns a dup to prevent
+mutation. (Jon Rowe)
+
+
Replace stdlib as an available expectation framework with
+test_unit and minitest. (Aaron Kromer)
+
+
Remove backtrace formatting helpers from BaseTextFormatter.
+(Jon Rowe)
+
+
Extract profiler support to ProfileFormatter and
+ProfileNotification. Formatters should implement
+dump_profile if they wish to respond to
+--profile. (Jon Rowe)
+
+
Extract remaining formatter state to reporter and notifications. Introduce
+ExamplesNotification to share information about examples that
+was previously held in BaseFormatter. (Jon Rowe)
+
+
+
Enhancements:
+
+
Add config.default_formatter attribute, which can be used to
+set a formatter which will only be used if no other formatter is set
+(e.g. via --formatter). (Myron Marston)
+
+
Support legacy colour definitions in LegacyFormatterAdaptor.
+(Jon Rowe)
+
+
Migrate execution_result (exposed by metadata) from a hash to
+a first-class object with appropriate attributes. status is
+now stored and returned as a symbol rather than a string. It retains
+deprecated hash behavior for backwards compatibility. (Myron Marston)
+
+
Provide console code helper for formatters. (Jon Rowe)
+
+
Use raw ruby hashes for the metadata hashes rather than a subclass of a
+hash. Computed metadata entries are now computed in advance rather than
+being done lazily on first access. (Myron Marston)
+
+
Add :block metadata entry to the example metadata, bringing
+parity with :block in the example group metadata. (Myron
+Marston)
+
+
Add fspecify and fexample as aliases of
+specify and example with :focus =>
+true metadata for parity with fit. (Myron Marston)
+
+
Add legacy support for colorize_summary. (Jon Rowe)
+
+
Restructure runner so it can be more easily customized in a subclass for
+an alternate runner. (Ben Hoskings)
+
+
Document RSpec::Core::ConfigurationOptions as an officially
+supported public API. (Myron Marston)
+
+
Add --deprecation-out CLI option which directs deprecation
+warnings to the named file. (Myron Marston)
+
+
Minitest 5 compatability for expect_with :stdlib (now
+available as expect_with :minitest). (Xavier Shay)
+
+
Reporter now notifies formatters of the load time of RSpec and your specs
+via StartNotification and SummaryNotification.
+(Jon Rowe)
+
+
Add disable_monkey_patching! config option that disables all
+monkey patching from whatever pieces of RSpec you use. (Alexey Fedorov)
+
+
Add Pathname support for setting all output streams. (Aaron
+Kromer)
+
+
Add config.define_derived_metadata, which can be used to apply
+additional metadata to all groups or examples that match a given filter.
+(Myron Marston)
+
+
Provide formatted and colorized backtraces via
+FailedExampleNotification and send
+PendingExampleFixedNotifications when the error is due to a
+passing spec you expect to fail. (Jon Rowe)
+
+
Add dump_profile to formatter API to allow formatters to
+implement support for --profile. (Jon Rowe)
+
+
Allow colourising text via ConsoleCodes with RSpec
+'states' (e.g. :success, :failure)
+rather than direct colour codes. (Jon Rowe)
+
+
Expose fully_formatted methods off the formatter notification
+objects that make it easy for a custom formatter to produce formatted
+output like rspec-core's. (Myron Marston)
+
+
+
Bug Fixes:
+
+
Fix spec_helper.rb file generated by rspec --init
+so that the recommended settings correctly use the documentation formatter
+when running one file. (Myron Marston)
+
+
Fix ordering problem where descriptions were generated after tearing down
+mocks, which resulted in unexpected exceptions. (Bradley Schaefer, Aaron
+Kromer, Andrey Savchenko)
+
+
Allow a symbol to be used as an implicit subject (e.g. describe
+:foo). (Myron Marston)
+
+
Prevent creating an isolated context (i.e. using
+RSpec.describe) when already inside a context. There is no
+reason to do this, and it could potentially cause unexpected bugs. (Xavier
+Shay)
+
+
Fix shared example group scoping so that when two shared example groups
+share the same name at different levels of nested contexts, the one in the
+nearest context is used. (Myron Marston)
+
+
Fix --warnings option so that it enables warnings immediately
+so that it applies to files loaded by --require. (Myron
+Marston)
+
+
Issue a warning when you set config.deprecation_stream too
+late for it to take effect because the reporter has already been setup.
+(Myron Marston)
+
+
Add the full RSpec::Core::Example interface to the argument
+yielded to around hooks. (Myron Marston)
+
+
Line number always takes precendence when running specs with filters.
+(Xavier Shay)
+
+
Ensure :if and :unless metadata filters are treated as a special case and
+are always in-effect. (Bradley Schaefer)
+
+
Ensure the currently running installation of RSpec is used when the rake
+task shells out to rspec, even if a newer version is also
+installed. (Postmodern)
+
+
Using a legacy formatter as default no longer causes an infinite loop.
+(Xavier Shay)
Make mock_with option more strict. Strings are no longer
+supported (e.g. mock_with "mocha") – use a symbol
+instead. Also, unrecognized values will now result in an error rather than
+falling back to the null mocking adapter. If you want to use the null
+mocking adapter, use mock_with :nothing (as has been
+documented for a long time). (Myron Marston)
+
+
Remove support for overriding RSpec's built-in :if and
+:unless filters. (Ashish Dixit)
+
+
Custom formatters are now required to call
+RSpec::Core::Formatters.register(formatter_class,
+*notifications) where notifications is the list of
+events the formatter wishes to be notified about. Notifications are
+handled by methods matching the names on formatters. This allows us to add
+or remove notifications without breaking existing formatters. (Jon Rowe)
+
+
Change arguments passed to formatters. Rather than passing multiple
+arguments (which limits are ability to add additional arguments as doing
+so would break existing formatters), we now pass a notification value
+object that exposes the same data via attributes. This will allow us to
+add new bits of data to a notification event without breaking existing
+formatters. (Jon Rowe)
+
+
Remove support for deprecated :alias option for
+RSpec.configuration.add_setting. (Myron Marston)
+
+
Remove support for deprecated RSpec.configuration.requires =
+[...]. (Myron Marston)
+
+
Remove support for deprecated --formatter CLI option. (Myron
+Marston)
+
+
Remove support for deprecated --configure CLI option. (Myron
+Marston)
+
+
Remove support for deprecated
+RSpec::Core::RakeTask#spec_opts=. (Myron Marston)
+
+
An example group level pending block or :pending
+metadata now executes the example and cause a failure if it passes,
+otherwise it will be pending if it fails. The old “never run” behaviour is
+still used for xexample, xit, and
+xspecify, or via a new skip method or
+:skip metadata option. (Xavier Shay)
+
+
After calling pending inside an example, the remainder of the
+example will now be run. If it passes a failure is raised, otherwise the
+example is marked pending. The old “never run” behaviour is provided a by
+a new skip method. (Xavier Shay)
+
+
Pending blocks inside an example have been removed as a feature with no
+direct replacement. Use skip or pending without a
+block. (Xavier Shay)
+
+
Pending statement is no longer allowed in before(:all) hooks.
+Use skip instead. (Xavier Shay)
Remove support for specifying the documentation formatter using
+'s', 'n', 'spec' or 'nested'. (Jon Rowe)
+
+
+
Enhancements:
+
+
Add example run time to JSON formatter output. (Karthik Kastury)
+
+
Add more suggested settings to the files generated by rspec
+--init. (Myron Marston)
+
+
Add config.alias_example_group_to, which can be used to define
+a new method that defines an example group with the provided metadata.
+(Michi Huber)
+
+
Add xdescribe and xcontext as shortcuts to skip
+an example group. (Myron Marston)
+
+
Add fdescribe and fcontext as shortcuts to focus
+an example group. (Myron Marston)
+
+
Don't autorun specs via #at_exit by default. require
+'rspec/autorun' is only needed when running specs via
+ruby, as it always has been. Running specs via
+rake or rspec are both unaffected. (Ben Hoskings)
+
+
Add expose_dsl_globally config option, defaulting to true.
+When disabled it will remove the monkey patches rspec-core adds to
+main and Module (e.g. describe,
+shared_examples_for, etc). (Jon Rowe)
+
+
Expose RSpec DSL entry point methods (describe,
+shared_examples_for, etc) on the RSpec constant.
+Intended for use when expose_dsl_globally is set to
+false. (Jon Rowe)
+
+
For consistency, expose all example group aliases (including
+context) on the RSpec constant. If
+expose_dsl_globally is set to true, also expose
+them on main and Module. Historically, only
+describe was exposed. (Jon Rowe, Michi Huber)
+
+
Add hook scope :example as an alias for :each,
+and :context as an alias for :all. (John
+Feminella)
+
+
+
Bug Fixes:
+
+
Fix failure (undefined method path) in end-of-run summary
+when raise_errors_for_deprecations! is configured. (Myron
+Marston)
+
+
Issue error when attempting to use -i or --I on
+command line, too close to -I to be considered short hand for
+--init. (Jon Rowe)
+
+
Prevent adding formatters to an output target if the same formatter has
+already been added to that output. (Alex Peattie)
+
+
Allow a matcher-generated example description to be used when the example
+is pending. (Myron Marston)
+
+
Ensure the configured failure_exit_code is used by the rake
+task when there is a failure. (Jon Rowe)
+
+
Restore behaviour whereby system exclusion filters take priority over
+working directory (was broken in beta1). (Jon Rowe)
+
+
Prevent RSpec mangling file names that have substrings containing
+line_number or default_path. (Matijs van
+Zuijlen)
Remove RSpec::Core::ExampleGroup#example and
+RSpec::Core::ExampleGroup#running_example methods. If you need
+access to the example (e.g. to get its metadata), use a block arg instead.
+(David Chelimsky)
+
+
Remove TextMateFormatter, it has been moved to
+rspec-tmbundle. (Aaron Kromer)
+
+
Remove RCov integration. (Jon Rowe)
+
+
Remove deprecated support for RSpec 1 constructs (Myron Marston):
+
+
The Spec and Rspec constants (rather than
+RSpec).
+
+
Spec::Runner.configure rather than
+RSpec.configure.
+
+
Rake::SpecTask rather than RSpec::Core::RakeTask.
+
+
Remove deprecated support for share_as. (Myron Marston)
+
+
Remove --debug option (and corresponding option on
+RSpec::Core::Configuration). Instead, use -r<debugger
+gem name> to load whichever debugger gem you wish to use (e.g.
+ruby-debug, debugger, or pry).
+(Myron Marston)
+
+
Extract Autotest support to a seperate gem. (Jon Rowe)
+
+
Raise an error when a let or subject declaration
+is accessed in a before(:all) or after(:all)
+hook. (Myron Marston)
+
+
Extract its support to a separate gem. (Peter Alfvin)
+
+
Disallow use of a shared example group from sibling contexts, making them
+fully isolated. 2.14 and 2.99 allowed this but printed a deprecation
+warning. (Jon Rowe)
+
+
Remove RSpec::Core::Configuration#output and
+RSpec::Core::Configuration#out aliases of
+RSpec::Core::Configuration#output_stream. (Myron Marston)
+
+
Remove legacy ordering APIs deprecated in 2.99.0.beta1. (Myron Marston)
+
+
+
Enhancements:
+
+
Replace unmaintained syntax gem with coderay gem. (Xavier Shay)
+
+
Times in profile output are now bold instead of failure_color.
+(Matthew Boedicker)
+
+
Add --no-fail-fast command line option. (Gonzalo
+Rodríguez-Baltanás Díaz)
+
+
Runner now considers the local system ip address when running under Drb.
+(Adrian CB)
+
+
JsonFormatter now includes --profile information. (Alex /
+@MasterLambaster)
+
+
Always treat symbols passed as metadata args as hash keys with true
+values. RSpec 2 supported this with the
+treat_symbols_as_metadata_keys_with_true_values but now this
+behavior is always enabled. (Myron Marston)
+
+
Add --dry-run option, which prints the formatter output of
+your suite without running any examples or hooks. (Thomas Stratmann, Myron
+Marston)
+
+
Document the configuration options and default values in the
+spec_helper.rb file that is generated by RSpec. (Parker
+Selbert)
+
+
Give generated example group classes a friendly name derived from the
+docstring, rather than something like “Nested_2”. (Myron Marston)
+
+
Avoid affecting randomization of user code when shuffling examples so that
+users can count on their own seeds working. (Travis Herrick)
+
+
Ordering is no longer a single global property of the test suite. Each
+group can pick an ordering using :order metadata. (Andy
+Lindeman, Sam Phippen, Myron Marston)
+
+
Allow named custom ordering strategies to be registered, which can then be
+used on individual example groups. (Andy Lindeman, Sam Phippen, Myron
+Marston)
+
+
+
Deprecations:
+
+
treat_symbols_as_metadata_keys_with_true_values is deprecated
+and no longer has an affect now that the behavior it enabled is always
+enabled. (Myron Marston)
Add missing deprecation warning for when RSpec::Core::Runner
+is used multiple times in the same process. In 2.x RSpec's global
+state was automatically cleared between runs but in 3.0 you need to call
+RSpec.reset manually in these situations. (Sam Phippen,
+#1587)
+
+
Prevent deprecation being accidentally issues when doubles used with
+be_ matchers due to automatically generated descriptions.
+(Jon Rowe, #1573)
+
+
Load rspec/core when loading rspec/core/rake_task
+to ensure we can issue deprecations correctly. (Jon Rowe, #1612)
Fix BaseTextFormatter so that it does not re-close a closed
+output stream. (Myron Marston)
+
+
Use RSpec::Configuration#backtrace_exclusion_patterns rather
+than the deprecated
+RSpec::Configuration#backtrace_clean_patterns when mocking
+with rr. (David Dollar)
Add --deprecation-out CLI option which directs deprecation
+warnings to the named file. (Myron Marston)
+
+
Backport support for skip in metadata to skip execution of an
+example. (Xavier Shay, #1472)
+
+
Add Pathname support for setting all output streams. (Aaron
+Kromer)
+
+
Add test_unit and minitest expectation
+frameworks. (Aaron Kromer)
+
+
+
Deprecations:
+
+
Deprecate RSpec::Core::Pending::PendingDeclaredInExample, use
+SkipDeclaredInExample instead. (Xavier Shay)
+
+
Issue a deprecation when described_class is accessed from
+within a nested describe <SomeClass> example group,
+since described_class will return the innermost described
+class in RSpec 3 rather than the outermost described class, as it behaved
+in RSpec 2. (Myron Marston)
+
+
Deprecate RSpec::Core::FilterManager::DEFAULT_EXCLUSIONS,
+RSpec::Core::FilterManager::STANDALONE_FILTERS and use of
+#empty_without_conditional_filters? on those filters. (Sergey
+Pchelincev)
+
+
Deprecate RSpec::Core::Example#options in favor of
+RSpec::Core::Example#metadata. (Myron Marston)
+
+
Issue warning when passing a symbol or hash to describe or
+context as the first argument. In RSpec 2.x this would be
+treated as metadata but in RSpec 3 it'll be treated as the described
+object. To continue having it treated as metadata, pass a description
+before the symbol or hash. (Myron Marston)
+
+
Deprecate RSpec::Core::BaseTextFormatter::VT100_COLORS and
+RSpec::Core::BaseTextFormatter::VT100_COLOR_CODES in favour
+of RSpec::Core::BaseTextFormatter::ConsoleCodes::VT100_CODES
+and
+RSpec::Core::BaseTextFormatter::ConsoleCodes::VT100_CODE_VALUES.
+(Jon Rowe)
+
+
Deprecate RSpec::Core::ExampleGroup.display_name in favor of
+RSpec::Core::ExampleGroup.description. (Myron Marston)
+
+
Deprecate RSpec::Core::ExampleGroup.describes in favor of
+RSpec::Core::ExampleGroup.described_class. (Myron Marston)
+
+
Deprecate RSpec::Core::ExampleGroup.alias_example_to in favor
+of RSpec::Core::Configuration#alias_example_to. (Myron
+Marston)
+
+
Deprecate RSpec::Core::ExampleGroup.alias_it_behaves_like_to
+in favor of
+RSpec::Core::Configuration#alias_it_behaves_like_to. (Myron
+Marston)
+
+
Deprecate RSpec::Core::ExampleGroup.focused in favor of
+RSpec::Core::ExampleGroup.focus. (Myron Marston)
+
+
Add deprecation warning for config.filter_run :focused since
+example aliases fit and focus will no longer
+include :focused metadata but will continue to include
+:focus. (Myron Marston)
+
+
Deprecate filtering by :line_number (e.g.
+--line-number from the CLI). Use location filtering instead.
+(Myron Marston)
+
+
Deprecate --default_path as an alternative to
+--default-path. (Jon Rowe)
+
+
Deprecate RSpec::Core::Configuration#warnings in favor of
+RSpec::Core::Configuration#warnings?. (Myron Marston)
+
+
Deprecate share_examples_for in favor of
+shared_examples_for or just shared_examples.
+(Myron Marston)
+
+
Deprecate RSpec::Core::CommandLine in favor of
+RSpec::Core::Runner. (Myron Marston)
+
+
Deprecate #color_enabled, #color_enabled= and
+#color? in favour of #color,
+#color= and #color_enabled? output. (Jon Rowe)
+
+
Deprecate #filename_pattern in favour of
+#pattern. (Jon Rowe)
+
+
Deprecate #backtrace_cleaner in favour of
+#backtrace_formatter. (Jon Rowe)
Add is_expected for one-liners that read well with the
+expect-based syntax. is_expected is simply
+defined as expect(subject) and can be used in an expression
+like: it { is_expected.to read_well }. (Myron Marston)
+
+
Backport skip from RSpec 3, which acts like
+pending did in RSpec 2 when not given a block, since the
+behavior of pending is changing in RSpec 3. (Xavier Shay)
+
+
+
Deprecations:
+
+
Deprecate inexact mock_with config options. RSpec 3 will only
+support the exact symbols :rspec, :mocha,
+:flexmock, :rr or :nothing (or any
+module that implements the adapter interface). RSpec 2 did fuzzy matching
+but this will not be supported going forward. (Myron Marston)
+
+
Deprecate show_failures_in_pending_blocks config option. To
+achieve the same behavior as the option enabled, you can use a custom
+formatter instead. (Xavier Shay)
+
+
Add a deprecation warning for the fact that the behavior of
+pending is changing in RSpec 3 – rather than skipping the
+example (as it did in 2.x when no block was provided), it will run the
+example and mark it as failed if no exception is raised. Use
+skip instead to preserve the old behavior. (Xavier Shay)
+
+
Deprecate 's', 'n', 'spec' and 'nested' as
+aliases for documentation formatter. (Jon Rowe)
+
+
Deprecate RSpec::Core::Reporter#abort in favor of
+RSpec::Core::Reporter#finish. (Jon Rowe)
+
+
+
Bug Fixes:
+
+
Fix failure (undefined method path) in end-of-run summary
+when raise_errors_for_deprecations! is configured. (Myron
+Marston)
+
+
Fix issue were overridding spec ordering from the command line wasn't
+fully recognised interally. (Jon Rowe)
Block-based DSL methods that run in the context of an example
+(it, before(:each), after(:each),
+let and subject) now yield the example as a
+block argument. (David Chelimsky)
+
+
Warn when the name of more than one example group is submitted to
+include_examples and it's aliases. (David Chelimsky)
+
+
Add expose_current_running_example_as config option for use
+during the upgrade process when external gems use the deprecated
+RSpec::Core::ExampleGroup#example and
+RSpec::Core::ExampleGroup#running_example methods. (Myron
+Marston)
+
+
Limit spamminess of deprecation messages. (Bradley Schaefer, Loren Segal)
+
+
Add config.raise_errors_for_deprecations! option, which turns
+deprecations warnings into errors to surface the full backtrace of the
+call site. (Myron Marston)
+
+
+
Deprecations
+
+
Deprecate RSpec::Core::ExampleGroup#example and
+RSpec::Core::ExampleGroup#running_example methods. If you need
+access to the example (e.g. to get its metadata), use a block argument
+instead. (David Chelimsky)
+
+
Deprecate use of autotest/rspec2 in favour of
+rspec-autotest. (Jon Rowe)
+
+
Deprecate RSpec's built-in debugger support. Use a CLI option like
+-rruby-debug (for the ruby-debug gem) or
+-rdebugger (for the debugger gem) instead. (Myron Marston)
+
+
Deprecate
+RSpec.configuration.treat_symbols_as_metadata_keys_with_true_values =
+false. RSpec 3 will not support having this option set to
+false. (Myron Marston)
+
+
Deprecate accessing a let or subject declaration
+in a after(:all) hook. (Myron Marston, Jon Rowe)
+
+
Deprecate built-in its usage in favor of
+rspec-its gem due to planned removal in RSpec 3. (Peter
+Alfvin)
+
+
Deprecate RSpec::Core::PendingExampleFixedError in favor of
+RSpec::Core::Pending::PendingExampleFixedError. (Myron
+Marston)
+
+
Deprecate RSpec::Core::Configuration#out and
+RSpec::Core::Configuration#output in favor of
+RSpec::Core::Configuration#output_stream. (Myron Marston)
+
+
Deprecate legacy ordering APIs.
+
+
You should use register_ordering(:global) instead of these:
These are deprecated with no replacement because in RSpec 3 ordering is a
+property of individual example groups rather than just a global property of
+the entire test suite:
+
+
RSpec::Core::Configuration#order
+
+
RSpec::Core::Configuration#randomize?
+
+
+
--order default is deprecated in favor of --order
+defined (Myron Marston)
Fix regression in 2.14.6 that broke the Fivemat formatter. It depended
+upon either
+example.execution_result[:exception].pending_fixed? (which
+was removed in 2.14.6 to fix an issue with frozen error objects) or
+RSpec::Core::PendingExampleFixedError (which was renamed to
+RSpec::Core::Pending::PendingExampleFixedError in 2.8. This
+fix makes a constant alias for the old error name. (Myron Marston)
Fix a NoMethodError that was being raised when there were no
+shared examples or contexts declared and RSpec.world.reset is
+invoked. (thepoho, Jon Rowe, Myron Marston)
+
+
Fix a deprecation warning that was being incorrectly displayed when
+shared_examples are declared at top level in a
+module scope. (Jon Rowe)
+
+
Fix after(:all) hooks so consecutive (same context) scopes will run even if
+one raises an error. (Jon Rowe, Trejkaz)
+
+
JsonFormatter no longer dies if dump_profile isn't defined
+(Alex / @MasterLambaster, Jon Rowe)
Fix regression in 2.14: ensure configured requires (via -r
+option) are loaded before spec files are loaded. This allows the spec
+files to programatically change the file pattern (Jon Rowe).
+
+
Autoload RSpec::Mocks and RSpec::Expectations
+when referenced if they are not already loaded
+(RSpec::Matches has been autoloaded for a while). In the
+rspec gem, we changed it recently to stop loading
+rspec/mocks and rspec/expectations by default, as
+some users reported problems where they were intending to use mocha, not
+rspec-mocks, but rspec-mocks was loaded and causing a conflict. rspec-core
+loads mocks and expectations at the appropriate time, so it seemed like a
+safe change – but caused a problem for some authors of libraries that
+integrate with RSpec. This fixes that problem. (Myron Marston)
+
+
Gracefully handle a command like rspec --profile
+path/to/spec.rb: the path/to/spec.rb arg was being
+wrongly treated as the profile integer arg, which got cast
+0 using to_i, causing no profiled examples to be
+printed. (Jon Rowe)
Fix deprecation notices issued from RSpec::Core::RakeTask so
+that they work properly when all of rspec-core is not loaded. (This was a
+regression in 2.14) (Jon Rowe)
Fix regression caused by 2.14.1 release: formatters that report that they
+respond_to? a notification, but had no corresponding method
+would raise an error when registered. The new fix is to just implement
+start on the deprecation formatter to fix the original
+JRuby/ruby-debug issue. (Jon Rowe)
Address deprecation formatter failure when using ruby-debug on
+JRuby: fix RSpec::Core::Reporter to not send a notification
+when the formatter's implementation of the notification method comes
+from Kernel (Alex Portnov, Jon Rowe).
Apply focus to examples defined with fit (equivalent of
+it "description", focus: true) (Michael de Silva)
+
+
+
Bug fix
+
+
Ensure methods defined by let take precedence over others
+when there is a name collision (e.g. from an included module). (Jon Rowe,
+Andy Lindeman and Myron Marston)
Improved Windows detection inside Git Bash, for better --color
+handling.
+
+
Add profiling of the slowest example groups to --profile
+option. The output is sorted by the slowest average example groups.
+
+
Don't show slow examples if there's a failure and both
+--fail-fast and --profile options are used
+(Paweł Gościcki).
+
+
Rather than always adding spec to the load path, add the
+configured --default-path to the load path (which defaults to
+spec). This better supports folks who choose to put their
+specs in a different directory (John Feminella).
+
+
Add some logic to test time duration precision. Make it a function of
+time, dropping precision as the time increases. (Aaron Kromer)
+
+
Add new backtrace_inclusion_patterns config option. Backtrace
+lines that match one of these patterns will always be included in
+the backtrace, even if they match an exclusion pattern, too (Sam Phippen).
+
+
Support ERB trim mode using the - when parsing
+.rspec as ERB (Gabor Garami).
+
+
Give a better error message when let and subject are called without a
+block. (Sam Phippen).
+
+
List the precedence of .rspec-local in the configuration
+documentation (Sam Phippen)
+
+
Support {a,b} shell expansion syntax in --pattern
+option (Konstantin Haase).
+
+
Add cucumber documentation for –require command line option (Bradley
+Schaefer)
+
+
Expose configuration options via config:
+
+
config.libs returns the libs configured to be added onto the
+load path
+
+
full_backtrace? returns the state of the backtrace cleaner
+
+
debug? returns true when the debugger is loaded
+
+
line_numbers returns the line numbers we are filtering by (if
+any)
+
+
full_description returns the RegExp used to filter
+descriptions (Jon Rowe)
+
+
Add setters for RSpec.world and RSpec.configuration (Alex Soulim)
+
+
Configure ruby's warning behaviour with --warnings (Jon
+Rowe)
+
+
Fix an obscure issue on old versions of 1.8.7 where
+Time.dup wouldn't allow access to Time.now
+(Jon Rowe)
+
+
Make shared_examples_for context aware, so that keys may be
+safely reused in multiple contexts without colliding. (Jon Rowe)
+
+
Add a configurable deprecation_stream (Jon Rowe)
+
+
Publish deprecations through a formatter (David Chelimsky)
+
+
+
Bug fixes
+
+
Make JSON formatter behave the same when it comes to --profile
+as the text formatter (Paweł Gościcki).
+
+
Fix named subjects so that if an inner group defines a method that
+overrides the named method, subject still retains the
+originally declared value (Myron Marston).
+
+
Fix random ordering so that it does not cause rand in examples
+in nested sibling contexts to return the same value (Max Shytikov).
+
+
Use the new backtrace_inclusion_patterns config option to
+ensure that folks who develop code in a directory matching one of the
+default exclusion patterns (e.g. gems) still get the normal
+backtrace filtering (Sam Phippen).
+
+
Fix ordering of before hooks so that before hooks
+declared in RSpec.configure run before before
+hooks declared in a shared context (Michi Huber and Tejas Dinkar).
+
+
Fix Example#full_description so that it gets filled in by the
+last matcher description (as Example#description already did)
+when no doc string has been provided (David Chelimsky).
+
+
Fix the memoized methods (let and subject)
+leaking define_method as a public method.
+(Thomas Holmes and Jon Rowe) (#873)
+
+
Fix warnings coming from the test suite. (Pete Higgins)
+
+
+
Deprecations
+
+
Deprecate Configuration#backtrace_clean_patterns in favor of
+Configuration#backtrace_exclusion_patterns for greater
+consistency and symmetry with new
+backtrace_inclusion_patterns config option (Sam Phippen).
+
+
Deprecate Configuration#requires= in favor of using ruby's
+require. Requires specified by the command line can still be
+accessed by the Configuration#require reader. (Bradley
+Schaefer)
+
+
Deprecate calling SharedExampleGroups defined across sibling
+contexts (Jon Rowe)
Use hook classes as proxies rather than extending hook blocks to support
+lambdas for before/after/around hooks. (David Chelimsky)
+
+
Fix regression in 2.13.0 that caused confusing behavior when overriding a
+named subject with an unnamed subject in an inner group and then
+referencing the outer group subject's name. The fix for this required
+us to disallow using super in a named subject (which is
+confusing, anyway – named subjects create 2 methods, so which method on
+the parent example group are you supering to?) but
+super in an unnamed subject continues to work (Myron
+Marston).
+
+
Do not allow a referenced let or subject in
+before(:all) to cause other let declarations to
+leak across examples (Myron Marston).
+
+
Work around odd ruby 1.9 bug with String#match that was
+triggered by passing it a regex from a let declaration. For
+more info, see bugs.ruby-lang.org/issues/8059
+(Aaron Kromer).
+
+
Add missing require 'set' to
+base_text_formatter.rb (Tom Anderson).
+
+
+
Deprecations
+
+
Deprecate accessing let or subject declarations
+in before(:all). These were not intended to be called in a
+before(:all) hook, as they exist to define state that is
+reset between each example, while before(:all) exists to
+define state that is shared across examples in an example group (Myron
+Marston).
Allow --profile option to take a count argument that
+determines the number of slow examples to dump (Greggory Rothmeier).
+
+
Add subject! that is the analog to let!. It
+defines an explicit subject and sets a before hook that will
+invoke the subject (Zubin Henner).
+
+
Fix let and subject declaration so that
+super and return can be used in them, just like
+in a normal method. (Myron Marston)
+
+
Allow output colors to be configured individually. (Charlie Maffitt)
+
+
Always dump slow examples when --profile option is given,
+even when an example failed (Myron Marston).
+
+
+
Bug fixes
+
+
Don't blow up when dumping error output for instances of anonymous
+error classes (Myron Marston).
+
+
Fix default backtrace filters so lines from projects containing “gems” in
+the name are not filtered, but lines from installed gems still are (Myron
+Marston).
+
+
Fix autotest command so that is uses double quotes rather than single
+quotes for windows compatibility (Jonas Tingeborn).
+
+
Fix its so that uses of subject in a
+before or let declaration in the parent group
+continue to reference the parent group's subject. (Olek Janiszewski)
Specs are run even if another at_exit hook calls exit. This
+allows Test::Unit and RSpec to run together. (Suraj N. Kurapati)
+
+
Fix full doc string concatenation so that it handles the case of a method
+string (e.g. “#foo”) being nested under a context string (e.g. “when it is
+tuesday”), so that we get “when it is tuesday #foo” rather than “when it
+is tuesday#foo”. (Myron Marston)
+
+
Restore public API I unintentionally broke in 2.12.0:
+RSpec::Core::Formatters::BaseFormatter#format_backtrce(backtrace,
+example) (Myron Marston).
Add support for custom ordering strategies for groups and examples. (Myron
+Marston)
+
+
JSON Formatter (Alex Chaffee)
+
+
Refactor rake task internals (Sam Phippen)
+
+
Refactor HtmlFormatter (Pete Hodgson)
+
+
Autotest supports a path to Ruby that contains spaces (dsisnero)
+
+
Provide a helpful warning when a shared example group is redefined. (Mark
+Burns).
+
+
--default_path can be specified as
+--default-line. --line_number can be specified
+as --line-number. Hyphens are more idiomatic command line
+argument separators (Sam Phippen).
+
+
A more useful error message is shown when an invalid command line option is
+used (Jordi Polo).
+
+
Add format_docstrings { |str| } config option. It can be used
+to apply formatting rules to example group and example docstrings. (Alex
+Tan)
+
+
Add support for an .rspec-local options file. This is intended
+to allow individual developers to set options in a git-ignored file that
+override the common project options in .rspec. (Sam Phippen)
+
+
Support for mocha 0.13.0. (Andy Lindeman)
+
+
+
Bug fixes
+
+
Remove override of ExampleGroup#ancestors. This is a core ruby
+method that RSpec shouldn't override. Instead, define
+ExampleGroup#parent_groups. (Myron Marston)
+
+
Limit monkey patching of shared example/context declaration methods
+(shared_examples_for, etc.) to just the objects that need it
+rather than every object in the system (Myron Marston).
+
+
Fix Metadata#fetch to support computed values (Sam Goldman).
+
+
Named subject can now be referred to from within subject block in a nested
+group (tomykaira).
+
+
Fix fail_fast so that it properly exits when an error occurs
+in a before(:all) hook (Bradley Schaefer).
+
+
Make the order spec files are loaded consistent, regardless of the order
+of the files returned by the OS or the order passed at the command line
+(Jo Liss and Sam Phippen).
+
+
Ensure instance variables from before(:all) are always exposed
+from after(:all), even if an error occurs in
+before(:all) (Sam Phippen).
+
+
rspec --init no longer generates an incorrect warning about
+--configure being deprecated (Sam Phippen).
+
+
Fix pluralization of 1 seconds (Odin Dutton)
+
+
Fix ANSICON url (Jarmo Pertman)
+
+
Use dup of Time so reporting isn't clobbered by examples that modify
+Time without properly restoring it. (David Chelimsky)
+
+
+
Deprecations
+
+
share_as is no longer needed. shared_context
+and/or RSpec::SharedContext provide better mechanisms (Sam
+Phippen).
+
+
Deprecate RSpec.configuration with a block (use
+RSpec.configure).
Fix the way we autoload RSpec::Matchers so that custom matchers can be
+defined before rspec-core has been configured to definitely use
+rspec-expectations. (Myron Marston)
+
+
Fix typo in –help message printed for -e option. (Jo Liss)
+
+
Fix ruby warnings. (Myron Marston)
+
+
Ignore mock expectation failures when the example has already failed. Mock
+expectation failures have always been ignored in this situation, but due
+to my changes in 27059bf1 it was printing a confusing message. (Myron
+Marston).
thanks to Bradley Schaefer for suggesting it and Avdi Grimm for almost
+suggesting it.
+
+
+
config.mock_with and config.expect_with yield
+custom config object to a block if given
+
+
aids decoupling from rspec-core's configuation
+
+
+
include_context and include_examples support a
+block, which gets eval'd in the current context (vs the nested context
+generated by it_behaves_like).
+
+
Add config.order = 'random' to the
+spec_helper.rb generated by rspec --init.
+
+
Delay the loading of DRb (Myron Marston).
+
+
Limit monkey patching of describe onto just the objects that
+need it rather than every object in the system (Myron Marston).
+
+
+
Bug fixes
+
+
Support alternative path separators. For example, on Windows, you can now
+do this: rspec spec\subdir. (Jarmo Pertman @jarmo)
+
+
When an example raises an error and an after or around hook does as well,
+print out the hook error. Previously, the error was silenced and the user
+got no feedback about what happened. (Myron Marston)
+
+
--require and -I are merged among different
+configuration sources (Andy Lindeman)
+
+
Delegate to mocha methods instead of aliasing them in mocha adapter.
NOTE: RSpec's release policy dictates that there should not be any
+backward incompatible changes in minor releases, but we're making an
+exception to release a change to how RSpec interacts with other command
+line tools.
+
+
As of 2.7.0, you must explicity require
+"rspec/autorun" unless you use the rspec
+command (which already does this for you).
+
+
Enhancements
+
+
Add example.exception (David Chelimsky)
+
+
--default_path command line option (Justin Ko)
+
+
support multiple --line_number options (David J. Hamilton)
+
+
also supports path/to/file.rb:5:9 (runs examples on lines 5
+and 9)
+
+
+
Allow classes/modules to be used as shared example group identifiers
+(Arthur Gunn)
+
+
Friendly error message when shared context cannot be found (Sławosz
+Sławiński)
+
+
Clear formatters when resetting config (John Bintz)
+
+
Add xspecify and xexample as temp-pending methods (David
+Chelimsky)
+
+
Add --no-drb option (Iain Hecker)
+
+
Provide more accurate run time by registering start time before code is
+loaded (David Chelimsky)
NOTE: RSpec's release policy dictates that there should not be new
+functionality in patch releases, but this minor enhancement slipped in by
+accident. As it doesn't add a new API, we decided to leave it in rather
+than roll back this release.
+
+
Enhancements
+
+
Add summary of commands to run individual failed examples.
+
+
+
Bug fixes
+
+
Support exclusion filters in DRb. (Yann Lugrin)
+
+
Fix –example escaping when run over DRb. (Elliot Winkler)
+
+
Use standard ANSI codes for color formatting so colors work in a wider set
+of color schemes.
Print a deprecation warning when you configure RSpec after defining an
+example. All configuration should happen before any examples are defined.
+(Myron Marston)
+
+
Pass the exit status of a DRb run to the invoking process. This causes
+specs run via DRb to not just return true or false. (Ilkka Laukkanen)
+
+
Refactoring of ConfigurationOptions#parse_options (Rodrigo
+Rosenfeld Rosas)
+
+
Report excluded filters in runner output (tip from andyl)
+
+
Clean up messages for filters/tags.
+
+
Restore –pattern/-P command line option from rspec-1
+
+
Support false as well as true in config.full_backtrace= (Andreas Tolf
+Tolfsen)
+
+
+
Bug fixes
+
+
Don't stumble over an exception without a message (Hans Hasselberg)
+
+
Remove non-ascii characters from comments that were choking rcov (Geoffrey
+Byers)
+
+
Fixed backtrace so it doesn't include lines from before the autorun
+at_exit hook (Myron Marston)
+
+
Include RSpec::Matchers when first example group is defined, rather than
+just before running the examples. This works around an obscure bug in ruby
+1.9 that can cause infinite recursion. (Myron Marston)
+
+
Don't send example_group_[started|finished] to formatters
+for empty groups.
+
+
Get specs passing on jruby (Sidu Ponnappa)
+
+
Fix bug where mixing nested groups and outer-level examples gave
+unpredictable :line_number behavior (Artur Małecki)
+
+
Regexp.escape the argument to –example (tip from Elliot Winkler)
+
+
Correctly pass/fail pending block with message expectations
+
+
CommandLine returns exit status (0/1) instead of true/false
+
+
Create path to formatter output file if it doesn't exist (marekj).
NOTE: this release breaks compatibility with rspec/autotest/bundler
+integration, but does so in order to greatly simplify it.
+
+
With this release, if you want the generated autotest command to include
+'bundle exec', require Autotest's bundler plugin in a .autotest
+file in the project's root directory or in your home directory:
+
+
require"autotest/bundler"
+
+
+
Now you can just type 'autotest' on the commmand line and it will
+work as you expect.
+
+
If you don't want 'bundle exec', there is nothing you have to
+do.
Copyright (c) 2012 Chad Humphries, David Chelimsky, Myron Marston Copyright (c) 2009 Chad Humphries, David Chelimsky Copyright (c) 2006 David Chelimsky, The RSpec Development Team Copyright (c) 2005 Steven Baker
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-core/file.README.html b/source/documentation/3.0/rspec-core/file.README.html
new file mode 100644
index 000000000..6c0aaf6be
--- /dev/null
+++ b/source/documentation/3.0/rspec-core/file.README.html
@@ -0,0 +1,315 @@
+
+
+
+
+
+ File: README
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
rspec-core provides the structure for writing executable examples of how
+your code should behave, and an rspec command with tools to
+constrain which examples get run and tailor the output.
+
+
install
+
+
geminstallrspec# for rspec-core, rspec-expectations, rspec-mocks
+geminstallrspec-core# for rspec-core only
+rspec--help
+
+
basic structure
+
+
RSpec uses the words “describe” and “it” so we can express concepts like a
+conversation:
+
+
"Describe an order."
+"It sums the prices of its line items."
+
+
RSpec.describeOrderdo
+ it"sums the prices of its line items"do
+ order=Order.new
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(1.11,:USD)
+ )))
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(2.22,:USD),
+ :quantity=>2
+ )))
+ expect(order.total).toeq(Money.new(5.55,:USD))
+ end
+end
+
+
+
The describe method creates an ExampleGroup.
+Within the block passed to describe you can declare examples
+using the it method.
+
+
Under the hood, an example group is a class in which the block passed to
+describe is evaluated. The blocks passed to it
+are evaluated in the context of an instance of that class.
+
+
nested groups
+
+
You can also declare nested nested groups using the describe
+or context methods:
+
+
RSpec.describeOrderdo
+ context"with no items"do
+ it"behaves one way"do
+ # ...
+end
+ end
+
+ context"with one item"do
+ it"behaves another way"do
+ # ...
+end
+ end
+end
+
+
+
aliases
+
+
You can declare example groups using either describe or
+context. For a top level example group, describe
+and context are available off of RSpec. For
+backwards compatibility, they are also available off of the
+main object and Module unless you disable monkey
+patching.
+
+
You can declare examples within a group using any of it,
+specify, or example.
+
+
shared examples and contexts
+
+
Declare a shared example group using shared_examples, and then
+include it in any group using include_examples.
+
+
RSpec.shared_examples"collections"do|collection_class|
+ it"is empty when first created"do
+ expect(collection_class.new).tobe_empty
+ end
+end
+
+RSpec.describeArraydo
+ include_examples"collections",Array
+end
+
+RSpec.describeHashdo
+ include_examples"collections",Hash
+end
+
+
+
Nearly anything that can be declared within an example group can be
+declared within a shared example group. This includes before,
+after, and around hooks, let
+declarations, and nested groups/contexts.
+
+
You can also use the names shared_context and
+include_context. These are pretty much the same as
+shared_examples and include_examples, providing
+more accurate naming when you share hooks, let declarations,
+helper methods, etc, but no examples.
+
+
metadata
+
+
rspec-core stores a metadata hash with every example and group, which
+contains their descriptions, the locations at which they were declared,
+etc, etc. This hash powers many of rspec-core's features, including
+output formatters (which access descriptions and locations), and filtering
+before and after hooks.
+
+
Although you probably won't ever need this unless you are writing an
+extension, you can access it from an example like this:
When a class is passed to describe, you can access it from an
+example using the described_class method, which is a wrapper
+for example.metadata[:described_class].
+
+
RSpec.describeWidgetdo
+ exampledo
+ expect(described_class).toequal(Widget)
+ end
+end
+
+
+
This is useful in extensions or shared example groups in which the specific
+class is unknown. Taking the collections shared example group from above,
+we can clean it up a bit using described_class:
+
+
RSpec.shared_examples"collections"do
+ it"is empty when first created"do
+ expect(described_class.new).tobe_empty
+ end
+end
+
+RSpec.describeArraydo
+ include_examples"collections"
+end
+
+RSpec.describeHashdo
+ include_examples"collections"
+end
+
+
+
the rspec command
+
+
When you install the rspec-core gem, it installs the rspec
+executable, which you'll use to run rspec. The rspec
+command comes with many useful options. Run rspec --help to
+see the complete list.
+
+
store command line options .rspec
+
+
You can store command line options in a .rspec file in the
+project's root directory, and the rspec command will read
+them as though you typed them on the command line.
+
+
autotest integration
+
+
rspec-core no longer ships with an Autotest extension, if you require
+Autotest integration, please use the rspec-autotest gem and
+see rspec/rspec-autotest for
+details
+
+
get started
+
+
Start with a simple example of behavior you expect from your system. Do
+this before you write any implementation code:
+
+
# in spec/calculator_spec.rb
+RSpec.describeCalculatordo
+ describe'#add'do
+ it'returns the sum of its arguments'do
+ expect(Calculator.new.add(1,2)).toeq(3)
+ end
+ end
+end
+
+
+
Run this with the rspec command, and watch it fail:
# in lib/calculator.rb
+classCalculator
+ defadd(a,b)
+ a+b
+ end
+end
+
+
+
Be sure to require the implementation file in the spec:
+
+
# in spec/calculator_spec.rb
+# - RSpec adds ./lib to the $LOAD_PATH
+require"calculator"
+
+
+
Now run the spec again, and watch it pass:
+
+
$ rspec spec/calculator_spec.rb
+.
+
+Finished in 0.000315 seconds
+1 example, 0 failures
+
+
Use the documentation formatter to see the resulting spec:
+
+
$ rspec spec/calculator_spec.rb --format doc
+Calculator
+ #add
+ returns the sum of its arguments
+
+Finished in 0.000379 seconds
+1 example, 0 failures
rspec-core provides the structure for writing executable examples of how
+your code should behave, and an rspec command with tools to
+constrain which examples get run and tailor the output.
+
+
install
+
+
geminstallrspec# for rspec-core, rspec-expectations, rspec-mocks
+geminstallrspec-core# for rspec-core only
+rspec--help
+
+
basic structure
+
+
RSpec uses the words “describe” and “it” so we can express concepts like a
+conversation:
+
+
"Describe an order."
+"It sums the prices of its line items."
+
+
RSpec.describeOrderdo
+ it"sums the prices of its line items"do
+ order=Order.new
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(1.11,:USD)
+ )))
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(2.22,:USD),
+ :quantity=>2
+ )))
+ expect(order.total).toeq(Money.new(5.55,:USD))
+ end
+end
+
+
+
The describe method creates an ExampleGroup.
+Within the block passed to describe you can declare examples
+using the it method.
+
+
Under the hood, an example group is a class in which the block passed to
+describe is evaluated. The blocks passed to it
+are evaluated in the context of an instance of that class.
+
+
nested groups
+
+
You can also declare nested nested groups using the describe
+or context methods:
+
+
RSpec.describeOrderdo
+ context"with no items"do
+ it"behaves one way"do
+ # ...
+end
+ end
+
+ context"with one item"do
+ it"behaves another way"do
+ # ...
+end
+ end
+end
+
+
+
aliases
+
+
You can declare example groups using either describe or
+context. For a top level example group, describe
+and context are available off of RSpec. For
+backwards compatibility, they are also available off of the
+main object and Module unless you disable monkey
+patching.
+
+
You can declare examples within a group using any of it,
+specify, or example.
+
+
shared examples and contexts
+
+
Declare a shared example group using shared_examples, and then
+include it in any group using include_examples.
+
+
RSpec.shared_examples"collections"do|collection_class|
+ it"is empty when first created"do
+ expect(collection_class.new).tobe_empty
+ end
+end
+
+RSpec.describeArraydo
+ include_examples"collections",Array
+end
+
+RSpec.describeHashdo
+ include_examples"collections",Hash
+end
+
+
+
Nearly anything that can be declared within an example group can be
+declared within a shared example group. This includes before,
+after, and around hooks, let
+declarations, and nested groups/contexts.
+
+
You can also use the names shared_context and
+include_context. These are pretty much the same as
+shared_examples and include_examples, providing
+more accurate naming when you share hooks, let declarations,
+helper methods, etc, but no examples.
+
+
metadata
+
+
rspec-core stores a metadata hash with every example and group, which
+contains their descriptions, the locations at which they were declared,
+etc, etc. This hash powers many of rspec-core's features, including
+output formatters (which access descriptions and locations), and filtering
+before and after hooks.
+
+
Although you probably won't ever need this unless you are writing an
+extension, you can access it from an example like this:
When a class is passed to describe, you can access it from an
+example using the described_class method, which is a wrapper
+for example.metadata[:described_class].
+
+
RSpec.describeWidgetdo
+ exampledo
+ expect(described_class).toequal(Widget)
+ end
+end
+
+
+
This is useful in extensions or shared example groups in which the specific
+class is unknown. Taking the collections shared example group from above,
+we can clean it up a bit using described_class:
+
+
RSpec.shared_examples"collections"do
+ it"is empty when first created"do
+ expect(described_class.new).tobe_empty
+ end
+end
+
+RSpec.describeArraydo
+ include_examples"collections"
+end
+
+RSpec.describeHashdo
+ include_examples"collections"
+end
+
+
+
the rspec command
+
+
When you install the rspec-core gem, it installs the rspec
+executable, which you'll use to run rspec. The rspec
+command comes with many useful options. Run rspec --help to
+see the complete list.
+
+
store command line options .rspec
+
+
You can store command line options in a .rspec file in the
+project's root directory, and the rspec command will read
+them as though you typed them on the command line.
+
+
autotest integration
+
+
rspec-core no longer ships with an Autotest extension, if you require
+Autotest integration, please use the rspec-autotest gem and
+see rspec/rspec-autotest for
+details
+
+
get started
+
+
Start with a simple example of behavior you expect from your system. Do
+this before you write any implementation code:
+
+
# in spec/calculator_spec.rb
+RSpec.describeCalculatordo
+ describe'#add'do
+ it'returns the sum of its arguments'do
+ expect(Calculator.new.add(1,2)).toeq(3)
+ end
+ end
+end
+
+
+
Run this with the rspec command, and watch it fail:
# in lib/calculator.rb
+classCalculator
+ defadd(a,b)
+ a+b
+ end
+end
+
+
+
Be sure to require the implementation file in the spec:
+
+
# in spec/calculator_spec.rb
+# - RSpec adds ./lib to the $LOAD_PATH
+require"calculator"
+
+
+
Now run the spec again, and watch it pass:
+
+
$ rspec spec/calculator_spec.rb
+.
+
+Finished in 0.000315 seconds
+1 example, 0 failures
+
+
Use the documentation formatter to see the resulting spec:
+
+
$ rspec spec/calculator_spec.rb --format doc
+Calculator
+ #add
+ returns the sum of its arguments
+
+Finished in 0.000379 seconds
+1 example, 0 failures
The legacy :should syntax adds the following methods directly to
+BasicObject so that they are available off of any object. Note, however,
+that this syntax does not always play nice with delegate/proxy objects.
+We recommend you use the non-monkeypatching :expect syntax instead.
RSpec::Expectations provides a simple, readable API to express
+the expected outcomes in a code example. To express an expected
+outcome, wrap an object or block in expect, call to or to_not
+(aliased as not_to) and pass it a matcher object:
The last form (the block form) is needed to match against ruby constructs
+that are not objects, but can only be observed when executing a block
+of code. This includes raising errors, throwing symbols, yielding,
+and changing values.
+
+
When expect(...).to is invoked with a matcher, it turns around
+and calls matcher.matches?(<object wrapped by expect>). For example,
+in the expression:
+
+
expect(order.total).toeq(Money.new(5.55,:USD))
+
+
+
...eq(Money.new(5.55, :USD)) returns a matcher object, and it results
+in the equivalent of eq.matches?(order.total). If matches? returns
+true, the expectation is met and execution continues. If false, then
+the spec fails with the message returned by eq.failure_message.
+
+
Given the expression:
+
+
expect(order.entries).not_toinclude(entry)
+
+
+
...the not_to method (also available as to_not) invokes the equivalent of
+include.matches?(order.entries), but it interprets false as success, and
+true as a failure, using the message generated by
+include.failure_message_when_negated.
+
+
rspec-expectations ships with a standard set of useful matchers, and writing
+your own matchers is quite simple.
+
+
See RSpec::Matchers for more information about the
+built-in matchers that ship with rspec-expectations, and how to write your
+own custom matchers.
# File 'lib/rspec/expectations/fail_with.rb', line 21
+
+deffail_with(message,expected=nil,actual=nil)
+ unlessmessage
+ raiseArgumentError,"Failure message is nil. Does your matcher define the " \
+ "appropriate failure_message[_when_negated] method to return a string?"
+ end
+
+ diff=differ.diff(actual,expected)
+ message="#{message}\nDiff:#{diff}"unlessdiff.empty?
+
+ raiseRSpec::Expectations::ExpectationNotMetError,message
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/RSpec/Expectations/Configuration.html b/source/documentation/3.0/rspec-expectations/RSpec/Expectations/Configuration.html
new file mode 100644
index 000000000..ed1f5f0bc
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/RSpec/Expectations/Configuration.html
@@ -0,0 +1,732 @@
+
+
+
+
+
+ Class: RSpec::Expectations::Configuration
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Provides configuration options for rspec-expectations.
+If you are using rspec-core, you can access this via a
+block passed to RSpec::Core::Configuration#expect_with.
+Otherwise, you can access it via RSpec::Expectations.configuration.
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.configuredo|rspec|
+ rspec.expect_with:rspecdo|c|
+ # c is the config object
+end
+end
+
+# or
+
+RSpec::Expectations.configuration
+
+
+
+
+
+
Constant Summary
+
+
+
+
NullBacktraceFormatter =
+
+
+
+ This constant is part of a private API.
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
+
+
Null implementation of a backtrace formatter used by default
+when rspec-core is not loaded. Does no filtering.
+
+
+
+
+
+
+
+
+
+
Module.newdo
+ defself.format_backtrace(backtrace)
+ backtrace
+ end
+end
Sets or gets the backtrace formatter. The backtrace formatter should
+implement #format_backtrace(Array<String>). This is used
+to format backtraces of errors handled by the raise_error
+matcher.
+
+
If you are using rspec-core, rspec-core's backtrace formatting
+will be used (including respecting the presence or absence of
+the --backtrace option).
+
+
+
+
+
+
+
+
+
+
+
+
+
+101
+
+
+
# File 'lib/rspec/expectations/configuration.rb', line 101
+
+attr_writer:backtrace_formatter
Adds should and should_not to the given classes
+or modules. This can be used to ensure should works
+properly on things like proxy objects (particular
+Delegator-subclassed objects on 1.8).
+
+
+
+
+
+
Parameters:
+
+
+
+
+ modules
+
+
+ (Array<Module>)
+
+
+
+ —
+
the list of classes or modules
+to add should and should_not to.
+
+
+
+
+
+
+
+
+
+
+
+
+
+85
+86
+87
+88
+89
+
+
+
# File 'lib/rspec/expectations/configuration.rb', line 85
+
+defadd_should_and_should_not_to(*modules)
+ modules.eachdo|mod|
+ Expectations::Syntax.enable_should(mod)
+ end
+end
+
+
+
+
+
+
+
+
+ - (Boolean) color?
+
+
+
+
+
+
+
+
Indicates whether or not diffs should be colored.
+Delegates to rspec-core's color option if rspec-core
+is loaded; otherwise you can set it here.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+73
+74
+75
+
+
+
# File 'lib/rspec/expectations/configuration.rb', line 73
+
+defcolor?
+ ::RSpec.configuration.color_enabled?
+end
In addition to matchers that are defined explicitly, RSpec will create
+custom matchers on the fly for any arbitrary predicate, giving your specs a
+much more natural language feel.
+
+
A Ruby predicate is a method that ends with a "?" and returns true or false.
+Common examples are empty?, nil?, and instance_of?.
+
+
All you need to do is write expect(..).to be_ followed by the predicate
+without the question mark, and RSpec will figure it out from there.
+For example:
RSpec will also create custom matchers for predicates like has_key?. To
+use this feature, just state that the object should have_key(:key) and RSpec will
+call has_key?(:key) on the target. For example:
You can use this feature to invoke any predicate that begins with "has_", whether it is
+part of the Ruby libraries (like Hash#has_key?) or a method you wrote on your own class.
+
+
Note that RSpec does not provide composable aliases for these dynamic predicate
+matchers. You can easily define your own aliases, though:
When you find that none of the stock matchers provide a natural feeling
+expectation, you can very easily write your own using RSpec's matcher DSL
+or writing one from scratch.
+
+
Matcher DSL
+
+
Imagine that you are writing a game in which players can be in various
+zones on a virtual board. To specify that bob should be in zone 4, you
+could say:
+
+
expect(bob.current_zone).toeql(Zone.new("4"))
+
+
+
But you might find it more expressive to say:
+
+
expect(bob).tobe_in_zone("4")
+
+
+
and/or
+
+
expect(bob).not_tobe_in_zone("3")
+
+
+
You can create such a matcher like so:
+
+
RSpec::Matchers.define:be_in_zonedo|zone|
+ matchdo|player|
+ player.in_zone?(zone)
+ end
+end
+
+
+
This will generate a be_in_zone method that returns a matcher
+with logical default messages for failures. You can override the failure
+messages and the generated description as follows:
+
+
RSpec::Matchers.define:be_in_zonedo|zone|
+ matchdo|player|
+ player.in_zone?(zone)
+ end
+
+ failure_messagedo|player|
+ # generate and return the appropriate string.
+end
+
+ failure_message_when_negateddo|player|
+ # generate and return the appropriate string.
+end
+
+ descriptiondo
+ # generate and return the appropriate string.
+end
+end
+
+
+
Each of the message-generation methods has access to the block arguments
+passed to the create method (in this case, zone). The
+failure message methods (failure_message and
+failure_message_when_negated) are passed the actual value (the
+receiver of expect(..) or expect(..).not_to).
+
+
Custom Matcher from scratch
+
+
You could also write a custom matcher from scratch, as follows:
+
+
classBeInZone
+ definitialize(expected)
+ @expected=expected
+ end
+
+ defmatches?(target)
+ @target=target
+ @target.current_zone.eql?(Zone.new(@expected))
+ end
+
+ deffailure_message
+ "expected #{@target.inspect} to be in Zone #{@expected}"
+ end
+
+ deffailure_message_when_negated
+ "expected #{@target.inspect} not to be in Zone #{@expected}"
+ end
+end
+
And then expose the method to your specs. This is normally done
+by including the method and the class in a module, which is then
+included in your spec:
Custom matchers can easily participate in composed matcher expressions like these.
+Include Composable in your custom matcher to make it support
+being composed (matchers defined using the DSL have this included automatically).
+Within your matcher's matches? method (or the match block, if using the DSL),
+use values_match?(expected, actual) rather than expected == actual.
+Under the covers, values_match? is able to match arbitrary
+nested data structures containing a mix of both matchers and non-matcher objects.
+It uses === and == to perform the matching, considering the values to
+match if either returns true. The Composable mixin also provides some helper
+methods for surfacing the matcher descriptions within your matcher's description
+or failure messages.
+
+
RSpec's built-in matchers each have a number of aliases that rephrase the matcher
+from a verb phrase (such as be_within) to a noun phrase (such as a_value_within),
+which reads better when the matcher is passed as an argument in a composed matcher
+expressions, and also uses the noun-phrase wording in the matcher's description,
+for readable failure messages. You can alias your custom matchers in similar fashion
+using Matchers.alias_matcher.
Given a Regexp or String, passes if actual.match(pattern) Given an arbitrary nested data structure (e.g. arrays and hashes), matches if expected === actual || actual == expected for each pair of elements.
Defines a matcher alias. The returned matcher's description will be overriden
+to reflect the phrasing of the new name, which will be used in failure messages
+when passed as an argument to another matcher in a composed matcher expression.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec::Matchers.alias_matcher:a_list_that_sums_to,:sum_to
+sum_to(3).description# => "sum to 3"
+a_list_that_sums_to(3).description# => "a list that sums to 3"
+
+
+
+RSpec::Matchers.alias_matcher:a_list_sorted_by,:be_sorted_bydo|description|
+ description.sub("be sorted by","a list sorted by")
+end
+
+be_sorted_by(:age).description# => "be sorted by age"
+a_list_sorted_by(:age).description# => "a list sorted by age"
+
+
+
Parameters:
+
+
+
+
+ new_name
+
+
+ (Symbol)
+
+
+
+ —
+
the new name for the matcher
+
+
+
+
+
+
+ old_name
+
+
+ (Symbol)
+
+
+
+ —
+
the original name for the matcher
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
optional block that, when given is used to define the overriden
+description. The yielded arg is the original description. If no block is
+provided, a default description override is used based on the old and
+new names.
Delegates to Expectations.configuration.
+This is here because rspec-core's expect_with option
+looks for a configuration method on the mixin
+(RSpec::Matchers) to yield to a block.
The negative form not_to all is not supported. Instead
+use not_to include or pass a negative form of a matcher
+as the argument (e.g. all exclude(:foo)).
+
+
+
+
+ Note:
+
You can also use this with compound matchers as well.
+
+
+
+
Passes if actual all expected objects pass. This works for
+any enumerable object.
# File 'lib/rspec/matchers.rb', line 599
+
+defall(expected)
+ BuiltIn::All.new(expected)
+end
+
+
+
+
+
+
+
+
+ - (Object) be(*args)
+
+
+
+ Also known as:
+ a_value
+
+
+
+
+
+
+
Given true, false, or nil, will pass if actual value is true, false or
+nil (respectively). Given no args means the caller should satisfy an if
+condition (to be or not to be).
+
+
Predicates are any Ruby method that ends in a "?" and returns true or
+false. Given be_ followed by arbitrary_predicate (without the "?"),
+RSpec will match convert that into a query against the target object.
+
+
The arbitrarypredicate feature will handle any predicate prefixed with
+"be_an" (e.g. bean_instance_of), "be_a" (e.g. bea_kind_of) or "be"
+(e.g. be_empty), letting you choose the prefix that best suits the
+predicate.
# File 'lib/rspec/matchers.rb', line 321
+
+defbe_an_instance_of(expected)
+ BuiltIn::BeAnInstanceOf.new(expected)
+end
+
+
+
+
+
+
+
+
+ - (Object) be_between(min, max)
+
+
+
+ Also known as:
+ a_value_between
+
+
+
+
+
+
+
Passes if actual.between?(min, max). Works with any Comparable object,
+including String, Symbol, Time, or Numeric (Fixnum, Bignum, Integer,
+Float, Complex, and Rational).
+
+
By default, be_between is inclusive (i.e. passes when given either the max or min value),
+but you can make it exclusive by chaining that off the matcher.
Applied to a proc, specifies that its execution will cause some value to
+change.
+
+
You can either pass receiver and message, or a block,
+but not both.
+
+
When passing a block, it must use the { ... } format, not
+do/end, as { ... } binds to the change method, whereas do/end
+would errantly bind to the expect(..).to or expect(...).not_to method.
+
+
You can chain any of the following off of the end to specify details
+about the change:
+
+
+
by
+
by_at_least
+
by_at_most
+
from
+
to
+
+
+
== Notes
+
+
Evaluates receiver.message or block before and after it
+evaluates the block passed to expect.
+
+
expect( ... ).not_to change supports the form that specifies from
+(which specifies what you expect the starting, unchanged value to be)
+but does not support forms with subsequent calls to by, by_at_least,
+by_at_most or to.
# File 'lib/rspec/matchers.rb', line 445
+
+defchange(receiver=nil,message=nil,&block)
+ BuiltIn::Change.new(receiver,message,&block)
+end
+
+
+
+
+
+
+
+
+ - (Object) contain_exactly(*items)
+
+
+
+ Also known as:
+ a_collection_containing_exactly, containing_exactly
+
+
+
+
+
+
+
+
+ Note:
+
This is also available using the =~ operator with should,
+but =~ is not supported with expect.
+
+
+
+
+ Note:
+
This matcher only supports positive expectations.
+expect(...).not_to contain_exactly(other_array) is not supported.
+
+
+
+
Passes if actual contains all of the expected regardless of order.
+This works for collections. Pass in multiple args and it will only
+pass if all args are found in collection.
Matches if the actual value ends with the expected value(s). In the case
+of a string, matches against the last expected.length characters of the
+actual string. In the case of an array, matches against the last
+expected.length elements of the actual array.
+
+ - (Object) include(*expected)
+
+
+
+ Also known as:
+ a_collection_including, a_string_including, a_hash_including, including
+
+
+
+
+
+
+
Passes if actual includes expected. This works for
+collections and Strings. You can also pass in multiple args
+and it will only pass if all args are found in collection.
The match_regex alias is deprecated and is not recommended for use.
+It was added in 2.12.1 to facilitate its use from within custom
+matchers (due to how the custom matcher DSL was evaluated in 2.x,
+match could not be used there), but is no longer needed in 3.x.
+
+
+
+
Given a Regexp or String, passes if actual.match(pattern)
+Given an arbitrary nested data structure (e.g. arrays and hashes),
+matches if expected === actual || actual == expected for each
+pair of elements.
This matcher works by temporarily replacing $stdout or $stderr,
+so it's not able to intercept stream output that explicitly uses STDOUT/STDERR
+or that uses a reference to $stdout/$stderr that was stored before the
+matcher is used.
+
+
+
+
With no arg, passes if the block outputs to_stdout or to_stderr.
+With a string, passes if the blocks outputs that specific string to_stdout or to_stderr.
+With a regexp or matcher, passes if the blocks outputs a string to_stdout or to_stderr that matches.
With no args, matches if any error is raised.
+With a named error, matches only if that specific error is raised.
+With a named error and messsage specified as a String, matches only if both match.
+With a named error and messsage specified as a Regexp, matches only if both match.
+Pass an optional block to perform extra verifications on the exception matched
+
+
+
+
+
+
+
+
Examples:
+
+
+
+expect{do_something_risky}.toraise_error
+expect{do_something_risky}.toraise_error(PoorRiskDecisionError)
+expect{do_something_risky}.toraise_error(PoorRiskDecisionError){|error|expect(error.data).toeq42}
+expect{do_something_risky}.toraise_error(PoorRiskDecisionError,"that was too risky")
+expect{do_something_risky}.toraise_error(PoorRiskDecisionError,/oo ri/)
+
+expect{do_something_risky}.not_toraise_error
+
+
+
+
+
+
+
+
+
+
+701
+702
+703
+
+
+
# File 'lib/rspec/matchers.rb', line 701
+
+defraise_error(error=Exception,message=nil,&block)
+ BuiltIn::RaiseError.new(error,message,&block)
+end
+
+
+
+
+
+
+
+
+ - (Object) respond_to(*names)
+
+
+
+ Also known as:
+ an_object_responding_to, responding_to
+
+
+
+
+
+
+
Matches if the target object responds to all of the names
+provided. Names can be Strings or Symbols.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+expect("string").torespond_to(:length)
+
+
+
+
+
+
+
+
+
+
+721
+722
+723
+
+
+
# File 'lib/rspec/matchers.rb', line 721
+
+defrespond_to(*names)
+ BuiltIn::RespondTo.new(*names)
+end
+
+
+
+
+
+
+
+
+ - (Object) satisfy(&block)
+
+
+
+ Also known as:
+ an_object_satisfying, satisfying
+
+
+
+
+
+
+
Passes if the submitted block returns true. Yields target to the
+block.
+
+
Generally speaking, this should be thought of as a last resort when
+you can't find any other way to specify the behaviour you wish to
+specify.
+
+
If you do find yourself in such a situation, you could always write
+a custom matcher, which would likely make your specs more expressive.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+expect(5).tosatisfy{|n|n>3}
+
+
+
+
+
+
+
+
+
+
+740
+741
+742
+
+
+
# File 'lib/rspec/matchers.rb', line 740
+
+defsatisfy(&block)
+ BuiltIn::Satisfy.new(&block)
+end
Matches if the actual value starts with the expected value(s). In the
+case of a string, matches against the first expected.length characters
+of the actual string. In the case of an array, matches against the first
+expected.length elements of the actual array.
# File 'lib/rspec/matchers.rb', line 803
+
+defyield_control
+ BuiltIn::YieldControl.new
+end
+
+
+
+
+
+
+
+
+ - (Object) yield_successive_args(*args)
+
+
+
+ Also known as:
+ a_block_yielding_successive_args, yielding_successive_args
+
+
+
+
+
+
+
+
+ Note:
+
Your expect block must accept a parameter and pass it on to
+the method-under-test as a block.
+
+
+
+
Designed for use with methods that repeatedly yield (such as
+iterators). Passes if the method called in the expect block yields
+multiple times with arguments matching those given.
+
+
Argument matching is done using === (the case match operator)
+and ==. If the expected and actual arguments match with either
+operator, the matcher will pass.
# File 'lib/rspec/matchers.rb', line 875
+
+defyield_successive_args(*args)
+ BuiltIn::YieldSuccessiveArgs.new(*args)
+end
+
+
+
+
+
+
+
+
+ - (Object) yield_with_args(*args)
+
+
+
+ Also known as:
+ a_block_yielding_with_args, yielding_with_args
+
+
+
+
+
+
+
+
+ Note:
+
Your expect block must accept a parameter and pass it on to
+the method-under-test as a block.
+
+
+
+
+ Note:
+
This matcher is not designed for use with methods that yield
+multiple times.
+
+
+
+
Given no arguments, matches if the method called in the expect
+block yields with arguments (regardless of what they are or how
+many there are).
+
+
Given arguments, matches if the method called in the expect block
+yields with arguments that match the given arguments.
+
+
Argument matching is done using === (the case match operator)
+and ==. If the expected and actual arguments match with either
+operator, the matcher will pass.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+expect{|b|5.tap(&b)}.toyield_with_args# because #tap yields an arg
+expect{|b|5.tap(&b)}.toyield_with_args(5)# because 5 == 5
+expect{|b|5.tap(&b)}.toyield_with_args(Fixnum)# because Fixnum === 5
+expect{|b|File.open("f.txt",&b)}.toyield_with_args(/txt/)# because /txt/ === "f.txt"
+
+expect{|b|User.transaction(&b)}.not_toyield_with_args# because it yields no args
+expect{|b|5.tap(&b)}.not_toyield_with_args(1,2,3)
+
+
+
+
+
+
+
+
+
+
+853
+854
+855
+
+
+
# File 'lib/rspec/matchers.rb', line 853
+
+defyield_with_args(*args)
+ BuiltIn::YieldWithArgs.new(*args)
+end
+
+
+
+
+
+
+
+
+ - (Object) yield_with_no_args
+
+
+
+ Also known as:
+ a_block_yielding_with_no_args, yielding_with_no_args
+
+
+
+
+
+
+
+
+ Note:
+
Your expect block must accept a parameter and pass it on to
+the method-under-test as a block.
+
+
+
+
+ Note:
+
This matcher is not designed for use with methods that yield
+multiple times.
+
+
+
+
Passes if the method called in the expect block yields with
+no arguments. Fails if it does not yield, or yields with arguments.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+expect{|b|User.transaction(&b)}.toyield_with_no_args
+expect{|b|5.tap(&b)}.not_toyield_with_no_args# because it yields with `5`
+expect{|b|"a".to_sym(&b)}.not_toyield_with_no_args# because it does not yield
+
+
+
+
+
+
+
+
+
+
+822
+823
+824
+
+
+
# File 'lib/rspec/matchers.rb', line 822
+
+defyield_with_no_args
+ BuiltIn::YieldWithNoArgs.new
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/RSpec/Matchers/AliasedMatcher.html b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/AliasedMatcher.html
new file mode 100644
index 000000000..1868795cf
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/AliasedMatcher.html
@@ -0,0 +1,394 @@
+
+
+
+
+
+ Class: RSpec::Matchers::AliasedMatcher
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This class is part of a private API.
+ You should avoid using this class if possible, as it may be removed or be changed in the future.
+
+
Decorator that wraps a matcher and overrides description
+using the provided block in order to support an alias
+of a matcher. This is intended for use when composing
+matchers, so that you can use an expression like
+include( a_value_within(0.1).of(3) ) rather than
+include( be_within(0.1).of(3) ), and have the corresponding
+description read naturally.
+ This class handles dynamic methods through the method_missing method
+
+
+
+
+
+
+ - (Object) method_missing
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Forward messages on to the wrapped matcher.
+Since many matchers provide a fluent interface
+(e.g. a_value_within(0.1).of(3)), we need to wrap
+the returned value if it responds to description,
+so that our override can be applied when it is eventually
+used.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Provides the description of the aliased matcher. Aliased matchers
+are designed to behave identically to the original matcher except
+for this method. The description is different to reflect the aliased
+name.
+
+
+
+
+
+
+
+
+
+
+
+
+
+36
+37
+38
+
+
+
# File 'lib/rspec/matchers/aliased_matcher.rb', line 36
+
+defdescription
+ @description_block.call(super)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn.html b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn.html
new file mode 100644
index 000000000..b0dd3fd78
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn.html
@@ -0,0 +1,133 @@
+
+
+
+
+
+ Module: RSpec::Matchers::BuiltIn
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Container module for all built-in matchers. The matcher classes are here
+(rather than directly under RSpec::Matchers) in order to prevent name
+collisions, since RSpec::Matchers gets included into the user's namespace.
+
+
Autoloading is used to delay when the matcher classes get loaded, allowing
+rspec-matchers to boot faster, and avoiding loading matchers the user is
+not using.
+ This class is part of a private API.
+ You should avoid using this class if possible, as it may be removed or be changed in the future.
+
+
Used internally as a base class for matchers that ship with
+rspec-expectations and rspec-rails.
+
+
Warning:
+
+
This class is for internal use, and subject to change without notice. We
+strongly recommend that you do not base your custom matchers on this
+class. If/when this changes, we will announce it and remove this warning.
Most matchers are value matchers (i.e. meant to work with expect(value)) rather than block matchers (i.e. meant to work with expect { }), so this defaults to false.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Matchers are not diffable by default. Override this to make your
+subclass diffable.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+86
+87
+88
+
+
+
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 86
+
+defdiffable?
+ false
+end
+
+
+
+
+
+
+
+
+ - (String) failure_message
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Provides a good generic failure message. Based on description.
+When subclassing, if you are not satisfied with this failure message
+you often only need to override description.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+60
+61
+62
+63
+
+
+
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 60
+
+deffailure_message
+ assert_ivars:@actual
+ "expected #{@actual.inspect} to #{description}"
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Provides a good generic negative failure message. Based on description.
+When subclassing, if you are not satisfied with this failure message
+you often only need to override description.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+70
+71
+72
+73
+
+
+
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 70
+
+deffailure_message_when_negated
+ assert_ivars:@actual
+ "expected #{@actual.inspect} not to #{description}"
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Used to wrap a block of code that will indicate failure by
+raising one of the named exceptions.
+
+
This is used by rspec-rails for some of its matchers that
+wrap rails' assertions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+45
+46
+47
+48
+49
+50
+51
+52
+53
+
+
+
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 45
+
+defmatch_unless_raises(*exceptions)
+ exceptions.unshiftExceptionifexceptions.empty?
+ begin
+ yield
+ true
+ rescue*exceptions=>@rescued_exception
+ false
+ end
+end
+
+
+
+
+
+
+
+
+ - (Boolean) matches?(actual)
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Indicates if the match is successful. Delegates to match, which
+should be defined on a subclass. Takes care of consistently
+initializing the actual attribute.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Most matchers are value matchers (i.e. meant to work with expect(value))
+rather than block matchers (i.e. meant to work with expect { }), so
+this defaults to false. Block matchers must override this to return true.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+94
+95
+96
+
+
+
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 94
+
+defsupports_block_expectations?
+ false
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/Be.html b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/Be.html
new file mode 100644
index 000000000..4b296a584
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/Be.html
@@ -0,0 +1,431 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::Be
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+157
+158
+159
+160
+161
+162
+163
+164
+
+
+
# File 'lib/rspec/matchers/built_in/be.rb', line 157
+
+deffailure_message_when_negated
+ message="`expect(#{@actual.inspect}).not_to be #{@operator}#{@expected.inspect}`"
+ if[:<,:>,:<=,:>=].include?(@operator)
+ message+" not only FAILED, it is a bit confusing."
+ else
+ message
+ end
+end
+
+
+
+
+
+
+
+
+ - (Boolean) matches?(actual)
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+48
+49
+50
+
+
+
# File 'lib/rspec/matchers/built_in/be_within.rb', line 48
+
+deffailure_message_when_negated
+ "expected #{@actual.inspect} not to #{description}"
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+62
+63
+64
+
+
+
# File 'lib/rspec/matchers/built_in/change.rb', line 62
+
+deffailure_message
+ "expected #{@change_details.message} to have changed, but #{positive_failure_reason}"
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+68
+69
+70
+
+
+
# File 'lib/rspec/matchers/built_in/change.rb', line 68
+
+deffailure_message_when_negated
+ "expected #{@change_details.message} not to have changed, but #{negative_failure_reason}"
+end
+
+
+
+
+
+
+
+
+ - (Object) from(value)
+
+
+
+
+
+
+
+
Specifies the original value.
+
+
+
+
+
+
+
+
+
+
+
+
+
+42
+43
+44
+
+
+
# File 'lib/rspec/matchers/built_in/change.rb', line 42
+
+deffrom(value)
+ ChangeFromValue.new(@change_details,value)
+end
+
+
+
+
+
+
+
+
+ - (Object) to(value)
+
+
+
+
+
+
+
+
Specifies the new value you expect.
+
+
+
+
+
+
+
+
+
+
+
+
+
+36
+37
+38
+
+
+
# File 'lib/rspec/matchers/built_in/change.rb', line 36
+
+defto(value)
+ ChangeToValue.new(@change_details,value)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/ChangeFromValue.html b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/ChangeFromValue.html
new file mode 100644
index 000000000..8fe39bee4
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/ChangeFromValue.html
@@ -0,0 +1,316 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::ChangeFromValue
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/built_in/contain_exactly.rb', line 10
+
+deffailure_message
+ ifArray===actual
+ message="expected collection contained: #{safe_sort(surface_descriptions_inexpected).inspect}\n"
+ message+="actual collection contained: #{safe_sort(actual).inspect}\n"
+ message+="the missing elements were: #{safe_sort(surface_descriptions_inmissing_items).inspect}\n"unlessmissing_items.empty?
+ message+="the extra elements were: #{safe_sort(extra_items).inspect}\n"unlessextra_items.empty?
+ message
+ else
+ "expected a collection that can be converted to an array with " \
+ "`#to_ary` or `#to_a`, but got #{actual.inspect}"
+ end
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+25
+26
+27
+
+
+
# File 'lib/rspec/matchers/built_in/contain_exactly.rb', line 25
+
+deffailure_message_when_negated
+ "`contain_exactly` does not support negation"
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/Cover.html b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/Cover.html
new file mode 100644
index 000000000..4264b7370
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/Cover.html
@@ -0,0 +1,429 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::Cover
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+36
+37
+38
+
+
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 36
+
+deffailure_message_when_negated
+ "expected #{@actual.inspect} not to exist#{@test.validity_message}"
+end
+
+
+
+
+
+
+
+
+ - (Boolean) matches?(actual)
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 43
+
+defactual
+ @actual
+end
+
+
+
+
+
+
+
+
+
+
+ - (Object) expected
+
+
+
+
+
+
+
+
Returns the value of attribute expected
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Object)
+
+
+
+ —
+
the current value of expected
+
+
+
+
+
+
+
+
+
+
+
+
+43
+44
+45
+
+
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 43
+
+defexpected
+ @expected
+end
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (Boolean) actual_exists?
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+52
+53
+54
+
+
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 52
+
+defactual_exists?
+ existence_values.first
+end
+
+
+
+
+
+
+
+
+ - (Boolean) valid_test?
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+46
+47
+48
+
+
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 46
+
+defvalid_test?
+ uniq_truthy_values.size==1
+end
+
+
+
+
+
+
+
+
+ - (String) validity_message
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+
+
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 58
+
+defvalidity_message
+ caseuniq_truthy_values.size
+ when0
+ " but it does not respond to either `exist?` or `exists?`"
+ when2
+ " but `exist?` and `exists?` returned different values:\n\n"\
+ " exist?: #{existence_values.first}\n"\
+ "exists?: #{existence_values.last}"
+ end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/Has.html b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/Has.html
new file mode 100644
index 000000000..5945eca1c
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/Has.html
@@ -0,0 +1,474 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::Has
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+22
+23
+24
+
+
+
# File 'lib/rspec/matchers/built_in/output.rb', line 22
+
+defdoes_not_match?(block)
+ !matches?(block)&&Proc===block
+end
+
+
+
+
+
+
+
+
+ - (String) failure_message
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+42
+43
+44
+
+
+
# File 'lib/rspec/matchers/built_in/output.rb', line 42
+
+deffailure_message
+ "expected block to #{description}, but #{positive_failure_reason}"
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+48
+49
+50
+
+
+
# File 'lib/rspec/matchers/built_in/output.rb', line 48
+
+deffailure_message_when_negated
+ "expected block to not #{description}, but #{negative_failure_reason}"
+end
+
+
+
+
+
+
+
+
+ - (Boolean) matches?(block)
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+15
+16
+17
+18
+19
+20
+21
+22
+23
+
+
+
# File 'lib/rspec/matchers/built_in/start_and_end_with.rb', line 15
+
+deffailure_message
+ super.tapdo|msg|
+ if@actual_does_not_have_ordered_elements
+ msg<<", but it does not have ordered elements"
+ elsif!actual.respond_to?(:[])
+ msg<<", but it cannot be indexed using #[]"
+ end
+ end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/StartWith.html b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/StartWith.html
new file mode 100644
index 000000000..19aa2cac6
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/BuiltIn/StartWith.html
@@ -0,0 +1,198 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::StartWith
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+153
+154
+155
+
+
+
# File 'lib/rspec/matchers/built_in/yield.rb', line 153
+
+deffailure_message_when_negated
+ 'expected given block not to yield control'+failure_reason
+end
+
+
+
+
+
+
+
+
+ - (Object) once
+
+
+
+
+
+
+
+
Specifies that the method is expected to yield once.
Mixin designed to support the composable matcher features
+of RSpec 3+. Mix it into your custom matcher classes to
+allow them to be used in a composable fashion.
Transforms the given data structue (typically a hash or array) into a new data structure that, when #inspect is called on it, will provide descriptions of any contained matchers rather than the normal #inspect output.
Transforms the given data structue (typically a hash or array)
+into a new data structure that, when #inspect is called on it,
+will provide descriptions of any contained matchers rather than
+the normal #inspect output.
+
+
You are encouraged to use this in your custom matcher's
+description, failure_message or
+failure_message_when_negated implementation if you are
+supporting any arguments which may be a data structure
+containing matchers.
# File 'lib/rspec/matchers/composable.rb', line 99
+
+defsurface_descriptions_in(item)
+ ifMatchers.is_a_describable_matcher?(item)
+ DescribableItem.new(item)
+ elsifHash===item
+ Hash[surface_descriptions_in(item.to_a)]
+ elsifStruct===item
+ item.inspect
+ elsifenumerable?(item)
+ begin
+ item.map{|subitem|surface_descriptions_in(subitem)}
+ rescueIOError# STDOUT is enumerable but `map` raises an error
+item.inspect
+ end
+ else
+ item
+ end
+end
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (Object) ===(value)
+
+
+
+
+
+
+
+
Delegates to #matches?. Allows matchers to be used in composable
+fashion and also supports using matchers in case statements.
+
+
+
+
+
+
+
+
+
+
+
+
+
+45
+46
+47
+
+
+
# File 'lib/rspec/matchers/composable.rb', line 45
+
+def===(value)
+ matches?(value)
+end
+
+
+
+
+
+
+
+
+ - (Object) and(matcher)
+
+
+
+ Also known as:
+ &
+
+
+
+
+
+
+
+
+ Note:
+
The negative form (expect(...).not_to matcher.and other)
+is not supported at this time.
+
+
+
+
Creates a compound and expectation. The matcher will
+only pass if both sub-matchers pass.
+This can be chained together to form an arbitrarily long
+chain of matchers.
# File 'lib/rspec/matchers/composable.rb', line 22
+
+defand(matcher)
+ BuiltIn::Compound::And.newself,matcher
+end
+
+
+
+
+
+
+
+
+ - (Object) description_of(object)
+
+
+
+
+
+
+
+
Returns the description of the given object in a way that is
+aware of composed matchers. If the object is a matcher with
+a description method, returns the description; otherwise
+returns object.inspect.
+
+
You are encouraged to use this in your custom matcher's
+description, failure_message or
+failure_message_when_negated implementation if you are
+supporting matcher arguments.
+
+ - (Object) or(matcher)
+
+
+
+ Also known as:
+ |
+
+
+
+
+
+
+
+
+ Note:
+
The negative form (expect(...).not_to matcher.or other)
+is not supported at this time.
+
+
+
+
Creates a compound or expectation. The matcher will
+pass if either sub-matcher passes.
+This can be chained together to form an arbitrarily long
+chain of matchers.
This provides a generic way to fuzzy-match an expected value against
+an actual value. It understands nested data structures (e.g. hashes
+and arrays) and is able to match against a matcher being used as
+the expected value or within the expected value at any level of
+nesting.
+
+
Within a custom matcher you are encouraged to use this whenever your
+matcher needs to match two values, unless it needs more precise semantics.
+For example, the eq matcher does not use this as it is meant to
+use == (and only ==) for matching.
Defines default implementations of the matcher
+protocol methods for custom matchers. You can
+override any of these using the Macros methods
+from within an RSpec::Matchers.define block.
The default failure message for negative expectations.
+
+
+
+
+
+
+
+
+
+
+
+
+
+261
+262
+263
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 261
+
+deffailure_message_when_negated
+ "expected #{actual.inspect} not to #{name_to_sentence}#{to_sentenceexpected}"
+end
Convenience for defining methods on this matcher to create a fluent
+interface. The trick about fluent interfaces is that each method must
+return self in order to chain methods together. chain handles that
+for you.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec::Matchers.define:have_errors_ondo|key|
+ chain:withdo|message|
+ @message=message
+ end
+
+ matchdo|actual|
+ actual.errors[key]==@message
+ end
+end
+
+expect(minor).tohave_errors_on(:age).with("Not old enough to participate")
+
+
+
+
+
+
+
+
+
+
+178
+179
+180
+181
+182
+183
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 178
+
+defchain(name,&definition)
+ define_user_override(name,definition)do|*args,&block|
+ super(*args,&block)
+ self
+ end
+end
Customizes the failure messsage to use when this matcher is
+asked to positively match. Only use this when the message
+generated by default doesn't suit your needs.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec::Matchers.define:have_strengthdo|expected|
+ match{your_match_logic}
+
+ failure_messagedo|actual|
+ "Expected strength of #{expected}, but had #{actual.strength}"
+ end
+end
+
+
+
+
Yields:
+
+
+
+
+
+ (Object)
+
+
+
+ —
+
actual the actual object (i.e. the value wrapped by expect)
+
+
+
+
+
+
+
+
+
+
+
+
+105
+106
+107
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 105
+
+deffailure_message(&definition)
+ define_user_override(__method__,definition)
+end
Customize the failure messsage to use when this matcher is asked
+to negatively match. Only use this when the message generated by
+default doesn't suit your needs.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec::Matchers.define:have_strengthdo|expected|
+ match{your_match_logic}
+
+ failure_message_when_negateddo|actual|
+ "Expected not to have strength of #{expected}, but did"
+ end
+end
+
+
+
+
Yields:
+
+
+
+
+
+ (Object)
+
+
+
+ —
+
actual the actual object (i.e. the value wrapped by expect)
+
+
+
+
+
+
+
+
+
+
+
+
+124
+125
+126
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 124
+
+deffailure_message_when_negated(&definition)
+ define_user_override(__method__,definition)
+end
+
+
+
+
+
+
+
+
+ - (Object) match {|Object| ... }
+
+
+
+
+
+
+
+
Stores the block that is used to determine whether this matcher passes
+or fails. The block should return a boolean value. When the matcher is
+passed to expect(...).to and the block returns true, then the expectation
+passes. Similarly, when the matcher is passed to expect(...).not_to and the
+block returns false, then the expectation passes.
Use this to define the block for a negative expectation (expect(...).not_to)
+when the positive and negative forms require different handling. This
+is rarely necessary, but can be helpful, for example, when specifying
+asynchronous processes that require different timeouts.
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+ (Object)
+
+
+
+ —
+
actual the actual value (i.e. the value wrapped by expect)
+
+
+
+
+
+
+
+
+
+
+
+
+56
+57
+58
+59
+60
+61
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 56
+
+defmatch_when_negated(&match_block)
+ define_user_override(:does_not_match?,match_block)do|actual|
+ @actual=actual
+ super(*actual_arg_for(match_block))
+ end
+end
Declares that the matcher can be used in a block expectation.
+Users will not be able to use your matcher in a block
+expectation without declaring this.
+(e.g. expect { do_something }.to matcher).
+
+
+
+
+
+
+
+
+
+
+
+
+
+156
+157
+158
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 156
+
+defsupports_block_expectations
+ define_method(:supports_block_expectations?){true}
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/RSpec/Matchers/DSL/Macros/Deprecated.html b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/DSL/Macros/Deprecated.html
new file mode 100644
index 000000000..1a0b385e4
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/DSL/Macros/Deprecated.html
@@ -0,0 +1,402 @@
+
+
+
+
+
+ Module: RSpec::Matchers::DSL::Macros::Deprecated
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
The class used for custom matchers. The block passed to
+RSpec::Matchers.define will be evaluated in the context
+of the singleton class of an instance, and will have the
+Macros methods available.
Takes care of forwarding unhandled messages to the
+@matcher_execution_context (typically the current
+running RSpec::Core::Example). This is needed by
+rspec-rails so that it can define matchers that wrap
+Rails' test helper methods, but it's also a useful
+feature in its own right.
+
+
+
+
+
+
+
+
+
+
+
+
+
+367
+368
+369
+370
+371
+372
+373
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 367
+
+defmethod_missing(method,*args,&block)
+ if@matcher_execution_context.respond_to?(method)
+ @matcher_execution_context.__send__method,*args,&block
+ else
+ super(method,*args,&block)
+ end
+end
+
+
+
+
+
+
+
+
+
Instance Attribute Details
+
+
+
+
+
+
+ - (Object) actual(readonly)
+
+
+
+
+
+
+
+
Exposes the value being matched against -- generally the object
+object wrapped by expect.
+
+
+
+
+
+
+
+
+
+
+
+
+
+295
+296
+297
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 295
+
+defactual
+ @actual
+end
Returns the expected value as an an array. This exists primarily
+to aid in upgrading from RSpec 2.x, since in RSpec 2, expected
+always returned an array.
Indicates that this matcher responds to messages
+from the @matcher_execution_context as well.
+Also, supports getting a method object for such methods.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+344
+345
+346
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 344
+
+defrespond_to_missing?(method,include_private=false)
+ super||@matcher_execution_context.respond_to?(method,include_private)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/RSpec/Matchers/Pretty.html b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/Pretty.html
new file mode 100644
index 000000000..3cb030951
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/RSpec/Matchers/Pretty.html
@@ -0,0 +1,446 @@
+
+
+
+
+
+ Module: RSpec::Matchers::Pretty
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Fix start_with and end_with so that they work properly with
+structs. (Myron Marston, #620)
+
Fix failure message generation so that structs are printed properly
+in failures. Previously failure messages would represent them as
+an array. (Myron Marston, #620)
+
Fix composable matcher support so that it does not wrongly treat
+structs as arrays. (Myron Marston, #620)
Fix regression in contain_exactly (AKA match_array) that caused it
+to wrongly pass when the expected array was empty. (Myron Marston, #581)
+
Provide a better error message when you use the change(obj, :msg)
+form of the change matcher but forget the message argument. (Alex
+Sunderland, #585)
+
Make the contain_exactly matcher work with arrays that contain hashes in
+arbitrary ordering. (Sam Phippen, #578)
Add a missing require that would cause the respond_to matcher to
+fail when used in a project where the rest of RSpec (e.g. core and
+expecatations) weren't being used. (Myron Marston, #566)
+
Structs are no longer treated as arrays when diffed. (Jon Rowe, #576)
Fix NoMethodError triggered by beta2 when YARD was loaded in
+the test environment. (Myron Marston)
+
Fix be_xyz matcher to accept a do...end block. (Myron Marston)
+
Fix composable matcher failure message generation logic
+so that it does not blow up when given $stdout or $stderr.
+(Myron Marston)
+
Fix change matcher to work properly with IO objects.
+(Myron Marston)
+
Fix exist matcher so that it can be used in composed matcher
+expressions involving objects that do not implement exist? or
+exists?. (Daniel Fone)
+
Fix composable matcher match logic so that it clones matchers
+before using them in order to work properly with matchers
+that use internal memoization based on a given actual value.
+(Myron Marston)
+
Fix be_xyz and has_xyz predicate matchers so that they can
+be used in composed matcher expressions involving objects that
+do not implement the predicate method. (Daniel Fone)
+
+
+
Enhancements:
+
+
+
Document the remaining public APIs. rspec-expectations now has 100% of
+the public API documented and will remain that way (as new undocumented
+methods will fail the build). (Myron Marston)
+
Improve the formatting of BigDecimal objects in eq matcher failure
+messages. (Daniel Fone)
+
Improve the failure message for be_xyz predicate matchers so
+that it includes the inspect output of the receiver.
+(Erik Michaels-Ober, Sam Phippen)
+
Add all matcher, to allow you to specify that a given matcher
+matches all elements in a collection:
+expect([1, 3, 5]).to all( be_odd ). (Adam Farhi)
+
Add boolean aliases (&/|) for compound operators (and/or). (Adam Farhi)
+
Give users a clear error when they wrongly use a value matcher
+in a block expectation expression (e.g. expect { 3 }.to eq(3))
+or vice versa. (Myron Marston)
Remove support for deprecated expect(...).should. (Myron Marston)
+
Explicitly disallow expect { }.not_to change { } with by,
+by_at_least, by_at_most or to. These have never been supported
+but did not raise explicit errors. (Myron Marston)
+
Provide === rather than == as an alias of matches? for
+all matchers. The semantics of === are closer to an RSpec
+matcher than ==. (Myron Marston)
Make RSpec::Expectations::ExpectationNotMetError subclass
+Exception rather than StandardError so they can bypass
+a bare rescue in end-user code (e.g. when an expectation is
+set from within a rspec-mocks stub implementation). (Myron Marston)
+
Remove Test::Unit and Minitest 4.x integration. (Myron Marston)
+
+
+
Enhancements:
+
+
+
Simplify the failure message of the be matcher when matching against:
+true, false and nil. (Sam Phippen)
+
Update matcher protocol and custom matcher DSL to better align
+with the newer expect syntax. If you want your matchers to
+maintain compatibility with multiple versions of RSpec, you can
+alias the new names to the old. (Myron Marston)
+
+
Improve generated descriptions from change matcher. (Myron Marston)
+
Add support for compound matcher expressions using and and or.
+Simply chain them off of any existing matcher to create an expression
+like expect(alphabet).to start_with("a").and end_with("z").
+(Eloy Espinaco)
+
Add contain_exactly as a less ambiguous version of match_array.
+Note that it expects the expected array to be splatted as
+individual args: expect(array).to contain_exactly(1, 2) is
+the same as expect(array).to match_array([1, 2]). (Myron Marston)
+
Update contain_exactly/match_array so that it can match against
+other non-array collections (such as a Set). (Myron Marston)
+
Update built-in matchers so that they can accept matchers as arguments
+to allow you to compose matchers in arbitrary ways. (Myron Marston)
+
Add RSpec::Matchers::Composable mixin that can be used to make
+a custom matcher composable as well. Note that custom matchers
+defined via RSpec::Matchers.define already have this. (Myron
+Marston)
+
Define noun-phrase aliases for built-in matchers, which can be
+used when creating composed matcher expressions that read better
+and provide better failure messages. (Myron Marston)
+
Add RSpec::Machers.alias_matcher so users can define their own
+matcher aliases. The description of the matcher will reflect the
+alternate matcher name. (Myron Marston)
+
Add explicit be_between matcher. be_between has worked for a
+long time as a dynamic predicate matcher, but the failure message
+was suboptimal. The new matcher provides a much better failure
+message. (Erik Michaels-Ober)
+
Enhance the be_between matcher to allow for inclusive or exclusive
+comparison (e.g. inclusive of min/max or exclusive of min/max).
+(Pedro Gimenez)
+
Make failure message for not_to be #{operator} less confusing by
+only saying it's confusing when comparison operators are used.
+(Prathamesh Sonpatki)
+
Improve failure message of eq matcher when Time or DateTime
+objects are used so that the full sub-second precision is included.
+(Thomas Holmes, Jeff Wallace)
+
Add output matcher for expecting that a block outputs to_stdout
+or to_stderr. (Luca Pette, Matthias Günther)
+
Forward a provided block on to the has_xyz? method call when
+the have_xyz matcher is used. (Damian Galarza)
+
Provide integration with Minitest 5.x. Require
+rspec/expectations/minitest_integration after loading minitest
+to use rspec-expectations with minitest. (Myron Marston)
+
+
+
Bug Fixes:
+
+
+
Fix wrong matcher descriptions with falsey expected value (yujinakayama)
+
Fix expect { }.not_to change { }.from(x) so that the matcher only
+passes if the starting value is x. (Tyler Rick, Myron Marston)
+
Fix hash diffing, so that it colorizes properly and doesn't consider trailing
+commas when performing the diff. (Jared Norman)
+
Fix built-in matchers to fail normally rather than raising
+ArgumentError when given an object of the wrong type to match
+against, so that they work well in composite matcher expressions like
+expect([1.51, "foo"]).to include(a_string_matching(/foo/), a_value_within(0.1).of(1.5)).
+(Myron Marston)
+
+
+
Deprecations:
+
+
+
Retain support for RSpec 2 matcher protocol (e.g. for matchers
+in 3rd party extension gems like shoulda), but it will print
+a deprecation warning. (Myron Marston)
Remove the deprecated be_close matcher, preferring be_within instead.
+(Sam Phippen)
+
Remove the deprecated have, have_at_least and have_at_most matchers.
+You can continue using those matchers through https://github.com/rspec/rspec-collection_matchers,
+or you can rewrite your expectations with something like
+expect(your_object.size).to eq(num). (Hugo Baraúna)
+
Rename be_true and be_false to be_truthy and be_falsey. (Sam Phippen)
+
Make expect { }.to_not raise_error(SomeSpecificClass, message),
+ expect { }.to_not raise_error(SomeSpecificClass) and
+ expect { }.to_not raise_error(message) invalid, since they are prone
+to hiding failures. Instead, use expect { }.to_not raise_error (with no
+args). (Sam Phippen)
+
Within RSpec::Matchers.define blocks, helper methods made available
+either via def self.helper or extend HelperModule are no longer
+available to the match block (or any of the others). Instead
+include your helper module and define the helper method as an
+instance method. (Myron Marston)
+
Force upgrading Diff::LCS for encoding compatability with diffs. (Jon Rowe)
+
+
+
Enhancements:
+
+
+
Support do..end style block with raise_error matcher. (Yuji Nakayama)
+
Rewrote custom matcher DSL to simplify its implementation and solve a
+few issues. (Myron Marston)
+
Allow early return from within custom matcher DSL blocks. (Myron
+Marston)
+
The custom matcher DSL's chain can now accept a block. (Myron
+Marston)
+
Support setting an expectation on a raise_error matcher via a chained
+with_message method call. (Sam Phippen)
+
+
+
Bug Fixes:
+
+
+
Allow include and match matchers to be used from within a
+DSL-defined custom matcher's match block. (Myron Marston)
+
Correct encoding error message on diff failure (Jon Rowe)
+
+
+
Deprecations:
+
+
+
Using the old :should syntax without explicitly configuring it is deprecated.
+It will continue to work but will emit a deprecation warning in RSpec 3 if
+you do not explicitly enable it. (Sam Phippen)
Fix regression in Expectations#method_handle_for where proxy objects
+with method delegated would wrongly not return a method handle.
+(Jon Rowe, #594)
+
Fix issue with detection of generic operator matchers so they work
+correctly when undefined. (Myron Marston, #597)
Deprecate RSpec::Matchers::Configuration in favor of
+RSpec::Expectations::Configuration. (Myron Marston)
+
Deprecate be_xyz predicate matcher on an object that doesn't respond to
+xyz? or xyzs?. (Daniel Fone)
+
Deprecate have_xyz matcher on an object that doesn't respond to has_xyz?.
+(Daniel Fone)
+
Deprecate have_xyz matcher on an object that has a private method has_xyz?.
+(Jon Rowe)
+
Issue a deprecation warning when a block expectation expression is
+used with a matcher that doesn't explicitly support block expectations
+via supports_block_expectations?. (Myron Marston)
+
Deprecate require 'rspec-expectations'. Use
+require 'rspec/expectations' instead. (Myron Marston)
Deprecate chaining by, by_at_least, by_at_most or to off of
+expect { }.not_to change { }. The docs have always said these are
+not supported for the negative form but now they explicitly raise
+errors in RSpec 3. (Myron Marston)
+
Change the semantics of expect { }.not_to change { x }.from(y).
+In RSpec 2.x, this expectation would only fail if x started with
+the value of y and changed. If it started with a different value
+and changed, it would pass. In RSpec 3, it will pass only if the
+value starts at y and it does not change. (Myron Marston)
+
Deprecate matcher == value as an alias for matcher.matches?(value),
+in favor of matcher === value. (Myron Marston)
+
Deprecate RSpec::Matchers::OperatorMatcher in favor of
+RSpec::Matchers::BuiltIn::OperatorMatcher. (Myron Marston)
+
Deprecate auto-integration with Test::Unit and minitest.
+Instead, include RSpec::Matchers in the appropriate test case
+base class yourself. (Myron Marston)
+
Deprecate treating #expected on a DSL-generated custom matcher
+as an array when only 1 argument is passed to the matcher method.
+In RSpec 3 it will be the single value in order to make diffs
+work properly. (Jon Rowe)
Deprecate have, have_at_least and have_at_most. You can continue using those
+matchers through https://github.com/rspec/rspec-collection_matchers, or
+you can rewrite your expectations with something like
+expect(your_object.size).to eq(num). (Hugo Baraúna)
+
Deprecate be_xyz predicate matcher when xyz? is a private method.
+(Jon Rowe)
+
Deprecate be_true/be_false in favour of be_truthy/be_falsey
+(for Ruby's conditional semantics) or be true/be false
+(for exact equality). (Sam Phippen)
+
Deprecate calling helper methods from a custom matcher with the wrong
+scope. (Myron Marston)
+
+
+
def self.foo / extend Helper can be used to add macro methods
+(e.g. methods that call the custom matcher DSL methods), but should
+not be used to define helper methods called from within the DSL
+blocks.
+
def foo / include Helper is the opposite: it's for helper methods
+callable from within a DSL block, but not for defining macros.
+
RSpec 2.x allowed helper methods defined either way to be used for
+either purpose, but RSpec 3.0 will not.
Fix be_<predicate> matcher to not support operator chaining like the
+be matcher does (e.g. be == 5). This led to some odd behaviors
+since be_<predicate> == anything returned a BeComparedTo matcher
+and was thus always truthy. This was a consequence of the implementation
+(e.g. subclassing the basic Be matcher) and was not intended behavior.
+(Myron Marston).
+
Fix change matcher to compare using == in addition to ===. This
+is important for an expression like:
+expect {}.to change { a.class }.from(ClassA).to(ClassB) because
+SomeClass === SomeClass returns false. (Myron Marston)
Ensure diff output uses the same encoding as the encoding of
+the string being diff'd to prevent Encoding::UndefinedConversionError
+errors (Jon Rowe).
Enhance yield_control so that you can specify an exact or relative
+number of times: expect { }.to yield_control.exactly(3).times,
+expect { }.to yield_control.at_least(2).times, etc (Bartek
+Borkowski).
+
Make the differ that is used when an expectation fails better handle arrays
+by splitting each element of the array onto its own line. (Sam Phippen)
+
Accept duck-typed strings that respond to :to_str as expectation messages.
+(Toby Ovod-Everett)
+
+
+
Bug fixes
+
+
+
Fix differ to not raise errors when dealing with differently-encoded
+strings (Jon Rowe).
+
Fix expect(something).to be_within(x).percent_of(y) where x and y are both
+integers (Sam Phippen).
+
Fix have matcher to handle the fact that on ruby 2.0,
+Enumerator#size may return nil (Kenta Murata).
+
Fix expect { raise s }.to raise_error(s) where s is an error instance
+on ruby 2.0 (Sam Phippen).
+
Fix expect(object).to raise_error passing. This now warns the user and
+fails the spec (tomykaira).
+
+
+
Deprecations
+
+
+
Deprecate expect { }.not_to raise_error(SpecificErrorClass) or
+expect { }.not_to raise_error("some specific message"). Using
+these was prone to hiding failures as they would allow any other
+error to pass. (Sam Phippen and David Chelimsky)
Add support for percent deltas to be_within matcher:
+expect(value).to be_within(10).percent_of(expected)
+(Myron Marston).
+
Add support to include matcher to allow it to be given a list
+of matchers as the expecteds to match against (Luke Redpath).
+
+
+
Bug fixes
+
+
+
Fix change matcher so that it dups strings in order to handle
+mutated strings (Myron Marston).
+
Fix should be =~ /some regex/ / expect(...).to be =~ /some regex/.
+Previously, these either failed with a confusing undefined method
+matches?' for false:FalseClass error or were no-ops that didn't
+actually verify anything (Myron Marston).
+
Add compatibility for diff-lcs 1.2 and relax the version
+constraint (Peter Goldstein).
+
Fix DSL-generated matchers to allow multiple instances of the
+same matcher in the same example to have different description
+and failure messages based on the expected value (Myron Marston).
+
Prevent undefined method #split for Array error when dumping
+the diff of an array of multiline strings (Myron Marston).
+
Don't blow up when comparing strings that are in an encoding
+that is not ASCII compatible (Myron Marston).
+
Remove confusing "Check the implementation of #==" message
+printed for empty diffs (Myron Marston).
Improve the failure message for an expression like
+{}.should =~ {}. (Myron Marston and Andy Lindeman)
+
Provide a match_regex alias so that custom matchers
+built using the matcher DSL can use it (since match
+is a different method in that context).
+(Steven Harman)
Colorize diffs if the --color option is configured. (Alex Coplan)
+
Include backtraces in unexpected errors handled by raise_error
+matcher (Myron Marston)
+
Print a warning when users accidentally pass a non-string argument
+as an expectation message (Sam Phippen)
+
=~ and match_array matchers output a more useful error message when
+the actual value is not an array (or an object that responds to #to_ary)
+(Sam Phippen)
+
+
+
Bug fixes
+
+
+
Fix include matcher so that expect({}).to include(:a => nil)
+fails as it should (Sam Phippen).
+
Fix be_an_instance_of matcher so that Class#to_s is used in the
+description rather than Class#inspect, since some classes (like
+ActiveRecord::Base) define a long, verbose #inspect.
+(Tom Stuart)
Fix (and deprecate) expect { }.should syntax so that it works even
+though it was never a documented or intended syntax. It worked as a
+consequence of the implementation of expect in RSpec 2.10 and
+earlier. (Myron Marston)
+
Ensure #== is defined on built in matchers so that they can be composed.
+For example:
Define should and should_not on Object rather than BasicObject
+on MacRuby. On MacRuby, BasicObject is defined but is not the root
+of the object hierarchy. (Gabriel Gilder)
Allow only Numeric values to be the "actual" in the be_within matcher.
+This prevents confusing error messages. (Su Zhang @zhangsu)
+
Define should and should_not on BasicObject rather than Kernel
+on 1.9. This makes should and should_not work properly with
+BasicObject-subclassed proxy objects like Delegator. (Myron
+Marston)
Copyright (c) 2012 David Chelimsky, Myron Marston Copyright (c) 2006 David Chelimsky, The RSpec Development Team Copyright (c) 2005 Steven Baker
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-expectations/file.README.html b/source/documentation/3.0/rspec-expectations/file.README.html
new file mode 100644
index 000000000..f42ae98fb
--- /dev/null
+++ b/source/documentation/3.0/rspec-expectations/file.README.html
@@ -0,0 +1,338 @@
+
+
+
+
+
+ File: README
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
If you want to use rspec-expectations with rspec, just install the rspec gem
+and RubyGems will also install rspec-expectations for you (along with
+rspec-core and rspec-mocks):
+
+
geminstallrspec
+
+
+
If you want to use rspec-expectations with another tool, like Test::Unit,
+Minitest, or Cucumber, you can install it directly:
+
+
geminstallrspec-expectations
+
+
+
Basic usage
+
+
Here's an example using rspec-core:
+
+
RSpec.describeOrderdo
+ it"sums the prices of the items in its line items"do
+ order=Order.new
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(1.11,:USD)
+ )))
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(2.22,:USD),
+ :quantity=>2
+ )))
+ expect(order.total).toeq(Money.new(5.55,:USD))
+ end
+end
+
+
+
The describe and it methods come from rspec-core. The Order, LineItem, Item and Money classes would be from your code. The last line of the example
+expresses an expected outcome. If order.total == Money.new(5.55, :USD), then
+the example passes. If not, it fails with a message like:
Note: The new expect syntax no longer supports the =~ matcher.
+
+
Types/classes
+
+
expect(actual).tobe_an_instance_of(expected)# passes if actual.class == expected
+expect(actual).tobe_a(expected)# passes if actual.is_a?(expected)
+expect(actual).tobe_an(expected)# an alias for be_a
+expect(actual).tobe_a_kind_of(expected)# another alias
+
+
+
Truthiness
+
+
expect(actual).tobe_truthy# passes if actual is truthy (not nil or false)
+expect(actual).tobetrue# passes if actual == true
+expect(actual).tobe_falsy# passes if actual is falsy (nil or false)
+expect(actual).tobefalse# passes if actual == false
+expect(actual).tobe_nil# passes if actual is nil
+
expect{|b|5.tap(&b)}.toyield_control# passes regardless of yielded args
+
+expect{|b|yield_if_true(true,&b)}.toyield_with_no_args# passes only if no args are yielded
+
+expect{|b|5.tap(&b)}.toyield_with_args(5)
+expect{|b|5.tap(&b)}.toyield_with_args(Fixnum)
+expect{|b|"a string".tap(&b)}.toyield_with_args(/str/)
+
+expect{|b|[1,2,3].each(&b)}.toyield_successive_args(1,2,3)
+expect{|b|{:a=>1,:b=>2}.each(&b)}.toyield_successive_args([:a,1],[:b,2])
+
+
+
Predicate matchers
+
+
expect(actual).tobe_xxx# passes if actual.xxx?
+expect(actual).tohave_xxx(:arg)# passes if actual.has_xxx?(:arg)
+
+
+
Ranges (Ruby >= 1.9 only)
+
+
expect(1..10).tocover(3)
+
+
+
Collection membership
+
+
expect(actual).toinclude(expected)
+expect(actual).tostart_with(expected)
+expect(actual).toend_with(expected)
+
+expect(actual).tocontain_exactly(individual,items)
+# ...which is the same as:
+expect(actual).tomatch_array(expected_array)
+
Many of the built-in matchers are designed to take matchers as
+arguments, to allow you to flexibly specify only the essential
+aspects of an object or data structure. In addition, all of the
+built-in matchers have one or more aliases that provide better
+phrasing for when they are used as arguments to another matcher.
If you want to use rspec-expectations with rspec, just install the rspec gem
+and RubyGems will also install rspec-expectations for you (along with
+rspec-core and rspec-mocks):
+
+
geminstallrspec
+
+
+
If you want to use rspec-expectations with another tool, like Test::Unit,
+Minitest, or Cucumber, you can install it directly:
+
+
geminstallrspec-expectations
+
+
+
Basic usage
+
+
Here's an example using rspec-core:
+
+
RSpec.describeOrderdo
+ it"sums the prices of the items in its line items"do
+ order=Order.new
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(1.11,:USD)
+ )))
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(2.22,:USD),
+ :quantity=>2
+ )))
+ expect(order.total).toeq(Money.new(5.55,:USD))
+ end
+end
+
+
+
The describe and it methods come from rspec-core. The Order, LineItem, Item and Money classes would be from your code. The last line of the example
+expresses an expected outcome. If order.total == Money.new(5.55, :USD), then
+the example passes. If not, it fails with a message like:
Note: The new expect syntax no longer supports the =~ matcher.
+
+
Types/classes
+
+
expect(actual).tobe_an_instance_of(expected)# passes if actual.class == expected
+expect(actual).tobe_a(expected)# passes if actual.is_a?(expected)
+expect(actual).tobe_an(expected)# an alias for be_a
+expect(actual).tobe_a_kind_of(expected)# another alias
+
+
+
Truthiness
+
+
expect(actual).tobe_truthy# passes if actual is truthy (not nil or false)
+expect(actual).tobetrue# passes if actual == true
+expect(actual).tobe_falsy# passes if actual is falsy (nil or false)
+expect(actual).tobefalse# passes if actual == false
+expect(actual).tobe_nil# passes if actual is nil
+
expect{|b|5.tap(&b)}.toyield_control# passes regardless of yielded args
+
+expect{|b|yield_if_true(true,&b)}.toyield_with_no_args# passes only if no args are yielded
+
+expect{|b|5.tap(&b)}.toyield_with_args(5)
+expect{|b|5.tap(&b)}.toyield_with_args(Fixnum)
+expect{|b|"a string".tap(&b)}.toyield_with_args(/str/)
+
+expect{|b|[1,2,3].each(&b)}.toyield_successive_args(1,2,3)
+expect{|b|{:a=>1,:b=>2}.each(&b)}.toyield_successive_args([:a,1],[:b,2])
+
+
+
Predicate matchers
+
+
expect(actual).tobe_xxx# passes if actual.xxx?
+expect(actual).tohave_xxx(:arg)# passes if actual.has_xxx?(:arg)
+
+
+
Ranges (Ruby >= 1.9 only)
+
+
expect(1..10).tocover(3)
+
+
+
Collection membership
+
+
expect(actual).toinclude(expected)
+expect(actual).tostart_with(expected)
+expect(actual).toend_with(expected)
+
+expect(actual).tocontain_exactly(individual,items)
+# ...which is the same as:
+expect(actual).tomatch_array(expected_array)
+
Many of the built-in matchers are designed to take matchers as
+arguments, to allow you to flexibly specify only the essential
+aspects of an object or data structure. In addition, all of the
+built-in matchers have one or more aliases that provide better
+phrasing for when they are used as arguments to another matcher.
The legacy :should syntax adds the following methods directly
+to BasicObject so that they are available off of any object.
+Note, however, that this syntax does not always play nice with
+delegate/proxy objects. We recommend you use the non-monkeypatching
+:expect syntax instead.
This is only available when you have enabled the should
+syntax.
+
+
+
+
+
Stubs a chain of methods.
+
+
Warning:
+
+
Chains can be arbitrarily long, which makes it quite painless to violate
+the Law of Demeter in violent ways, so you should consider any use of
+stub_chain a code smell. Even though not all code smells
+indicate real problems (think fluent interfaces), stub_chain
+still results in brittle examples. For example, if you write
+foo.stub_chain(:bar, :baz => 37) in a spec and then the
+implementation calls foo.baz.bar, the stub will not work.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+double.stub_chain("foo.bar"){:baz}
+double.stub_chain(:foo,:bar=>:baz)
+double.stub_chain(:foo,:bar){:baz}
+
+# Given any of ^^ these three forms ^^:
+double.foo.bar# => :baz
+
+# Common use in Rails/ActiveRecord:
+Article.stub_chain("recent.published"){[Article.new]}
This is only available when you have enabled the should
+syntax.
+
+
+
+
+
Removes a stub. On a double, the object will no longer respond to
+message. On a real object, the original method (if it exists)
+is restored.
+
+
This is rarely used, but can be useful when a stub is set up during a
+shared before hook for the common case, but you want to
+replace it for a special case.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/mocks/syntax.rb', line 243
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-mocks/Class.html b/source/documentation/3.0/rspec-mocks/Class.html
new file mode 100644
index 000000000..27381f6b3
--- /dev/null
+++ b/source/documentation/3.0/rspec-mocks/Class.html
@@ -0,0 +1,271 @@
+
+
+
+
+
+ Class: Class
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
The legacy :should syntax adds the any_instance
+to Class. We generally recommend you use the newer
+:expect syntax instead, which allows you to stub any instance
+of a class using allow_any_instance_of(klass) or mock any
+instance using expect_any_instance_of(klass).
Used to set stubs and message expectations on any instance of a given
+class.
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (Recorder) any_instance
+
+
+
+
+
+
+
+
+
+ Note:
+
+
This is only available when you have enabled the should
+syntax.
+
+
+
+
+
Used to set stubs and message expectations on any instance of a given
+class. Returns a Recorder, which records messages
+like stub and should_receive for later playback
+on instances of the class.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+Car.any_instance.should_receive(:go)
+race=Race.new
+race.cars<<Car.new
+race.go# assuming this delegates to all of its cars
+# this example would pass
+
+Account.any_instance.stub(:balance){Money.new(:USD,25)}
+Account.new.balance# => Money.new(:USD, 25))
Contains top-level utility methods. While this contains a few public
+methods, these are not generally meant to be called from a test or example.
+They exist primarily for integration with test frameworks (such as
+rspec-core).
Expect the message foo to receive bar, then call
+it
+
+
+
RSpec::Mocks.expect_message(bar,:foo)
+bar.foo
+
+
+
Parameters:
+
+
+
+
+ subject
+
+
+
+
+
+
+ —
+
+
the subject on which the message will be expected
+
+
+
+
+
+
+ message
+
+
+
+
+
+
+ —
+
+
a symbol, representing the message that will be expected.
+
+
+
+
+
+
+ opts
+
+
+
+
+
+ (defaults to: {})
+
+
+ —
+
+
a hash of options, :expected_from is used to set the original call site
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+
+
+
+
+
+
+
an optional implementation for the expectation
+
+
+
+
+
+
+
+
+
+
+
+
+84
+85
+86
+
+
+
# File 'lib/rspec/mocks.rb', line 84
+
+defself.expect_message(subject,message,opts={},&block)
+ space.proxy_for(subject).add_message_expectation(message,opts,&block)
+end
+
+
+
+
+
+
+
+
+ + (Object) setup
+
+
+
+
+
+
+
+
+
Performs per-test/example setup. This should be called before an test or
+example begins.
+
+
+
+
+
+
+
+
+
+
+
+
+
+38
+39
+40
+
+
+
# File 'lib/rspec/mocks.rb', line 38
+
+defself.setup
+ @space_stack<<(@space=space.new_scope)
+end
+
+
+
+
+
+
+
+
+ + (Object) teardown
+
+
+
+
+
+
+
+
+
Cleans up all test double state (including any methods that were redefined
+on partial doubles). This must be called after each example, even
+if an error was raised during the example.
Can also be used directly to match the contents of any Array.
+This enables 3rd party mocking libs to take advantage of rspec's
+argument matching without using the rest of rspec-mocks.
Adds stub and should_receive to the given modules
+or classes. This is usually only necessary if you application uses some
+proxy classes that “strip themselves down” to a bare minimum set of methods
+and remove stub and should_receive in the
+process.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|rspec|
+ rspec.mock_with:rspecdo|mocks|
+ mocks.add_stub_and_should_receive_toDelegator
+ end
+end
+
+
+
+
+
+
+
+
+
+
+48
+49
+50
+51
+52
+
+
+
# File 'lib/rspec/mocks/configuration.rb', line 48
+
+defadd_stub_and_should_receive_to(*modules)
+ modules.eachdo|mod|
+ Syntax.enable_should(mod)
+ end
+end
Monkey-patch Marshal.dump to enable dumping of mocked or
+stubbed objects. By default this will not work since RSpec mocks works by
+adding singleton methods that cannot be serialized. This patch removes
+these singleton methods before serialization. Setting to falsey removes the
+patch.
+
+
This method is idempotent.
+
+
+
+
+
+
+
+
+
+
+
+
+
+140
+141
+142
+143
+144
+145
+146
+
+
+
# File 'lib/rspec/mocks/configuration.rb', line 140
+
+defpatch_marshal_to_support_partial_doubles=(val)
+ ifval
+ RSpec::Mocks::MarshalExtension.patch!
+ else
+ RSpec::Mocks::MarshalExtension.unpatch!
+ end
+end
Provides the ability to set either expect, should
+or both syntaxes. RSpec uses expect syntax by default. This is
+needed if you want to explicitly enable should syntax and/or
+explicitly disable expect syntax.
+
+
end
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configure do |rspec|
+ rspec.mock_with :rspec do |mocks|
+ mocks.syntax = [:expect, :should]
+ end
When this is set to true, an error will be raised when
+instance_double or class_double is given the name
+of an undefined constant. You probably only want to set this when running
+your entire test suite, with all production code loaded. Setting this for
+an isolated unit test will prevent you from being able to isolate it!
+
+
+
+
+
+
+
+
+
+
+
+
+
+108
+109
+110
+
+
+
# File 'lib/rspec/mocks/configuration.rb', line 108
+
+defverify_doubled_constant_names=(val)
+ @verify_doubled_constant_names=val
+end
When set to true, partial mocks will be verified the same as object
+doubles. Any stubs will have their arguments checked against the original
+method, and methods that do not exist cannot be stubbed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+125
+126
+127
+
+
+
# File 'lib/rspec/mocks/configuration.rb', line 125
+
+defverify_partial_doubles=(val)
+ @verify_partial_doubles=!!val
+end
Sets whether or not RSpec will yield the receiving instance of a message to
+blocks that are used for any_instance stub implementations. When set, the
+first yielded argument will be the receiving instance. Defaults to
+true.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|rspec|
+ rspec.mock_with:rspecdo|mocks|
+ mocks.yield_receiver_to_any_instance_implementation_blocks=false
+ end
+end
+
+
+
+
+
+
+
+
+
+
+29
+30
+31
+
+
+
# File 'lib/rspec/mocks/configuration.rb', line 29
+
+defyield_receiver_to_any_instance_implementation_blocks=(arg)
+ @yield_receiver_to_any_instance_implementation_blocks=arg
+end
Used internally by the constant stubbing to raise a helpful error when a
+constant like “A::B::C” is stubbed and A::B is not a module (and thus,
+it's impossible to define “A::B::C” since only modules can have nested
+constants).
It's recommended that you use hide_const in your examples.
+This is an alternate public API that is provided so you can hide constants
+in other contexts (e.g. helper classes).
+
+
+
+
+
Hides a constant.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ constant_name
+
+
+ (String)
+
+
+
+ —
+
+
The fully qualified name of the constant. The current constant scoping at
+the point of call is not considered.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
Used internally by the constant stubbing to raise a helpful error when a
+constant like “A::B::C” is stubbed and A::B is not a module (and thus,
+it's impossible to define “A::B::C” since only modules can have nested
+constants).
+
+
+
+
+
+
+
+
+
+
+
+
+
+390
+391
+392
+393
+394
+395
+
+
+
# File 'lib/rspec/mocks/mutate_const.rb', line 390
+
+defself.raise_on_invalid_const
+ lambdado|const_name,failed_name|
+ raise"Cannot stub constant #{failed_name} on #{const_name}"+
+ "since #{const_name} is not a module."
+ end
+end
It's recommended that you use stub_const in your examples.
+This is an alternate public API that is provided so you can stub constants
+in other contexts (e.g. helper classes).
+
+
+
+
+
Stubs a constant.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ constant_name
+
+
+ (String)
+
+
+
+ —
+
+
The fully qualified name of the constant. The current constant scoping at
+the point of call is not considered.
+
+
+
+
+
+
+ value
+
+
+ (Object)
+
+
+
+ —
+
+
The value to make the constant refer to. When the example completes, the
+constant will be restored to its prior state.
Determines what nested constants, if any, will be transferred from the
+original value of the constant to the new value of the constant. This only
+works if both the original and new values are modules (or classes).
Contains methods intended to be used from within code examples. Mix this in
+to your test context (such as a test framework base class) to use
+rspec-mocks with your test framework. If you're using rspec-core,
+it'll take care of doing this for you.
Constructs an instance of :Mocks::Double
+configured with an optional name, used for reporting in failure messages,
+and an optional hash of message/return-value pairs.
Constructs a test double against a specific class. If the given class name
+has been loaded, only class methods defined on the class are allowed to be
+stubbed. In all other ways it behaves like a double.
Constructs an instance of :Mocks::Double
+configured with an optional name, used for reporting in failure messages,
+and an optional hash of message/return-value pairs.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+book=double("book",:title=>"The RSpec Book")
+book.title#=> "The RSpec Book"
+
+card=double("card",:suit=>"Spades",:rank=>"A")
+card.suit#=> "Spades"
+card.rank#=> "A"
# File 'lib/rspec/mocks/example_methods.rb', line 35
+
+defdouble(*args)
+ ExampleMethods.declare_double(Double,*args)
+end
+
+
+
+
+
+
+
+
+ - (Object) expect
+
+
+
+
+
+
+
+
+
+ Note:
+
+
This method is usually provided by rspec-expectations. However, if you use
+rspec-mocks without rspec-expectations, there's a definition of it that
+is made available here. If you disable the :expect syntax this
+method will be undefined.
+
+
+
+
+
Used to wrap an object in preparation for setting a mock expectation on it.
Verifies that the given object received the expected message during the
+course of the test. The method must have previously been stubbed in order
+for messages to be verified.
+
+
Stubbing and verifying messages received in this way implements the Test
+Spy pattern.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+invitation=double('invitation',accept:true)
+user.accept_invitation(invitation)
+expect(invitation).tohave_received(:accept)
+
+# You can also use most message expectations:
+expect(invitation).tohave_received(:accept).with(mailer).once
+
+
+
Parameters:
+
+
+
+
+ method_name
+
+
+ (Symbol)
+
+
+
+ —
+
+
name of the method expected to have been called.
+
+
+
+
+
+
+
+
+
+
+
+
+
+171
+172
+173
+
+
+
# File 'lib/rspec/mocks/example_methods.rb', line 171
+
+defhave_received(method_name,&block)
+ Matchers::HaveReceived.new(method_name,&block)
+end
Constructs a test double against a specific class. If the given class name
+has been loaded, only instance methods defined on the class are allowed to
+be stubbed. In all other ways it behaves like a double.
Constructs a test double against a specific object. Only the methods the
+object responds to are allowed to be stubbed. If a String argument is
+provided, it is assumed to reference a constant object which is used for
+verification. In all other ways it behaves like a double.
If you disable the :expect syntax this method will be
+undefined.
+
+
+
+
+
Used to specify a message that you expect or allow an object to receive.
+The object returned by receive supports the same fluent
+interface that should_receive and stub have
+always supported, allowing you to constrain the arguments or number of
+times, and configure how the object should respond to the message.
If you disable the :expect syntax this method will be
+undefined.
+
+
+
+
+
stubs/mocks a chain of messages on an object or test double.
+
+
Warning:
+
+
Chains can be arbitrarily long, which makes it quite painless to violate
+the Law of Demeter in violent ways, so you should consider any use of
+receive_message_chain a code smell. Even though not all code
+smells indicate real problems (think fluent interfaces),
+receive_message_chain still results in brittle examples. For
+example, if you write allow(foo).to receive_message_chain(:bar, :baz
+=> 37) in a spec and then the implementation calls
+foo.baz.bar, the stub will not work.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+allow(double).toreceive_message_chain("foo.bar"){:baz}
+allow(double).toreceive_message_chain(:foo,:bar=>:baz)
+allow(double).toreceive_message_chain(:foo,:bar){:baz}
+
+# Given any of ^^ these three forms ^^:
+double.foo.bar# => :baz
+
+# Common use in Rails/ActiveRecord:
+allow(Article).toreceive_message_chain("recent.published"){[Article.new]}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/mocks/example_methods.rb', line 245
+
+
+
+
+
+
+
+
+
+
+ - (Object) receive_messages
+
+
+
+
+
+
+
+
+
+ Note:
+
+
If you disable the :expect syntax this method will be
+undefined.
+
+
+
+
+
Shorthand syntax used to setup message(s), and their return value(s), that
+you expect or allow an object to receive. The method takes a hash of
+messages and their respective return values. Unlike with
+receive, you cannot apply further customizations using a block
+or the fluent interface.
Stubs the named constant with the given value. Like method stubs, the
+constant will be restored to its original value (or lack of one, if it was
+undefined) when the example completes.
Determines what nested constants, if any, will be transferred from the
+original value of the constant to the new value of the constant. This only
+works if both the original and new values are modules (or classes).
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Object)
+
+
+
+ —
+
+
the stubbed value of the constant
+
+
+
+
+
+
+
+
+
+
+
+
+133
+134
+135
+
+
+
# File 'lib/rspec/mocks/example_methods.rb', line 133
+
+defstub_const(constant_name,value,options={})
+ ConstantMutator.stub(constant_name,value,options)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-mocks/RSpec/Mocks/ExampleMethods/ExpectHost.html b/source/documentation/3.0/rspec-mocks/RSpec/Mocks/ExampleMethods/ExpectHost.html
new file mode 100644
index 000000000..e94e4d649
--- /dev/null
+++ b/source/documentation/3.0/rspec-mocks/RSpec/Mocks/ExampleMethods/ExpectHost.html
@@ -0,0 +1,117 @@
+
+
+
+
+
+ Module: RSpec::Mocks::ExampleMethods::ExpectHost
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/mocks/syntax.rb', line 181
+
+defself.default_should_syntax_host
+ # JRuby 1.7.4 introduces a regression whereby `defined?(::BasicObject) => nil`
+# yet `BasicObject` still exists and patching onto ::Object breaks things
+# e.g. SimpleDelegator expectations won't work
+#
+# See: https://github.com/jruby/jruby/issues/814
+ifdefined?(JRUBY_VERSION)&&JRUBY_VERSION=='1.7.4'&&RUBY_VERSION.to_f>1.8
+ return::BasicObject
+ end
+
+ # On 1.8.7, Object.ancestors.last == Kernel but
+# things blow up if we include `RSpec::Mocks::Methods`
+# into Kernel...not sure why.
+returnObjectunlessdefined?(::BasicObject)
+
+ # MacRuby has BasicObject but it's not the root class.
+returnObjectunlessObject.ancestors.last==::BasicObject
+
+ ::BasicObject
+end
Implements the methods needed for a pure test double. RSpec::Mocks::Double
+includes this module, and it is provided for cases where you want a pure
+test double without subclassing RSpec::Mocks::Double.
# File 'lib/rspec/mocks/test_double.rb', line 73
+
+defmethod_missing(message,*args,&block)
+ proxy=__mock_proxy
+ proxy.record_message_received(message,*args,&block)
+
+ ifproxy.null_object?
+ casemessage
+ when:to_intthenreturn0
+ when:to_a,:to_arythenreturnnil
+ when:to_strthenreturnto_s
+ elsereturnself
+ end
+ end
+
+ # Defined private and protected methods will still trigger `method_missing`
+# when called publicly. We want ruby's method visibility error to get raised,
+# so we simply delegate to `super` in that case.
+# ...well, we would delegate to `super`, but there's a JRuby
+# bug, so we raise our own visibility error instead:
+# https://github.com/jruby/jruby/issues/1398
+visibility=proxy.visibility_for(message)
+ ifvisibility==:private||visibility==:protected
+ ErrorGenerator.new(self,@name).raise_non_public_error(
+ message,visibility
+ )
+ end
+
+ # Required wrapping doubles in an Array on Ruby 1.9.2
+raiseNoMethodErrorif[:to_a,:to_ary].include?message
+ proxy.raise_unexpected_message_error(message,*args)
+end
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (Object) ==(other)
+
+
+
+
+
+
+
+
+
This allows for comparing the mock to other objects that proxy such as
+ActiveRecords belongs_to proxy objects. By making the other object run the
+comparison, we're sure the call gets delegated to the proxy target.
+
+
+
+
+
+
+
+
+
+
+
+
+
+36
+37
+38
+
+
+
# File 'lib/rspec/mocks/test_double.rb', line 36
+
+def==(other)
+ other==__mock_proxy
+end
+
+
+
+
+
+
+
+
+ - (Object) as_null_object
+
+
+
+
+
+
+
+
+
Tells the object to respond to all messages. If specific stub values are
+declared, they'll work as expected. If not, the receiver is returned.
+
+
+
+
+
+
+
+
+
+
+
+
+
+23
+24
+25
+
+
+
# File 'lib/rspec/mocks/test_double.rb', line 23
+
+defas_null_object
+ __mock_proxy.as_null_object
+end
+
+
+
+
+
+
+
+
+ - (Object) freeze
+
+
+
+
+
+
+
+
+
Override for default freeze implementation to prevent freezing of test
+doubles.
+
+
+
+
+
+
+
+
+
+
+
+
+
+67
+68
+69
+
+
+
# File 'lib/rspec/mocks/test_double.rb', line 67
+
+deffreeze
+ RSpec.warn_with("WARNING: you attempted to freeze a test double. This is explicitly a no-op as freezing doubles can lead to undesired behaviour when resetting tests.")
+end
+ This class is part of a private API.
+ You should avoid using this class if possible, as it may be removed or be changed in the future.
+
+
+
A message expectation that knows about the real implementation of the
+message being expected, so that it can verify that any expectations have
+the valid arguments.
A level of indirection is used here rather than just passing in the method
+itself, since method look up is expensive and we only want to do it if
+actually needed.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
Returns a new instance of VerifyingMessageExpectation
+
+
+
+
+
+
+
+
+
+
+
+
+
+22
+23
+24
+
+
+
# File 'lib/rspec/mocks/verifying_message_expecation.rb', line 22
+
+definitialize(*args)
+ super
+end
+
+
+
+
+
+
+
+
+
Instance Attribute Details
+
+
+
+
+
+
+ - (Object) method_reference
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
A level of indirection is used here rather than just passing in the method
+itself, since method look up is expensive and we only want to do it if
+actually needed.
+
+
Conceptually the method reference makes more sense as a constructor
+argument since it should be immutable, but it is significantly more
+straight forward to build the object in pieces so for now it stays as an
+accessor.
+
+
+
+
+
+
+
+
+
+
+
+
+
+20
+21
+22
+
+
+
# File 'lib/rspec/mocks/verifying_message_expecation.rb', line 20
+
+defmethod_reference
+ @method_reference
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-mocks/RSpec/Mocks/Version.html b/source/documentation/3.0/rspec-mocks/RSpec/Mocks/Version.html
new file mode 100644
index 000000000..e1547e84e
--- /dev/null
+++ b/source/documentation/3.0/rspec-mocks/RSpec/Mocks/Version.html
@@ -0,0 +1,139 @@
+
+
+
+
+
+ Module: RSpec::Mocks::Version
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Fix edge case that triggered “can't add a new key into hash during
+iteration” during mock verification. (Sam Phippen, Myron Marston, #711)
+
+
Fix verifying doubles so that when they accidentally leak into another
+example, they provide the same clear error message that normal doubles do.
+(Myron Marston, #718)
+
+
Make ordered work with exact receive counts. (Sam Phippen,
+#713)
Fix module prepend detection to work properly on ruby 2.0 for a case where
+a module is extended onto itself. (Myron Marston)
+
+
Fix transfer_nested_constants option so that transferred
+constants get properly reset at the end of the example. (Myron Marston)
+
+
Fix config.transfer_nested_constants = true so that you
+don't erroneously get errors when stubbing a constant that is not a
+module or a class. (Myron Marston)
+
+
Fix regression that caused double(:class => SomeClass) to
+later trigger infinite recursion. (Myron Marston)
+
+
Fix bug in have_received(...).with(...).ordered where it was
+not taking the args into account when checking the order. (Myron Marston)
+
+
Fix bug in have_received(...).ordered where it was wrongly
+considering stubs when checking the order. (Myron Marston)
+
+
Message expectation matchers now show descriptions from argument matchers
+when their expectations aren't met. (Jon Rowe)
+
+
Display warning when encountering TypeError during instance
+method staging on 2.0.0-p195, suffers from bugs.ruby-lang.org/issues/8686
+too. (Cezar Halmagean).
Make monkey-patch of Marshal to support dumping of stubbed objects opt-in.
+(Xavier Shay)
+
+
+
Enhancements:
+
+
Instead of crashing when cleaning up stub methods on a frozen object, it
+now issues a warning explaining that it's impossible to clean up the
+stubs. (Justin Coyne and Sam Phippen)
+
+
Add meaningful descriptions to anything,
+duck_type and instance_of argument matchers.
+(Jon Rowe)
+
+
+
Bug Fixes:
+
+
Fix regression introduced in 3.0.0.beta2 that caused
+double.as_null_object.to_str to return the double rather than
+a string. (Myron Marston)
+
+
Fix bug in expect(dbl).to receive_message_chain(:foo, :bar)
+where it was not setting an expectation for the last message in the chain.
+(Jonathan del Strother)
+
+
Allow verifying partial doubles to have private methods stubbed. (Xavier
+Shay)
+
+
Fix bug with allowing/expecting messages on Class objects which have had
+their singleton class prepended to. (Jon Rowe)
+
+
Fix an issue with 1.8.7 not running implementation blocks on partial
+doubles. (Maurício Linhares)
+
+
Prevent StackLevelTooDeep errors when stubbing an
+any_instance method that's accessed in
+inspect by providing our own inspect output. (Jon Rowe)
+
+
Fix bug in any_instance logic that did not allow you to mock
+or stub private methods if verify_partial_doubles was
+configured. (Oren Dobzinski)
+
+
Include useful error message when trying to observe an unimplemented method
+on an any instance. (Xavier Shay)
+
+
Fix and_call_original to work properly when multiple classes
+in an inheritance hierarchy have been stubbed with the same method. (Myron
+Marston)
+
+
Fix any_instance so that it updates existing instances that
+have already been stubbed. (Myron Marston)
+
+
Fix verified doubles so that their class name is included in failure
+messages. (Myron Marston)
+
+
Fix expect_any_instance_of so that when the message is
+received on an individual instance that has been directly stubbed, it
+still satisfies the expectation. (Sam Phippen, Myron Marston)
+
+
Explicitly disallow using any_instance to mock or stub a
+method that is defined on a module prepended onto the class. This
+triggered SystemStackError before and is very hard to support
+so we are not supporting it at this time. (Myron Marston)
Rename RSpec::Mocks::Mock to
+RSpec::Mocks::Double. (Myron Marston)
+
+
Change how to integrate rspec-mocks in other test frameworks. You now need
+to include RSpec::Mocks::ExampleMethods in your test context.
+(Myron Marston)
+
+
Prevent RSpec mocks' doubles and partial doubles from being used
+outside of the per-test lifecycle (e.g. from a before(:all)
+hook). (Sam Phippen)
+
+
Remove the host argument of RSpec::Mocks.setup.
+Instead RSpec::Mocks::ExampleMethods should be included
+directly in the scope where RSpec's mocking capabilities are used.
+(Sam Phippen)
+
+
Make test doubles raise errors if you attempt to use them after they get
+reset, to help surface issues when you accidentally retain references to
+test doubles and attempt to reuse them in another example. (Myron Marston)
+
+
Remove support for and_return { value } and
+and_return without arguments. (Yuji Nakayama)
+
+
+
Enhancements:
+
+
Add receive_message_chain which provides the functionality of
+the old stub_chain for the new allow/expect syntax. Use it
+like so: allow(...).to receive_message_chain(:foo, :bar,
+:bazz). (Sam Phippen).
+
+
Change argument matchers to use === as their primary matching
+protocol, since their semantics mirror that of a case or rescue statement
+(which uses === for matching). (Myron Marston)
+
+
Add RSpec::Mocks.with_temporary_scope, which allows you to
+create temporary rspec-mocks scopes in arbitrary places (such as a
+before(:all) hook). (Myron Marston)
+
+
Support keyword arguments when checking arity with verifying doubles.
+(Xavier Shay)
+
+
+
Bug Fixes:
+
+
Fix regression in 3.0.0.beta1 that caused
+double("string_name" => :value) to stop working.
+(Xavier Shay)
+
+
Fix the way rspec-mocks and rspec-core interact so that if users define a
+let with the same name as one of the methods from
+RSpec::Mocks::ArgumentMatchers, the user's
+let takes precedence. (Michi Huber, Myron Marston)
+
+
Fix verified doubles so that their methods match the visibility (public,
+protected or private) of the interface they verify against. (Myron
+Marston)
+
+
Fix verified null object doubles so that they do not wrongly report that
+they respond to anything. They only respond to methods available on the
+interface they verify against. (Myron Marston)
+
+
Fix deprecation warning for use of old :should syntax w/o
+explicit config so that it no longer is silenced by an extension gem such
+as rspec-rails when it calls
+config.add_stub_and_should_receive_to. (Sam Phippen)
+
+
Fix expect syntax so that it does not wrongly emit a
+“You're overriding a previous implementation for this stub” warning
+when you are not actually doing that. (Myron Marston)
+
+
Fix any_instance.unstub when used on sub classes for whom the
+super class has had any_instance.stub invoked on. (Jon Rowe)
+
+
Fix regression in
+stub_chain/receive_message_chain that caused it
+to raise an ArgumentError when passing args to the stubbed
+methods. (Sam Phippen)
+
+
Correct stub of undefined parent modules all the way down when stubbing a
+nested constant. (Xavier Shay)
+
+
Raise VerifyingDoubleNotDefinedError when a constant is not
+defined for a verifying class double. (Maurício Linhares)
+
+
Remove Double#to_str, which caused confusing raise
+some_double behavior. (Maurício Linhares)
Raise an explicit error if should_not_receive(...).and_return
+is used. (Sam Phippen)
+
+
Remove 1.8.6 workarounds. (Jon Rowe)
+
+
Remove stub! and unstub!. (Sam Phippen)
+
+
Remove mock(name, methods) and stub(name,
+methods), leaving double(name, methods) for creating
+test doubles. (Sam Phippen, Michi Huber)
+
+
Remove any_number_of_times since
+should_receive(:msg).any_number_of_times is really a stub in
+a mock's clothing. (Sam Phippen)
+
+
Remove support for re-using the same null-object test double in multiple
+examples. Test doubles are designed to only live for one example. (Myron
+Marston)
+
+
Make at_least(0) raise an error. (Sam Phippen)
+
+
Remove support for require 'spec/mocks' which had been
+kept in place for backwards compatibility with RSpec 1. (Myron Marston)
+
+
Blocks provided to with are always used as implementation.
+(Xavier Shay)
+
+
The config option (added in 2.99) to yield the receiver to
+any_instance implementation blocks now defaults to “on”. (Sam
+Phippen)
+
+
+
Enhancements:
+
+
Allow the have_received matcher to use a block to set further
+expectations on arguments. (Tim Cowlishaw)
+
+
Provide instance_double and class_double to
+create verifying doubles, ported from rspec-fire. (Xavier
+Shay)
+
+
as_null_object on a verifying double only responds to defined
+methods. (Xavier Shay)
+
+
Provide object_double to create verified doubles of specific
+object instances. (Xavier Shay)
+
+
Provide verify_partial_doubles configuration that provides
+object_double like verification behaviour on partial doubles.
+(Xavier Shay)
+
+
Improved performance of double creation, particularly those with many
+attributes. (Xavier Shay)
+
+
Default value of transfer_nested_constants option for constant
+stubbing can be configured. (Xavier Shay)
+
+
Messages can be allowed or expected on in bulk via
+receive_messages(:message => :value). (Jon Rowe)
+
+
allow(Klass.any_instance) and
+expect(Klass.any_instance) now print a warning. This is
+usually a mistake, and users usually want
+allow_any_instance_of or expect_any_instance_of
+instead. (Sam Phippen)
+
+
instance_double and class_double raise
+ArgumentError if the underlying module is loaded and the
+arity of the method being invoked does not match the arity of the method
+as it is actually implemented. (Andy Lindeman)
+
+
Spies can now check their invocation ordering is correct. (Jon Rowe)
+
+
+
Deprecations:
+
+
Using the old :should syntax without explicitly configuring it
+is deprecated. It will continue to work but will emit a deprecation
+warning in RSpec 3 if you do not explicitly enable it. (Sam Phippen)
+
+
+
Bug Fixes:
+
+
Fix and_call_original to handle a complex edge case involving
+singleton class ancestors. (Marc-André Lafortune, Myron Marston)
+
+
When generating an error message for unexpected arguments, use
+#inspect rather than #description if
+#description returns nil or
+'' so that you still get a useful message. (Nick
+DeLuca)
Deprecate RSpec::Mocks::Mock in favor of
+RSpec::Mocks::Double. (Myron Marston)
+
+
Deprecate the host argument of
+RSpec::Mocks.setup. Instead
+RSpec::Mocks::ExampleMethods should be included directly in
+the scope where RSpec's mocking capabilities are used. (Sam Phippen)
+
+
Deprecate using any of rspec-mocks' features outside the per-test
+lifecycle (e.g. from a before(:all) hook). (Myron Marston)
+
+
Deprecate re-using a test double in another example. (Myron Marston)
+
+
Deprecate and_return { value } and and_return
+without arguments. (Yuji Nakayama)
Expecting to use lambdas or other strong arity implementations for stub
+methods with mis-matched arity is deprecated and support for them will be
+removed in 3.0. Either provide the right amount of arguments or use a weak
+arity implementation (methods with splats or procs). (Jon Rowe)
+
+
Using the same test double instance in multiple examples is deprecated.
+Test doubles are only meant to live for one example. The mocks and stubs
+have always been reset between examples; however, in 2.x the
+as_null_object state was not reset and some users relied on
+this to have a null object double that is used for many examples. This
+behavior will be removed in 3.0. (Myron Marston)
+
+
Print a detailed warning when an any_instance implementation
+block is used when the new
+yield_receiver_to_any_instance_implementation_blocks config
+option is not explicitly set, as RSpec 3.0 will default to enabling this
+new feature. (Sam Phippen)
+
+
+
Enhancements:
+
+
Add a config option to yield the receiver to any_instance
+implementation blocks. (Sam Phippen)
Fix regression that caused block implementations to not receive all args
+on 1.8.7 if the block also receives a block, due to Proc#arity reporting
+1 no matter how many args the block receives if it receives a
+block, too. (Myron Marston)
Restore double.as_null_object behavior from 2.13 and earlier:
+a double's nullness persisted between examples in earlier examples.
+While this is not an intended use case (test doubles are meant to live for
+only one example), we don't want to break behavior users rely on in a
+minor relase. This will be deprecated in 2.99 and removed in 3.0. (Myron
+Marston)
Document test spies in the readme. (Adarsh Pandit)
+
+
Add an array_including matcher. (Sam Phippen)
+
+
Add a syntax-agnostic API for mocking or stubbing a method. This is
+intended for use by libraries such as rspec-rails that need to mock or
+stub a method, and work regardless of the syntax the user has configured
+(Paul Annesley, Myron Marston and Sam Phippen).
+
+
+
Bug Fixes:
+
+
Fix double so that it sets up passed stubs correctly
+regardless of the configured syntax (Paul Annesley).
+
+
Allow a block implementation to be used in combination with
+and_yield, and_raise, and_return or
+and_throw. This got fixed in 2.13.1 but failed to get merged
+into master for the 2.14.0.rc1 release (Myron Marston).
+
+
Marshal.dump does not unnecessarily duplicate objects when
+rspec-mocks has not been fully initialized. This could cause errors when
+using spork or similar preloading gems (Andy Lindeman).
Refactor internals so that the mock proxy methods and state are held
+outside of the mocked object rather than inside it. This paves the way for
+future syntax enhancements and removes the need for some hacky work
+arounds for any_instance dup'ing and YAML
+serialization, among other things. Note that the code now relies upon
+__id__ returning a unique, consistent value for any object
+you want to mock or stub (Myron Marston).
+
+
Add support for test spies. This allows you to verify a message was
+received afterwards using the have_received matcher. Note
+that you must first stub the method or use a null double. (Joe Ferris and
+Joël Quenneville)
+
+
Make at_least and at_most style receive
+expectations print that they were expecting at least or at most some
+number of calls, rather than just the number of calls given in the
+expectation (Sam Phippen)
+
+
Make with style receive expectations print the args they were
+expecting, and the args that they got (Sam Phippen)
+
+
Fix some warnings seen under ruby 2.0.0p0 (Sam Phippen).
+
+
Add a new :expect syntax for message expectations (Myron
+Marston and Sam Phippen).
+
+
+
Bug fixes
+
+
Fix any_instance so that a frozen object can be
+dup'd when methods have been stubbed on that type using
+any_instance (Jon Rowe).
+
+
Fix and_call_original so that it properly raises an
+ArgumentError when the wrong number of args are passed (Jon
+Rowe).
+
+
Fix double on 1.9.2 so you can wrap them in an Array using
+Array(my_double) (Jon Rowe).
+
+
Fix stub_const and hide_const to handle constants
+that redefine send (Sam Phippen).
+
+
Fix Marshal.dump extension so that it correctly handles nil.
+(Luke Imhoff, Jon Rowe)
+
+
Fix isolation of allow_message_expectations_on_nil (Jon Rowe)
+
+
Use inspect to format actual arguments on expectations in failure messages
+(#280, Ben Langfeld)
+
+
Protect against improperly initialised test doubles (#293) (Joseph
+Shraibman and Jon Rowe)
+
+
+
Deprecations
+
+
Deprecate stub and mock as aliases for
+double. double is the best term for creating a
+test double, and it reduces confusion to have only one term (Michi Huber).
+
+
Deprecate stub! and unstub! in favor of
+stub and unstub (Jon Rowe).
+
+
Deprecate at_least(0).times and
+any_number_of_times (Michi Huber).
Fix bug that caused weird behavior when a method that had previously been
+stubbed with multiple return values (e.g.
+obj.stub(:foo).and_return(1, 2)) was later mocked with a
+single return value (e.g.
+obj.should_receive(:foo).once.and_return(1)). (Myron Marston)
+
+
Fix bug related to a mock expectation for a method that already had
+multiple stubs with different with constraints. Previously,
+the first stub was used, even though it may not have matched the passed
+args. The fix defers this decision until the message is received so that
+the proper stub response can be chosen based on the passed arguments
+(Myron Marston).
+
+
Do not call nil? extra times on a mocked object, in case
+nil? itself is expected a set number of times (Myron
+Marston).
+
+
Fix missing_default_stub_error message so array args are
+handled properly (Myron Marston).
Fix any_instance stubbing so that it works with
+Delegator subclasses (Myron Marston).
+
+
Fix and_call_original so that it works with
+Delegator subclasses (Myron Marston).
+
+
Fix any_instance.should_not_receive when
+any_instance.should_receive is used on the same class in the
+same example. Previously it would wrongly report a failure even when the
+message was not received (Myron Marston).
Fix and_call_original to work properly for methods defined on
+a module extended onto an object instance (Myron Marston).
+
+
Fix stub_const with an undefined constnat name to work
+properly with constant strings that are prefixed with :: –
+and edge case I missed in the bug fix in the 2.12.1 release (Myron
+Marston).
+
+
Ensure method visibility on a partial mock is restored after reseting
+method stubs, even on a singleton module (created via extend
+self) when the method visibility differs between the instance and
+singleton versions (Andy Lindeman).
and_raise can accept an exception class and message, more
+closely matching Kernel#raise (e.g.,
+foo.stub(:bar).and_raise(RuntimeError, "message"))
+(Bas Vodde)
+
+
Add and_call_original, which will delegate the message to the
+original method (Myron Marston).
+
+
+
Deprecations:
+
+
Add deprecation warning when using and_return with
+should_not_receive (Neha Kumari)
Fix should_receive so that when it is called on an
+as_null_object double with no implementation, and there is a
+previous explicit stub for the same method, the explicit stub remains
+(rather than being overriden with the null object
+implementation–return self). (Myron Marston)
supports use by 3rd party mock frameworks like Surrogate
+
+
+
Add stub_const API to stub constants for the duration of an
+example (Myron Marston).
+
+
+
Bug fixes
+
+
Fix regression of edge case behavior. double.should_receive(:foo) { a
+} was causing a NoMethodError when
+double.stub(:foo).and_return(a, b) had been setup before
+(Myron Marston).
+
+
Infinite loop generated by using any_instance and
+dup. (Sidu Ponnappa @kaiwren)
+
+
double.should_receive(:foo).at_least(:once).and_return(a)
+always returns a even if :foo is already stubbed.
+
+
Prevent infinite loop when interpolating a null double into a string as an
+integer ("%i" % double.as_null_object). (Myron
+Marston)
+
+
Fix should_receive so that null object behavior (e.g.
+returning self) is preserved if no implementation is given (Myron
+Marston).
+
+
Fix and_raise so that it raises RuntimeError
+rather than Exception by default, just like ruby does.
+(Andrew Marshall)
Copyright (c) 2012 David Chelimsky, Myron Marston Copyright (c) 2006 David Chelimsky, The RSpec Development Team Copyright (c) 2005 Steven Baker
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.0/rspec-mocks/file.README.html b/source/documentation/3.0/rspec-mocks/file.README.html
new file mode 100644
index 000000000..85033dba9
--- /dev/null
+++ b/source/documentation/3.0/rspec-mocks/file.README.html
@@ -0,0 +1,453 @@
+
+
+
+
+
+ File: README
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
rspec-mocks is a test-double framework for rspec with support for method
+stubs, fakes, and message expectations on generated test-doubles and real
+objects alike.
+
+
Install
+
+
geminstallrspec# for rspec-core, rspec-expectations, rspec-mocks
+geminstallrspec-mocks# for rspec-mocks only
+
+
Test Doubles
+
+
A test double is an object that stands in for another object in your system
+during a code example. Use the double method, passing in an
+optional identifier, to create one:
+
+
book=double("book")
+
+
+
Most of the time you will want some confidence that your doubles resemble
+an existing object in your system. Verifying doubles are provided for this
+purpose. If the existing object is available, they will prevent you from
+adding stubs and expectations for methods that do not exist or that have an
+invalid number of parameters.
+
+
book=instance_double("Book",:pages=>250)
+
+
+
Verifying doubles have some clever tricks to enable you to both test in
+isolation without your dependencies loaded while still being able to
+validate them against real objects. More detail is available in their
+documentation.
+
+
Method Stubs
+
+
A method stub is an implementation that returns a pre-determined value.
+Method stubs can be declared on test doubles or real objects using the same
+syntax. rspec-mocks supports 3 forms for declaring method stubs:
You can also use this shortcut, which creates a test double and declares a
+method stub in one statement:
+
+
book=double("book",:title=>"The RSpec Book")
+
+
+
The first argument is a name, which is used for documentation and appears
+in failure messages. If you don't care about the name, you can leave it
+out, making the combined instantiation/stub declaration very terse:
+
+
double(:foo=>'bar')
+
+
+
This is particularly nice when providing a list of test doubles to a method
+that iterates through them:
When a stub might be invoked more than once, you can provide additional
+arguments to and_return. The invocations cycle through the
+list. The last value is returned for any subsequent invocations:
A message expectation is an expectation that the test double will receive a
+message some time before the example ends. If the message is received, the
+expectation is satisfied. If not, the example fails.
Verifies the given object received the expected message during the course
+of the test. The method must have previously been stubbed in order for
+messages to be verified.
+
+
Stubbing and verifying messages received in this way implements the Test
+Spy pattern.
+
+
invitation=double('invitation',:accept=>true)
+
+ user.accept_invitation(invitation)
+
+ expect(invitation).tohave_received(:accept)
+
+ # You can also use other common message expectations. For example:
+expect(invitation).tohave_received(:accept).with(mailer)
+ expect(invitation).tohave_received(:accept).twice
+ expect(invitation).to_nothave_received(:accept).with(mailer)
+
+
+
Nomenclature
+
+
Mock Objects and Test Stubs
+
+
The names Mock Object and Test Stub suggest specialized Test Doubles. i.e.
+a Test Stub is a Test Double that only supports method stubs, and a Mock
+Object is a Test Double that supports message expectations and method
+stubs.
+
+
There is a lot of overlapping nomenclature here, and there are many
+variations of these patterns (fakes, spies, etc). Keep in mind that most of
+the time we're talking about method-level concepts that are variations
+of method stubs and message expectations, and we're applying to them to
+one generic kind of object: a Test Double.
+
+
Test-Specific Extension
+
+
a.k.a. Partial Double, a Test-Specific Extension is an extension of a real
+object in a system that is instrumented with test-double like behaviour in
+the context of a test. This technique is very common in Ruby because we
+often see class objects acting as global namespaces for methods. For
+example, in Rails:
In this case we're instrumenting Person to return the person object
+we've defined whenever it receives the find message. We
+can also set a message expectation so that the example fails if
+find is not called:
RSpec replaces the method we're stubbing or mocking with its own
+test-double-like method. At the end of the example, RSpec verifies any
+message expectations, and then restores the original methods.
Arguments that are passed to with are compared with actual
+arguments received using ==. In cases in which you want to specify things
+about the arguments rather than the arguments themselves, you can use any
+of the matchers that ship with rspec-expectations. They don't all make
+syntactic sense (they were primarily designed for use with
+RSpec::Expectations), but you are free to create your own custom
+RSpec::Matchers.
+
+
rspec-mocks also adds some keyword Symbols that you can use to specify
+certain kinds of arguments:
+
+
expect(double).toreceive(:msg).with(no_args())
+expect(double).toreceive(:msg).with(any_args())
+expect(double).toreceive(:msg).with(1,kind_of(Numeric),"b")#2nd argument can be any kind of Numeric
+expect(double).toreceive(:msg).with(1,boolean(),"b")#2nd argument can be true or false
+expect(double).toreceive(:msg).with(1,/abc/,"b")#2nd argument can be any String matching the submitted Regexp
+expect(double).toreceive(:msg).with(1,anything(),"b")#2nd argument can be anything at all
+expect(double).toreceive(:msg).with(1,duck_type(:abs,:div),"b")
+ #2nd argument can be object that responds to #abs and #div
+
Whether you are setting a message expectation or a method stub, you can
+tell the object precisely how to respond. The most generic way is to pass a
+block to receive:
+
+
expect(double).toreceive(:msg){value}
+
+
+
When the double receives the msg message, it evaluates the
+block and returns the result.
+
+
expect(double).toreceive(:msg).and_return(value)
+expect(double).toreceive(:msg).exactly(3).times.and_return(value1,value2,value3)
+ # returns value1 the first time, value2 the second, etc
+expect(double).toreceive(:msg).and_raise(error)
+ # error can be an instantiated object or a class
+# if it is a class, it must be instantiable with no args
+expect(double).toreceive(:msg).and_throw(:msg)
+expect(double).toreceive(:msg).and_yield(values,to,yield)
+expect(double).toreceive(:msg).and_yield(values,to,yield).and_yield(some,other,values,this,time)
+ # for methods that yield to a block multiple times
+
+
+
Any of these responses can be applied to a stub as well
Once in a while you'll find that the available expectations don't
+solve the particular problem you are trying to solve. Imagine that you
+expect the message to come with an Array argument that has a specific
+length, but you don't care what is in it. You could do this:
When working with a partial mock object, you may occasionally want to set a
+message expecation without interfering with how the object responds to the
+message. You can use and_call_original to achieve this:
+
+
expect(Person).toreceive(:find).and_call_original
+Person.find# => executes the original find method and returns the result
+
+
+
Combining Expectation Details
+
+
Combining the message name with specific arguments, receive counts and
+responses you can get quite a bit of detail in your expectations:
While this is a good thing when you really need it, you probably don't
+really need it! Take care to specify only the things that matter to the
+behavior of your code.
Stubs in before(:context) are not supported. The reason is
+that all stubs and mocks get cleared out after each example, so any stub
+that is set in before(:context) would work in the first
+example that happens to run in that group, but not for any others.
+
+
Instead of before(:context), use
+before(:example).
+
+
Settings mocks or stubs on any instance of a class
+
+
rspec-mocks provides two methods, allow_any_instance_of and
+expect_any_instance_of, that will allow you to stub or mock
+any instance of a class. They are used in place of allow or
+expect:
These methods add the appropriate stub or expectation to all instances of
+Widget.
+
+
This feature is sometimes useful when working with legacy code, though in
+general we discourage its use for a number of reasons:
+
+
The rspec-mocks API is designed for individual object
+instances, but this feature operates on entire classes of objects. As a
+result there are some sematically confusing edge cases. For example in
+expect_any_instance_of(Widget).to receive(:name).twice it
+isn't clear whether each specific instance is expected to receive
+name twice, or if two receives total are expected. (It's
+the former.)
+
+
Using this feature is often a design smell. It may be that your test is
+trying to do too much or that the object under test is too complex.
+
+
It is the most complicated feature of rspec-mocks, and has
+historically received the most bug reports. (None of the core team
+actively use it, which doesn't help.)
+
+
+
Further Reading
+
+
There are many different viewpoints about the meaning of mocks and stubs.
+If you are interested in learning more, here is some recommended reading:
rspec-mocks is a test-double framework for rspec with support for method
+stubs, fakes, and message expectations on generated test-doubles and real
+objects alike.
+
+
Install
+
+
geminstallrspec# for rspec-core, rspec-expectations, rspec-mocks
+geminstallrspec-mocks# for rspec-mocks only
+
+
Test Doubles
+
+
A test double is an object that stands in for another object in your system
+during a code example. Use the double method, passing in an
+optional identifier, to create one:
+
+
book=double("book")
+
+
+
Most of the time you will want some confidence that your doubles resemble
+an existing object in your system. Verifying doubles are provided for this
+purpose. If the existing object is available, they will prevent you from
+adding stubs and expectations for methods that do not exist or that have an
+invalid number of parameters.
+
+
book=instance_double("Book",:pages=>250)
+
+
+
Verifying doubles have some clever tricks to enable you to both test in
+isolation without your dependencies loaded while still being able to
+validate them against real objects. More detail is available in their
+documentation.
+
+
Method Stubs
+
+
A method stub is an implementation that returns a pre-determined value.
+Method stubs can be declared on test doubles or real objects using the same
+syntax. rspec-mocks supports 3 forms for declaring method stubs:
You can also use this shortcut, which creates a test double and declares a
+method stub in one statement:
+
+
book=double("book",:title=>"The RSpec Book")
+
+
+
The first argument is a name, which is used for documentation and appears
+in failure messages. If you don't care about the name, you can leave it
+out, making the combined instantiation/stub declaration very terse:
+
+
double(:foo=>'bar')
+
+
+
This is particularly nice when providing a list of test doubles to a method
+that iterates through them:
When a stub might be invoked more than once, you can provide additional
+arguments to and_return. The invocations cycle through the
+list. The last value is returned for any subsequent invocations:
A message expectation is an expectation that the test double will receive a
+message some time before the example ends. If the message is received, the
+expectation is satisfied. If not, the example fails.
Verifies the given object received the expected message during the course
+of the test. The method must have previously been stubbed in order for
+messages to be verified.
+
+
Stubbing and verifying messages received in this way implements the Test
+Spy pattern.
+
+
invitation=double('invitation',:accept=>true)
+
+ user.accept_invitation(invitation)
+
+ expect(invitation).tohave_received(:accept)
+
+ # You can also use other common message expectations. For example:
+expect(invitation).tohave_received(:accept).with(mailer)
+ expect(invitation).tohave_received(:accept).twice
+ expect(invitation).to_nothave_received(:accept).with(mailer)
+
+
+
Nomenclature
+
+
Mock Objects and Test Stubs
+
+
The names Mock Object and Test Stub suggest specialized Test Doubles. i.e.
+a Test Stub is a Test Double that only supports method stubs, and a Mock
+Object is a Test Double that supports message expectations and method
+stubs.
+
+
There is a lot of overlapping nomenclature here, and there are many
+variations of these patterns (fakes, spies, etc). Keep in mind that most of
+the time we're talking about method-level concepts that are variations
+of method stubs and message expectations, and we're applying to them to
+one generic kind of object: a Test Double.
+
+
Test-Specific Extension
+
+
a.k.a. Partial Double, a Test-Specific Extension is an extension of a real
+object in a system that is instrumented with test-double like behaviour in
+the context of a test. This technique is very common in Ruby because we
+often see class objects acting as global namespaces for methods. For
+example, in Rails:
In this case we're instrumenting Person to return the person object
+we've defined whenever it receives the find message. We
+can also set a message expectation so that the example fails if
+find is not called:
RSpec replaces the method we're stubbing or mocking with its own
+test-double-like method. At the end of the example, RSpec verifies any
+message expectations, and then restores the original methods.
Arguments that are passed to with are compared with actual
+arguments received using ==. In cases in which you want to specify things
+about the arguments rather than the arguments themselves, you can use any
+of the matchers that ship with rspec-expectations. They don't all make
+syntactic sense (they were primarily designed for use with
+RSpec::Expectations), but you are free to create your own custom
+RSpec::Matchers.
+
+
rspec-mocks also adds some keyword Symbols that you can use to specify
+certain kinds of arguments:
+
+
expect(double).toreceive(:msg).with(no_args())
+expect(double).toreceive(:msg).with(any_args())
+expect(double).toreceive(:msg).with(1,kind_of(Numeric),"b")#2nd argument can be any kind of Numeric
+expect(double).toreceive(:msg).with(1,boolean(),"b")#2nd argument can be true or false
+expect(double).toreceive(:msg).with(1,/abc/,"b")#2nd argument can be any String matching the submitted Regexp
+expect(double).toreceive(:msg).with(1,anything(),"b")#2nd argument can be anything at all
+expect(double).toreceive(:msg).with(1,duck_type(:abs,:div),"b")
+ #2nd argument can be object that responds to #abs and #div
+
Whether you are setting a message expectation or a method stub, you can
+tell the object precisely how to respond. The most generic way is to pass a
+block to receive:
+
+
expect(double).toreceive(:msg){value}
+
+
+
When the double receives the msg message, it evaluates the
+block and returns the result.
+
+
expect(double).toreceive(:msg).and_return(value)
+expect(double).toreceive(:msg).exactly(3).times.and_return(value1,value2,value3)
+ # returns value1 the first time, value2 the second, etc
+expect(double).toreceive(:msg).and_raise(error)
+ # error can be an instantiated object or a class
+# if it is a class, it must be instantiable with no args
+expect(double).toreceive(:msg).and_throw(:msg)
+expect(double).toreceive(:msg).and_yield(values,to,yield)
+expect(double).toreceive(:msg).and_yield(values,to,yield).and_yield(some,other,values,this,time)
+ # for methods that yield to a block multiple times
+
+
+
Any of these responses can be applied to a stub as well
Once in a while you'll find that the available expectations don't
+solve the particular problem you are trying to solve. Imagine that you
+expect the message to come with an Array argument that has a specific
+length, but you don't care what is in it. You could do this:
When working with a partial mock object, you may occasionally want to set a
+message expecation without interfering with how the object responds to the
+message. You can use and_call_original to achieve this:
+
+
expect(Person).toreceive(:find).and_call_original
+Person.find# => executes the original find method and returns the result
+
+
+
Combining Expectation Details
+
+
Combining the message name with specific arguments, receive counts and
+responses you can get quite a bit of detail in your expectations:
While this is a good thing when you really need it, you probably don't
+really need it! Take care to specify only the things that matter to the
+behavior of your code.
Stubs in before(:context) are not supported. The reason is
+that all stubs and mocks get cleared out after each example, so any stub
+that is set in before(:context) would work in the first
+example that happens to run in that group, but not for any others.
+
+
Instead of before(:context), use
+before(:example).
+
+
Settings mocks or stubs on any instance of a class
+
+
rspec-mocks provides two methods, allow_any_instance_of and
+expect_any_instance_of, that will allow you to stub or mock
+any instance of a class. They are used in place of allow or
+expect:
These methods add the appropriate stub or expectation to all instances of
+Widget.
+
+
This feature is sometimes useful when working with legacy code, though in
+general we discourage its use for a number of reasons:
+
+
The rspec-mocks API is designed for individual object
+instances, but this feature operates on entire classes of objects. As a
+result there are some sematically confusing edge cases. For example in
+expect_any_instance_of(Widget).to receive(:name).twice it
+isn't clear whether each specific instance is expected to receive
+name twice, or if two receives total are expected. (It's
+the former.)
+
+
Using this feature is often a design smell. It may be that your test is
+trying to do too much or that the object under test is too complex.
+
+
It is the most complicated feature of rspec-mocks, and has
+historically received the most bug reports. (None of the core team
+actively use it, which doesn't help.)
+
+
+
Further Reading
+
+
There are many different viewpoints about the meaning of mocks and stubs.
+If you are interested in learning more, here is some recommended reading:
Used to ensure examples get reloaded between multiple runs in the same
+process.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Class Method Details
+
+
+
+
+
+ + (void) configuration
+
+
+
+
+
+
+
+
+
Returns the global Configuration
+object. While you can use this method to access the configuration,
+the more common convention is to use RSpec.configure.
# File 'lib/rspec/core.rb', line 80
+
+defself.configure
+ yieldconfigurationifblock_given?
+end
+
+
+
+
+
+
+
+
+ + (void) current_example
+
+
+
+
+
+
+
+
+
The example being executed.
+
+
The primary audience for this method is library authors who need access to
+the example currently being executed and also want to support all versions
+of RSpec 2 and 3.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|c|
+ # context.example is deprecated, but RSpec.current_example is not
+# available until RSpec 3.0.
+fetch_current_example=RSpec.respond_to?(:current_example)?
+ proc{RSpec.current_example}:proc{|context|context.example}
+
+ c.before(:example)do
+ example=fetch_current_example.call(self)
+
+ # ...
+end
+end
+
+
+
+
+
+
+
+
+
+
+105
+106
+107
+
+
+
# File 'lib/rspec/core.rb', line 105
+
+defself.current_example
+ thread_local_metadata[:current_example]
+end
Configuration options are loaded from ~/.rspec,
+.rspec, .rspec-local, command line switches, and
+the SPEC_OPTS environment variable (listed in lowest to
+highest precedence; for example, an option in ~/.rspec can be
+overridden by an option in .rspec-local).
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.
defaults to :white but can be set to one of the
+following:[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+243
+
+
+
# File 'lib/rspec/core/configuration.rb', line 243
+
+add_setting:default_color
+
+
+
+
+
+
+
+
+
+
+ - (void) default_path
+
+
+
+
+
+
+
+
+
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.
+
+
Note: Other scripts invoking rspec indirectly will ignore this
+setting.
+
+
+
+
+
+
+
+
+
+
+
+
+
+95
+
+
+
# File 'lib/rspec/core/configuration.rb', line 95
+
+add_setting:default_path
+
+
+
+
+
+
+
+
+
+
+ - (void) detail_color
+
+
+
+
+
+
+
+
+
Color used to print details.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ color
+
+
+ (Symbol)
+
+
+
+ —
+
+
defaults to :cyan but can be set to one of the following:
+[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+257
+
+
+
# File 'lib/rspec/core/configuration.rb', line 257
+
+add_setting:detail_color
+
+
+
+
+
+
+
+
+
+
+ - (void) drb
+
+
+
+
+
+
+
+
+
Run examples over DRb (default: false). RSpec doesn't
+supply the DRb server, but you can use tools like spork.
+
+
+
+
+
+
+
+
+
+
+
+
+
+100
+
+
+
# File 'lib/rspec/core/configuration.rb', line 100
+
+add_setting:drb
+
+
+
+
+
+
+
+
+
+
+ - (void) drb_port
+
+
+
+
+
+
+
+
+
The drb_port (default: nil).
+
+
+
+
+
+
+
+
+
+
+
+
+
+104
+
+
+
# File 'lib/rspec/core/configuration.rb', line 104
+
+add_setting:drb_port
+
+
+
+
+
+
+
+
+
+
+ - (void) dry_run
+
+
+
+
+
+
+
+
+
Prints the formatter output of your suite without running any examples or
+hooks.
+
+
+
+
+
+
+
+
+
+
+
+
+
+156
+
+
+
# File 'lib/rspec/core/configuration.rb', line 156
+
+add_setting:dry_run
+
+
+
+
+
+
+
+
+
+
+ - (void) error_stream
+
+
+
+
+
+
+
+
+
Default: $stderr.
+
+
+
+
+
+
+
+
+
+
+
+
+
+108
+
+
+
# File 'lib/rspec/core/configuration.rb', line 108
+
+add_setting:error_stream
+
+
+
+
+
+
+
+
+
+
+ - (void) exclude_pattern
+
+
+
+
+
+
+
+
+
Exclude files matching this pattern
+
+
+
+
+
+
+
+
+
+
+
+
+
+200
+
+
+
# File 'lib/rspec/core/configuration.rb', line 200
+
+define_reader:exclude_pattern
+
+
+
+
+
+
+
+
+
+
+ - (void) fail_fast
+
+
+
+
+
+
+
+
+
Clean up and exit after the first failure (default: false).
+
+
+
+
+
+
+
+
+
+
+
+
+
+151
+
+
+
# File 'lib/rspec/core/configuration.rb', line 151
+
+add_setting:fail_fast
+
+
+
+
+
+
+
+
+
+
+ - (void) failure_color
+
+
+
+
+
+
+
+
+
Color to use to indicate failure.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ color
+
+
+ (Symbol)
+
+
+
+ —
+
+
defaults to :red but can be set to one of the following:
+[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+236
+
+
+
# File 'lib/rspec/core/configuration.rb', line 236
+
+add_setting:failure_color
+
+
+
+
+
+
+
+
+
+
+ - (void) failure_exit_code
+
+
+
+
+
+
+
+
+
The exit code to return if there are any failures (default: 1).
+
+
+
+
+
+
+
+
+
+
+
+
+
+160
+
+
+
# File 'lib/rspec/core/configuration.rb', line 160
+
+add_setting:failure_exit_code
+
+
+
+
+
+
+
+
+
+
+ - (Array) files_to_run
+
+
+
+
+
+
+
+
+
The spec files RSpec will run
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Array)
+
+
+
+ —
+
+
specified files about to run
+
+
+
+
+
+
+
+
+
+
+
+
+767
+768
+769
+
+
+
# File 'lib/rspec/core/configuration.rb', line 767
+
+deffiles_to_run
+ @files_to_run||=get_files_to_run(@files_or_directories_to_run)
+end
+
+
+
+
+
+
+
+
+
+
+ - (void) fixed_color
+
+
+
+
+
+
+
+
+
Color used when a pending example is fixed.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ color
+
+
+ (Symbol)
+
+
+
+ —
+
+
defaults to :blue but can be set to one of the following:
+[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+250
+
+
+
# File 'lib/rspec/core/configuration.rb', line 250
+
+add_setting:fixed_color
+
+
+
+
+
+
+
+
+
+
+ - (void) libs
+
+
+
+
+
+
+
+
+
Returns dirs that have been prepended to the load path by the
+-I command line option
+
+
+
+
+
+
+
+
+
+
+
+
+
+168
+
+
+
# File 'lib/rspec/core/configuration.rb', line 168
+
+define_reader:libs
+
+
+
+
+
+
+
+
+
+
+ - (void) output_stream
+
+
+
+
+
+
+
+
+
Determines where RSpec will send its output. Default: $stdout.
+
+
+
+
+
+
+
+
+
+
+
+
+
+173
+
+
+
# File 'lib/rspec/core/configuration.rb', line 173
+
+define_reader:output_stream
+
+
+
+
+
+
+
+
+
+
+ - (void) pattern
+
+
+
+
+
+
+
+
+
Load files matching this pattern (default:
+'**{,//*}/*_spec.rb')
+
+
+
+
+
+
+
+
+
+
+
+
+
+190
+
+
+
# File 'lib/rspec/core/configuration.rb', line 190
+
+define_reader:pattern
+
+
+
+
+
+
+
+
+
+
+ - (void) pending_color
+
+
+
+
+
+
+
+
+
Color to use to print pending examples.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ color
+
+
+ (Symbol)
+
+
+
+ —
+
+
defaults to :yellow but can be set to one of the following:
+[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+229
+
+
+
# File 'lib/rspec/core/configuration.rb', line 229
+
+add_setting:pending_color
+
+
+
+
+
+
+
+
+
+
+ - (void) profile_examples
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
Defaults profile_examples to 10 examples when
+@profile_examples is true.
+
+
+
+
+
+
+
+
+
+
+
+
+
+211
+
+
+
# File 'lib/rspec/core/configuration.rb', line 211
+
+add_setting:profile_examples
+
+
+
+
+
+
+
+
+
+
+ - (void) requires
+
+
+
+
+
+
+
+
+
Indicates files configured to be required
+
+
+
+
+
+
+
+
+
+
+
+
+
+164
+
+
+
# File 'lib/rspec/core/configuration.rb', line 164
+
+define_reader:requires
Run all examples if none match the configured filters (default:
+false).
+
+
+
+
+
+
+
+
+
+
+
+
+
+215
+
+
+
# File 'lib/rspec/core/configuration.rb', line 215
+
+add_setting:run_all_when_everything_filtered
+
+
+
+
+
+
+
+
+
+
+ - (void) success_color
+
+
+
+
+
+
+
+
+
Color to use to indicate success.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ color
+
+
+ (Symbol)
+
+
+
+ —
+
+
defaults to :green but can be set to one of the following:
+[:black, :white, :red, :green, :yellow, :blue, :magenta,
+:cyan]
+
+
+
+
+
+
+
+
+
+
+
+
+
+222
+
+
+
# File 'lib/rspec/core/configuration.rb', line 222
+
+add_setting:success_color
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (void) add_formatter(formatter)
+
+
+
+ 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 paths to use for output streams, but you should consider that a
+private api that may change at any time without notice.
The defined aliased will also be added to the top level (e.g.
+main and from within modules) if
+expose_dsl_globally is set to true.
+
+
+
+
+
Creates a method that defines an example group with the provided metadata.
+Can be used to define example group/metadata shortcuts.
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.configuredo|config|
+ config.alias_example_group_to:describe_model,:type=>:model
+end
+
+shared_context_for"model tests",:type=>:modeldo
+ # define common model test helper methods, `let` declarations, etc
+end
+
+# This lets you do this:
+
+RSpec.describe_modelUserdo
+end
+
+# ... which is the equivalent of
+
+RSpec.describeUser,:type=>:modeldo
+end
The specific example alias below (pending) is already defined
+for you.
+
+
+
+
+ Note:
+
+
Use with caution. This extends the language used in your specs, but does
+not add any additional documentation. We use this in rspec to define
+methods like focus and xit, but we also add docs
+for those methods.
+
+
+
+
+
Creates a method that delegates to example including the
+submitted args. Used internally to add variants of
+example like pending:
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.configuredo|config|
+ config.alias_example_to:pending,:pending=>true
+end
+
+# This lets you do this:
+
+describeThingdo
+ pending"does something"do
+ thing=Thing.new
+ end
+end
+
+# ... which is the equivalent of
+
+describeThingdo
+ it"does something",:pending=>truedo
+ thing=Thing.new
+ end
+end
Use with caution. This extends the language used in your specs, but does
+not add any additional documentation. We use this in rspec to define
+it_should_behave_like (for backward compatibility), but we
+also add docs for that method.
+
+
+
+
+
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.
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.configuredo|config|
+ config.alias_it_behaves_like_to(:it_has_behavior,'has behavior:')
+end
+
+# allows the user to include a shared example group like:
+
+describeEntitydo
+ 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
+
+
+
+
+
+
+
+
+
+
+866
+867
+868
+
+
+
# File 'lib/rspec/core/configuration.rb', line 866
+
+defalias_it_behaves_like_to(new_name,report_label='')
+ RSpec::Core::ExampleGroup.define_nested_shared_group_method(new_name,report_label)
+end
Excludes lines from ruby (and jruby) source, installed gems, anything in
+any “bin” directory, and any of the rspec libs (outside gem installs) by
+default.
+
+
You can modify the list via the getter, or replace it with the setter.
+
+
To override this behaviour and display a full backtrace, use
+--backtraceon the command line, in a .rspec file,
+or in the rspec_options attribute of RSpec's rake task.
+
+
+
+
+
+
+
+
+
+
+
+
+
+406
+407
+408
+
+
+
# File 'lib/rspec/core/configuration.rb', line 406
+
+defbacktrace_exclusion_patterns
+ @backtrace_formatter.exclusion_patterns
+end
# File 'lib/rspec/core/configuration.rb', line 629
+
+defcolor=(true_or_false)
+ returnunlesstrue_or_false
+
+ ifRSpec.world.windows_os?&&!ENV['ANSICON']
+ RSpec.warning"You must use ANSICON 1.31 or later (http://adoxa.3eeweb.com/ansicon/) to use colour on Windows"
+ @color=false
+ else
+ @color=true
+ end
+end
Defines a callback that can assign derived metadata values.
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.configuredo|config|
+ # Tag all groups and examples in the spec/unit directory with :type => :unit
+config.define_derived_metadata(:file_path=>%r{/spec/unit/})do|metadata|
+ metadata[:type]=:unit
+ end
+end
metadata filters that determine which example or group metadata hashes the
+callback will be triggered for. If none are given, the callback will be run
+against the metadata hashes of all groups and examples.
+
+
+
+
+
+
+
Yield Parameters:
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
original metadata hash from an example or group. Mutate this in your block
+as needed.
# File 'lib/rspec/core/configuration.rb', line 137
+
+defdeprecation_stream=(value)
+ if@reporter&&!value.equal?(@deprecation_stream)
+ warn"RSpec's reporter has already been initialized with " \
+ "#{deprecation_stream.inspect} as the deprecation stream, so your change to "\
+ "`deprecation_stream` will be ignored. You should configure it earlier for " \
+ "it to take effect, or use the `--deprecation-out` CLI option. " \
+ "(Called from #{CallerFilter.first_non_rspec_line})"
+ else
+ @deprecation_stream=value
+ end
+end
+
+
+
+
+
+
+
+
+ - (void) disable_monkey_patching!
+
+
+
+
+
+
+
+
+
+ Note:
+
+
It configures rspec-mocks and rspec-expectations only if the user is using
+those (either explicitly or implicitly by not setting
+mock_with or expect_with to anything else).
+
+
+
+
+ Note:
+
+
If the user uses this options with mock_with :mocha (or
+similiar) they will still have monkey patching active in their test
+environment from mocha.
+
+
+
+
+
Enables zero monkey patching mode for RSpec. It removes monkey patching of
+the top-level DSL methods (describe,
+shared_examples_for, etc) onto main and
+Module, instead requiring you to prefix these methods with
+RSpec.. It enables expect-only syntax for rspec-mocks and
+rspec-expectations. It simply disables monkey patching on whatever pieces
+of rspec the user is using.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+# It disables all monkey patching
+RSpec.configuredo|config|
+ config.disable_monkey_patching!
+end
+
+# Is an equivalent to
+RSpec.configuredo|config|
+ config.expose_dsl_globally=false
+
+ config.mock_with:rspecdo|mocks|
+ mocks.syntax=:expect
+ mocks.patch_marshal_to_support_partial_doubles=false
+ end
+
+ config.mock_with:rspecdo|expectations|
+ expectations.syntax=:expect
+ end
+end
# File 'lib/rspec/core/configuration.rb', line 565
+
+defexpect_with(*frameworks)
+ modules=frameworks.mapdo|framework|
+ caseframework
+ whenModule
+ framework
+ when:rspec
+ require'rspec/expectations'
+ self.expecting_with_rspec=true
+ ::RSpec::Matchers
+ when:test_unit
+ require'rspec/core/test_unit_assertions_adapter'
+ ::RSpec::Core::TestUnitAssertionsAdapter
+ when:minitest
+ require'rspec/core/minitest_assertions_adapter'
+ ::RSpec::Core::MinitestAssertionsAdapter
+ else
+ raiseArgumentError,"#{framework.inspect} is not supported"
+ end
+ end
+
+ if(modules-@expectation_frameworks).any?
+ assert_no_example_groups_defined(:expect_with)
+ end
+
+ ifblock_given?
+ raise"expect_with only accepts a block with a single argument. Call expect_with #{modules.length} times, once with each argument, instead."ifmodules.length>1
+ raise"#{modules.first} must respond to `configuration` so that expect_with can yield it."unlessmodules.first.respond_to?(:configuration)
+ yieldmodules.first.configuration
+ end
+
+ @expectation_frameworks.push(*modules)
+end
Exposes the current running example via the named helper method. RSpec 2.x
+exposed this via example, but in RSpec 3.0, the example is
+instead exposed via an arg yielded to it, before,
+let, etc. However, some extension gems (such as Capybara)
+depend on the RSpec 2.x's example method, so this config
+option can be used to maintain compatibility.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|rspec|
+ rspec.expose_current_running_example_as:example
+end
+
+describeMyClassdo
+ beforedo
+ # `example` can be used here because of the above config.
+do_somethingifexample.metadata[:type]=="foo"
+ end
+end
Use this to expose the core RSpec DSL via Module and the
+main object. It will be set automatically but you can override
+it to remove the DSL. Default: true
Indicates if the DSL has been exposed off of modules and main.
+Default: true
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+112
+113
+114
+
+
+
# File 'lib/rspec/core/configuration.rb', line 112
+
+defexpose_dsl_globally?
+ Core::DSL.exposed_globally?
+end
+
+
+
+
+
+
+
+
+ - (void) extend(mod, *filters)
+
+
+
+
+
+
+
+
+
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.
The patterns this adds will match the named gems in their common locations
+(e.g. system gems, vendored with bundler, installed as a :git dependency
+with bundler, etc) but is not guaranteed to work for all possible gem
+locations. For example, if you have the gem source in a directory with a
+completely unrelated name, and use bundler's :path option, this will
+not filter it.
Adds key/value pairs to the exclusion_filter. If
+args includes any symbols that are not part of the 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:
+
+
+
# 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'}
+
+filter_run_excluding:foo# same as filter_run_excluding :foo => true
+
+ - (void) filter_run_including(*args)
+
+
+
+ Also known as:
+ filter_run
+
+
+
+
+
+
+
+
Adds key/value pairs to the inclusion_filter. If
+args includes any symbols that are not part of the 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:
+
+
+
# 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'}
+
+filter_run_including:foo# same as filter_run_including :foo => true
# File 'lib/rspec/core/configuration.rb', line 650
+
+deffull_description=(description)
+ filter_run:full_description=>Regexp.union(*Array(description).map{|d|Regexp.new(d)})
+end
+
+
+
+
+
+
+
+
+ - (void) include(mod, *filters)
+
+
+
+
+
+
+
+
+
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:
+
+
+
+moduleAuthenticationHelpers
+ deflogin_as(user)
+ # ...
+end
+end
+
+moduleUserHelpers
+ defusers(username)
+ # ...
+end
+end
+
+RSpec.configuredo|config|
+ config.include(UserHelpers)# included in all modules
+config.include(AuthenticationHelpers,:type=>:request)
+end
+
+describe"edit profile",:type=>:requestdo
+ it"can be viewed by owning user"do
+ login_asusers(:jdoe)
+ get"/profiles/jdoe"
+ assert_select".username",:text=>'jdoe'
+ end
+end
# File 'lib/rspec/core/configuration.rb', line 391
+
+defmock_framework=(framework)
+ mock_withframework
+end
+
+
+
+
+
+
+
+
+ - (void) mock_with(framework)
+
+
+
+
+
+
+
+
+
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 if the example hasn't yet failed.
+ 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.
Turns deprecation warnings into errors, in order to surface the full
+backtrace of the call site. This can be useful when you need more context
+to address a deprecation than the single-line call site normally provided.
Pass the symbol :global to set the ordering strategy that will
+be used to order the top-level example groups and any example groups that
+do not have declared :order metadata.
+
+
+
+
+
Registers a named ordering strategy that can later be used to order an
+example group's subgroups by adding :order =>
+<name> metadata to the example group.
# File 'lib/rspec/core/configuration.rb', line 1187
+
+delegate_to_ordering_manager:register_ordering
+
+
+
+
+
+
+
+
+ - (void) seed
+
+
+
+
+
+
+
+
+
Seed for random ordering (default: generated randomly each run).
+
+
When you run specs with --order random, RSpec generates a
+random seed for the randomization and prints it to the
+output_stream (assuming you're using RSpec's built-in
+formatters). If you discover an ordering dependency (i.e. examples fail
+intermittently depending on order), set this (on Configuration or on the
+command line with --seed) to run using the same seed while you
+debug the issue.
+
+
We recommend, actually, that you use the command line approach so you
+don't accidentally leave the seed encoded.
+
+
+
+
+
+
+
+
+
+
+
+
+
+1156
+
+
+
# File 'lib/rspec/core/configuration.rb', line 1156
+
+delegate_to_ordering_manager:seed
+
+
+
+
+
+
+
+
+ - (void) seed=
+
+
+
+
+
+
+
+
+
Sets the seed value and sets the default global ordering to random.
+
+
+
+
+
+
+
+
+
+
+
+
+
+1142
+
+
+
# File 'lib/rspec/core/configuration.rb', line 1142
+
+delegate_to_ordering_manager:seed=
Deprecated. This config option was added in RSpec 2 to pave the way for
+this being the default behavior in RSpec 3. Now this option is a no-op.
+
+
+
+
+
+
+
+
+
+
+
+
+
+262
+263
+264
+265
+266
+
+
+
# File 'lib/rspec/core/configuration.rb', line 262
+
+deftreat_symbols_as_metadata_keys_with_true_values=(_value)
+ RSpec.deprecate("RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values=",
+ :message=>"RSpec::Core::Configuration#treat_symbols_as_metadata_keys_with_true_values= " \
+ "is deprecated, it is now set to true as default and setting it to false has no effect.")
+end
+
+
+
+
+
+
+
+
+ - (void) warnings=(value)
+
+
+
+
+
+
+
+
+
Set Ruby warnings on or off
+
+
+
+
+
+
+
+
+
+
+
+
+
+1193
+1194
+1195
+
+
+
# File 'lib/rspec/core/configuration.rb', line 1193
+
+defwarnings=(value)
+ $VERBOSE=!!value
+end
+
+
+
+
+
+
+
+
+ - (Boolean) warnings?
+
+
+
+
+
+
+
+
+
Returns Whether or not ruby warnings are enabled.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
+
Whether or not ruby warnings are enabled.
+
+
+
+
+
+
+
+
+
+
+
+
+1198
+1199
+1200
+
+
+
# File 'lib/rspec/core/configuration.rb', line 1198
+
+defwarnings?
+ $VERBOSE
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-core/RSpec/Core/ConfigurationOptions.html b/source/documentation/3.1/rspec-core/RSpec/Core/ConfigurationOptions.html
new file mode 100644
index 000000000..9630a0099
--- /dev/null
+++ b/source/documentation/3.1/rspec-core/RSpec/Core/ConfigurationOptions.html
@@ -0,0 +1,530 @@
+
+
+
+
+
+ Class: RSpec::Core::ConfigurationOptions
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Responsible for utilizing externally provided configuration options,
+whether via the command line, .rspec, ~/.rspec,
+.rspec-local or a custom options file.
DSL defines methods to group examples, most notably describe,
+and exposes them as class methods of RSpec. They can also be exposed
+globally (on main and instances of Module)
+through the Configuration option expose_dsl_globally.
+
+
By default the methods describe, context and
+example_group are exposed. These methods define a named
+context for one or more examples. The given block is evaluated in the
+context of a generated subclass of ExampleGroup
+
+
Examples:
+
+
RSpec.describe"something"do
+ context"when something is a certain way"do
+ it"does something"do
+ # example code goes here
+end
+ end
+end
Example blocks are evaluated in the context of an instance of an
+ExampleGroup, not in the context of an instance of
+Example.
+
+
+
+
+
Wrapper for an instance of a subclass of ExampleGroup. An instance of
+RSpec::Core::Example is returned by example definition methods
+such as it and is yielded to the it,
+before, after, around,
+let and
+subject blocks.
+
+
This allows us to provide rich metadata about each individual example
+without adding tons of methods directly to the ExampleGroup that users may
+inadvertantly redefine.
+
+
Useful for configuring logging and/or taking some action based on the state
+of an example's metadata.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|config|
+ config.beforedo|example|
+ logexample.description
+ end
+
+ config.afterdo|example|
+ logexample.description
+ end
+
+ config.arounddo|example|
+ logexample.description
+ example.run
+ end
+end
+
+shared_examples"auditable"do
+ it"does something"do
+ log"#{example.full_description}: #{auditable.inspect}"
+ auditable.shoulddo_something
+ end
+end
Returns the first exception raised in the context of running this example
+(nil if no exception is raised)
+
+
+
+
+
+
+
+
+
+
+
+
+
+89
+90
+91
+
+
+
# File 'lib/rspec/core/example.rb', line 89
+
+defexception
+ @exception
+end
+
+
+
+
+
+
+
+
+
+
+ - (void) metadata(readonly)
+
+
+
+
+
+
+
+
+
Returns the metadata object associated with this example.
+
+
+
+
+
+
+
+
+
+
+
+
+
+94
+95
+96
+
+
+
# File 'lib/rspec/core/example.rb', line 94
+
+defmetadata
+ @metadata
+end
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (void) description
+
+
+
+
+
+
+
+
+
Returns the string submitted to example or its aliases (e.g.
+specify, it, etc). If no string is submitted
+(e.g. it { is_expected.to do_something }) it returns the
+message generated by the matcher if there is one, otherwise returns a
+message including the location of the example.
+
+
+
+
+
+
+
+
+
+
+
+
+
+75
+76
+77
+78
+79
+80
+81
+82
+83
+
+
+
# File 'lib/rspec/core/example.rb', line 75
+
+defdescription
+ description=ifmetadata[:description].to_s.empty?
+ "example at #{location}"
+ else
+ metadata[:description]
+ end
+
+ RSpec.configuration.format_docstrings_block.call(description)
+end
+
+
+
+
+
+
+
+
+ - (void) example_group
+
+
+
+
+
+
+
+
+
Returns the example group class that provides the context for running this
+example.
+
+
+
+
+
+
+
+
+
+
+
+
+
+127
+128
+129
+
+
+
# File 'lib/rspec/core/example.rb', line 127
+
+defexample_group
+ @example_group_class
+end
# File 'lib/rspec/core/example.rb', line 53
+
+delegate_to_metadata:execution_result
+
+
+
+
+
+
+
+
+ - (String) file_path
+
+
+
+
+
+
+
+
+
Returns the relative path to the file where this example was defined.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
+
the relative path to the file where this example was defined.
+
+
+
+
+
+
+
+
+
+
+
+
+55
+
+
+
# File 'lib/rspec/core/example.rb', line 55
+
+delegate_to_metadata:file_path
+
+
+
+
+
+
+
+
+ - (String) full_description
+
+
+
+
+
+
+
+
+
Returns the full description (including the docstrings of all parent
+example groups).
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
+
the full description (including the docstrings of all parent example
+groups).
+
+
+
+
+
+
+
+
+
+
+
+
+58
+
+
+
# File 'lib/rspec/core/example.rb', line 58
+
+delegate_to_metadata:full_description
+
+
+
+
+
+
+
+
+ - (String) location
+
+
+
+
+
+
+
+
+
Returns the exact source location of this example in a form like
+./path/to/spec.rb:17
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
+
the exact source location of this example in a form like
+./path/to/spec.rb:17
+
+
+
+
+
+
+
+
+
+
+
+
+61
+
+
+
# File 'lib/rspec/core/example.rb', line 61
+
+delegate_to_metadata:location
+
+
+
+
+
+
+
+
+ - (Boolean) pending
+
+
+
+ Also known as:
+ pending?
+
+
+
+
+
+
+
+
Returns flag that indicates that the example is not expected to pass. It
+will be run and will either have a pending result (if a failure occurs) or
+a failed result (if no failure occurs).
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
+
flag that indicates that the example is not expected to pass. It will be
+run and will either have a pending result (if a failure occurs) or a failed
+result (if no failure occurs).
+
+
+
+
+
+
+
+
+
+
+
+
+65
+
+
+
# File 'lib/rspec/core/example.rb', line 65
+
+delegate_to_metadata:pending
# File 'lib/rspec/core/example.rb', line 424
+
+defexception
+ @exception
+end
+
+
+
+
+
+
+
+
+
+
+ - (Time) finished_at
+
+
+
+
+
+
+
+
+
Returns When the example finished.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Time)
+
+
+
+ —
+
+
When the example finished.
+
+
+
+
+
+
+
+
+
+
+
+
+430
+431
+432
+
+
+
# File 'lib/rspec/core/example.rb', line 430
+
+deffinished_at
+ @finished_at
+end
+
+
+
+
+
+
+
+
+
+
+ - (Exception?) pending_exception
+
+
+
+
+
+
+
+
+
Returns The exception triggered while executing the pending example. If no
+exception was triggered it would no longer get a status of
+:pending unless it was tagged with :skip.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Exception, nil)
+
+
+
+ —
+
+
The exception triggered while executing the pending example. If no
+exception was triggered it would no longer get a status of
+:pending unless it was tagged with :skip.
+
+
+
+
+
+
+
+
+
+
+
+
+443
+444
+445
+
+
+
# File 'lib/rspec/core/example.rb', line 443
+
+defpending_exception
+ @pending_exception
+end
+
+
+
+
+
+
+
+
+
+
+ - (Boolean) pending_fixed
+
+
+
+ Also known as:
+ pending_fixed?
+
+
+
+
+
+
+
+
Returns For examples tagged with :pending, this indicates
+whether or not it now passes.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
+
For examples tagged with :pending, this indicates whether or
+not it now passes.
+
+
+
+
+
+
+
+
+
+
+
+
+447
+448
+449
+
+
+
# File 'lib/rspec/core/example.rb', line 447
+
+defpending_fixed
+ @pending_fixed
+end
+
+
+
+
+
+
+
+
+
+
+ - (String?) pending_message
+
+
+
+
+
+
+
+
+
Returns The reason the example was pending, or nil if the example was not
+pending.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String, nil)
+
+
+
+ —
+
+
The reason the example was pending, or nil if the example was not pending.
+
+
+
+
+
+
+
+
+
+
+
+
+437
+438
+439
+
+
+
# File 'lib/rspec/core/example.rb', line 437
+
+defpending_message
+ @pending_message
+end
+
+
+
+
+
+
+
+
+
+
+ - (Float) run_time
+
+
+
+
+
+
+
+
+
Returns How long the example took in seconds.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Float)
+
+
+
+ —
+
+
How long the example took in seconds.
+
+
+
+
+
+
+
+
+
+
+
+
+433
+434
+435
+
+
+
# File 'lib/rspec/core/example.rb', line 433
+
+defrun_time
+ @run_time
+end
+
+
+
+
+
+
+
+
+
+
+ - (Time) started_at
+
+
+
+
+
+
+
+
+
Returns When the example started.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Time)
+
+
+
+ —
+
+
When the example started.
+
+
+
+
+
+
+
+
+
+
+
+
+427
+428
+429
+
+
+
# File 'lib/rspec/core/example.rb', line 427
+
+defstarted_at
+ @started_at
+end
+
+
+
+
+
+
+
+
+
+
+ - (Symbol) status
+
+
+
+
+
+
+
+
+
Returns :passed, :failed or
+:pending.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Symbol)
+
+
+
+ —
+
+
:passed, :failed or :pending.
+
+
+
+
+
+
+
+
+
+
+
+
+421
+422
+423
+
+
+
# File 'lib/rspec/core/example.rb', line 421
+
+defstatus
+ @status
+end
Wraps both a Proc and an RSpec::Core::Example for use in around hooks. In around hooks we need to yield this special kind of object
+(rather than the raw RSpec::Core::Example) because when there are multiple
+around hooks we have to wrap them recursively.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|c|
+ c.arounddo|ex|# Procsy which wraps the example
+ifex.metadata[:key]==:some_value&&some_global_condition
+ raise"some message"
+ end
+ ex.run# run delegates to ex.call
+end
+end
ExampleGroup and Example are the main structural elements of rspec-core.
+Consider this example:
+
+
describeThingdo
+ it"does something"do
+ end
+end
+
+
The object returned by describe Thing is a subclass of
+ExampleGroup. The object returned by it "does
+something" is an instance of Example, which serves as a wrapper
+for an instance of the ExampleGroup in which it is declared.
+
+
Example group bodies (e.g. describe or context
+blocks) are evaluated in the context of a new subclass of ExampleGroup.
+Individual examples are evaluated in the context of an instance of the
+specific ExampleGroup subclass to which they belong.
An alias of example_group. Generally used when grouping
+examples contextually (e.g. “with xyz”, “when xyz” or “if xyz”). Generates
+a subclass of this example group which inherits everything except the
+examples themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ context"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
# File 'lib/rspec/core/example_group.rb', line 241
+
+define_example_group_method:context
+
+
+
+
+
+
+
+
+ + (void) describe { ... }
+
+
+
+
+
+
+
+
+
An alias of example_group. Generally used when grouping
+examples by a thing you are describing (e.g. an object, class or method).
+Generates a subclass of this example group which inherits everything except
+the examples themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ describe"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
exampledo
+end
+
+example"does something"do
+end
+
+example"does something",:with=>'additional metadata'do
+end
+
+example"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 123
+
+define_example_method:example
+
+
+
+
+
+
+
+
+ + (void) example_group { ... }
+
+
+
+
+
+
+
+
+
Generates a subclass of this example group which inherits everything except
+the examples themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ example_group"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+
+
+
+
+
+
+
The example group definition
+
+
+
+
+
+
+
+
+
+
+
+
+231
+
+
+
# File 'lib/rspec/core/example_group.rb', line 231
+
+define_example_group_method:example_group
+
+
+
+
+
+
+
+
+ + (void) fcontext { ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example group with :focus => true.
+Generates a subclass of this example group which inherits everything except
+the examples themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ fcontext"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
# File 'lib/rspec/core/example_group.rb', line 257
+
+define_example_group_method:fcontext,:focus=>true
+
+
+
+
+
+
+
+
+ + (void) fdescribe { ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example group with :focus => true.
+Generates a subclass of this example group which inherits everything except
+the examples themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ fdescribe"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
fexampledo
+end
+
+fexample"does something"do
+end
+
+fexample"does something",:with=>'additional metadata'do
+end
+
+fexample"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 142
+
+define_example_method:fexample,:focus=>true
+
+
+
+
+
+
+
+
+ + (void) fit {|Example| ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example with :focus => true
+
+
+
+
+
+
+
+
Examples:
+
+
+
fitdo
+end
+
+fit"does something"do
+end
+
+fit"does something",:with=>'additional metadata'do
+end
+
+fit"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 145
+
+define_example_method:fit,:focus=>true
+
+
+
+
+
+
+
+
+ + (void) focus {|Example| ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example with :focus => true
+
+
+
+
+
+
+
+
Examples:
+
+
+
focusdo
+end
+
+focus"does something"do
+end
+
+focus"does something",:with=>'additional metadata'do
+end
+
+focus"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
fspecifydo
+end
+
+fspecify"does something"do
+end
+
+fspecify"does something",:with=>'additional metadata'do
+end
+
+fspecify"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
Includes shared content mapped to name directly in the group
+in which it is declared, as opposed to it_behaves_like, which
+creates a nested group. If given a block, that block is also eval'd in
+the current context.
Includes shared content mapped to name directly in the group
+in which it is declared, as opposed to it_behaves_like, which
+creates a nested group. If given a block, that block is also eval'd in
+the current context.
# File 'lib/rspec/core/example_group.rb', line 302
+
+defself.include_examples(name,*args,&block)
+ find_and_eval_shared("examples",name,*args,&block)
+end
+
+
+
+
+
+
+
+
+ + (void) it {|Example| ... }
+
+
+
+
+
+
+
+
+
Defines an example within a group. This is the primary API to define a code
+example.
+
+
+
+
+
+
+
+
Examples:
+
+
+
itdo
+end
+
+it"does something"do
+end
+
+it"does something",:with=>'additional metadata'do
+end
+
+it"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 46
+
+defself.metadata
+ @metadataifdefined?(@metadata)
+end
+
+
+
+
+
+
+
+
+ + (void) pending {|Example| ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example with :pending => true
+
+
+
+
+
+
+
+
Examples:
+
+
+
pendingdo
+end
+
+pending"does something"do
+end
+
+pending"does something",:with=>'additional metadata'do
+end
+
+pending"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
skipdo
+end
+
+skip"does something"do
+end
+
+skip"does something",:with=>'additional metadata'do
+end
+
+skip"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 160
+
+define_example_method:skip,:skip=>true
+
+
+
+
+
+
+
+
+ + (void) specify {|Example| ... }
+
+
+
+
+
+
+
+
+
Defines an example within a group. Useful for when your docstring does not
+read well off of it.
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.describeMyClassdo
+ specify"#do_something is deprecated"do
+ # ...
+end
+end
+
+
+
specifydo
+end
+
+specify"does something"do
+end
+
+specify"does something",:with=>'additional metadata'do
+end
+
+specify"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 135
+
+define_example_method:specify
+
+
+
+
+
+
+
+
+ + (void) xcontext { ... }
+
+
+
+
+
+
+
+
+
Shortcut to temporarily make an example group skipped. Generates a subclass
+of this example group which inherits everything except the examples
+themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ xcontext"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
# File 'lib/rspec/core/example_group.rb', line 249
+
+define_example_group_method:xcontext,:skip=>"Temporarily skipped with xcontext"
+
+
+
+
+
+
+
+
+ + (void) xdescribe { ... }
+
+
+
+
+
+
+
+
+
Shortcut to temporarily make an example group skipped. Generates a subclass
+of this example group which inherits everything except the examples
+themselves.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.describe"something"do# << This describe method is defined in
+# << RSpec::Core::DSL, included in the
+# << global namespace (optional)
+beforedo
+ do_something_before
+ end
+
+ let(:thing){Thing.new}
+
+ xdescribe"attribute (of something)"do
+ # examples in the group get the before hook
+# declared above, and can access `thing`
+end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String)
+
+
+
+ —
+
+
The example group doc string
+
+
+
+
+
+
+ metadata
+
+
+ (Hash)
+
+
+
+ —
+
+
Additional metadata to attach to the example group
Shortcut to define an example with :skip => 'Temporarily
+skipped with xexample'
+
+
+
+
+
+
+
+
Examples:
+
+
+
xexampledo
+end
+
+xexample"does something"do
+end
+
+xexample"does something",:with=>'additional metadata'do
+end
+
+xexample"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
# File 'lib/rspec/core/example_group.rb', line 151
+
+define_example_method:xexample,:skip=>'Temporarily skipped with xexample'
+
+
+
+
+
+
+
+
+ + (void) xit {|Example| ... }
+
+
+
+
+
+
+
+
+
Shortcut to define an example with :skip => 'Temporarily
+skipped with xit'
+
+
+
+
+
+
+
+
Examples:
+
+
+
xitdo
+end
+
+xit"does something"do
+end
+
+xit"does something",:with=>'additional metadata'do
+end
+
+xit"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
Shortcut to define an example with :skip => 'Temporarily
+skipped with xspecify'
+
+
+
+
+
+
+
+
Examples:
+
+
+
xspecifydo
+end
+
+xspecify"does something"do
+end
+
+xspecify"does something",:with=>'additional metadata'do
+end
+
+xspecify"does something"do|ex|
+ # ex is the Example object that contains metadata about the example
+end
progress (default) - prints dots for passing examples, F for
+failures, * for pending
+
+
documentation - prints the docstrings passed to describe and
+it methods (and their aliases)
+
+
html
+
+
json - useful for archiving data for subsequent analysis
+
+
+
The progress formatter is the default, but you can choose any one or more
+of the other formatters by passing with the --format (or
+-f for short) command-line option, e.g.
+
+
rspec --format documentation
+
+
You can also send the output of multiple formatters to different streams,
+e.g.
+
+
rspec --format documentation --format html --out results.html
+
+
This example sends the output of the documentation formatter to
+$stdout, and the output of the html formatter to results.html.
+
+
Custom Formatters
+
+
You can tell RSpec to use a custom formatter by passing its path and name
+to the rspec commmand. For example, if you define
+MyCustomFormatter in path/to/my_custom_formatter.rb, you would type this
+command:
The reporter calls every formatter with this protocol:
+
+
To start
+
+
start(StartNotification)
+
+
Once per example group
+
+
example_group_started(GroupNotification)
+
+
Once per example
+
+
example_started(ExampleNotification)
+
+
One of these per example, depending on outcome
+
+
example_passed(ExampleNotification)
+
+
example_failed(FailedExampleNotification)
+
+
example_pending(ExampleNotification)
+
+
Optionally at any time
+
+
message(MessageNotification)
+
+
At the end of the suite
+
+
stop(ExamplesNotification)
+
+
start_dump(NullNotification)
+
+
dump_pending(ExamplesNotification)
+
+
dump_failures(ExamplesNotification)
+
+
dump_summary(SummaryNotification)
+
+
seed(SeedNotification)
+
+
close(NullNotification)
+
+
+
Only the notifications to which you subscribe your formatter will be called
+on your formatter. To subscribe your formatter use:
+RSpec::Core::Formatters#register e.g.
We recommend you implement the methods yourself; for simplicity we provide
+the default formatter output via our notification objects but if you prefer
+you can subclass RSpec::Core::Formatters::BaseTextFormatter
+and override the methods you wish to enhance.
Base for all of RSpec's built-in formatters. See
+RSpec::Core::Formatters::BaseFormatter to learn more about all of the
+methods called by the reporter.
Formats seconds to have 5 digits of precision with trailing zeros removed
+if the number is less than 1 or with 2 digits of precision if the number is
+greater than zero.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
Formats seconds to have 5 digits of precision with trailing zeros removed
+if the number is less than 1 or with 2 digits of precision if the number is
+greater than zero.
+
+
The precision used is set in SUB_SECOND_PRECISION and
+DEFAULT_PRECISION.
+ This class is part of a private API.
+ You should avoid using this class if possible, as it may be removed or be changed in the future.
+
+
+
RSpec::Core::Formatters::Loader is an internal class for
+managing formatters used by a particular configuration. It is not expected
+to be used directly, but only through the configuration interface.
This class isn't loaded at runtime but serves to document all of the
+notifications implemented as part of the standard interface. The reporter
+will issue these during a normal test suite run, but a formatter will only
+receive those notifications it has registered itself to receive. To
+register a formatter call:
# File 'lib/rspec/core/formatters/protocol.rb', line 89
+
+
+
+
+
+
+
+
+
+
+ - (void) start
+
+
+
+
+
+
+
+
+
This method is invoked before any examples are run, right after they have
+all been collected. This can be useful for special formatters that need to
+provide progress on feedback (graphical ones).
+
+
This will only be invoked once, and the next one to be invoked is
+#example_group_started.
# File 'lib/rspec/core/formatters/protocol.rb', line 25
+
+
+
+
+
+
+
+
+
+
+ - (void) start_dump
+
+
+
+
+
+
+
+
+
This method is invoked after all of the examples have executed. The next
+method to be invoked after this one is #dump_failures (BaseTextFormatter
+then calls #dump_failure once for each failed example.)
+
+
+
+
+
+
Parameters:
+
+
+
+
+ notification
+
+
+ (NullNotification)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/core/formatters/protocol.rb', line 105
+
+
+
+
+
+
+
+
+
+
+ - (void) stop
+
+
+
+
+
+
+
+
+
Invoked after all examples have executed, before dumping post-run reports.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ notification
+
+
+ (NullNotification)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/core/formatters/protocol.rb', line 97
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-core/RSpec/Core/Formatters/SnippetExtractor.html b/source/documentation/3.1/rspec-core/RSpec/Core/Formatters/SnippetExtractor.html
new file mode 100644
index 000000000..4869fc717
--- /dev/null
+++ b/source/documentation/3.1/rspec-core/RSpec/Core/Formatters/SnippetExtractor.html
@@ -0,0 +1,681 @@
+
+
+
+
+
+ Class: RSpec::Core::Formatters::SnippetExtractor
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Provides before, after and around
+hooks as a means of supporting common setup and teardown. This module is
+extended onto ExampleGroup, making the methods available from any
+describe or context block and included in
+Configuration, making them available off of the configuration object to
+define global setup or teardown logic.
The :example and :context scopes are also
+available as :each and :all, respectively. Use
+whichever you prefer.
+
+
+
+
+
Declare a block of code to be run after each example (using
+:example) or once after all examples n the context (using
+:context). See #before for more information about ordering.
+
+
Exceptions
+
+
after hooks are guaranteed to run even when there are
+exceptions in before hooks or examples. When an exception is
+raised in an after block, the exception is captured for later reporting,
+and subsequent after blocks are run.
+
+
Order
+
+
after hooks are stored in three scopes, which are run in
+order: :example, :context, and
+:suite. They can also be declared in several different places:
+RSpec.configure, a parent group, the current group. They are
+run in the following order:
+
+
after(:example)# declared in the current group
+after(:example)# declared in a parent group
+after(:example)# declared in RSpec.configure
+after(:context)# declared in the current group
+after(:context)# declared in a parent group
+after(:context)# declared in RSpec.configure
+after(:suite)# declared in RSpec.configure
+
+
This is the reverse of the order in which before hooks are
+run. Similarly, if more than one after is declared within any
+one scope, they are run in reverse order of that in which they are
+declared.
+
+
+
+
+
+
+
Overloads:
+
+
+
+
+
+ - (void) after(scope, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ scope
+
+
+ (Symbol)
+
+
+
+ —
+
+
:example, :context, or :suite
+(defaults to :example)
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) after(scope, conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ scope
+
+
+ (Symbol)
+
+
+
+ —
+
+
:example, :context, or :suite
+(defaults to :example)
+
+
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+after(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) after(conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+after(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
the syntax of around is similar to that of before
+and after but the semantics are quite different.
+before and after hooks are run in the context of
+of the examples with which they are associated, whereas around
+hooks are actually responsible for running the examples. Consequently,
+around hooks do not have direct access to resources that are
+made available within the examples and their associated before
+and after hooks.
+
+
+
+
+ Note:
+
+
:example/:each is the only supported scope.
+
+
+
+
+
Declare a block of code, parts of which will be run before and parts after
+the example. It is your responsibility to run the example:
+
+
around(:example)do|ex|
+ # do some stuff before
+ex.run
+ # do some stuff after
+end
+
+
+
The yielded example aliases run with call, which
+lets you treat it like a Proc. This is especially handy when
+working with libaries that manage their own setup and teardown using a
+block or proc syntax, e.g.
:example (defaults to :example) present for
+syntax parity with before and after, but
+:example/:each is the only supported value.
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) around(scope, conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ scope
+
+
+ (Symbol)
+
+
+
+ —
+
+
:example (defaults to :example) present for
+syntax parity with before and after, but
+:example/:each is the only supported value.
+
+
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+around(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) around(conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+around(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
The :example and :context scopes are also
+available as :each and :all, respectively. Use
+whichever you prefer.
+
+
+
+
+
Declare a block of code to be run before each example (using
+:example) or once before any example (using
+:context). These are usually declared directly in the
+ExampleGroup to which they apply, but they can also be shared across
+multiple groups.
+
+
You can also use before(:suite) to run a block of code before
+any example groups are run. This should be declared in RSpec.configure
+
+
Instance variables declared in before(:example) or
+before(:context) are accessible within each example.
+
+
Order
+
+
before hooks are stored in three scopes, which are run in
+order: :suite, :context, and
+:example. They can also be declared in several different
+places: RSpec.configure, a parent group, the current group.
+They are run in the following order:
+
+
before(:suite)# declared in RSpec.configure
+before(:context)# declared in RSpec.configure
+before(:context)# declared in a parent group
+before(:context)# declared in the current group
+before(:example)# declared in RSpec.configure
+before(:example)# declared in a parent group
+before(:example)# declared in the current group
+
+
If more than one before is declared within any one scope, they
+are run in the order in which they are declared.
+
+
Conditions
+
+
When you add a conditions hash to before(:example) or
+before(:context), RSpec will only apply that hook to groups or
+examples that match the conditions. e.g.
+
+
RSpec.configuredo|config|
+ config.before(:example,:authorized=>true)do
+ log_in_as:authorized_user
+ end
+end
+
+describeSomething,:authorized=>truedo
+ # the before hook will run in before each example in this group
+end
+
+describeSomethingElsedo
+ it"does something",:authorized=>truedo
+ # the before hook will run before this example
+end
+
+ it"does something else"do
+ # the hook will not run before this example
+end
+end
+
+
+
Warning: before(:suite, :with => :conditions)
+
+
The conditions hash is used to match against specific examples. Since
+before(:suite) is not run in relation to any specific example
+or group, conditions passed along with :suite are effectively
+ignored.
+
+
Exceptions
+
+
When an exception is raised in a before block, RSpec skips any
+subsequent before blocks and the example, but runs all of the
+after(:example) and after(:context) hooks.
+
+
Warning: implicit before blocks
+
+
before hooks can also be declared in shared contexts which get
+included implicitly either by you or by extension libraries. Since RSpec
+runs these in the order in which they are declared within each scope, load
+order matters, and can lead to confusing results when one before block
+depends on state that is prepared in another before block that gets run
+later.
+
+
Warning: before(:context)
+
+
It is very tempting to use before(:context) to speed things
+up, but we recommend that you avoid this as there are a number of gotchas,
+as well as things that simply don't work.
+
+
context
+
+
before(:context) is run in an example that is generated to
+provide group context for the block.
+
+
instance variables
+
+
Instance variables declared in before(:context) are shared
+across all the examples in the group. This means that each example can
+change the state of a shared object, resulting in an ordering dependency
+that can make it difficult to reason about failures.
+
+
unsupported rspec constructs
+
+
RSpec has several constructs that reset state between each example
+automatically. These are not intended for use from within
+before(:context):
+
+
let declarations
+
+
subject declarations
+
+
Any mocking, stubbing or test double declaration
+
+
+
other frameworks
+
+
Mock object frameworks and database transaction managers (like
+ActiveRecord) are typically designed around the idea of setting up before
+an example, running that one example, and then tearing down. This means
+that mocks and stubs can (sometimes) be declared in
+before(:context), but get torn down before the first real
+example is ever run.
+
+
You can create database-backed model objects in a
+before(:context) in rspec-rails, but it will not be wrapped in
+a transaction for you, so you are on your own to clean up in an
+after(:context) block.
+describeParserdo
+ before(:context)do
+ File.open(file_to_parse,'w')do|f|
+ f.write<<-CONTENT
+ stuff in the file
+ CONTENT
+end
+ end
+
+ it"parses the file"do
+ Parser.parse(file_to_parse)
+ end
+
+ after(:context)do
+ File.delete(file_to_parse)
+ end
+end
+
+
+
+
Overloads:
+
+
+
+
+
+ - (void) before(scope, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ scope
+
+
+ (Symbol)
+
+
+
+ —
+
+
:example, :context, or :suite
+(defaults to :example)
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) before(scope, conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ scope
+
+
+ (Symbol)
+
+
+
+ —
+
+
:example, :context, or :suite
+(defaults to :example)
+
+
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+before(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
+
+
+
+
+
+
+
+
+
+
+
+
+ - (void) before(conditions, &block)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ conditions
+
+
+ (Hash)
+
+
+
+ —
+
+
constrains this hook to examples matching these conditions e.g.
+before(:example, :ui => true) { ... } will only run with
+examples or groups declared with :ui => true.
This only works if you are using rspec-expectations.
+
+
+
+
+ Note:
+
+
If you are using RSpec's newer expect-based syntax you may want to use
+is_expected.to instead of should.
+
+
+
+
+
When should is called with no explicit receiver, the call is
+delegated to the object returned by subject. Combined with an
+implicit subject this supports very concise expressions.
# File 'lib/rspec/core/memoized_helpers.rb', line 99
+
+defshould_not(matcher=nil,message=nil)
+ RSpec::Expectations::NegativeExpectationHandler.handle_matcher(subject,matcher,message)
+end
+
+
+
+
+
+
+
+
+ - (void) subject
+
+
+
+
+
+
+
+
+
+ Note:
+
+
subject was contributed by Joe Ferris to support the one-liner
+syntax embraced by shoulda matchers:
+
+
describeWidgetdo
+ it{is_expected.tovalidate_presence_of(:name)}
+ # or
+it{shouldvalidate_presence_of(:name)}
+end
+
+
While the examples below demonstrate how to use subject
+explicitly in examples, we recommend that you define a method with an
+intention revealing name instead.
+
+
+
+
+ Note:
+
+
Because subject is designed to create state that is reset
+between each example, and before(:context) is designed to
+setup state that is shared across all examples in an example
+group, subject is not intended to be used in a
+before(:context) hook.
+
+
+
+
+
+
+
+
+
+
+
Examples:
+
+
+
+# explicit declaration of subject
+describePersondo
+ subject{Person.new(:birthdate=>19.years.ago)}
+ it"should be eligible to vote"do
+ subject.shouldbe_eligible_to_vote
+ # ^ ^ explicit reference to subject not recommended
+end
+end
+
+# implicit subject => { Person.new }
+describePersondo
+ it"should be eligible to vote"do
+ subject.shouldbe_eligible_to_vote
+ # ^ ^ explicit reference to subject not recommended
+end
+end
+
+# one-liner syntax - expectation is set on the subject
+describePersondo
+ it{is_expected.tobe_eligible_to_vote}
+ # or
+it{shouldbe_eligible_to_vote}
+end
This module is extended onto ExampleGroup, making the methods available
+to be called from within example group blocks. You can think of them as
+being analagous to class macros.
Declares a subject for an example group which can then be
+wrapped with expect using is_expected to make it
+the target of an expectation in a concise, one-line example.
Just like subject, except the block is invoked by an implicit
+before hook.
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (void) let(name, &block)
+
+
+
+
+
+
+
+
+
+ Note:
+
+
letcan enhance readability when used sparingly (1,2,
+or maybe 3 declarations) in any given example group, but that can quickly
+degrade with overuse. YMMV.
+
+
+
+
+ Note:
+
+
let uses an ||= conditional that has the
+potential to behave in surprising ways in examples that spawn separate
+threads, though we have yet to see this in practice. You've been
+warned.
+
+
+
+
+ Note:
+
+
Because let is designed to create state that is reset between
+each example, and before(:context) is designed to setup state
+that is shared across all examples in an example group,
+let is not intended to be used in a
+before(:context) hook.
+
+
+
+
+
Generates a method whose return value is memoized after the first call.
+Useful for reducing duplication between examples that assign values to the
+same local variable.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+describeThingdo
+ let(:thing){Thing.new}
+
+ it"does something"do
+ # first invocation, executes block, memoizes and returns result
+thing.do_something
+
+ # second invocation, returns the memoized value
+thing.shouldbe_something
+ end
+end
# File 'lib/rspec/core/memoized_helpers.rb', line 231
+
+deflet(name,&block)
+ # We have to pass the block directly to `define_method` to
+# allow it to use method constructs like `super` and `return`.
+raise"#let or #subject called without a block"ifblock.nil?
+ MemoizedHelpers.module_for(self).__send__(:define_method,name,&block)
+
+ # Apply the memoization. The method has been defined in an ancestor
+# module so we can use `super` here to get the value.
+ifblock.arity==1
+ define_method(name){__memoized.fetch(name){|k|__memoized[k]=super(RSpec.current_example,&nil)}}
+ else
+ define_method(name){__memoized.fetch(name){|k|__memoized[k]=super(&nil)}}
+ end
+end
+
+
+
+
+
+
+
+
+ - (void) let!(name, &block)
+
+
+
+
+
+
+
+
+
Just like let, except the block is invoked by an implicit
+before hook. This serves a dual purpose of setting up state
+and providing a memoized reference to that state.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+classThing
+ defself.count
+ @count||=0
+ end
+
+ defself.count=(val)
+ @count+=val
+ end
+
+ defself.reset_count
+ @count=0
+ end
+
+ definitialize
+ self.class.count+=1
+ end
+end
+
+describeThingdo
+ after(:example){Thing.reset_count}
+
+ context"using let"do
+ let(:thing){Thing.new}
+
+ it"is not invoked implicitly"do
+ Thing.count.shouldeq(0)
+ end
+
+ it"can be invoked explicitly"do
+ thing
+ Thing.count.shouldeq(1)
+ end
+ end
+
+ context"using let!"do
+ let!(:thing){Thing.new}
+
+ it"is invoked implicitly"do
+ Thing.count.shouldeq(1)
+ end
+
+ it"returns memoized version on first invocation"do
+ thing
+ Thing.count.shouldeq(1)
+ end
+ end
+end
Declares a subject for an example group which can then be
+wrapped with expect using is_expected to make it
+the target of an expectation in a concise, one-line example.
+
+
Given a name, defines a method with that name which returns
+the subject. This lets you declare the subject once and access
+it implicitly in one-liners and explicitly using an intention revealing
+name.
+
+
When given a name, calling super in the block is
+not supported.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+describeCheckingAccount,"with $50"do
+ subject{CheckingAccount.new(Money.new(50,:USD))}
+ it{is_expected.tohave_a_balance_of(Money.new(50,:USD))}
+ it{is_expected.not_tobe_overdrawn}
+end
+
+describeCheckingAccount,"with a non-zero starting balance"do
+ subject(:account){CheckingAccount.new(Money.new(50,:USD))}
+ it{is_expected.not_tobe_overdrawn}
+ it"has a balance equal to the starting balance"do
+ account.balance.shouldeq(Money.new(50,:USD))
+ end
+end
+
+
+
Parameters:
+
+
+
+
+ name
+
+
+ (String, Symbol)
+
+
+ (defaults to: nil)
+
+
+ —
+
+
used to define an accessor with an intention revealing name
+
+
+
+
+
+
+ block
+
+
+
+
+
+
+ —
+
+
defines the value to be returned by subject in examples
# File 'lib/rspec/core/memoized_helpers.rb', line 338
+
+defsubject(name=nil,&block)
+ ifname
+ let(name,&block)
+ alias_method:subject,name
+
+ self::NamedSubjectPreventSuper.__send__(:define_method,name)do
+ raiseNotImplementedError,"`super` in named subjects is not supported"
+ end
+ else
+ let(:subject,&block)
+ end
+end
Just like subject, except the block is invoked by an implicit
+before hook. This serves a dual purpose of setting up state
+and providing a memoized reference to that state.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+classThing
+ defself.count
+ @count||=0
+ end
+
+ defself.count=(val)
+ @count+=val
+ end
+
+ defself.reset_count
+ @count=0
+ end
+
+ definitialize
+ self.class.count+=1
+ end
+end
+
+describeThingdo
+ after(:example){Thing.reset_count}
+
+ context"using subject"do
+ subject{Thing.new}
+
+ it"is not invoked implicitly"do
+ Thing.count.shouldeq(0)
+ end
+
+ it"can be invoked explicitly"do
+ subject
+ Thing.count.shouldeq(1)
+ end
+ end
+
+ context"using subject!"do
+ subject!(:thing){Thing.new}
+
+ it"is invoked implicitly"do
+ Thing.count.shouldeq(1)
+ end
+
+ it"returns memoized version on first invocation"do
+ subject
+ Thing.count.shouldeq(1)
+ end
+ end
+end
Each ExampleGroup class and Example instance owns an instance of Metadata,
+which is Hash extended to support lazy evaluation of values associated with
+keys that may or may not be used by any example or group.
+
+
In addition to metadata that is used internally, this also stores
+user-supplied metadata, e.g.
:type => :ui is stored in the Metadata owned by the example
+group, and :slow => true is stored in the Metadata owned by
+the example. These can then be used to select which examples are run using
+the --tag option on the command line, or several methods on
+Configuration used to filter a run (e.g.
+filter_run_including, filter_run_excluding, etc).
# File 'lib/rspec/core/metadata.rb', line 32
+
+defself.relative_path(line)
+ # Matches strings either at the beginning of the input or prefixed with a whitespace,
+# containing the current path, either postfixed with the separator, or at the end of the string.
+# Match groups are the character before and the character after the string if any.
+#
+# http://rubular.com/r/fT0gmX6VJX
+# http://rubular.com/r/duOrD4i3wb
+# http://rubular.com/r/sbAMHFrOx1
+#
+
+ regex=/(\A|\s)#{File.expand_path('.')}(#{File::SEPARATOR}|\s|\Z)/
+
+ line=line.sub(regex,"\\1.\\2")
+ line=line.sub(/\A([^:]+:\d+)$/,'\\1')
+ returnnilifline=='-e:1'
+ line
+rescueSecurityError
+ nil
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-core/RSpec/Core/MetadataFilter.html b/source/documentation/3.1/rspec-core/RSpec/Core/MetadataFilter.html
new file mode 100644
index 000000000..0aa271747
--- /dev/null
+++ b/source/documentation/3.1/rspec-core/RSpec/Core/MetadataFilter.html
@@ -0,0 +1,120 @@
+
+
+
+
+
+ Module: RSpec::Core::MetadataFilter
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Contains metadata filtering logic. This has been extracted from the
+metadata classes because it operates ON a metadata hash but does not manage
+any of the state in the hash. We're moving towards having metadata be a
+raw hash (not a custom subclass), so externalizing this filtering logic
+helps us move in that direction.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-core/RSpec/Core/Notifications.html b/source/documentation/3.1/rspec-core/RSpec/Core/Notifications.html
new file mode 100644
index 000000000..a2e48bb2d
--- /dev/null
+++ b/source/documentation/3.1/rspec-core/RSpec/Core/Notifications.html
@@ -0,0 +1,127 @@
+
+
+
+
+
+ Module: RSpec::Core::Notifications
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
The DeprecationNotification is issued by the reporter when a
+deprecated part of RSpec is encountered. It represents information about
+the deprecated call site.
The ExampleNotification represents notifications sent by the
+reporter which contain information about the current (or soon to be)
+example. It is used by formatters to access information about that example.
+
+
+
+
+
+
+
+
Examples:
+
+
+
defexample_started(notification)
+ puts"Hey I started #{notification.example.description}"
+end
The GroupNotification represents notifications sent by the
+reporter which contain information about the currently running (or soon to
+be) example group It is used by formatters to access information about that
+group.
+
+
+
+
+
+
+
+
Examples:
+
+
+
defexample_group_started(notification)
+ puts"Hey I started #{notification.group.description}"
+end
Returns the message generated for this failure line by line.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Array(String))
+
+
+
+ —
+
+
The example failure message
+
+
+
+
+
+
+
+
+
+
+
+
+305
+306
+307
+
+
+
# File 'lib/rspec/core/notifications.rb', line 305
+
+defmessage_lines
+ ["Expected pending '#{example.execution_result.pending_message}' to fail. No Error was raised."]
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-core/RSpec/Core/Notifications/ProfileNotification.html b/source/documentation/3.1/rspec-core/RSpec/Core/Notifications/ProfileNotification.html
new file mode 100644
index 000000000..12acab5a8
--- /dev/null
+++ b/source/documentation/3.1/rspec-core/RSpec/Core/Notifications/ProfileNotification.html
@@ -0,0 +1,410 @@
+
+
+
+
+
+ Class: RSpec::Core::Notifications::ProfileNotification
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
The ProfileNotification holds information about the results of
+running a test suite when profiling is enabled. It is used by formatters to
+provide information at the end of the test run for profiling information.
The StartNotification represents a notification sent by the
+reporter when the suite is started. It contains the expected amount of
+examples to be executed, and the load time of RSpec.
The SummaryNotification holds information about the results of
+running a test suite. It is used by formatters to provide information at
+the end of the test run.
before(:example) hooks are eval'd when you use the
+pending method within an example. If you want to declare an
+example pending and bypass the before hooks as
+well, you can pass :pending => true to the it
+method:
Marks an example as pending. The rest of the example will still be
+executed, and if it passes the example will fail to indicate that the
+pending can be removed.
+
+
+
+
+
+
+
+
Examples:
+
+
+
describe"an example"do
+ # reported as "Pending: no reason given"
+it"is pending with no message"do
+ pending
+ raise"broken"
+ end
+
+ # reported as "Pending: something else getting finished"
+it"is pending with a custom message"do
+ pending("something else getting finished")
+ raise"broken"
+ end
+end
# File 'lib/rspec/core/pending.rb', line 68
+
+defpending(message=nil)
+ current_example=RSpec.current_example
+
+ ifblock_given?
+ raiseArgumentError,<<-EOS.gsub(/^\s+\|/,'')
+ |The semantics of `RSpec::Core::Pending#pending` have changed in
+ |RSpec 3. In RSpec 2.x, it caused the example to be skipped. In
+ |RSpec 3, the rest of the example is still run but is expected to
+ |fail, and will be marked as a failure (rather than as pending) if
+ |the example passes.
+ |
+ |Passing a block within an example is now deprecated. Marking the
+ |example as pending provides the same behavior in RSpec 3 which was
+ |provided only by the block in RSpec 2.x.
+ |
+ |Move the code in the block provided to `pending` into the rest of
+ |the example body.
+ |
+ |Called from #{CallerFilter.first_non_rspec_line}.
+ |
+ EOS
+elsifcurrent_example
+ Pending.mark_pending!current_example,message
+ else
+ raise"`pending` may not be used outside of examples, such as in " \
+ "before(:context). Maybe you want `skip`?"
+ end
+end
describe"an example"do
+ # reported as "Pending: no reason given"
+it"is skipped with no message"do
+ skip
+ end
+
+ # reported as "Pending: something else getting finished"
+it"is skipped with a custom message"do
+ skip"something else getting finished"
+ end
+end
Initializes the report run and yields itself for further reporting. The
+block is required, so that the reporter can manage cleaning up after the
+run.
This is not generally needed. The rspec command takes care of
+running examples for you without involving an at_exit hook.
+This is only needed if you are running specs using the ruby
+command, and even then, the normal way to invoke this is by requiring
+rspec/autorun.
+
+
+
+
+
Register an at_exit hook that runs the suite when the process
+exits.
# File 'lib/rspec/core/runner.rb', line 12
+
+defself.autorun
+ ifautorun_disabled?
+ RSpec.deprecate("Requiring `rspec/autorun` when running RSpec via the `rspec` command")
+ return
+ elsifinstalled_at_exit?||running_in_drb?
+ return
+ end
+
+ at_exitdo
+ # Don't bother running any specs and just let the program terminate
+# if we got here due to an unrescued exception (anything other than
+# SystemExit, which is raised when somebody calls Kernel#exit).
+nextunless$!.nil?||$!.is_a?(SystemExit)
+
+ # We got here because either the end of the program was reached or
+# somebody called Kernel#exit. Run the specs and then override any
+# existing exit status with RSpec's exit status if any specs failed.
+invoke
+ end
+ @installed_at_exit=true
+end
+
+
+
+
+
+
+
+
+ + (void) invoke
+
+
+
+
+
+
+
+
+
Runs the suite of specs and exits the process with an appropriate exit
+code.
This is used internally by RSpec to run a suite, but is available for use
+by any other automation tool.
+
+
If you want to run this multiple times in the same process, and you want
+files like spec_helper.rb to be reloaded, be sure to load
+load instead of require.
# File 'lib/rspec/core/runner.rb', line 56
+
+defself.run(args,err=$stderr,out=$stdout)
+ trap_interrupt
+ options=ConfigurationOptions.new(args)
+
+ ifoptions.options[:drb]
+ require'rspec/core/drb'
+ begin
+ DRbRunner.new(options).run(err,out)
+ rescueDRb::DRbConnError
+ err.puts"No DRb server is running. Running in local process instead ..."
+ new(options).run(err,out)
+ end
+ else
+ new(options).run(err,out)
+ end
+end
Shared example groups let you define common context and/or common examples
+that you wish to use in multiple example groups.
+
+
When defined, the shared group block is stored for later evaluation. It can
+later be included in an example group either explicitly (using
+include_examples, include_context or
+it_behaves_like) or implicitly (via matching metadata).
+
+
Named shared example groups are scoped based on where they are defined.
+Shared groups defined in an example group are available for inclusion in
+that example group or any child example groups, but not in any parent or
+sibling example groups. Shared example groups defined at the top level can
+be included from any example group.
Stores the block for later use. The block will be evaluated in the context
+of an example group via include_examples,
+include_context, or it_behaves_like.
+
+
+
+
+
+
+
+
Examples:
+
+
+
shared_examples"auditable"do
+ it"stores an audit record on save!"do
+ expect{auditable.save!}.tochange(Audit,:count).by(1)
+ end
+end
+
+describeAccountdo
+ it_behaves_like"auditable"do
+ let(:auditable){Account.new}
+ end
+end
# File 'lib/rspec/core/shared_example_group.rb', line 50
+
+defshared_examples(name,*args,&block)
+ top_level=self==ExampleGroup
+ iftop_level&&RSpec.thread_local_metadata[:in_example_group]
+ raise"Creating isolated shared examples from within a context is " \
+ "not allowed. Remove `RSpec.` prefix or move this to a " \
+ "top-level scope."
+ end
+
+ RSpec.world.shared_example_group_registry.add(self,name,*args,&block)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-core/RSpec/Core/SharedExampleGroup/TopLevelDSL.html b/source/documentation/3.1/rspec-core/RSpec/Core/SharedExampleGroup/TopLevelDSL.html
new file mode 100644
index 000000000..084056623
--- /dev/null
+++ b/source/documentation/3.1/rspec-core/RSpec/Core/SharedExampleGroup/TopLevelDSL.html
@@ -0,0 +1,295 @@
+
+
+
+
+
+ Module: RSpec::Core::SharedExampleGroup::TopLevelDSL
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Apply --seed before loading --require files so
+that required files can access the provided seed. (Myron Marston, #1745)
+
+
Handle
+RSpec::Core::Formatters::DeprecationFormatter::FileStream
+being reopened with an IO stream, which sometimes happens with spring.
+(Kevin Mook, #1757)
Fix Metadata.relative_path so that for a current directory of
+/foo/bar, /foo/bar_1 is not wrongly converted to
+._1. (Akos Vandra, #1730)
+
+
Prevent constant lookup mistakenly finding
+RSpec::ExampleGroups generated constants on 1.9.2 by
+appending a trailing _ to the generated names. (Jon Rowe,
+#1737)
+
+
Fix bug in :pending metadata. If it got set in any way besides
+passing it as part of the metadata literal passed to it (such
+as by using define_derived_metadata), it did not have the
+desired effect, instead marking the example as :passed.
+(Myron Marston, #1739)
Fix regression in rake task pattern handling, that prevented patterns that
+were relative from the current directory rather than from spec
+from working properly. (Myron Marston, #1734)
Fix issue with the rake task incorrectly escaping strings on Windows. (Jon
+Rowe #1718)
+
+
Support absolute path patterns. While this wasn't officially supported
+previously, setting rake_task.pattern to an absolute path
+pattern in RSpec 3.0 and before worked since it delegated to
+FileList internally (but now just forwards the pattern on to
+the rspec command). (Myron Marston, #1726)
Fix implicit subject when using describe false or
+describe nil so that it returns the provided primitive rather
+than the string representation. (Myron Marston, #1710)
+
+
Fix backtrace filtering to allow code in subdirectories of your current
+working directory (such as vendor/bundle/…) to be filtered from
+backtraces. (Myron Marston, #1708)
Fix yet another regression in rake task pattern handling, to allow
+task.pattern = FileList["..."] to work. That was never
+intended to be supported but accidentally worked in 3.0 and earlier.
+(Myron Marston, #1701)
+
+
Fix pattern handling so that files are normalized to absolute paths before
+subtracting the --exclude-pattern matched files from the
+--pattern matched files so that it still works even if the
+patterns are in slightly different forms (e.g. one starting with
+./). (Christian Nelson, #1698)
Fix a regression in rake task pattern handling, so that
+rake_task.pattern = array works again. While we never
+intended to support array values (or even knew that worked!), the
+implementation from 3.0 and earlier used FileList internally,
+which allows arrays. The fix restores the old behavior. (Myron Marston,
+#1694)
Update files generated by rspec --init so that warnings are
+enabled in commented out section of spec_helper rather than
+.rspec so users have to consciously opt-in to the setting.
+(Andrew Hooker, #1572)
+
+
Update spec_helper generated by rspec --init so
+that it sets the new rspec-expectations
+include_chain_clauses_in_custom_matcher_descriptions config
+option (which will be on by default in RSpec 4) and also sets the
+rspec-mocks verify_partial_doubles option (which will also
+default to on in RSpec 4). (Myron Marston, #1647)
+
+
Provide an inspect output for example procsy objects (used in
+around hooks) that doesn't make them look like procs. (Jon Rowe,
+#1620)
+
+
Remove a few unneeded require statements from
+rspec/core/rake_task.rb, making it even more lighterweight.
+(Myron Marston, #1640)
+
+
Allow rspec-core to be used when neither rspec-mocks or rspec-expectations
+are installed, without requiring any user configuration. (Sam Phippen,
+Myron Marston, #1615)
+
+
Don't filter out gems from backtraces by default. (The RSpec gems will
+still be filtered). User feedback has indicated that including gems in
+default backtraces will be useful. (Myron Marston, #1641)
+
+
Add new config.filter_gems_from_backtrace "rack",
+"rake" API to easily filter the named gems from
+backtraces. (Myron Marston, #1682)
+
+
Fix default backtrace filters so that the RSpec binary is excluded when
+installing RSpec as a bundler :git dependency. (Myron
+Marston, #1648)
+
+
Simplify command generated by the rake task so that it no longer includes
+unnecessary -S. (Myron Marston, #1559)
+
+
Add --exclude-pattern CLI option, config.exclude_pattern
+= config option and task.exclude_pattern = rake task
+config option. Matching files will be excluded. (John Gesimondo, Myron
+Marston, #1651, #1671)
+
+
When an around hook fails to execute the example, mark it as pending
+(rather than passing) so the user is made aware of the fact that the
+example did not actually run. (Myron Marston, #1660)
+
+
Remove dependency on FileUtils from the standard library so
+that users do not get false positives where their code relies on it but
+they are not requiring it. (Sam Phippen, #1565)
+
+
+
Bug Fixes:
+
+
Fix rake task t.pattern = option so that it does not run all
+specs when it matches no files, by passing along a --pattern
+option to the rspec command, rather than resolving the file
+list and passing along the files individually. (Evgeny Zislis, #1653)
+
+
Fix rake task default pattern so that it follows symlinks properly. (Myron
+Marston, #1672)
+
+
Fix default pattern used with rspec command so that it follows
+symlinks properly. (Myron Marston, #1672)
+
+
Change how we assign constant names to example group classes so that it
+avoids a problem with describe "Core". (Daniela
+Wellisz, #1679)
+
+
Handle rendering exceptions that have a different encoding than that of
+their original source file. (Jon Rowe, #1681)
+
+
Allow access to message_lines without colour for failed examples even when
+they're part of a shared example group. (tomykaira, #1689)
Fix processing order of CLI options so that if
+config.files_to_run is accessed from a file loaded by
+--require, --pattern is still applied. (Myron
+Marston, #1652)
+
+
Fix config.pattern= so that it still takes affect even if
+config.files_to_run has already been accessed. (Myron Marston,
+#1652)
Fix regression in CLI option handling that prevented --tag
+slow passed at the command line from overriding --tag
+~slow in .rspec. (Colin Jones, #1602)
+
+
Fix metadata :example_group deprecation warning so that it
+gets issued at the call site of the configuration that specified it as a
+filter rather than later when an example group is defined. (Myron Marston,
+#1562)
+
+
Make the line that is printed when a shared example group fails indicating
+where the concrete example group is white, separating it from the stack
+trace that is produced for the failure. (Sam Phippen, Jon Rowe, #1606)
Fix BaseTextFormatter so that it does not re-close a closed
+output stream. (Myron Marston)
+
+
Fix regression in metadata that caused the metadata hash of a top-level
+example group to have a :parent_example_group key even though
+it has no parent example group. (Myron Marston)
+
+
+
Enhancements:
+
+
Alter the default spec_helper.rb to no longer recommend
+config.full_backtrace = true see #1536 for discussion. (Jon
+Rowe)
Change described_class so that in a nested group like
+describe MyClass, it returns MyClass rather
+than the outer group's described class. (Myron Marston)
+
+
Refactor filter manager so that it no longer subclasses Hash and has a
+tighter, more domain-specific interface. (Sergey Pchelincev)
+
+
Remove legacy colours definitions from BaseTextFormatter. (Jon
+Rowe)
+
+
Remove console color definitions from BaseTextFormatter. (Jon
+Rowe)
+
+
Restructure example group metadata so that the computed keys are exposed
+directly off of the metadata hash rather than being on a nested
+:example_group subhash. In addition, the parent example group
+metadata is now available as [:parent_example_group] rather
+than [:example_group][:example_group]. Deprecated access via
+the old key structure is still provided. (Myron Marston)
+
+
Remove :describes metadata key. It duplicates
+:described_class for no good reason. Deprecated access via
+:describes is still provided. (Myron Marston)
+
+
Rename :example_group_block metadata key to
+:block. (Myron Marston)
Move BaseTextFormatter#colorize_summary to
+SummaryNotification#colorize_with (Jon Rowe).
+
+
describe some_hash treated some_hash as metadata
+in RSpec 2.x but will treat it as the described object in RSpec 3.0.
+Metadata must always come after the description args. (Myron Marston)
+
+
Remove deprecated display_name alias of
+ExampleGroup.description. (Myron Marston)
+
+
Remove deprecated describes alias of
+ExampleGroup.described_class. (Myron Marston)
+
+
Remove deprecated
+RSpec::Core::ExampleGroup.alias_it_behaves_like_to. Use
+RSpec::Core::Configuration#alias_it_behaves_like_to instead.
+(Myron Marston)
Removed focused example alias and change example/group aliases
+fit, focus, fcontext and
+fdescribe to no longer include :focused =>
+true metadata. They only contain :focus => true
+metadata now. This means that you will need to filter them with
+filter_run :focus, not filter_run :focused.
+(Myron Marston)
+
+
Remove --line-number filtering. It's semantically dubious
+since it's a global filter (potentially applied to multiple files) but
+there's no meaningful connection between the same line number in
+multiple files. Instead use the rspec path/to/spec.rb:23:46
+form, which is terser and makes more sense as it is scoped to a file.
+(Myron Marston)
+
+
Remove --default_path as an alias for
+--default-path. (Jon Rowe)
+
+
Remove deprecated share_examples_for. There's still
+shared_examples and shared_examples_for. (Myron
+Marston)
+
+
Rename RSpec::Core::Configuration#warnings to
+RSpec::Core::Configuration#warnings? since it's a boolean
+flag. (Myron Marston)
+
+
RSpec's global state is no longer reset after a spec run. This gives
+more flexibility to alternate runners to decide when and if they want the
+state reset. Alternate runners are now responsible for calling this (or
+doing a similar reset) if they are going to run the spec suite multiple
+times in the same process. (Sam Phippen)
+
+
Merge RSpec::Core::CommandLine (never formally declared
+public) into RSpec::Core::Runner. (Myron Marston)
+
+
Remove color_enabled as an alias of color. (Jon
+Rowe)
+
+
Remove backtrace_cleaner as an alias of
+backtrace_formatter. (Jon Rowe)
+
+
Remove filename_pattern as an alias of pattern.
+(Jon Rowe)
+
+
Extract support for legacy formatters to
+rspec-legacy_formatters. (Jon Rowe)
+
+
RSpec::Configuration#formatters now returns a dup to prevent
+mutation. (Jon Rowe)
+
+
Replace stdlib as an available expectation framework with
+test_unit and minitest. (Aaron Kromer)
+
+
Remove backtrace formatting helpers from BaseTextFormatter.
+(Jon Rowe)
+
+
Extract profiler support to ProfileFormatter and
+ProfileNotification. Formatters should implement
+dump_profile if they wish to respond to
+--profile. (Jon Rowe)
+
+
Extract remaining formatter state to reporter and notifications. Introduce
+ExamplesNotification to share information about examples that
+was previously held in BaseFormatter. (Jon Rowe)
+
+
+
Enhancements:
+
+
Add config.default_formatter attribute, which can be used to
+set a formatter which will only be used if no other formatter is set
+(e.g. via --formatter). (Myron Marston)
+
+
Support legacy colour definitions in LegacyFormatterAdaptor.
+(Jon Rowe)
+
+
Migrate execution_result (exposed by metadata) from a hash to
+a first-class object with appropriate attributes. status is
+now stored and returned as a symbol rather than a string. It retains
+deprecated hash behavior for backwards compatibility. (Myron Marston)
+
+
Provide console code helper for formatters. (Jon Rowe)
+
+
Use raw ruby hashes for the metadata hashes rather than a subclass of a
+hash. Computed metadata entries are now computed in advance rather than
+being done lazily on first access. (Myron Marston)
+
+
Add :block metadata entry to the example metadata, bringing
+parity with :block in the example group metadata. (Myron
+Marston)
+
+
Add fspecify and fexample as aliases of
+specify and example with :focus =>
+true metadata for parity with fit. (Myron Marston)
+
+
Add legacy support for colorize_summary. (Jon Rowe)
+
+
Restructure runner so it can be more easily customized in a subclass for
+an alternate runner. (Ben Hoskings)
+
+
Document RSpec::Core::ConfigurationOptions as an officially
+supported public API. (Myron Marston)
+
+
Add --deprecation-out CLI option which directs deprecation
+warnings to the named file. (Myron Marston)
+
+
Minitest 5 compatability for expect_with :stdlib (now
+available as expect_with :minitest). (Xavier Shay)
+
+
Reporter now notifies formatters of the load time of RSpec and your specs
+via StartNotification and SummaryNotification.
+(Jon Rowe)
+
+
Add disable_monkey_patching! config option that disables all
+monkey patching from whatever pieces of RSpec you use. (Alexey Fedorov)
+
+
Add Pathname support for setting all output streams. (Aaron
+Kromer)
+
+
Add config.define_derived_metadata, which can be used to apply
+additional metadata to all groups or examples that match a given filter.
+(Myron Marston)
+
+
Provide formatted and colorized backtraces via
+FailedExampleNotification and send
+PendingExampleFixedNotifications when the error is due to a
+passing spec you expect to fail. (Jon Rowe)
+
+
Add dump_profile to formatter API to allow formatters to
+implement support for --profile. (Jon Rowe)
+
+
Allow colourising text via ConsoleCodes with RSpec
+'states' (e.g. :success, :failure)
+rather than direct colour codes. (Jon Rowe)
+
+
Expose fully_formatted methods off the formatter notification
+objects that make it easy for a custom formatter to produce formatted
+output like rspec-core's. (Myron Marston)
+
+
+
Bug Fixes:
+
+
Fix spec_helper.rb file generated by rspec --init
+so that the recommended settings correctly use the documentation formatter
+when running one file. (Myron Marston)
+
+
Fix ordering problem where descriptions were generated after tearing down
+mocks, which resulted in unexpected exceptions. (Bradley Schaefer, Aaron
+Kromer, Andrey Savchenko)
+
+
Allow a symbol to be used as an implicit subject (e.g. describe
+:foo). (Myron Marston)
+
+
Prevent creating an isolated context (i.e. using
+RSpec.describe) when already inside a context. There is no
+reason to do this, and it could potentially cause unexpected bugs. (Xavier
+Shay)
+
+
Fix shared example group scoping so that when two shared example groups
+share the same name at different levels of nested contexts, the one in the
+nearest context is used. (Myron Marston)
+
+
Fix --warnings option so that it enables warnings immediately
+so that it applies to files loaded by --require. (Myron
+Marston)
+
+
Issue a warning when you set config.deprecation_stream too
+late for it to take effect because the reporter has already been setup.
+(Myron Marston)
+
+
Add the full RSpec::Core::Example interface to the argument
+yielded to around hooks. (Myron Marston)
+
+
Line number always takes precendence when running specs with filters.
+(Xavier Shay)
+
+
Ensure :if and :unless metadata filters are treated as a special case and
+are always in-effect. (Bradley Schaefer)
+
+
Ensure the currently running installation of RSpec is used when the rake
+task shells out to rspec, even if a newer version is also
+installed. (Postmodern)
+
+
Using a legacy formatter as default no longer causes an infinite loop.
+(Xavier Shay)
Make mock_with option more strict. Strings are no longer
+supported (e.g. mock_with "mocha") – use a symbol
+instead. Also, unrecognized values will now result in an error rather than
+falling back to the null mocking adapter. If you want to use the null
+mocking adapter, use mock_with :nothing (as has been
+documented for a long time). (Myron Marston)
+
+
Remove support for overriding RSpec's built-in :if and
+:unless filters. (Ashish Dixit)
+
+
Custom formatters are now required to call
+RSpec::Core::Formatters.register(formatter_class,
+*notifications) where notifications is the list of
+events the formatter wishes to be notified about. Notifications are
+handled by methods matching the names on formatters. This allows us to add
+or remove notifications without breaking existing formatters. (Jon Rowe)
+
+
Change arguments passed to formatters. Rather than passing multiple
+arguments (which limits are ability to add additional arguments as doing
+so would break existing formatters), we now pass a notification value
+object that exposes the same data via attributes. This will allow us to
+add new bits of data to a notification event without breaking existing
+formatters. (Jon Rowe)
+
+
Remove support for deprecated :alias option for
+RSpec.configuration.add_setting. (Myron Marston)
+
+
Remove support for deprecated RSpec.configuration.requires =
+[...]. (Myron Marston)
+
+
Remove support for deprecated --formatter CLI option. (Myron
+Marston)
+
+
Remove support for deprecated --configure CLI option. (Myron
+Marston)
+
+
Remove support for deprecated
+RSpec::Core::RakeTask#spec_opts=. (Myron Marston)
+
+
An example group level pending block or :pending
+metadata now executes the example and cause a failure if it passes,
+otherwise it will be pending if it fails. The old “never run” behaviour is
+still used for xexample, xit, and
+xspecify, or via a new skip method or
+:skip metadata option. (Xavier Shay)
+
+
After calling pending inside an example, the remainder of the
+example will now be run. If it passes a failure is raised, otherwise the
+example is marked pending. The old “never run” behaviour is provided a by
+a new skip method. (Xavier Shay)
+
+
Pending blocks inside an example have been removed as a feature with no
+direct replacement. Use skip or pending without a
+block. (Xavier Shay)
+
+
Pending statement is no longer allowed in before(:all) hooks.
+Use skip instead. (Xavier Shay)
Remove support for specifying the documentation formatter using
+'s', 'n', 'spec' or 'nested'. (Jon Rowe)
+
+
+
Enhancements:
+
+
Add example run time to JSON formatter output. (Karthik Kastury)
+
+
Add more suggested settings to the files generated by rspec
+--init. (Myron Marston)
+
+
Add config.alias_example_group_to, which can be used to define
+a new method that defines an example group with the provided metadata.
+(Michi Huber)
+
+
Add xdescribe and xcontext as shortcuts to skip
+an example group. (Myron Marston)
+
+
Add fdescribe and fcontext as shortcuts to focus
+an example group. (Myron Marston)
+
+
Don't autorun specs via #at_exit by default. require
+'rspec/autorun' is only needed when running specs via
+ruby, as it always has been. Running specs via
+rake or rspec are both unaffected. (Ben Hoskings)
+
+
Add expose_dsl_globally config option, defaulting to true.
+When disabled it will remove the monkey patches rspec-core adds to
+main and Module (e.g. describe,
+shared_examples_for, etc). (Jon Rowe)
+
+
Expose RSpec DSL entry point methods (describe,
+shared_examples_for, etc) on the RSpec constant.
+Intended for use when expose_dsl_globally is set to
+false. (Jon Rowe)
+
+
For consistency, expose all example group aliases (including
+context) on the RSpec constant. If
+expose_dsl_globally is set to true, also expose
+them on main and Module. Historically, only
+describe was exposed. (Jon Rowe, Michi Huber)
+
+
Add hook scope :example as an alias for :each,
+and :context as an alias for :all. (John
+Feminella)
+
+
+
Bug Fixes:
+
+
Fix failure (undefined method path) in end-of-run summary
+when raise_errors_for_deprecations! is configured. (Myron
+Marston)
+
+
Issue error when attempting to use -i or --I on
+command line, too close to -I to be considered short hand for
+--init. (Jon Rowe)
+
+
Prevent adding formatters to an output target if the same formatter has
+already been added to that output. (Alex Peattie)
+
+
Allow a matcher-generated example description to be used when the example
+is pending. (Myron Marston)
+
+
Ensure the configured failure_exit_code is used by the rake
+task when there is a failure. (Jon Rowe)
+
+
Restore behaviour whereby system exclusion filters take priority over
+working directory (was broken in beta1). (Jon Rowe)
+
+
Prevent RSpec mangling file names that have substrings containing
+line_number or default_path. (Matijs van
+Zuijlen)
Remove RSpec::Core::ExampleGroup#example and
+RSpec::Core::ExampleGroup#running_example methods. If you need
+access to the example (e.g. to get its metadata), use a block arg instead.
+(David Chelimsky)
+
+
Remove TextMateFormatter, it has been moved to
+rspec-tmbundle. (Aaron Kromer)
+
+
Remove RCov integration. (Jon Rowe)
+
+
Remove deprecated support for RSpec 1 constructs (Myron Marston):
+
+
The Spec and Rspec constants (rather than
+RSpec).
+
+
Spec::Runner.configure rather than
+RSpec.configure.
+
+
Rake::SpecTask rather than RSpec::Core::RakeTask.
+
+
Remove deprecated support for share_as. (Myron Marston)
+
+
Remove --debug option (and corresponding option on
+RSpec::Core::Configuration). Instead, use -r<debugger
+gem name> to load whichever debugger gem you wish to use (e.g.
+ruby-debug, debugger, or pry).
+(Myron Marston)
+
+
Extract Autotest support to a seperate gem. (Jon Rowe)
+
+
Raise an error when a let or subject declaration
+is accessed in a before(:all) or after(:all)
+hook. (Myron Marston)
+
+
Extract its support to a separate gem. (Peter Alfvin)
+
+
Disallow use of a shared example group from sibling contexts, making them
+fully isolated. 2.14 and 2.99 allowed this but printed a deprecation
+warning. (Jon Rowe)
+
+
Remove RSpec::Core::Configuration#output and
+RSpec::Core::Configuration#out aliases of
+RSpec::Core::Configuration#output_stream. (Myron Marston)
+
+
Remove legacy ordering APIs deprecated in 2.99.0.beta1. (Myron Marston)
+
+
+
Enhancements:
+
+
Replace unmaintained syntax gem with coderay gem. (Xavier Shay)
+
+
Times in profile output are now bold instead of failure_color.
+(Matthew Boedicker)
+
+
Add --no-fail-fast command line option. (Gonzalo
+Rodríguez-Baltanás Díaz)
+
+
Runner now considers the local system ip address when running under Drb.
+(Adrian CB)
+
+
JsonFormatter now includes --profile information. (Alex /
+@MasterLambaster)
+
+
Always treat symbols passed as metadata args as hash keys with true
+values. RSpec 2 supported this with the
+treat_symbols_as_metadata_keys_with_true_values but now this
+behavior is always enabled. (Myron Marston)
+
+
Add --dry-run option, which prints the formatter output of
+your suite without running any examples or hooks. (Thomas Stratmann, Myron
+Marston)
+
+
Document the configuration options and default values in the
+spec_helper.rb file that is generated by RSpec. (Parker
+Selbert)
+
+
Give generated example group classes a friendly name derived from the
+docstring, rather than something like “Nested_2”. (Myron Marston)
+
+
Avoid affecting randomization of user code when shuffling examples so that
+users can count on their own seeds working. (Travis Herrick)
+
+
Ordering is no longer a single global property of the test suite. Each
+group can pick an ordering using :order metadata. (Andy
+Lindeman, Sam Phippen, Myron Marston)
+
+
Allow named custom ordering strategies to be registered, which can then be
+used on individual example groups. (Andy Lindeman, Sam Phippen, Myron
+Marston)
+
+
+
Deprecations:
+
+
treat_symbols_as_metadata_keys_with_true_values is deprecated
+and no longer has an affect now that the behavior it enabled is always
+enabled. (Myron Marston)
Add missing deprecation warning for when RSpec::Core::Runner
+is used multiple times in the same process. In 2.x RSpec's global
+state was automatically cleared between runs but in 3.0 you need to call
+RSpec.reset manually in these situations. (Sam Phippen,
+#1587)
+
+
Prevent deprecation being accidentally issues when doubles used with
+be_ matchers due to automatically generated descriptions.
+(Jon Rowe, #1573)
+
+
Load rspec/core when loading rspec/core/rake_task
+to ensure we can issue deprecations correctly. (Jon Rowe, #1612)
Fix BaseTextFormatter so that it does not re-close a closed
+output stream. (Myron Marston)
+
+
Use RSpec::Configuration#backtrace_exclusion_patterns rather
+than the deprecated
+RSpec::Configuration#backtrace_clean_patterns when mocking
+with rr. (David Dollar)
Add --deprecation-out CLI option which directs deprecation
+warnings to the named file. (Myron Marston)
+
+
Backport support for skip in metadata to skip execution of an
+example. (Xavier Shay, #1472)
+
+
Add Pathname support for setting all output streams. (Aaron
+Kromer)
+
+
Add test_unit and minitest expectation
+frameworks. (Aaron Kromer)
+
+
+
Deprecations:
+
+
Deprecate RSpec::Core::Pending::PendingDeclaredInExample, use
+SkipDeclaredInExample instead. (Xavier Shay)
+
+
Issue a deprecation when described_class is accessed from
+within a nested describe <SomeClass> example group,
+since described_class will return the innermost described
+class in RSpec 3 rather than the outermost described class, as it behaved
+in RSpec 2. (Myron Marston)
+
+
Deprecate RSpec::Core::FilterManager::DEFAULT_EXCLUSIONS,
+RSpec::Core::FilterManager::STANDALONE_FILTERS and use of
+#empty_without_conditional_filters? on those filters. (Sergey
+Pchelincev)
+
+
Deprecate RSpec::Core::Example#options in favor of
+RSpec::Core::Example#metadata. (Myron Marston)
+
+
Issue warning when passing a symbol or hash to describe or
+context as the first argument. In RSpec 2.x this would be
+treated as metadata but in RSpec 3 it'll be treated as the described
+object. To continue having it treated as metadata, pass a description
+before the symbol or hash. (Myron Marston)
+
+
Deprecate RSpec::Core::BaseTextFormatter::VT100_COLORS and
+RSpec::Core::BaseTextFormatter::VT100_COLOR_CODES in favour
+of RSpec::Core::BaseTextFormatter::ConsoleCodes::VT100_CODES
+and
+RSpec::Core::BaseTextFormatter::ConsoleCodes::VT100_CODE_VALUES.
+(Jon Rowe)
+
+
Deprecate RSpec::Core::ExampleGroup.display_name in favor of
+RSpec::Core::ExampleGroup.description. (Myron Marston)
+
+
Deprecate RSpec::Core::ExampleGroup.describes in favor of
+RSpec::Core::ExampleGroup.described_class. (Myron Marston)
+
+
Deprecate RSpec::Core::ExampleGroup.alias_example_to in favor
+of RSpec::Core::Configuration#alias_example_to. (Myron
+Marston)
+
+
Deprecate RSpec::Core::ExampleGroup.alias_it_behaves_like_to
+in favor of
+RSpec::Core::Configuration#alias_it_behaves_like_to. (Myron
+Marston)
+
+
Deprecate RSpec::Core::ExampleGroup.focused in favor of
+RSpec::Core::ExampleGroup.focus. (Myron Marston)
+
+
Add deprecation warning for config.filter_run :focused since
+example aliases fit and focus will no longer
+include :focused metadata but will continue to include
+:focus. (Myron Marston)
+
+
Deprecate filtering by :line_number (e.g.
+--line-number from the CLI). Use location filtering instead.
+(Myron Marston)
+
+
Deprecate --default_path as an alternative to
+--default-path. (Jon Rowe)
+
+
Deprecate RSpec::Core::Configuration#warnings in favor of
+RSpec::Core::Configuration#warnings?. (Myron Marston)
+
+
Deprecate share_examples_for in favor of
+shared_examples_for or just shared_examples.
+(Myron Marston)
+
+
Deprecate RSpec::Core::CommandLine in favor of
+RSpec::Core::Runner. (Myron Marston)
+
+
Deprecate #color_enabled, #color_enabled= and
+#color? in favour of #color,
+#color= and #color_enabled? output. (Jon Rowe)
+
+
Deprecate #filename_pattern in favour of
+#pattern. (Jon Rowe)
+
+
Deprecate #backtrace_cleaner in favour of
+#backtrace_formatter. (Jon Rowe)
Add is_expected for one-liners that read well with the
+expect-based syntax. is_expected is simply
+defined as expect(subject) and can be used in an expression
+like: it { is_expected.to read_well }. (Myron Marston)
+
+
Backport skip from RSpec 3, which acts like
+pending did in RSpec 2 when not given a block, since the
+behavior of pending is changing in RSpec 3. (Xavier Shay)
+
+
+
Deprecations:
+
+
Deprecate inexact mock_with config options. RSpec 3 will only
+support the exact symbols :rspec, :mocha,
+:flexmock, :rr or :nothing (or any
+module that implements the adapter interface). RSpec 2 did fuzzy matching
+but this will not be supported going forward. (Myron Marston)
+
+
Deprecate show_failures_in_pending_blocks config option. To
+achieve the same behavior as the option enabled, you can use a custom
+formatter instead. (Xavier Shay)
+
+
Add a deprecation warning for the fact that the behavior of
+pending is changing in RSpec 3 – rather than skipping the
+example (as it did in 2.x when no block was provided), it will run the
+example and mark it as failed if no exception is raised. Use
+skip instead to preserve the old behavior. (Xavier Shay)
+
+
Deprecate 's', 'n', 'spec' and 'nested' as
+aliases for documentation formatter. (Jon Rowe)
+
+
Deprecate RSpec::Core::Reporter#abort in favor of
+RSpec::Core::Reporter#finish. (Jon Rowe)
+
+
+
Bug Fixes:
+
+
Fix failure (undefined method path) in end-of-run summary
+when raise_errors_for_deprecations! is configured. (Myron
+Marston)
+
+
Fix issue were overridding spec ordering from the command line wasn't
+fully recognised interally. (Jon Rowe)
Block-based DSL methods that run in the context of an example
+(it, before(:each), after(:each),
+let and subject) now yield the example as a
+block argument. (David Chelimsky)
+
+
Warn when the name of more than one example group is submitted to
+include_examples and it's aliases. (David Chelimsky)
+
+
Add expose_current_running_example_as config option for use
+during the upgrade process when external gems use the deprecated
+RSpec::Core::ExampleGroup#example and
+RSpec::Core::ExampleGroup#running_example methods. (Myron
+Marston)
+
+
Limit spamminess of deprecation messages. (Bradley Schaefer, Loren Segal)
+
+
Add config.raise_errors_for_deprecations! option, which turns
+deprecations warnings into errors to surface the full backtrace of the
+call site. (Myron Marston)
+
+
+
Deprecations
+
+
Deprecate RSpec::Core::ExampleGroup#example and
+RSpec::Core::ExampleGroup#running_example methods. If you need
+access to the example (e.g. to get its metadata), use a block argument
+instead. (David Chelimsky)
+
+
Deprecate use of autotest/rspec2 in favour of
+rspec-autotest. (Jon Rowe)
+
+
Deprecate RSpec's built-in debugger support. Use a CLI option like
+-rruby-debug (for the ruby-debug gem) or
+-rdebugger (for the debugger gem) instead. (Myron Marston)
+
+
Deprecate
+RSpec.configuration.treat_symbols_as_metadata_keys_with_true_values =
+false. RSpec 3 will not support having this option set to
+false. (Myron Marston)
+
+
Deprecate accessing a let or subject declaration
+in a after(:all) hook. (Myron Marston, Jon Rowe)
+
+
Deprecate built-in its usage in favor of
+rspec-its gem due to planned removal in RSpec 3. (Peter
+Alfvin)
+
+
Deprecate RSpec::Core::PendingExampleFixedError in favor of
+RSpec::Core::Pending::PendingExampleFixedError. (Myron
+Marston)
+
+
Deprecate RSpec::Core::Configuration#out and
+RSpec::Core::Configuration#output in favor of
+RSpec::Core::Configuration#output_stream. (Myron Marston)
+
+
Deprecate legacy ordering APIs.
+
+
You should use register_ordering(:global) instead of these:
These are deprecated with no replacement because in RSpec 3 ordering is a
+property of individual example groups rather than just a global property of
+the entire test suite:
+
+
RSpec::Core::Configuration#order
+
+
RSpec::Core::Configuration#randomize?
+
+
+
--order default is deprecated in favor of --order
+defined (Myron Marston)
Fix regression in 2.14.6 that broke the Fivemat formatter. It depended
+upon either
+example.execution_result[:exception].pending_fixed? (which
+was removed in 2.14.6 to fix an issue with frozen error objects) or
+RSpec::Core::PendingExampleFixedError (which was renamed to
+RSpec::Core::Pending::PendingExampleFixedError in 2.8. This
+fix makes a constant alias for the old error name. (Myron Marston)
Fix a NoMethodError that was being raised when there were no
+shared examples or contexts declared and RSpec.world.reset is
+invoked. (thepoho, Jon Rowe, Myron Marston)
+
+
Fix a deprecation warning that was being incorrectly displayed when
+shared_examples are declared at top level in a
+module scope. (Jon Rowe)
+
+
Fix after(:all) hooks so consecutive (same context) scopes will run even if
+one raises an error. (Jon Rowe, Trejkaz)
+
+
JsonFormatter no longer dies if dump_profile isn't defined
+(Alex / @MasterLambaster, Jon Rowe)
Fix regression in 2.14: ensure configured requires (via -r
+option) are loaded before spec files are loaded. This allows the spec
+files to programatically change the file pattern (Jon Rowe).
+
+
Autoload RSpec::Mocks and RSpec::Expectations
+when referenced if they are not already loaded
+(RSpec::Matches has been autoloaded for a while). In the
+rspec gem, we changed it recently to stop loading
+rspec/mocks and rspec/expectations by default, as
+some users reported problems where they were intending to use mocha, not
+rspec-mocks, but rspec-mocks was loaded and causing a conflict. rspec-core
+loads mocks and expectations at the appropriate time, so it seemed like a
+safe change – but caused a problem for some authors of libraries that
+integrate with RSpec. This fixes that problem. (Myron Marston)
+
+
Gracefully handle a command like rspec --profile
+path/to/spec.rb: the path/to/spec.rb arg was being
+wrongly treated as the profile integer arg, which got cast
+0 using to_i, causing no profiled examples to be
+printed. (Jon Rowe)
Fix deprecation notices issued from RSpec::Core::RakeTask so
+that they work properly when all of rspec-core is not loaded. (This was a
+regression in 2.14) (Jon Rowe)
Fix regression caused by 2.14.1 release: formatters that report that they
+respond_to? a notification, but had no corresponding method
+would raise an error when registered. The new fix is to just implement
+start on the deprecation formatter to fix the original
+JRuby/ruby-debug issue. (Jon Rowe)
Address deprecation formatter failure when using ruby-debug on
+JRuby: fix RSpec::Core::Reporter to not send a notification
+when the formatter's implementation of the notification method comes
+from Kernel (Alex Portnov, Jon Rowe).
Apply focus to examples defined with fit (equivalent of
+it "description", focus: true) (Michael de Silva)
+
+
+
Bug fix
+
+
Ensure methods defined by let take precedence over others
+when there is a name collision (e.g. from an included module). (Jon Rowe,
+Andy Lindeman and Myron Marston)
Improved Windows detection inside Git Bash, for better --color
+handling.
+
+
Add profiling of the slowest example groups to --profile
+option. The output is sorted by the slowest average example groups.
+
+
Don't show slow examples if there's a failure and both
+--fail-fast and --profile options are used
+(Paweł Gościcki).
+
+
Rather than always adding spec to the load path, add the
+configured --default-path to the load path (which defaults to
+spec). This better supports folks who choose to put their
+specs in a different directory (John Feminella).
+
+
Add some logic to test time duration precision. Make it a function of
+time, dropping precision as the time increases. (Aaron Kromer)
+
+
Add new backtrace_inclusion_patterns config option. Backtrace
+lines that match one of these patterns will always be included in
+the backtrace, even if they match an exclusion pattern, too (Sam Phippen).
+
+
Support ERB trim mode using the - when parsing
+.rspec as ERB (Gabor Garami).
+
+
Give a better error message when let and subject are called without a
+block. (Sam Phippen).
+
+
List the precedence of .rspec-local in the configuration
+documentation (Sam Phippen)
+
+
Support {a,b} shell expansion syntax in --pattern
+option (Konstantin Haase).
+
+
Add cucumber documentation for –require command line option (Bradley
+Schaefer)
+
+
Expose configuration options via config:
+
+
config.libs returns the libs configured to be added onto the
+load path
+
+
full_backtrace? returns the state of the backtrace cleaner
+
+
debug? returns true when the debugger is loaded
+
+
line_numbers returns the line numbers we are filtering by (if
+any)
+
+
full_description returns the RegExp used to filter
+descriptions (Jon Rowe)
+
+
Add setters for RSpec.world and RSpec.configuration (Alex Soulim)
+
+
Configure ruby's warning behaviour with --warnings (Jon
+Rowe)
+
+
Fix an obscure issue on old versions of 1.8.7 where
+Time.dup wouldn't allow access to Time.now
+(Jon Rowe)
+
+
Make shared_examples_for context aware, so that keys may be
+safely reused in multiple contexts without colliding. (Jon Rowe)
+
+
Add a configurable deprecation_stream (Jon Rowe)
+
+
Publish deprecations through a formatter (David Chelimsky)
+
+
+
Bug fixes
+
+
Make JSON formatter behave the same when it comes to --profile
+as the text formatter (Paweł Gościcki).
+
+
Fix named subjects so that if an inner group defines a method that
+overrides the named method, subject still retains the
+originally declared value (Myron Marston).
+
+
Fix random ordering so that it does not cause rand in examples
+in nested sibling contexts to return the same value (Max Shytikov).
+
+
Use the new backtrace_inclusion_patterns config option to
+ensure that folks who develop code in a directory matching one of the
+default exclusion patterns (e.g. gems) still get the normal
+backtrace filtering (Sam Phippen).
+
+
Fix ordering of before hooks so that before hooks
+declared in RSpec.configure run before before
+hooks declared in a shared context (Michi Huber and Tejas Dinkar).
+
+
Fix Example#full_description so that it gets filled in by the
+last matcher description (as Example#description already did)
+when no doc string has been provided (David Chelimsky).
+
+
Fix the memoized methods (let and subject)
+leaking define_method as a public method.
+(Thomas Holmes and Jon Rowe) (#873)
+
+
Fix warnings coming from the test suite. (Pete Higgins)
+
+
+
Deprecations
+
+
Deprecate Configuration#backtrace_clean_patterns in favor of
+Configuration#backtrace_exclusion_patterns for greater
+consistency and symmetry with new
+backtrace_inclusion_patterns config option (Sam Phippen).
+
+
Deprecate Configuration#requires= in favor of using ruby's
+require. Requires specified by the command line can still be
+accessed by the Configuration#require reader. (Bradley
+Schaefer)
+
+
Deprecate calling SharedExampleGroups defined across sibling
+contexts (Jon Rowe)
Use hook classes as proxies rather than extending hook blocks to support
+lambdas for before/after/around hooks. (David Chelimsky)
+
+
Fix regression in 2.13.0 that caused confusing behavior when overriding a
+named subject with an unnamed subject in an inner group and then
+referencing the outer group subject's name. The fix for this required
+us to disallow using super in a named subject (which is
+confusing, anyway – named subjects create 2 methods, so which method on
+the parent example group are you supering to?) but
+super in an unnamed subject continues to work (Myron
+Marston).
+
+
Do not allow a referenced let or subject in
+before(:all) to cause other let declarations to
+leak across examples (Myron Marston).
+
+
Work around odd ruby 1.9 bug with String#match that was
+triggered by passing it a regex from a let declaration. For
+more info, see bugs.ruby-lang.org/issues/8059
+(Aaron Kromer).
+
+
Add missing require 'set' to
+base_text_formatter.rb (Tom Anderson).
+
+
+
Deprecations
+
+
Deprecate accessing let or subject declarations
+in before(:all). These were not intended to be called in a
+before(:all) hook, as they exist to define state that is
+reset between each example, while before(:all) exists to
+define state that is shared across examples in an example group (Myron
+Marston).
Allow --profile option to take a count argument that
+determines the number of slow examples to dump (Greggory Rothmeier).
+
+
Add subject! that is the analog to let!. It
+defines an explicit subject and sets a before hook that will
+invoke the subject (Zubin Henner).
+
+
Fix let and subject declaration so that
+super and return can be used in them, just like
+in a normal method. (Myron Marston)
+
+
Allow output colors to be configured individually. (Charlie Maffitt)
+
+
Always dump slow examples when --profile option is given,
+even when an example failed (Myron Marston).
+
+
+
Bug fixes
+
+
Don't blow up when dumping error output for instances of anonymous
+error classes (Myron Marston).
+
+
Fix default backtrace filters so lines from projects containing “gems” in
+the name are not filtered, but lines from installed gems still are (Myron
+Marston).
+
+
Fix autotest command so that is uses double quotes rather than single
+quotes for windows compatibility (Jonas Tingeborn).
+
+
Fix its so that uses of subject in a
+before or let declaration in the parent group
+continue to reference the parent group's subject. (Olek Janiszewski)
Specs are run even if another at_exit hook calls exit. This
+allows Test::Unit and RSpec to run together. (Suraj N. Kurapati)
+
+
Fix full doc string concatenation so that it handles the case of a method
+string (e.g. “#foo”) being nested under a context string (e.g. “when it is
+tuesday”), so that we get “when it is tuesday #foo” rather than “when it
+is tuesday#foo”. (Myron Marston)
+
+
Restore public API I unintentionally broke in 2.12.0:
+RSpec::Core::Formatters::BaseFormatter#format_backtrce(backtrace,
+example) (Myron Marston).
Add support for custom ordering strategies for groups and examples. (Myron
+Marston)
+
+
JSON Formatter (Alex Chaffee)
+
+
Refactor rake task internals (Sam Phippen)
+
+
Refactor HtmlFormatter (Pete Hodgson)
+
+
Autotest supports a path to Ruby that contains spaces (dsisnero)
+
+
Provide a helpful warning when a shared example group is redefined. (Mark
+Burns).
+
+
--default_path can be specified as
+--default-line. --line_number can be specified
+as --line-number. Hyphens are more idiomatic command line
+argument separators (Sam Phippen).
+
+
A more useful error message is shown when an invalid command line option is
+used (Jordi Polo).
+
+
Add format_docstrings { |str| } config option. It can be used
+to apply formatting rules to example group and example docstrings. (Alex
+Tan)
+
+
Add support for an .rspec-local options file. This is intended
+to allow individual developers to set options in a git-ignored file that
+override the common project options in .rspec. (Sam Phippen)
+
+
Support for mocha 0.13.0. (Andy Lindeman)
+
+
+
Bug fixes
+
+
Remove override of ExampleGroup#ancestors. This is a core ruby
+method that RSpec shouldn't override. Instead, define
+ExampleGroup#parent_groups. (Myron Marston)
+
+
Limit monkey patching of shared example/context declaration methods
+(shared_examples_for, etc.) to just the objects that need it
+rather than every object in the system (Myron Marston).
+
+
Fix Metadata#fetch to support computed values (Sam Goldman).
+
+
Named subject can now be referred to from within subject block in a nested
+group (tomykaira).
+
+
Fix fail_fast so that it properly exits when an error occurs
+in a before(:all) hook (Bradley Schaefer).
+
+
Make the order spec files are loaded consistent, regardless of the order
+of the files returned by the OS or the order passed at the command line
+(Jo Liss and Sam Phippen).
+
+
Ensure instance variables from before(:all) are always exposed
+from after(:all), even if an error occurs in
+before(:all) (Sam Phippen).
+
+
rspec --init no longer generates an incorrect warning about
+--configure being deprecated (Sam Phippen).
+
+
Fix pluralization of 1 seconds (Odin Dutton)
+
+
Fix ANSICON url (Jarmo Pertman)
+
+
Use dup of Time so reporting isn't clobbered by examples that modify
+Time without properly restoring it. (David Chelimsky)
+
+
+
Deprecations
+
+
share_as is no longer needed. shared_context
+and/or RSpec::SharedContext provide better mechanisms (Sam
+Phippen).
+
+
Deprecate RSpec.configuration with a block (use
+RSpec.configure).
Fix the way we autoload RSpec::Matchers so that custom matchers can be
+defined before rspec-core has been configured to definitely use
+rspec-expectations. (Myron Marston)
+
+
Fix typo in –help message printed for -e option. (Jo Liss)
+
+
Fix ruby warnings. (Myron Marston)
+
+
Ignore mock expectation failures when the example has already failed. Mock
+expectation failures have always been ignored in this situation, but due
+to my changes in 27059bf1 it was printing a confusing message. (Myron
+Marston).
thanks to Bradley Schaefer for suggesting it and Avdi Grimm for almost
+suggesting it.
+
+
+
config.mock_with and config.expect_with yield
+custom config object to a block if given
+
+
aids decoupling from rspec-core's configuation
+
+
+
include_context and include_examples support a
+block, which gets eval'd in the current context (vs the nested context
+generated by it_behaves_like).
+
+
Add config.order = 'random' to the
+spec_helper.rb generated by rspec --init.
+
+
Delay the loading of DRb (Myron Marston).
+
+
Limit monkey patching of describe onto just the objects that
+need it rather than every object in the system (Myron Marston).
+
+
+
Bug fixes
+
+
Support alternative path separators. For example, on Windows, you can now
+do this: rspec spec\subdir. (Jarmo Pertman @jarmo)
+
+
When an example raises an error and an after or around hook does as well,
+print out the hook error. Previously, the error was silenced and the user
+got no feedback about what happened. (Myron Marston)
+
+
--require and -I are merged among different
+configuration sources (Andy Lindeman)
+
+
Delegate to mocha methods instead of aliasing them in mocha adapter.
NOTE: RSpec's release policy dictates that there should not be any
+backward incompatible changes in minor releases, but we're making an
+exception to release a change to how RSpec interacts with other command
+line tools.
+
+
As of 2.7.0, you must explicity require
+"rspec/autorun" unless you use the rspec
+command (which already does this for you).
+
+
Enhancements
+
+
Add example.exception (David Chelimsky)
+
+
--default_path command line option (Justin Ko)
+
+
support multiple --line_number options (David J. Hamilton)
+
+
also supports path/to/file.rb:5:9 (runs examples on lines 5
+and 9)
+
+
+
Allow classes/modules to be used as shared example group identifiers
+(Arthur Gunn)
+
+
Friendly error message when shared context cannot be found (Sławosz
+Sławiński)
+
+
Clear formatters when resetting config (John Bintz)
+
+
Add xspecify and xexample as temp-pending methods (David
+Chelimsky)
+
+
Add --no-drb option (Iain Hecker)
+
+
Provide more accurate run time by registering start time before code is
+loaded (David Chelimsky)
NOTE: RSpec's release policy dictates that there should not be new
+functionality in patch releases, but this minor enhancement slipped in by
+accident. As it doesn't add a new API, we decided to leave it in rather
+than roll back this release.
+
+
Enhancements
+
+
Add summary of commands to run individual failed examples.
+
+
+
Bug fixes
+
+
Support exclusion filters in DRb. (Yann Lugrin)
+
+
Fix –example escaping when run over DRb. (Elliot Winkler)
+
+
Use standard ANSI codes for color formatting so colors work in a wider set
+of color schemes.
Print a deprecation warning when you configure RSpec after defining an
+example. All configuration should happen before any examples are defined.
+(Myron Marston)
+
+
Pass the exit status of a DRb run to the invoking process. This causes
+specs run via DRb to not just return true or false. (Ilkka Laukkanen)
+
+
Refactoring of ConfigurationOptions#parse_options (Rodrigo
+Rosenfeld Rosas)
+
+
Report excluded filters in runner output (tip from andyl)
+
+
Clean up messages for filters/tags.
+
+
Restore –pattern/-P command line option from rspec-1
+
+
Support false as well as true in config.full_backtrace= (Andreas Tolf
+Tolfsen)
+
+
+
Bug fixes
+
+
Don't stumble over an exception without a message (Hans Hasselberg)
+
+
Remove non-ascii characters from comments that were choking rcov (Geoffrey
+Byers)
+
+
Fixed backtrace so it doesn't include lines from before the autorun
+at_exit hook (Myron Marston)
+
+
Include RSpec::Matchers when first example group is defined, rather than
+just before running the examples. This works around an obscure bug in ruby
+1.9 that can cause infinite recursion. (Myron Marston)
+
+
Don't send example_group_[started|finished] to formatters
+for empty groups.
+
+
Get specs passing on jruby (Sidu Ponnappa)
+
+
Fix bug where mixing nested groups and outer-level examples gave
+unpredictable :line_number behavior (Artur Małecki)
+
+
Regexp.escape the argument to –example (tip from Elliot Winkler)
+
+
Correctly pass/fail pending block with message expectations
+
+
CommandLine returns exit status (0/1) instead of true/false
+
+
Create path to formatter output file if it doesn't exist (marekj).
NOTE: this release breaks compatibility with rspec/autotest/bundler
+integration, but does so in order to greatly simplify it.
+
+
With this release, if you want the generated autotest command to include
+'bundle exec', require Autotest's bundler plugin in a .autotest
+file in the project's root directory or in your home directory:
+
+
require"autotest/bundler"
+
+
+
Now you can just type 'autotest' on the commmand line and it will
+work as you expect.
+
+
If you don't want 'bundle exec', there is nothing you have to
+do.
Copyright (c) 2012 Chad Humphries, David Chelimsky, Myron Marston Copyright (c) 2009 Chad Humphries, David Chelimsky Copyright (c) 2006 David Chelimsky, The RSpec Development Team Copyright (c) 2005 Steven Baker
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-core/file.README.html b/source/documentation/3.1/rspec-core/file.README.html
new file mode 100644
index 000000000..1357e5eca
--- /dev/null
+++ b/source/documentation/3.1/rspec-core/file.README.html
@@ -0,0 +1,315 @@
+
+
+
+
+
+ File: README
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
rspec-core provides the structure for writing executable examples of how
+your code should behave, and an rspec command with tools to
+constrain which examples get run and tailor the output.
+
+
install
+
+
geminstallrspec# for rspec-core, rspec-expectations, rspec-mocks
+geminstallrspec-core# for rspec-core only
+rspec--help
+
+
basic structure
+
+
RSpec uses the words “describe” and “it” so we can express concepts like a
+conversation:
+
+
"Describe an order."
+"It sums the prices of its line items."
+
+
RSpec.describeOrderdo
+ it"sums the prices of its line items"do
+ order=Order.new
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(1.11,:USD)
+ )))
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(2.22,:USD),
+ :quantity=>2
+ )))
+ expect(order.total).toeq(Money.new(5.55,:USD))
+ end
+end
+
+
+
The describe method creates an ExampleGroup.
+Within the block passed to describe you can declare examples
+using the it method.
+
+
Under the hood, an example group is a class in which the block passed to
+describe is evaluated. The blocks passed to it
+are evaluated in the context of an instance of that class.
+
+
nested groups
+
+
You can also declare nested nested groups using the describe
+or context methods:
+
+
RSpec.describeOrderdo
+ context"with no items"do
+ it"behaves one way"do
+ # ...
+end
+ end
+
+ context"with one item"do
+ it"behaves another way"do
+ # ...
+end
+ end
+end
+
+
+
aliases
+
+
You can declare example groups using either describe or
+context. For a top level example group, describe
+and context are available off of RSpec. For
+backwards compatibility, they are also available off of the
+main object and Module unless you disable monkey
+patching.
+
+
You can declare examples within a group using any of it,
+specify, or example.
+
+
shared examples and contexts
+
+
Declare a shared example group using shared_examples, and then
+include it in any group using include_examples.
+
+
RSpec.shared_examples"collections"do|collection_class|
+ it"is empty when first created"do
+ expect(collection_class.new).tobe_empty
+ end
+end
+
+RSpec.describeArraydo
+ include_examples"collections",Array
+end
+
+RSpec.describeHashdo
+ include_examples"collections",Hash
+end
+
+
+
Nearly anything that can be declared within an example group can be
+declared within a shared example group. This includes before,
+after, and around hooks, let
+declarations, and nested groups/contexts.
+
+
You can also use the names shared_context and
+include_context. These are pretty much the same as
+shared_examples and include_examples, providing
+more accurate naming when you share hooks, let declarations,
+helper methods, etc, but no examples.
+
+
metadata
+
+
rspec-core stores a metadata hash with every example and group, which
+contains their descriptions, the locations at which they were declared,
+etc, etc. This hash powers many of rspec-core's features, including
+output formatters (which access descriptions and locations), and filtering
+before and after hooks.
+
+
Although you probably won't ever need this unless you are writing an
+extension, you can access it from an example like this:
When a class is passed to describe, you can access it from an
+example using the described_class method, which is a wrapper
+for example.metadata[:described_class].
+
+
RSpec.describeWidgetdo
+ exampledo
+ expect(described_class).toequal(Widget)
+ end
+end
+
+
+
This is useful in extensions or shared example groups in which the specific
+class is unknown. Taking the collections shared example group from above,
+we can clean it up a bit using described_class:
+
+
RSpec.shared_examples"collections"do
+ it"is empty when first created"do
+ expect(described_class.new).tobe_empty
+ end
+end
+
+RSpec.describeArraydo
+ include_examples"collections"
+end
+
+RSpec.describeHashdo
+ include_examples"collections"
+end
+
+
+
the rspec command
+
+
When you install the rspec-core gem, it installs the rspec
+executable, which you'll use to run rspec. The rspec
+command comes with many useful options. Run rspec --help to
+see the complete list.
+
+
store command line options .rspec
+
+
You can store command line options in a .rspec file in the
+project's root directory, and the rspec command will read
+them as though you typed them on the command line.
+
+
autotest integration
+
+
rspec-core no longer ships with an Autotest extension, if you require
+Autotest integration, please use the rspec-autotest gem and
+see rspec/rspec-autotest for
+details
+
+
get started
+
+
Start with a simple example of behavior you expect from your system. Do
+this before you write any implementation code:
+
+
# in spec/calculator_spec.rb
+RSpec.describeCalculatordo
+ describe'#add'do
+ it'returns the sum of its arguments'do
+ expect(Calculator.new.add(1,2)).toeq(3)
+ end
+ end
+end
+
+
+
Run this with the rspec command, and watch it fail:
# in lib/calculator.rb
+classCalculator
+ defadd(a,b)
+ a+b
+ end
+end
+
+
+
Be sure to require the implementation file in the spec:
+
+
# in spec/calculator_spec.rb
+# - RSpec adds ./lib to the $LOAD_PATH
+require"calculator"
+
+
+
Now run the spec again, and watch it pass:
+
+
$ rspec spec/calculator_spec.rb
+.
+
+Finished in 0.000315 seconds
+1 example, 0 failures
+
+
Use the documentation formatter to see the resulting spec:
+
+
$ rspec spec/calculator_spec.rb --format doc
+Calculator
+ #add
+ returns the sum of its arguments
+
+Finished in 0.000379 seconds
+1 example, 0 failures
rspec-core provides the structure for writing executable examples of how
+your code should behave, and an rspec command with tools to
+constrain which examples get run and tailor the output.
+
+
install
+
+
geminstallrspec# for rspec-core, rspec-expectations, rspec-mocks
+geminstallrspec-core# for rspec-core only
+rspec--help
+
+
basic structure
+
+
RSpec uses the words “describe” and “it” so we can express concepts like a
+conversation:
+
+
"Describe an order."
+"It sums the prices of its line items."
+
+
RSpec.describeOrderdo
+ it"sums the prices of its line items"do
+ order=Order.new
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(1.11,:USD)
+ )))
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(2.22,:USD),
+ :quantity=>2
+ )))
+ expect(order.total).toeq(Money.new(5.55,:USD))
+ end
+end
+
+
+
The describe method creates an ExampleGroup.
+Within the block passed to describe you can declare examples
+using the it method.
+
+
Under the hood, an example group is a class in which the block passed to
+describe is evaluated. The blocks passed to it
+are evaluated in the context of an instance of that class.
+
+
nested groups
+
+
You can also declare nested nested groups using the describe
+or context methods:
+
+
RSpec.describeOrderdo
+ context"with no items"do
+ it"behaves one way"do
+ # ...
+end
+ end
+
+ context"with one item"do
+ it"behaves another way"do
+ # ...
+end
+ end
+end
+
+
+
aliases
+
+
You can declare example groups using either describe or
+context. For a top level example group, describe
+and context are available off of RSpec. For
+backwards compatibility, they are also available off of the
+main object and Module unless you disable monkey
+patching.
+
+
You can declare examples within a group using any of it,
+specify, or example.
+
+
shared examples and contexts
+
+
Declare a shared example group using shared_examples, and then
+include it in any group using include_examples.
+
+
RSpec.shared_examples"collections"do|collection_class|
+ it"is empty when first created"do
+ expect(collection_class.new).tobe_empty
+ end
+end
+
+RSpec.describeArraydo
+ include_examples"collections",Array
+end
+
+RSpec.describeHashdo
+ include_examples"collections",Hash
+end
+
+
+
Nearly anything that can be declared within an example group can be
+declared within a shared example group. This includes before,
+after, and around hooks, let
+declarations, and nested groups/contexts.
+
+
You can also use the names shared_context and
+include_context. These are pretty much the same as
+shared_examples and include_examples, providing
+more accurate naming when you share hooks, let declarations,
+helper methods, etc, but no examples.
+
+
metadata
+
+
rspec-core stores a metadata hash with every example and group, which
+contains their descriptions, the locations at which they were declared,
+etc, etc. This hash powers many of rspec-core's features, including
+output formatters (which access descriptions and locations), and filtering
+before and after hooks.
+
+
Although you probably won't ever need this unless you are writing an
+extension, you can access it from an example like this:
When a class is passed to describe, you can access it from an
+example using the described_class method, which is a wrapper
+for example.metadata[:described_class].
+
+
RSpec.describeWidgetdo
+ exampledo
+ expect(described_class).toequal(Widget)
+ end
+end
+
+
+
This is useful in extensions or shared example groups in which the specific
+class is unknown. Taking the collections shared example group from above,
+we can clean it up a bit using described_class:
+
+
RSpec.shared_examples"collections"do
+ it"is empty when first created"do
+ expect(described_class.new).tobe_empty
+ end
+end
+
+RSpec.describeArraydo
+ include_examples"collections"
+end
+
+RSpec.describeHashdo
+ include_examples"collections"
+end
+
+
+
the rspec command
+
+
When you install the rspec-core gem, it installs the rspec
+executable, which you'll use to run rspec. The rspec
+command comes with many useful options. Run rspec --help to
+see the complete list.
+
+
store command line options .rspec
+
+
You can store command line options in a .rspec file in the
+project's root directory, and the rspec command will read
+them as though you typed them on the command line.
+
+
autotest integration
+
+
rspec-core no longer ships with an Autotest extension, if you require
+Autotest integration, please use the rspec-autotest gem and
+see rspec/rspec-autotest for
+details
+
+
get started
+
+
Start with a simple example of behavior you expect from your system. Do
+this before you write any implementation code:
+
+
# in spec/calculator_spec.rb
+RSpec.describeCalculatordo
+ describe'#add'do
+ it'returns the sum of its arguments'do
+ expect(Calculator.new.add(1,2)).toeq(3)
+ end
+ end
+end
+
+
+
Run this with the rspec command, and watch it fail:
# in lib/calculator.rb
+classCalculator
+ defadd(a,b)
+ a+b
+ end
+end
+
+
+
Be sure to require the implementation file in the spec:
+
+
# in spec/calculator_spec.rb
+# - RSpec adds ./lib to the $LOAD_PATH
+require"calculator"
+
+
+
Now run the spec again, and watch it pass:
+
+
$ rspec spec/calculator_spec.rb
+.
+
+Finished in 0.000315 seconds
+1 example, 0 failures
+
+
Use the documentation formatter to see the resulting spec:
+
+
$ rspec spec/calculator_spec.rb --format doc
+Calculator
+ #add
+ returns the sum of its arguments
+
+Finished in 0.000379 seconds
+1 example, 0 failures
The legacy :should syntax adds the following methods directly to
+BasicObject so that they are available off of any object. Note, however,
+that this syntax does not always play nice with delegate/proxy objects.
+We recommend you use the non-monkeypatching :expect syntax instead.
RSpec::Expectations provides a simple, readable API to express
+the expected outcomes in a code example. To express an expected
+outcome, wrap an object or block in expect, call to or to_not
+(aliased as not_to) and pass it a matcher object:
The last form (the block form) is needed to match against ruby constructs
+that are not objects, but can only be observed when executing a block
+of code. This includes raising errors, throwing symbols, yielding,
+and changing values.
+
+
When expect(...).to is invoked with a matcher, it turns around
+and calls matcher.matches?(<object wrapped by expect>). For example,
+in the expression:
+
+
expect(order.total).toeq(Money.new(5.55,:USD))
+
+
+
...eq(Money.new(5.55, :USD)) returns a matcher object, and it results
+in the equivalent of eq.matches?(order.total). If matches? returns
+true, the expectation is met and execution continues. If false, then
+the spec fails with the message returned by eq.failure_message.
+
+
Given the expression:
+
+
expect(order.entries).not_toinclude(entry)
+
+
+
...the not_to method (also available as to_not) invokes the equivalent of
+include.matches?(order.entries), but it interprets false as success, and
+true as a failure, using the message generated by
+include.failure_message_when_negated.
+
+
rspec-expectations ships with a standard set of useful matchers, and writing
+your own matchers is quite simple.
+
+
See RSpec::Matchers for more information about the
+built-in matchers that ship with rspec-expectations, and how to write your
+own custom matchers.
# File 'lib/rspec/expectations/fail_with.rb', line 21
+
+deffail_with(message,expected=nil,actual=nil)
+ unlessmessage
+ raiseArgumentError,"Failure message is nil. Does your matcher define the " \
+ "appropriate failure_message[_when_negated] method to return a string?"
+ end
+
+ diff=differ.diff(actual,expected)
+ message="#{message}\nDiff:#{diff}"unlessdiff.empty?
+
+ raiseRSpec::Expectations::ExpectationNotMetError,message
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Expectations/Configuration.html b/source/documentation/3.1/rspec-expectations/RSpec/Expectations/Configuration.html
new file mode 100644
index 000000000..a0dc0da9b
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Expectations/Configuration.html
@@ -0,0 +1,896 @@
+
+
+
+
+
+ Class: RSpec::Expectations::Configuration
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Provides configuration options for rspec-expectations.
+If you are using rspec-core, you can access this via a
+block passed to RSpec::Core::Configuration#expect_with.
+Otherwise, you can access it via RSpec::Expectations.configuration.
+
+
+
+
+
+
+
+
Examples:
+
+
+
RSpec.configuredo|rspec|
+ rspec.expect_with:rspecdo|c|
+ # c is the config object
+end
+end
+
+# or
+
+RSpec::Expectations.configuration
+
+
+
+
+
+
Constant Summary
+
+
+
+
NullBacktraceFormatter =
+
+
+
+ This constant is part of a private API.
+ You should avoid using this constant if possible, as it may be removed or be changed in the future.
+
+
Null implementation of a backtrace formatter used by default
+when rspec-core is not loaded. Does no filtering.
+
+
+
+
+
+
+
+
+
+
Module.newdo
+ defself.format_backtrace(backtrace)
+ backtrace
+ end
+end
Sets or gets the backtrace formatter. The backtrace formatter should
+implement #format_backtrace(Array<String>). This is used
+to format backtraces of errors handled by the raise_error
+matcher.
+
+
If you are using rspec-core, rspec-core's backtrace formatting
+will be used (including respecting the presence or absence of
+the --backtrace option).
+
+
+
+
+
+
+
+
+
+
+
+
+
+101
+
+
+
# File 'lib/rspec/expectations/configuration.rb', line 101
+
+attr_writer:backtrace_formatter
Adds should and should_not to the given classes
+or modules. This can be used to ensure should works
+properly on things like proxy objects (particular
+Delegator-subclassed objects on 1.8).
+
+
+
+
+
+
Parameters:
+
+
+
+
+ modules
+
+
+ (Array<Module>)
+
+
+
+ —
+
the list of classes or modules
+to add should and should_not to.
+
+
+
+
+
+
+
+
+
+
+
+
+
+85
+86
+87
+88
+89
+
+
+
# File 'lib/rspec/expectations/configuration.rb', line 85
+
+defadd_should_and_should_not_to(*modules)
+ modules.eachdo|mod|
+ Expectations::Syntax.enable_should(mod)
+ end
+end
+
+
+
+
+
+
+
+
+ - (Boolean) color?
+
+
+
+
+
+
+
+
Indicates whether or not diffs should be colored.
+Delegates to rspec-core's color option if rspec-core
+is loaded; otherwise you can set it here.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+73
+74
+75
+
+
+
# File 'lib/rspec/expectations/configuration.rb', line 73
+
+defcolor?
+ ::RSpec.configuration.color_enabled?
+end
Indicates whether or not custom matcher descriptions and failure messages
+should include clauses from methods defined using chain. It is
+false by default for backwards compatibility.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+118
+119
+120
+
+
+
# File 'lib/rspec/expectations/configuration.rb', line 118
+
+definclude_chain_clauses_in_custom_matcher_descriptions?
+ @include_chain_clauses_in_custom_matcher_descriptions||=false
+end
RSpec::Matchers provides a number of useful matchers we use to define
+expectations. Any object that implements the matcher protocol
+can be used as a matcher.
+
+
Predicates
+
+
In addition to matchers that are defined explicitly, RSpec will create
+custom matchers on the fly for any arbitrary predicate, giving your specs a
+much more natural language feel.
+
+
A Ruby predicate is a method that ends with a "?" and returns true or false.
+Common examples are empty?, nil?, and instance_of?.
+
+
All you need to do is write expect(..).to be_ followed by the predicate
+without the question mark, and RSpec will figure it out from there.
+For example:
RSpec will also create custom matchers for predicates like has_key?. To
+use this feature, just state that the object should have_key(:key) and RSpec will
+call has_key?(:key) on the target. For example:
You can use this feature to invoke any predicate that begins with "has_", whether it is
+part of the Ruby libraries (like Hash#has_key?) or a method you wrote on your own class.
+
+
Note that RSpec does not provide composable aliases for these dynamic predicate
+matchers. You can easily define your own aliases, though:
When you find that none of the stock matchers provide a natural feeling
+expectation, you can very easily write your own using RSpec's matcher DSL
+or writing one from scratch.
+
+
Matcher DSL
+
+
Imagine that you are writing a game in which players can be in various
+zones on a virtual board. To specify that bob should be in zone 4, you
+could say:
+
+
expect(bob.current_zone).toeql(Zone.new("4"))
+
+
+
But you might find it more expressive to say:
+
+
expect(bob).tobe_in_zone("4")
+
+
+
and/or
+
+
expect(bob).not_tobe_in_zone("3")
+
+
+
You can create such a matcher like so:
+
+
RSpec::Matchers.define:be_in_zonedo|zone|
+ matchdo|player|
+ player.in_zone?(zone)
+ end
+end
+
+
+
This will generate a be_in_zone method that returns a matcher
+with logical default messages for failures. You can override the failure
+messages and the generated description as follows:
+
+
RSpec::Matchers.define:be_in_zonedo|zone|
+ matchdo|player|
+ player.in_zone?(zone)
+ end
+
+ failure_messagedo|player|
+ # generate and return the appropriate string.
+end
+
+ failure_message_when_negateddo|player|
+ # generate and return the appropriate string.
+end
+
+ descriptiondo
+ # generate and return the appropriate string.
+end
+end
+
+
+
Each of the message-generation methods has access to the block arguments
+passed to the create method (in this case, zone). The
+failure message methods (failure_message and
+failure_message_when_negated) are passed the actual value (the
+receiver of expect(..) or expect(..).not_to).
+
+
Custom Matcher from scratch
+
+
You could also write a custom matcher from scratch, as follows:
+
+
classBeInZone
+ definitialize(expected)
+ @expected=expected
+ end
+
+ defmatches?(target)
+ @target=target
+ @target.current_zone.eql?(Zone.new(@expected))
+ end
+
+ deffailure_message
+ "expected #{@target.inspect} to be in Zone #{@expected}"
+ end
+
+ deffailure_message_when_negated
+ "expected #{@target.inspect} not to be in Zone #{@expected}"
+ end
+end
+
And then expose the method to your specs. This is normally done
+by including the method and the class in a module, which is then
+included in your spec:
Custom matchers can easily participate in composed matcher expressions like these.
+Include Composable in your custom matcher to make it support
+being composed (matchers defined using the DSL have this included automatically).
+Within your matcher's matches? method (or the match block, if using the DSL),
+use values_match?(expected, actual) rather than expected == actual.
+Under the covers, values_match? is able to match arbitrary
+nested data structures containing a mix of both matchers and non-matcher objects.
+It uses === and == to perform the matching, considering the values to
+match if either returns true. The Composable mixin also provides some helper
+methods for surfacing the matcher descriptions within your matcher's description
+or failure messages.
+
+
RSpec's built-in matchers each have a number of aliases that rephrase the matcher
+from a verb phrase (such as be_within) to a noun phrase (such as a_value_within),
+which reads better when the matcher is passed as an argument in a composed matcher
+expressions, and also uses the noun-phrase wording in the matcher's description,
+for readable failure messages. You can alias your custom matchers in similar fashion
+using Matchers.alias_matcher.
Given a Regexp or String, passes if actual.match(pattern) Given an arbitrary nested data structure (e.g. arrays and hashes), matches if expected === actual || actual == expected for each pair of elements.
Defines a matcher alias. The returned matcher's description will be overriden
+to reflect the phrasing of the new name, which will be used in failure messages
+when passed as an argument to another matcher in a composed matcher expression.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec::Matchers.alias_matcher:a_list_that_sums_to,:sum_to
+sum_to(3).description# => "sum to 3"
+a_list_that_sums_to(3).description# => "a list that sums to 3"
+
+
+
+RSpec::Matchers.alias_matcher:a_list_sorted_by,:be_sorted_bydo|description|
+ description.sub("be sorted by","a list sorted by")
+end
+
+be_sorted_by(:age).description# => "be sorted by age"
+a_list_sorted_by(:age).description# => "a list sorted by age"
the ruby class to use as the decorator. (Not normally used).
+
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
optional block that, when given is used to define the overriden
+description. The yielded arg is the original description. If no block is
+provided, a default description override is used based on the old and
+new names.
Delegates to Expectations.configuration.
+This is here because rspec-core's expect_with option
+looks for a configuration method on the mixin
+(RSpec::Matchers) to yield to a block.
Defines a negated matcher. The returned matcher's description and failure_message
+will be overriden to reflect the phrasing of the new name, and the match logic will
+be based on the original matcher but negated.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec::Matchers.define_negated_matcher:a_value_not_between,:a_value_between
+a_value_between(3,5).description# => "a value between 3 and 5"
+a_value_not_between(3,5).description# => "a value not between 3 and 5"
+
+
+
Parameters:
+
+
+
+
+ negated_name
+
+
+ (Symbol)
+
+
+
+ —
+
the name for the negated matcher
+
+
+
+
+
+
+ base_name
+
+
+ (Symbol)
+
+
+
+ —
+
the name of the original matcher that will be negated
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
optional block that, when given is used to define the overriden
+description. The yielded arg is the original description. If no block is
+provided, a default description override is used based on the old and
+new names.
+
+
+
+
+
+
+
+
+
+
+
+
+274
+275
+276
+
+
+
# File 'lib/rspec/matchers.rb', line 274
+
+defself.define_negated_matcher(negated_name,base_name,&description_override)
+ alias_matcher(negated_name,base_name,:klass=>AliasedNegatedMatcher,&description_override)
+end
+
+
+
+
+
+
+
+
+ + (Object) generated_description
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Generates an an example description based on the last expectation.
+Used by rspec-core's one-liner syntax.
The negative form not_to all is not supported. Instead
+use not_to include or pass a negative form of a matcher
+as the argument (e.g. all exclude(:foo)).
+
+
+
+
+ Note:
+
You can also use this with compound matchers as well.
+
+
+
+
Passes if actual all expected objects pass. This works for
+any enumerable object.
# File 'lib/rspec/matchers.rb', line 635
+
+defall(expected)
+ BuiltIn::All.new(expected)
+end
+
+
+
+
+
+
+
+
+ - (Object) be(*args)
+
+
+
+ Also known as:
+ a_value
+
+
+
+
+
+
+
Given true, false, or nil, will pass if actual value is true, false or
+nil (respectively). Given no args means the caller should satisfy an if
+condition (to be or not to be).
+
+
Predicates are any Ruby method that ends in a "?" and returns true or
+false. Given be_ followed by arbitrary_predicate (without the "?"),
+RSpec will match convert that into a query against the target object.
+
+
The arbitrarypredicate feature will handle any predicate prefixed with
+"be_an" (e.g. bean_instance_of), "be_a" (e.g. bea_kind_of) or "be"
+(e.g. be_empty), letting you choose the prefix that best suits the
+predicate.
# File 'lib/rspec/matchers.rb', line 336
+
+defbe_an_instance_of(expected)
+ BuiltIn::BeAnInstanceOf.new(expected)
+end
+
+
+
+
+
+
+
+
+ - (Object) be_between(min, max)
+
+
+
+ Also known as:
+ a_value_between
+
+
+
+
+
+
+
Passes if actual.between?(min, max). Works with any Comparable object,
+including String, Symbol, Time, or Numeric (Fixnum, Bignum, Integer,
+Float, Complex, and Rational).
+
+
By default, be_between is inclusive (i.e. passes when given either the max or min value),
+but you can make it exclusive by chaining that off the matcher.
Applied to a proc, specifies that its execution will cause some value to
+change.
+
+
You can either pass receiver and message, or a block,
+but not both.
+
+
When passing a block, it must use the { ... } format, not
+do/end, as { ... } binds to the change method, whereas do/end
+would errantly bind to the expect(..).to or expect(...).not_to method.
+
+
You can chain any of the following off of the end to specify details
+about the change:
+
+
+
from
+
to
+
+
+
or any one of:
+
+
+
by
+
by_at_least
+
by_at_most
+
+
+
== Notes
+
+
Evaluates receiver.message or block before and after it
+evaluates the block passed to expect.
+
+
expect( ... ).not_to change supports the form that specifies from
+(which specifies what you expect the starting, unchanged value to be)
+but does not support forms with subsequent calls to by, by_at_least,
+by_at_most or to.
# File 'lib/rspec/matchers.rb', line 463
+
+defchange(receiver=nil,message=nil,&block)
+ BuiltIn::Change.new(receiver,message,&block)
+end
+
+
+
+
+
+
+
+
+ - (Object) contain_exactly(*items)
+
+
+
+ Also known as:
+ a_collection_containing_exactly, containing_exactly
+
+
+
+
+
+
+
+
+ Note:
+
This is also available using the =~ operator with should,
+but =~ is not supported with expect.
+
+
+
+
Passes if actual contains all of the expected regardless of order.
+This works for collections. Pass in multiple args and it will only
+pass if all args are found in collection.
Matches if the actual value ends with the expected value(s). In the case
+of a string, matches against the last expected.length characters of the
+actual string. In the case of an array, matches against the last
+expected.length elements of the actual array.
# File 'lib/rspec/matchers.rb', line 594
+
+defhave_attributes(expected)
+ BuiltIn::HaveAttributes.new(expected)
+end
+
+
+
+
+
+
+
+
+ - (Object) include(*expected)
+
+
+
+ Also known as:
+ a_collection_including, a_string_including, a_hash_including, including
+
+
+
+
+
+
+
Passes if actual includes expected. This works for
+collections and Strings. You can also pass in multiple args
+and it will only pass if all args are found in collection.
The match_regex alias is deprecated and is not recommended for use.
+It was added in 2.12.1 to facilitate its use from within custom
+matchers (due to how the custom matcher DSL was evaluated in 2.x,
+match could not be used there), but is no longer needed in 3.x.
+
+
+
+
Given a Regexp or String, passes if actual.match(pattern)
+Given an arbitrary nested data structure (e.g. arrays and hashes),
+matches if expected === actual || actual == expected for each
+pair of elements.
This matcher works by temporarily replacing $stdout or $stderr,
+so it's not able to intercept stream output that explicitly uses STDOUT/STDERR
+or that uses a reference to $stdout/$stderr that was stored before the
+matcher is used.
+
+
+
+
With no arg, passes if the block outputs to_stdout or to_stderr.
+With a string, passes if the blocks outputs that specific string to_stdout or to_stderr.
+With a regexp or matcher, passes if the blocks outputs a string to_stdout or to_stderr that matches.
With no args, matches if any error is raised.
+With a named error, matches only if that specific error is raised.
+With a named error and messsage specified as a String, matches only if both match.
+With a named error and messsage specified as a Regexp, matches only if both match.
+Pass an optional block to perform extra verifications on the exception matched
+
+
+
+
+
+
+
+
Examples:
+
+
+
+expect{do_something_risky}.toraise_error
+expect{do_something_risky}.toraise_error(PoorRiskDecisionError)
+expect{do_something_risky}.toraise_error(PoorRiskDecisionError){|error|expect(error.data).toeq42}
+expect{do_something_risky}.toraise_error(PoorRiskDecisionError,"that was too risky")
+expect{do_something_risky}.toraise_error(PoorRiskDecisionError,/oo ri/)
+
+expect{do_something_risky}.not_toraise_error
+
+
+
+
+
+
+
+
+
+
+737
+738
+739
+
+
+
# File 'lib/rspec/matchers.rb', line 737
+
+defraise_error(error=Exception,message=nil,&block)
+ BuiltIn::RaiseError.new(error,message,&block)
+end
+
+
+
+
+
+
+
+
+ - (Object) respond_to(*names)
+
+
+
+ Also known as:
+ an_object_responding_to, responding_to
+
+
+
+
+
+
+
Matches if the target object responds to all of the names
+provided. Names can be Strings or Symbols.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+expect("string").torespond_to(:length)
+
+
+
+
+
+
+
+
+
+
+757
+758
+759
+
+
+
# File 'lib/rspec/matchers.rb', line 757
+
+defrespond_to(*names)
+ BuiltIn::RespondTo.new(*names)
+end
+
+
+
+
+
+
+
+
+ - (Object) satisfy(&block)
+
+
+
+ Also known as:
+ an_object_satisfying, satisfying
+
+
+
+
+
+
+
Passes if the submitted block returns true. Yields target to the
+block.
+
+
Generally speaking, this should be thought of as a last resort when
+you can't find any other way to specify the behaviour you wish to
+specify.
+
+
If you do find yourself in such a situation, you could always write
+a custom matcher, which would likely make your specs more expressive.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+expect(5).tosatisfy{|n|n>3}
+
+
+
+
+
+
+
+
+
+
+776
+777
+778
+
+
+
# File 'lib/rspec/matchers.rb', line 776
+
+defsatisfy(&block)
+ BuiltIn::Satisfy.new(&block)
+end
Matches if the actual value starts with the expected value(s). In the
+case of a string, matches against the first expected.length characters
+of the actual string. In the case of an array, matches against the first
+expected.length elements of the actual array.
# File 'lib/rspec/matchers.rb', line 839
+
+defyield_control
+ BuiltIn::YieldControl.new
+end
+
+
+
+
+
+
+
+
+ - (Object) yield_successive_args(*args)
+
+
+
+ Also known as:
+ a_block_yielding_successive_args, yielding_successive_args
+
+
+
+
+
+
+
+
+ Note:
+
Your expect block must accept a parameter and pass it on to
+the method-under-test as a block.
+
+
+
+
Designed for use with methods that repeatedly yield (such as
+iterators). Passes if the method called in the expect block yields
+multiple times with arguments matching those given.
+
+
Argument matching is done using === (the case match operator)
+and ==. If the expected and actual arguments match with either
+operator, the matcher will pass.
# File 'lib/rspec/matchers.rb', line 911
+
+defyield_successive_args(*args)
+ BuiltIn::YieldSuccessiveArgs.new(*args)
+end
+
+
+
+
+
+
+
+
+ - (Object) yield_with_args(*args)
+
+
+
+ Also known as:
+ a_block_yielding_with_args, yielding_with_args
+
+
+
+
+
+
+
+
+ Note:
+
Your expect block must accept a parameter and pass it on to
+the method-under-test as a block.
+
+
+
+
+ Note:
+
This matcher is not designed for use with methods that yield
+multiple times.
+
+
+
+
Given no arguments, matches if the method called in the expect
+block yields with arguments (regardless of what they are or how
+many there are).
+
+
Given arguments, matches if the method called in the expect block
+yields with arguments that match the given arguments.
+
+
Argument matching is done using === (the case match operator)
+and ==. If the expected and actual arguments match with either
+operator, the matcher will pass.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+expect{|b|5.tap(&b)}.toyield_with_args# because #tap yields an arg
+expect{|b|5.tap(&b)}.toyield_with_args(5)# because 5 == 5
+expect{|b|5.tap(&b)}.toyield_with_args(Fixnum)# because Fixnum === 5
+expect{|b|File.open("f.txt",&b)}.toyield_with_args(/txt/)# because /txt/ === "f.txt"
+
+expect{|b|User.transaction(&b)}.not_toyield_with_args# because it yields no args
+expect{|b|5.tap(&b)}.not_toyield_with_args(1,2,3)
+
+
+
+
+
+
+
+
+
+
+889
+890
+891
+
+
+
# File 'lib/rspec/matchers.rb', line 889
+
+defyield_with_args(*args)
+ BuiltIn::YieldWithArgs.new(*args)
+end
+
+
+
+
+
+
+
+
+ - (Object) yield_with_no_args
+
+
+
+ Also known as:
+ a_block_yielding_with_no_args, yielding_with_no_args
+
+
+
+
+
+
+
+
+ Note:
+
Your expect block must accept a parameter and pass it on to
+the method-under-test as a block.
+
+
+
+
+ Note:
+
This matcher is not designed for use with methods that yield
+multiple times.
+
+
+
+
Passes if the method called in the expect block yields with
+no arguments. Fails if it does not yield, or yields with arguments.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+expect{|b|User.transaction(&b)}.toyield_with_no_args
+expect{|b|5.tap(&b)}.not_toyield_with_no_args# because it yields with `5`
+expect{|b|"a".to_sym(&b)}.not_toyield_with_no_args# because it does not yield
+
+
+
+
+
+
+
+
+
+
+858
+859
+860
+
+
+
# File 'lib/rspec/matchers.rb', line 858
+
+defyield_with_no_args
+ BuiltIn::YieldWithNoArgs.new
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/AliasedMatcher.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/AliasedMatcher.html
new file mode 100644
index 000000000..fbb1dd6d8
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/AliasedMatcher.html
@@ -0,0 +1,545 @@
+
+
+
+
+
+ Class: RSpec::Matchers::AliasedMatcher
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This class is part of a private API.
+ You should avoid using this class if possible, as it may be removed or be changed in the future.
+
+
Decorator that wraps a matcher and overrides description
+using the provided block in order to support an alias
+of a matcher. This is intended for use when composing
+matchers, so that you can use an expression like
+include( a_value_within(0.1).of(3) ) rather than
+include( be_within(0.1).of(3) ), and have the corresponding
+description read naturally.
+ This class handles dynamic methods through the method_missing method
+
+
+
+
+
+
+ - (Object) method_missing
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Forward messages on to the wrapped matcher.
+Since many matchers provide a fluent interface
+(e.g. a_value_within(0.1).of(3)), we need to wrap
+the returned value if it responds to description,
+so that our override can be applied when it is eventually
+used.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Provides the description of the aliased matcher. Aliased matchers
+are designed to behave identically to the original matcher except
+for the description and failure messages. The description is different
+to reflect the aliased name.
+
+
+
+
+
+
+
+
+
+
+
+
+
+36
+37
+38
+
+
+
# File 'lib/rspec/matchers/aliased_matcher.rb', line 36
+
+defdescription
+ @description_block.call(super)
+end
+
+
+
+
+
+
+
+
+ - (Object) failure_message
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Provides the failure_message of the aliased matcher. Aliased matchers
+are designed to behave identically to the original matcher except
+for the description and failure messages. The failure_message is different
+to reflect the aliased name.
+
+
+
+
+
+
+
+
+
+
+
+
+
+46
+47
+48
+
+
+
# File 'lib/rspec/matchers/aliased_matcher.rb', line 46
+
+deffailure_message
+ @description_block.call(super)
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Provides the failure_message_when_negated of the aliased matcher. Aliased matchers
+are designed to behave identically to the original matcher except
+for the description and failure messages. The failure_message_when_negated is different
+to reflect the aliased name.
+
+
+
+
+
+
+
+
+
+
+
+
+
+56
+57
+58
+
+
+
# File 'lib/rspec/matchers/aliased_matcher.rb', line 56
+
+deffailure_message_when_negated
+ @description_block.call(super)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn.html
new file mode 100644
index 000000000..a9b77223c
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn.html
@@ -0,0 +1,133 @@
+
+
+
+
+
+ Module: RSpec::Matchers::BuiltIn
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Container module for all built-in matchers. The matcher classes are here
+(rather than directly under RSpec::Matchers) in order to prevent name
+collisions, since RSpec::Matchers gets included into the user's namespace.
+
+
Autoloading is used to delay when the matcher classes get loaded, allowing
+rspec-matchers to boot faster, and avoiding loading matchers the user is
+not using.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+23
+24
+25
+26
+27
+28
+29
+30
+31
+32
+33
+
+
+
# File 'lib/rspec/matchers/built_in/all.rb', line 23
+
+deffailure_message
+ unlessiterable?
+ return"#{improve_hash_formatting(super)}, but was not iterable"
+ end
+
+ all_messages=[improve_hash_formatting(super)]
+ failed_objects.eachdo|index,matcher_failure_message|
+ all_messages<<failure_message_for_item(index,matcher_failure_message)
+ end
+ all_messages.join("\n\n")
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/BaseMatcher.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/BaseMatcher.html
new file mode 100644
index 000000000..84c872cd3
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/BaseMatcher.html
@@ -0,0 +1,799 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::BaseMatcher
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This class is part of a private API.
+ You should avoid using this class if possible, as it may be removed or be changed in the future.
+
+
Used internally as a base class for matchers that ship with
+rspec-expectations and rspec-rails.
+
+
Warning:
+
+
This class is for internal use, and subject to change without notice. We
+strongly recommend that you do not base your custom matchers on this
+class. If/when this changes, we will announce it and remove this warning.
Most matchers are value matchers (i.e. meant to work with expect(value)) rather than block matchers (i.e. meant to work with expect { }), so this defaults to false.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Used to wrap a block of code that will indicate failure by
+raising one of the named exceptions.
+
+
This is used by rspec-rails for some of its matchers that
+wrap rails' assertions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+45
+46
+47
+48
+49
+50
+51
+52
+53
+
+
+
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 45
+
+defmatch_unless_raises(*exceptions)
+ exceptions.unshiftExceptionifexceptions.empty?
+ begin
+ yield
+ true
+ rescue*exceptions=>@rescued_exception
+ false
+ end
+end
+
+
+
+
+
+
+
+
+ - (Boolean) matches?(actual)
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Indicates if the match is successful. Delegates to match, which
+should be defined on a subclass. Takes care of consistently
+initializing the actual attribute.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Most matchers are value matchers (i.e. meant to work with expect(value))
+rather than block matchers (i.e. meant to work with expect { }), so
+this defaults to false. Block matchers must override this to return true.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+74
+75
+76
+
+
+
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 74
+
+defsupports_block_expectations?
+ false
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/BaseMatcher/DefaultFailureMessages.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/BaseMatcher/DefaultFailureMessages.html
new file mode 100644
index 000000000..5e30ed422
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/BaseMatcher/DefaultFailureMessages.html
@@ -0,0 +1,304 @@
+
+
+
+
+
+ Module: RSpec::Matchers::BuiltIn::BaseMatcher::DefaultFailureMessages
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Provides a good generic failure message. Based on description.
+When subclassing, if you are not satisfied with this failure message
+you often only need to override description.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+106
+107
+108
+
+
+
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 106
+
+deffailure_message
+ "expected #{actual.inspect} to #{description}"
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
Provides a good generic negative failure message. Based on description.
+When subclassing, if you are not satisfied with this failure message
+you often only need to override description.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+115
+116
+117
+
+
+
# File 'lib/rspec/matchers/built_in/base_matcher.rb', line 115
+
+deffailure_message_when_negated
+ "expected #{actual.inspect} not to #{description}"
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/Be.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/Be.html
new file mode 100644
index 000000000..d5586852c
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/Be.html
@@ -0,0 +1,437 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::Be
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+157
+158
+159
+160
+161
+162
+163
+164
+
+
+
# File 'lib/rspec/matchers/built_in/be.rb', line 157
+
+deffailure_message_when_negated
+ message="`expect(#{@actual.inspect}).not_to be #{@operator}#{@expected.inspect}`"
+ if[:<,:>,:<=,:>=].include?(@operator)
+ message+" not only FAILED, it is a bit confusing."
+ else
+ message
+ end
+end
+
+
+
+
+
+
+
+
+ - (Boolean) matches?(actual)
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+46
+47
+48
+
+
+
# File 'lib/rspec/matchers/built_in/be_within.rb', line 46
+
+deffailure_message_when_negated
+ "expected #{@actual.inspect} not to #{description}"
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+60
+61
+62
+
+
+
# File 'lib/rspec/matchers/built_in/change.rb', line 60
+
+deffailure_message
+ "expected #{@change_details.message} to have changed, but #{positive_failure_reason}"
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+66
+67
+68
+
+
+
# File 'lib/rspec/matchers/built_in/change.rb', line 66
+
+deffailure_message_when_negated
+ "expected #{@change_details.message} not to have changed, but #{negative_failure_reason}"
+end
+
+
+
+
+
+
+
+
+ - (Object) from(value)
+
+
+
+
+
+
+
+
Specifies the original value.
+
+
+
+
+
+
+
+
+
+
+
+
+
+40
+41
+42
+
+
+
# File 'lib/rspec/matchers/built_in/change.rb', line 40
+
+deffrom(value)
+ ChangeFromValue.new(@change_details,value)
+end
+
+
+
+
+
+
+
+
+ - (Object) to(value)
+
+
+
+
+
+
+
+
Specifies the new value you expect.
+
+
+
+
+
+
+
+
+
+
+
+
+
+34
+35
+36
+
+
+
# File 'lib/rspec/matchers/built_in/change.rb', line 34
+
+defto(value)
+ ChangeToValue.new(@change_details,value)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/ChangeFromValue.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/ChangeFromValue.html
new file mode 100644
index 000000000..a4c4b7577
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/ChangeFromValue.html
@@ -0,0 +1,357 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::ChangeFromValue
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/built_in/contain_exactly.rb', line 10
+
+deffailure_message
+ ifArray===actual
+ message="expected collection contained: #{safe_sort(surface_descriptions_inexpected).inspect}\n"
+ message+="actual collection contained: #{safe_sort(actual).inspect}\n"
+ message+="the missing elements were: #{safe_sort(surface_descriptions_inmissing_items).inspect}\n"unlessmissing_items.empty?
+ message+="the extra elements were: #{safe_sort(extra_items).inspect}\n"unlessextra_items.empty?
+ message
+ else
+ "expected a collection that can be converted to an array with " \
+ "`#to_ary` or `#to_a`, but got #{actual.inspect}"
+ end
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+25
+26
+27
+
+
+
# File 'lib/rspec/matchers/built_in/contain_exactly.rb', line 25
+
+deffailure_message_when_negated
+ "expected #{actual.inspect} not to contain exactly#{to_sentence(surface_descriptions_inexpected)}"
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/Cover.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/Cover.html
new file mode 100644
index 000000000..2f1134264
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/Cover.html
@@ -0,0 +1,440 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::Cover
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+36
+37
+38
+
+
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 36
+
+deffailure_message_when_negated
+ "expected #{@actual.inspect} not to exist#{@test.validity_message}"
+end
+
+
+
+
+
+
+
+
+ - (Boolean) matches?(actual)
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 43
+
+defactual
+ @actual
+end
+
+
+
+
+
+
+
+
+
+
+ - (Object) expected
+
+
+
+
+
+
+
+
Returns the value of attribute expected
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Object)
+
+
+
+ —
+
the current value of expected
+
+
+
+
+
+
+
+
+
+
+
+
+43
+44
+45
+
+
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 43
+
+defexpected
+ @expected
+end
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (Boolean) actual_exists?
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+52
+53
+54
+
+
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 52
+
+defactual_exists?
+ existence_values.first
+end
+
+
+
+
+
+
+
+
+ - (Boolean) valid_test?
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+46
+47
+48
+
+
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 46
+
+defvalid_test?
+ uniq_truthy_values.size==1
+end
+
+
+
+
+
+
+
+
+ - (String) validity_message
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+
+
+
# File 'lib/rspec/matchers/built_in/exist.rb', line 58
+
+defvalidity_message
+ caseuniq_truthy_values.size
+ when0
+ " but it does not respond to either `exist?` or `exists?`"
+ when2
+ " but `exist?` and `exists?` returned different values:\n\n"\
+ " exist?: #{existence_values.first}\n"\
+ "exists?: #{existence_values.last}"
+ end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/Has.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/Has.html
new file mode 100644
index 000000000..cca74ae94
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/Has.html
@@ -0,0 +1,509 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::Has
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+24
+25
+26
+
+
+
# File 'lib/rspec/matchers/built_in/output.rb', line 24
+
+defdoes_not_match?(block)
+ !matches?(block)&&Proc===block
+end
+
+
+
+
+
+
+
+
+ - (String) failure_message
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+44
+45
+46
+
+
+
# File 'lib/rspec/matchers/built_in/output.rb', line 44
+
+deffailure_message
+ "expected block to #{description}, but #{positive_failure_reason}"
+end
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+50
+51
+52
+
+
+
# File 'lib/rspec/matchers/built_in/output.rb', line 50
+
+deffailure_message_when_negated
+ "expected block to not #{description}, but #{negative_failure_reason}"
+end
+
+
+
+
+
+
+
+
+ - (Boolean) matches?(block)
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+15
+16
+17
+18
+19
+20
+21
+22
+23
+
+
+
# File 'lib/rspec/matchers/built_in/start_and_end_with.rb', line 15
+
+deffailure_message
+ super.tapdo|msg|
+ if@actual_does_not_have_ordered_elements
+ msg<<", but it does not have ordered elements"
+ elsif!actual.respond_to?(:[])
+ msg<<", but it cannot be indexed using #[]"
+ end
+ end
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/StartWith.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/StartWith.html
new file mode 100644
index 000000000..b8c4cbcb1
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/BuiltIn/StartWith.html
@@ -0,0 +1,209 @@
+
+
+
+
+
+ Class: RSpec::Matchers::BuiltIn::StartWith
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+
+
+
+
+
+
+
+
+
+
+174
+175
+176
+
+
+
# File 'lib/rspec/matchers/built_in/yield.rb', line 174
+
+deffailure_message_when_negated
+ 'expected given block not to yield control'+failure_reason
+end
+
+
+
+
+
+
+
+
+ - (Object) once
+
+
+
+
+
+
+
+
Specifies that the method is expected to yield once.
Mixin designed to support the composable matcher features
+of RSpec 3+. Mix it into your custom matcher classes to
+allow them to be used in a composable fashion.
Transforms the given data structue (typically a hash or array) into a new data structure that, when #inspect is called on it, will provide descriptions of any contained matchers rather than the normal #inspect output.
Transforms the given data structue (typically a hash or array)
+into a new data structure that, when #inspect is called on it,
+will provide descriptions of any contained matchers rather than
+the normal #inspect output.
+
+
You are encouraged to use this in your custom matcher's
+description, failure_message or
+failure_message_when_negated implementation if you are
+supporting any arguments which may be a data structure
+containing matchers.
# File 'lib/rspec/matchers/composable.rb', line 99
+
+defsurface_descriptions_in(item)
+ ifMatchers.is_a_describable_matcher?(item)
+ DescribableItem.new(item)
+ elsifHash===item
+ Hash[surface_descriptions_in(item.to_a)]
+ elsifStruct===item
+ item.inspect
+ elsifenumerable?(item)
+ begin
+ item.map{|subitem|surface_descriptions_in(subitem)}
+ rescueIOError# STDOUT is enumerable but `map` raises an error
+item.inspect
+ end
+ else
+ item
+ end
+end
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (Object) ===(value)
+
+
+
+
+
+
+
+
Delegates to #matches?. Allows matchers to be used in composable
+fashion and also supports using matchers in case statements.
+
+
+
+
+
+
+
+
+
+
+
+
+
+45
+46
+47
+
+
+
# File 'lib/rspec/matchers/composable.rb', line 45
+
+def===(value)
+ matches?(value)
+end
+
+
+
+
+
+
+
+
+ - (Object) and(matcher)
+
+
+
+ Also known as:
+ &
+
+
+
+
+
+
+
+
+ Note:
+
The negative form (expect(...).not_to matcher.and other)
+is not supported at this time.
+
+
+
+
Creates a compound and expectation. The matcher will
+only pass if both sub-matchers pass.
+This can be chained together to form an arbitrarily long
+chain of matchers.
# File 'lib/rspec/matchers/composable.rb', line 22
+
+defand(matcher)
+ BuiltIn::Compound::And.newself,matcher
+end
+
+
+
+
+
+
+
+
+ - (Object) description_of(object)
+
+
+
+
+
+
+
+
Returns the description of the given object in a way that is
+aware of composed matchers. If the object is a matcher with
+a description method, returns the description; otherwise
+returns object.inspect.
+
+
You are encouraged to use this in your custom matcher's
+description, failure_message or
+failure_message_when_negated implementation if you are
+supporting matcher arguments.
+
+ - (Object) or(matcher)
+
+
+
+ Also known as:
+ |
+
+
+
+
+
+
+
+
+ Note:
+
The negative form (expect(...).not_to matcher.or other)
+is not supported at this time.
+
+
+
+
Creates a compound or expectation. The matcher will
+pass if either sub-matcher passes.
+This can be chained together to form an arbitrarily long
+chain of matchers.
This provides a generic way to fuzzy-match an expected value against
+an actual value. It understands nested data structures (e.g. hashes
+and arrays) and is able to match against a matcher being used as
+the expected value or within the expected value at any level of
+nesting.
+
+
Within a custom matcher you are encouraged to use this whenever your
+matcher needs to match two values, unless it needs more precise semantics.
+For example, the eq matcher does not use this as it is meant to
+use == (and only ==) for matching.
Defines default implementations of the matcher
+protocol methods for custom matchers. You can
+override any of these using the Macros methods
+from within an RSpec::Matchers.define block.
Convenience for defining methods on this matcher to create a fluent
+interface. The trick about fluent interfaces is that each method must
+return self in order to chain methods together. chain handles that
+for you. If the method is invoked and the
+include_chain_clauses_in_custom_matcher_descriptions config option
+hash been enabled, the chained method name and args will be added to the
+default description and failure message.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec::Matchers.define:have_errors_ondo|key|
+ chain:withdo|message|
+ @message=message
+ end
+
+ matchdo|actual|
+ actual.errors[key]==@message
+ end
+end
+
+expect(minor).tohave_errors_on(:age).with("Not old enough to participate")
+
+
+
+
+
+
+
+
+
+
+181
+182
+183
+184
+185
+186
+187
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 181
+
+defchain(name,&definition)
+ define_user_override(name,definition)do|*args,&block|
+ super(*args,&block)
+ @chained_method_clauses.push([name,args])
+ self
+ end
+end
Customizes the failure messsage to use when this matcher is
+asked to positively match. Only use this when the message
+generated by default doesn't suit your needs.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec::Matchers.define:have_strengthdo|expected|
+ match{your_match_logic}
+
+ failure_messagedo|actual|
+ "Expected strength of #{expected}, but had #{actual.strength}"
+ end
+end
+
+
+
+
Yields:
+
+
+
+
+
+ (Object)
+
+
+
+ —
+
actual the actual object (i.e. the value wrapped by expect)
+
+
+
+
+
+
+
+
+
+
+
+
+105
+106
+107
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 105
+
+deffailure_message(&definition)
+ define_user_override(__method__,definition)
+end
Customize the failure messsage to use when this matcher is asked
+to negatively match. Only use this when the message generated by
+default doesn't suit your needs.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec::Matchers.define:have_strengthdo|expected|
+ match{your_match_logic}
+
+ failure_message_when_negateddo|actual|
+ "Expected not to have strength of #{expected}, but did"
+ end
+end
+
+
+
+
Yields:
+
+
+
+
+
+ (Object)
+
+
+
+ —
+
actual the actual object (i.e. the value wrapped by expect)
+
+
+
+
+
+
+
+
+
+
+
+
+124
+125
+126
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 124
+
+deffailure_message_when_negated(&definition)
+ define_user_override(__method__,definition)
+end
+
+
+
+
+
+
+
+
+ - (Object) match {|Object| ... }
+
+
+
+
+
+
+
+
Stores the block that is used to determine whether this matcher passes
+or fails. The block should return a boolean value. When the matcher is
+passed to expect(...).to and the block returns true, then the expectation
+passes. Similarly, when the matcher is passed to expect(...).not_to and the
+block returns false, then the expectation passes.
Use this to define the block for a negative expectation (expect(...).not_to)
+when the positive and negative forms require different handling. This
+is rarely necessary, but can be helpful, for example, when specifying
+asynchronous processes that require different timeouts.
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+ (Object)
+
+
+
+ —
+
actual the actual value (i.e. the value wrapped by expect)
+
+
+
+
+
+
+
+
+
+
+
+
+56
+57
+58
+59
+60
+61
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 56
+
+defmatch_when_negated(&match_block)
+ define_user_override(:does_not_match?,match_block)do|actual|
+ @actual=actual
+ super(*actual_arg_for(match_block))
+ end
+end
Declares that the matcher can be used in a block expectation.
+Users will not be able to use your matcher in a block
+expectation without declaring this.
+(e.g. expect { do_something }.to matcher).
+
+
+
+
+
+
+
+
+
+
+
+
+
+156
+157
+158
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 156
+
+defsupports_block_expectations
+ define_method(:supports_block_expectations?){true}
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/DSL/Macros/Deprecated.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/DSL/Macros/Deprecated.html
new file mode 100644
index 000000000..c0fde7fa7
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/DSL/Macros/Deprecated.html
@@ -0,0 +1,402 @@
+
+
+
+
+
+ Module: RSpec::Matchers::DSL::Macros::Deprecated
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
The class used for custom matchers. The block passed to
+RSpec::Matchers.define will be evaluated in the context
+of the singleton class of an instance, and will have the
+Macros methods available.
Takes care of forwarding unhandled messages to the
+@matcher_execution_context (typically the current
+running RSpec::Core::Example). This is needed by
+rspec-rails so that it can define matchers that wrap
+Rails' test helper methods, but it's also a useful
+feature in its own right.
+
+
+
+
+
+
+
+
+
+
+
+
+
+379
+380
+381
+382
+383
+384
+385
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 379
+
+defmethod_missing(method,*args,&block)
+ if@matcher_execution_context.respond_to?(method)
+ @matcher_execution_context.__send__method,*args,&block
+ else
+ super(method,*args,&block)
+ end
+end
+
+
+
+
+
+
+
+
+
Instance Attribute Details
+
+
+
+
+
+
+ - (Object) actual(readonly)
+
+
+
+
+
+
+
+
Exposes the value being matched against -- generally the object
+object wrapped by expect.
+
+
+
+
+
+
+
+
+
+
+
+
+
+306
+307
+308
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 306
+
+defactual
+ @actual
+end
Returns the expected value as an an array. This exists primarily
+to aid in upgrading from RSpec 2.x, since in RSpec 2, expected
+always returned an array.
Indicates that this matcher responds to messages
+from the @matcher_execution_context as well.
+Also, supports getting a method object for such methods.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+
+
+
+
+
+
+
+
+
+
+356
+357
+358
+
+
+
# File 'lib/rspec/matchers/dsl.rb', line 356
+
+defrespond_to_missing?(method,include_private=false)
+ super||@matcher_execution_context.respond_to?(method,include_private)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/MatcherProtocol.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/MatcherProtocol.html
new file mode 100644
index 000000000..0592db2c0
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/MatcherProtocol.html
@@ -0,0 +1,1068 @@
+
+
+
+
+
+ Class: RSpec::Matchers::MatcherProtocol
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Indicates that this matcher provides actual and expected attributes, and that the values returned by these can be usefully diffed, which can be included in the output.
Indicates that when this matcher is used in a block expectation expression, it expects the block to use a ruby construct that causes a call stack jump (such as raising an error or throwing a symbol).
Indicates that this matcher can be used in a block expectation expression, such as expect { foo }.to raise_error.
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (String, Object) actual
+
+
+
+
+
+
+
+
+
+ Note:
+
This method is required if diffable? returns true.
+
+
+
+
The actual value for the purposes of a diff.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String, Object)
+
+
+
+ —
+
If an object (rather than a string) is provided,
+RSpec will use the pp library to convert it to multi-line output in
+order to diff.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/matcher_protocol.rb', line 82
+
+
+
+
+
+
+
+
+
+
+ - (String) description
+
+
+
+
+
+
+
+
The description is used for two things:
+
+
+
When using RSpec's one-liner syntax
+(e.g. it { is_expected.to matcher }), the description
+is used to generate the example's doc string since you
+have not provided one.
+
In a composed matcher expression, the description is used
+as part of the failure message (and description) of the outer
+matcher.
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
Description of the matcher.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/matcher_protocol.rb', line 42
+
+
+
+
+
+
+
+
+
+
+ - (Boolean) diffable?
+
+
+
+
+
+
+
+
Indicates that this matcher provides actual and expected attributes,
+and that the values returned by these can be usefully diffed, which can
+be included in the output.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
true if actual and expected can be diffed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/matcher_protocol.rb', line 76
+
+
In a negative expectation such as expect(x).not_to foo, RSpec will
+call foo.does_not_match?(x) if this method is defined. If it's not
+defined it will fall back to using !foo.matches?(x). This allows you
+to provide custom logic for the negative case.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ actual
+
+
+ (Object)
+
+
+
+ —
+
The object being matched against.
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+
+
+
+
+
+
For an expression like expect(x).not_to matcher do...end, the do/end
+block binds to not_to. It passes that block, if there is one, on to this method.
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
true if this matcher does not match the provided object.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/matcher_protocol.rb', line 24
+
+
+
+
+
+
+
+
+
+
+ - (String, Object) expected
+
+
+
+
+
+
+
+
+
+ Note:
+
This method is required if diffable? returns true.
+
+
+
+
The expected value for the purposes of a diff.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String, Object)
+
+
+
+ —
+
If an object (rather than a string) is provided,
+RSpec will use the pp library to convert it to multi-line output in
+order to diff.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/matcher_protocol.rb', line 89
+
+
If not defined, RSpec assumes a value of false for this method.
+
+
+
+
Indicates that when this matcher is used in a block expectation
+expression, it expects the block to use a ruby construct that causes
+a call stack jump (such as raising an error or throwing a symbol).
+
+
This is used internally for compound block expressions, as matchers
+which expect call stack jumps must be treated with care to work properly.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
true if the matcher expects a call stack jump
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/matcher_protocol.rb', line 63
+
+
+
+
+
+
+
+
+
+
+ - (String) failure_message
+
+
+
+
+
+
+
+
This will only be called if #matches? returns false.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
Explanation for the failure.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/matcher_protocol.rb', line 16
+
+
This method is listed as optional because matchers do not have to
+support negation. But if your matcher does support negation, this is a
+required method -- otherwise, you'll get a NoMethodError.
+
+
+
+
This will only be called when a negative match fails.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (String)
+
+
+
+ —
+
Explanation for the failure.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/matcher_protocol.rb', line 35
+
+
+
+
+
+
+
+
+
+
+ - (Boolean) matches? { ... }
+
+
+
+
+
+
+
+
Returns true if this matcher matches the provided object.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ actual
+
+
+ (Object)
+
+
+
+ —
+
The object being matched against.
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+
+
+
+
+
+
For an expression like expect(x).to matcher do...end, the do/end
+block binds to to. It passes that block, if there is one, on to this method.
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
true if this matcher matches the provided object.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/matcher_protocol.rb', line 10
+
+
If not defined, RSpec assumes a value of false for this method.
+
+
+
+
Indicates that this matcher can be used in a block expectation expression,
+such as expect { foo }.to raise_error. Generally speaking, this is
+only needed for matchers which operate on a side effect of a block, rather
+than on a particular object.
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Boolean)
+
+
+
+ —
+
true if this matcher can be used in block expressions.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/matchers/matcher_protocol.rb', line 55
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/RSpec/Matchers/Pretty.html b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/Pretty.html
new file mode 100644
index 000000000..c8f770c46
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/RSpec/Matchers/Pretty.html
@@ -0,0 +1,446 @@
+
+
+
+
+
+ Module: RSpec::Matchers::Pretty
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Fix define_negated_matcher so that matchers that support fluent
+interfaces continue to be negated after you use the chained method.
+(Myron Marston, #656)
+
Fix define_negated_matcher so that the matchers fail with an
+appropriate failure message. (Myron Marston, #659)
Fix regression in all matcher in 3.1.0 that prevented it from
+working on objects that are not Enumerable but do implement
+each_with_index (such as an ActiveRecord proxy). (Jori Hardman, #647)
Add have_attributes matcher, that passes if actual's attribute
+values match the expected attributes hash:
+Person = Struct.new(:name, :age)
+person = Person.new("Bob", 32)
+expect(person).to have_attributes(:name => "Bob", :age => 32).
+(Adam Farhi, #571)
+
Extended compound matcher support to block matchers, for cases like:
+expect { ... }.to change { x }.to(3).and change { y }.to(4). (Myron
+Marston, #567)
+
Include chained methods in custom matcher description and failure message
+when new include_chain_clauses_in_custom_matcher_descriptions config
+option is enabled. (Dan Oved, #600)
+
Add thrice modifier to yield_control matcher as a synonym for
+exactly(3).times. (Dennis Taylor, #615)
+
Add RSpec::Matchers.define_negated_matcher, which defines a negated
+version of the named matcher. (Adam Farhi, Myron Marston, #618)
+
Document and support negation of contain_exactly/match_array.
+(Jon Rowe, #626).
Fix start_with and end_with so that they work properly with
+structs. (Myron Marston, #620)
+
Fix failure message generation so that structs are printed properly
+in failures. Previously failure messages would represent them as
+an array. (Myron Marston, #620)
+
Fix composable matcher support so that it does not wrongly treat
+structs as arrays. (Myron Marston, #620)
Fix regression in contain_exactly (AKA match_array) that caused it
+to wrongly pass when the expected array was empty. (Myron Marston, #581)
+
Provide a better error message when you use the change(obj, :msg)
+form of the change matcher but forget the message argument. (Alex
+Sunderland, #585)
+
Make the contain_exactly matcher work with arrays that contain hashes in
+arbitrary ordering. (Sam Phippen, #578)
Add a missing require that would cause the respond_to matcher to
+fail when used in a project where the rest of RSpec (e.g. core and
+expecatations) weren't being used. (Myron Marston, #566)
+
Structs are no longer treated as arrays when diffed. (Jon Rowe, #576)
Fix NoMethodError triggered by beta2 when YARD was loaded in
+the test environment. (Myron Marston)
+
Fix be_xyz matcher to accept a do...end block. (Myron Marston)
+
Fix composable matcher failure message generation logic
+so that it does not blow up when given $stdout or $stderr.
+(Myron Marston)
+
Fix change matcher to work properly with IO objects.
+(Myron Marston)
+
Fix exist matcher so that it can be used in composed matcher
+expressions involving objects that do not implement exist? or
+exists?. (Daniel Fone)
+
Fix composable matcher match logic so that it clones matchers
+before using them in order to work properly with matchers
+that use internal memoization based on a given actual value.
+(Myron Marston)
+
Fix be_xyz and has_xyz predicate matchers so that they can
+be used in composed matcher expressions involving objects that
+do not implement the predicate method. (Daniel Fone)
+
+
+
Enhancements:
+
+
+
Document the remaining public APIs. rspec-expectations now has 100% of
+the public API documented and will remain that way (as new undocumented
+methods will fail the build). (Myron Marston)
+
Improve the formatting of BigDecimal objects in eq matcher failure
+messages. (Daniel Fone)
+
Improve the failure message for be_xyz predicate matchers so
+that it includes the inspect output of the receiver.
+(Erik Michaels-Ober, Sam Phippen)
+
Add all matcher, to allow you to specify that a given matcher
+matches all elements in a collection:
+expect([1, 3, 5]).to all( be_odd ). (Adam Farhi)
+
Add boolean aliases (&/|) for compound operators (and/or). (Adam Farhi)
+
Give users a clear error when they wrongly use a value matcher
+in a block expectation expression (e.g. expect { 3 }.to eq(3))
+or vice versa. (Myron Marston)
Remove support for deprecated expect(...).should. (Myron Marston)
+
Explicitly disallow expect { }.not_to change { } with by,
+by_at_least, by_at_most or to. These have never been supported
+but did not raise explicit errors. (Myron Marston)
+
Provide === rather than == as an alias of matches? for
+all matchers. The semantics of === are closer to an RSpec
+matcher than ==. (Myron Marston)
Make RSpec::Expectations::ExpectationNotMetError subclass
+Exception rather than StandardError so they can bypass
+a bare rescue in end-user code (e.g. when an expectation is
+set from within a rspec-mocks stub implementation). (Myron Marston)
+
Remove Test::Unit and Minitest 4.x integration. (Myron Marston)
+
+
+
Enhancements:
+
+
+
Simplify the failure message of the be matcher when matching against:
+true, false and nil. (Sam Phippen)
+
Update matcher protocol and custom matcher DSL to better align
+with the newer expect syntax. If you want your matchers to
+maintain compatibility with multiple versions of RSpec, you can
+alias the new names to the old. (Myron Marston)
+
+
Improve generated descriptions from change matcher. (Myron Marston)
+
Add support for compound matcher expressions using and and or.
+Simply chain them off of any existing matcher to create an expression
+like expect(alphabet).to start_with("a").and end_with("z").
+(Eloy Espinaco)
+
Add contain_exactly as a less ambiguous version of match_array.
+Note that it expects the expected array to be splatted as
+individual args: expect(array).to contain_exactly(1, 2) is
+the same as expect(array).to match_array([1, 2]). (Myron Marston)
+
Update contain_exactly/match_array so that it can match against
+other non-array collections (such as a Set). (Myron Marston)
+
Update built-in matchers so that they can accept matchers as arguments
+to allow you to compose matchers in arbitrary ways. (Myron Marston)
+
Add RSpec::Matchers::Composable mixin that can be used to make
+a custom matcher composable as well. Note that custom matchers
+defined via RSpec::Matchers.define already have this. (Myron
+Marston)
+
Define noun-phrase aliases for built-in matchers, which can be
+used when creating composed matcher expressions that read better
+and provide better failure messages. (Myron Marston)
+
Add RSpec::Matchers.alias_matcher so users can define their own
+matcher aliases. The description of the matcher will reflect the
+alternate matcher name. (Myron Marston)
+
Add explicit be_between matcher. be_between has worked for a
+long time as a dynamic predicate matcher, but the failure message
+was suboptimal. The new matcher provides a much better failure
+message. (Erik Michaels-Ober)
+
Enhance the be_between matcher to allow for inclusive or exclusive
+comparison (e.g. inclusive of min/max or exclusive of min/max).
+(Pedro Gimenez)
+
Make failure message for not_to be #{operator} less confusing by
+only saying it's confusing when comparison operators are used.
+(Prathamesh Sonpatki)
+
Improve failure message of eq matcher when Time or DateTime
+objects are used so that the full sub-second precision is included.
+(Thomas Holmes, Jeff Wallace)
+
Add output matcher for expecting that a block outputs to_stdout
+or to_stderr. (Luca Pette, Matthias Günther)
+
Forward a provided block on to the has_xyz? method call when
+the have_xyz matcher is used. (Damian Galarza)
+
Provide integration with Minitest 5.x. Require
+rspec/expectations/minitest_integration after loading minitest
+to use rspec-expectations with minitest. (Myron Marston)
+
+
+
Bug Fixes:
+
+
+
Fix wrong matcher descriptions with falsey expected value (yujinakayama)
+
Fix expect { }.not_to change { }.from(x) so that the matcher only
+passes if the starting value is x. (Tyler Rick, Myron Marston)
+
Fix hash diffing, so that it colorizes properly and doesn't consider trailing
+commas when performing the diff. (Jared Norman)
+
Fix built-in matchers to fail normally rather than raising
+ArgumentError when given an object of the wrong type to match
+against, so that they work well in composite matcher expressions like
+expect([1.51, "foo"]).to include(a_string_matching(/foo/), a_value_within(0.1).of(1.5)).
+(Myron Marston)
+
+
+
Deprecations:
+
+
+
Retain support for RSpec 2 matcher protocol (e.g. for matchers
+in 3rd party extension gems like shoulda), but it will print
+a deprecation warning. (Myron Marston)
Remove the deprecated be_close matcher, preferring be_within instead.
+(Sam Phippen)
+
Remove the deprecated have, have_at_least and have_at_most matchers.
+You can continue using those matchers through https://github.com/rspec/rspec-collection_matchers,
+or you can rewrite your expectations with something like
+expect(your_object.size).to eq(num). (Hugo Baraúna)
+
Rename be_true and be_false to be_truthy and be_falsey. (Sam Phippen)
+
Make expect { }.to_not raise_error(SomeSpecificClass, message),
+ expect { }.to_not raise_error(SomeSpecificClass) and
+ expect { }.to_not raise_error(message) invalid, since they are prone
+to hiding failures. Instead, use expect { }.to_not raise_error (with no
+args). (Sam Phippen)
+
Within RSpec::Matchers.define blocks, helper methods made available
+either via def self.helper or extend HelperModule are no longer
+available to the match block (or any of the others). Instead
+include your helper module and define the helper method as an
+instance method. (Myron Marston)
+
Force upgrading Diff::LCS for encoding compatability with diffs. (Jon Rowe)
+
+
+
Enhancements:
+
+
+
Support do..end style block with raise_error matcher. (Yuji Nakayama)
+
Rewrote custom matcher DSL to simplify its implementation and solve a
+few issues. (Myron Marston)
+
Allow early return from within custom matcher DSL blocks. (Myron
+Marston)
+
The custom matcher DSL's chain can now accept a block. (Myron
+Marston)
+
Support setting an expectation on a raise_error matcher via a chained
+with_message method call. (Sam Phippen)
+
+
+
Bug Fixes:
+
+
+
Allow include and match matchers to be used from within a
+DSL-defined custom matcher's match block. (Myron Marston)
+
Correct encoding error message on diff failure (Jon Rowe)
+
+
+
Deprecations:
+
+
+
Using the old :should syntax without explicitly configuring it is deprecated.
+It will continue to work but will emit a deprecation warning in RSpec 3 if
+you do not explicitly enable it. (Sam Phippen)
Fix regression in Expectations#method_handle_for where proxy objects
+with method delegated would wrongly not return a method handle.
+(Jon Rowe, #594)
+
Fix issue with detection of generic operator matchers so they work
+correctly when undefined. (Myron Marston, #597)
Deprecate RSpec::Matchers::Configuration in favor of
+RSpec::Expectations::Configuration. (Myron Marston)
+
Deprecate be_xyz predicate matcher on an object that doesn't respond to
+xyz? or xyzs?. (Daniel Fone)
+
Deprecate have_xyz matcher on an object that doesn't respond to has_xyz?.
+(Daniel Fone)
+
Deprecate have_xyz matcher on an object that has a private method has_xyz?.
+(Jon Rowe)
+
Issue a deprecation warning when a block expectation expression is
+used with a matcher that doesn't explicitly support block expectations
+via supports_block_expectations?. (Myron Marston)
+
Deprecate require 'rspec-expectations'. Use
+require 'rspec/expectations' instead. (Myron Marston)
Deprecate chaining by, by_at_least, by_at_most or to off of
+expect { }.not_to change { }. The docs have always said these are
+not supported for the negative form but now they explicitly raise
+errors in RSpec 3. (Myron Marston)
+
Change the semantics of expect { }.not_to change { x }.from(y).
+In RSpec 2.x, this expectation would only fail if x started with
+the value of y and changed. If it started with a different value
+and changed, it would pass. In RSpec 3, it will pass only if the
+value starts at y and it does not change. (Myron Marston)
+
Deprecate matcher == value as an alias for matcher.matches?(value),
+in favor of matcher === value. (Myron Marston)
+
Deprecate RSpec::Matchers::OperatorMatcher in favor of
+RSpec::Matchers::BuiltIn::OperatorMatcher. (Myron Marston)
+
Deprecate auto-integration with Test::Unit and minitest.
+Instead, include RSpec::Matchers in the appropriate test case
+base class yourself. (Myron Marston)
+
Deprecate treating #expected on a DSL-generated custom matcher
+as an array when only 1 argument is passed to the matcher method.
+In RSpec 3 it will be the single value in order to make diffs
+work properly. (Jon Rowe)
Deprecate have, have_at_least and have_at_most. You can continue using those
+matchers through https://github.com/rspec/rspec-collection_matchers, or
+you can rewrite your expectations with something like
+expect(your_object.size).to eq(num). (Hugo Baraúna)
+
Deprecate be_xyz predicate matcher when xyz? is a private method.
+(Jon Rowe)
+
Deprecate be_true/be_false in favour of be_truthy/be_falsey
+(for Ruby's conditional semantics) or be true/be false
+(for exact equality). (Sam Phippen)
+
Deprecate calling helper methods from a custom matcher with the wrong
+scope. (Myron Marston)
+
+
+
def self.foo / extend Helper can be used to add macro methods
+(e.g. methods that call the custom matcher DSL methods), but should
+not be used to define helper methods called from within the DSL
+blocks.
+
def foo / include Helper is the opposite: it's for helper methods
+callable from within a DSL block, but not for defining macros.
+
RSpec 2.x allowed helper methods defined either way to be used for
+either purpose, but RSpec 3.0 will not.
Fix be_<predicate> matcher to not support operator chaining like the
+be matcher does (e.g. be == 5). This led to some odd behaviors
+since be_<predicate> == anything returned a BeComparedTo matcher
+and was thus always truthy. This was a consequence of the implementation
+(e.g. subclassing the basic Be matcher) and was not intended behavior.
+(Myron Marston).
+
Fix change matcher to compare using == in addition to ===. This
+is important for an expression like:
+expect {}.to change { a.class }.from(ClassA).to(ClassB) because
+SomeClass === SomeClass returns false. (Myron Marston)
Ensure diff output uses the same encoding as the encoding of
+the string being diff'd to prevent Encoding::UndefinedConversionError
+errors (Jon Rowe).
Enhance yield_control so that you can specify an exact or relative
+number of times: expect { }.to yield_control.exactly(3).times,
+expect { }.to yield_control.at_least(2).times, etc (Bartek
+Borkowski).
+
Make the differ that is used when an expectation fails better handle arrays
+by splitting each element of the array onto its own line. (Sam Phippen)
+
Accept duck-typed strings that respond to :to_str as expectation messages.
+(Toby Ovod-Everett)
+
+
+
Bug fixes
+
+
+
Fix differ to not raise errors when dealing with differently-encoded
+strings (Jon Rowe).
+
Fix expect(something).to be_within(x).percent_of(y) where x and y are both
+integers (Sam Phippen).
+
Fix have matcher to handle the fact that on ruby 2.0,
+Enumerator#size may return nil (Kenta Murata).
+
Fix expect { raise s }.to raise_error(s) where s is an error instance
+on ruby 2.0 (Sam Phippen).
+
Fix expect(object).to raise_error passing. This now warns the user and
+fails the spec (tomykaira).
+
+
+
Deprecations
+
+
+
Deprecate expect { }.not_to raise_error(SpecificErrorClass) or
+expect { }.not_to raise_error("some specific message"). Using
+these was prone to hiding failures as they would allow any other
+error to pass. (Sam Phippen and David Chelimsky)
Add support for percent deltas to be_within matcher:
+expect(value).to be_within(10).percent_of(expected)
+(Myron Marston).
+
Add support to include matcher to allow it to be given a list
+of matchers as the expecteds to match against (Luke Redpath).
+
+
+
Bug fixes
+
+
+
Fix change matcher so that it dups strings in order to handle
+mutated strings (Myron Marston).
+
Fix should be =~ /some regex/ / expect(...).to be =~ /some regex/.
+Previously, these either failed with a confusing undefined method
+matches?' for false:FalseClass error or were no-ops that didn't
+actually verify anything (Myron Marston).
+
Add compatibility for diff-lcs 1.2 and relax the version
+constraint (Peter Goldstein).
+
Fix DSL-generated matchers to allow multiple instances of the
+same matcher in the same example to have different description
+and failure messages based on the expected value (Myron Marston).
+
Prevent undefined method #split for Array error when dumping
+the diff of an array of multiline strings (Myron Marston).
+
Don't blow up when comparing strings that are in an encoding
+that is not ASCII compatible (Myron Marston).
+
Remove confusing "Check the implementation of #==" message
+printed for empty diffs (Myron Marston).
Improve the failure message for an expression like
+{}.should =~ {}. (Myron Marston and Andy Lindeman)
+
Provide a match_regex alias so that custom matchers
+built using the matcher DSL can use it (since match
+is a different method in that context).
+(Steven Harman)
Colorize diffs if the --color option is configured. (Alex Coplan)
+
Include backtraces in unexpected errors handled by raise_error
+matcher (Myron Marston)
+
Print a warning when users accidentally pass a non-string argument
+as an expectation message (Sam Phippen)
+
=~ and match_array matchers output a more useful error message when
+the actual value is not an array (or an object that responds to #to_ary)
+(Sam Phippen)
+
+
+
Bug fixes
+
+
+
Fix include matcher so that expect({}).to include(:a => nil)
+fails as it should (Sam Phippen).
+
Fix be_an_instance_of matcher so that Class#to_s is used in the
+description rather than Class#inspect, since some classes (like
+ActiveRecord::Base) define a long, verbose #inspect.
+(Tom Stuart)
Fix (and deprecate) expect { }.should syntax so that it works even
+though it was never a documented or intended syntax. It worked as a
+consequence of the implementation of expect in RSpec 2.10 and
+earlier. (Myron Marston)
+
Ensure #== is defined on built in matchers so that they can be composed.
+For example:
Define should and should_not on Object rather than BasicObject
+on MacRuby. On MacRuby, BasicObject is defined but is not the root
+of the object hierarchy. (Gabriel Gilder)
Allow only Numeric values to be the "actual" in the be_within matcher.
+This prevents confusing error messages. (Su Zhang @zhangsu)
+
Define should and should_not on BasicObject rather than Kernel
+on 1.9. This makes should and should_not work properly with
+BasicObject-subclassed proxy objects like Delegator. (Myron
+Marston)
Copyright (c) 2012 David Chelimsky, Myron Marston Copyright (c) 2006 David Chelimsky, The RSpec Development Team Copyright (c) 2005 Steven Baker
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-expectations/file.README.html b/source/documentation/3.1/rspec-expectations/file.README.html
new file mode 100644
index 000000000..662d94038
--- /dev/null
+++ b/source/documentation/3.1/rspec-expectations/file.README.html
@@ -0,0 +1,338 @@
+
+
+
+
+
+ File: README
+
+ — Documentation by YARD 0.8.7.4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
If you want to use rspec-expectations with rspec, just install the rspec gem
+and RubyGems will also install rspec-expectations for you (along with
+rspec-core and rspec-mocks):
+
+
geminstallrspec
+
+
+
If you want to use rspec-expectations with another tool, like Test::Unit,
+Minitest, or Cucumber, you can install it directly:
+
+
geminstallrspec-expectations
+
+
+
Basic usage
+
+
Here's an example using rspec-core:
+
+
RSpec.describeOrderdo
+ it"sums the prices of the items in its line items"do
+ order=Order.new
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(1.11,:USD)
+ )))
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(2.22,:USD),
+ :quantity=>2
+ )))
+ expect(order.total).toeq(Money.new(5.55,:USD))
+ end
+end
+
+
+
The describe and it methods come from rspec-core. The Order, LineItem, Item and Money classes would be from your code. The last line of the example
+expresses an expected outcome. If order.total == Money.new(5.55, :USD), then
+the example passes. If not, it fails with a message like:
Note: The new expect syntax no longer supports the =~ matcher.
+
+
Types/classes
+
+
expect(actual).tobe_an_instance_of(expected)# passes if actual.class == expected
+expect(actual).tobe_a(expected)# passes if actual.is_a?(expected)
+expect(actual).tobe_an(expected)# an alias for be_a
+expect(actual).tobe_a_kind_of(expected)# another alias
+
+
+
Truthiness
+
+
expect(actual).tobe_truthy# passes if actual is truthy (not nil or false)
+expect(actual).tobetrue# passes if actual == true
+expect(actual).tobe_falsy# passes if actual is falsy (nil or false)
+expect(actual).tobefalse# passes if actual == false
+expect(actual).tobe_nil# passes if actual is nil
+
expect{|b|5.tap(&b)}.toyield_control# passes regardless of yielded args
+
+expect{|b|yield_if_true(true,&b)}.toyield_with_no_args# passes only if no args are yielded
+
+expect{|b|5.tap(&b)}.toyield_with_args(5)
+expect{|b|5.tap(&b)}.toyield_with_args(Fixnum)
+expect{|b|"a string".tap(&b)}.toyield_with_args(/str/)
+
+expect{|b|[1,2,3].each(&b)}.toyield_successive_args(1,2,3)
+expect{|b|{:a=>1,:b=>2}.each(&b)}.toyield_successive_args([:a,1],[:b,2])
+
+
+
Predicate matchers
+
+
expect(actual).tobe_xxx# passes if actual.xxx?
+expect(actual).tohave_xxx(:arg)# passes if actual.has_xxx?(:arg)
+
+
+
Ranges (Ruby >= 1.9 only)
+
+
expect(1..10).tocover(3)
+
+
+
Collection membership
+
+
expect(actual).toinclude(expected)
+expect(actual).tostart_with(expected)
+expect(actual).toend_with(expected)
+
+expect(actual).tocontain_exactly(individual,items)
+# ...which is the same as:
+expect(actual).tomatch_array(expected_array)
+
Many of the built-in matchers are designed to take matchers as
+arguments, to allow you to flexibly specify only the essential
+aspects of an object or data structure. In addition, all of the
+built-in matchers have one or more aliases that provide better
+phrasing for when they are used as arguments to another matcher.
If you want to use rspec-expectations with rspec, just install the rspec gem
+and RubyGems will also install rspec-expectations for you (along with
+rspec-core and rspec-mocks):
+
+
geminstallrspec
+
+
+
If you want to use rspec-expectations with another tool, like Test::Unit,
+Minitest, or Cucumber, you can install it directly:
+
+
geminstallrspec-expectations
+
+
+
Basic usage
+
+
Here's an example using rspec-core:
+
+
RSpec.describeOrderdo
+ it"sums the prices of the items in its line items"do
+ order=Order.new
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(1.11,:USD)
+ )))
+ order.add_entry(LineItem.new(:item=>Item.new(
+ :price=>Money.new(2.22,:USD),
+ :quantity=>2
+ )))
+ expect(order.total).toeq(Money.new(5.55,:USD))
+ end
+end
+
+
+
The describe and it methods come from rspec-core. The Order, LineItem, Item and Money classes would be from your code. The last line of the example
+expresses an expected outcome. If order.total == Money.new(5.55, :USD), then
+the example passes. If not, it fails with a message like:
Note: The new expect syntax no longer supports the =~ matcher.
+
+
Types/classes
+
+
expect(actual).tobe_an_instance_of(expected)# passes if actual.class == expected
+expect(actual).tobe_a(expected)# passes if actual.is_a?(expected)
+expect(actual).tobe_an(expected)# an alias for be_a
+expect(actual).tobe_a_kind_of(expected)# another alias
+
+
+
Truthiness
+
+
expect(actual).tobe_truthy# passes if actual is truthy (not nil or false)
+expect(actual).tobetrue# passes if actual == true
+expect(actual).tobe_falsy# passes if actual is falsy (nil or false)
+expect(actual).tobefalse# passes if actual == false
+expect(actual).tobe_nil# passes if actual is nil
+
expect{|b|5.tap(&b)}.toyield_control# passes regardless of yielded args
+
+expect{|b|yield_if_true(true,&b)}.toyield_with_no_args# passes only if no args are yielded
+
+expect{|b|5.tap(&b)}.toyield_with_args(5)
+expect{|b|5.tap(&b)}.toyield_with_args(Fixnum)
+expect{|b|"a string".tap(&b)}.toyield_with_args(/str/)
+
+expect{|b|[1,2,3].each(&b)}.toyield_successive_args(1,2,3)
+expect{|b|{:a=>1,:b=>2}.each(&b)}.toyield_successive_args([:a,1],[:b,2])
+
+
+
Predicate matchers
+
+
expect(actual).tobe_xxx# passes if actual.xxx?
+expect(actual).tohave_xxx(:arg)# passes if actual.has_xxx?(:arg)
+
+
+
Ranges (Ruby >= 1.9 only)
+
+
expect(1..10).tocover(3)
+
+
+
Collection membership
+
+
expect(actual).toinclude(expected)
+expect(actual).tostart_with(expected)
+expect(actual).toend_with(expected)
+
+expect(actual).tocontain_exactly(individual,items)
+# ...which is the same as:
+expect(actual).tomatch_array(expected_array)
+
Many of the built-in matchers are designed to take matchers as
+arguments, to allow you to flexibly specify only the essential
+aspects of an object or data structure. In addition, all of the
+built-in matchers have one or more aliases that provide better
+phrasing for when they are used as arguments to another matcher.
The legacy :should syntax adds the following methods directly
+to BasicObject so that they are available off of any object.
+Note, however, that this syntax does not always play nice with
+delegate/proxy objects. We recommend you use the non-monkeypatching
+:expect syntax instead.
This is only available when you have enabled the should
+syntax.
+
+
+
+
+
Stubs a chain of methods.
+
+
Warning:
+
+
Chains can be arbitrarily long, which makes it quite painless to violate
+the Law of Demeter in violent ways, so you should consider any use of
+stub_chain a code smell. Even though not all code smells
+indicate real problems (think fluent interfaces), stub_chain
+still results in brittle examples. For example, if you write
+foo.stub_chain(:bar, :baz => 37) in a spec and then the
+implementation calls foo.baz.bar, the stub will not work.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+double.stub_chain("foo.bar"){:baz}
+double.stub_chain(:foo,:bar=>:baz)
+double.stub_chain(:foo,:bar){:baz}
+
+# Given any of ^^ these three forms ^^:
+double.foo.bar# => :baz
+
+# Common use in Rails/ActiveRecord:
+Article.stub_chain("recent.published"){[Article.new]}
This is only available when you have enabled the should
+syntax.
+
+
+
+
+
Removes a stub. On a double, the object will no longer respond to
+message. On a real object, the original method (if it exists)
+is restored.
+
+
This is rarely used, but can be useful when a stub is set up during a
+shared before hook for the common case, but you want to
+replace it for a special case.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/mocks/syntax.rb', line 243
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-mocks/Class.html b/source/documentation/3.1/rspec-mocks/Class.html
new file mode 100644
index 000000000..3e0063a64
--- /dev/null
+++ b/source/documentation/3.1/rspec-mocks/Class.html
@@ -0,0 +1,271 @@
+
+
+
+
+
+ Class: Class
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
The legacy :should syntax adds the any_instance
+to Class. We generally recommend you use the newer
+:expect syntax instead, which allows you to stub any instance
+of a class using allow_any_instance_of(klass) or mock any
+instance using expect_any_instance_of(klass).
Used to set stubs and message expectations on any instance of a given
+class.
+
+
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (Recorder) any_instance
+
+
+
+
+
+
+
+
+
+ Note:
+
+
This is only available when you have enabled the should
+syntax.
+
+
+
+
+
Used to set stubs and message expectations on any instance of a given
+class. Returns a Recorder, which records messages
+like stub and should_receive for later playback
+on instances of the class.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+Car.any_instance.should_receive(:go)
+race=Race.new
+race.cars<<Car.new
+race.go# assuming this delegates to all of its cars
+# this example would pass
+
+Account.any_instance.stub(:balance){Money.new(:USD,25)}
+Account.new.balance# => Money.new(:USD, 25))
Contains top-level utility methods. While this contains a few public
+methods, these are not generally meant to be called from a test or example.
+They exist primarily for integration with test frameworks (such as
+rspec-core).
Expect the message foo to receive bar, then call
+it
+
+
+
RSpec::Mocks.expect_message(bar,:foo)
+bar.foo
+
+
+
Parameters:
+
+
+
+
+ subject
+
+
+
+
+
+
+ —
+
+
the subject on which the message will be expected
+
+
+
+
+
+
+ message
+
+
+
+
+
+
+ —
+
+
a symbol, representing the message that will be expected.
+
+
+
+
+
+
+ opts
+
+
+
+
+
+ (defaults to: {})
+
+
+ —
+
+
a hash of options, :expected_from is used to set the original call site
+
+
+
+
+
+
+
Yields:
+
+
+
+
+
+
+
+
+
+
+
+
an optional implementation for the expectation
+
+
+
+
+
+
+
+
+
+
+
+
+84
+85
+86
+
+
+
# File 'lib/rspec/mocks.rb', line 84
+
+defself.expect_message(subject,message,opts={},&block)
+ space.proxy_for(subject).add_message_expectation(message,opts,&block)
+end
+
+
+
+
+
+
+
+
+ + (Object) setup
+
+
+
+
+
+
+
+
+
Performs per-test/example setup. This should be called before an test or
+example begins.
+
+
+
+
+
+
+
+
+
+
+
+
+
+38
+39
+40
+
+
+
# File 'lib/rspec/mocks.rb', line 38
+
+defself.setup
+ @space_stack<<(@space=space.new_scope)
+end
+
+
+
+
+
+
+
+
+ + (Object) teardown
+
+
+
+
+
+
+
+
+
Cleans up all test double state (including any methods that were redefined
+on partial doubles). This must be called after each example, even
+if an error was raised during the example.
Can also be used directly to match the contents of any Array.
+This enables 3rd party mocking libs to take advantage of rspec's
+argument matching without using the rest of rspec-mocks.
When this is set to true, an error will be raised when
+instance_double or class_double is given the name
+of an undefined constant. You probably only want to set this when running
+your entire test suite, with all production code loaded. Setting this for
+an isolated unit test will prevent you from being able to isolate it!
+
+
+
+
+
+
+
+
+
+
+
+
+
+105
+106
+107
+
+
+
# File 'lib/rspec/mocks/configuration.rb', line 105
+
+defverify_doubled_constant_names=(value)
+ @verify_doubled_constant_names=value
+end
Sets whether or not RSpec will yield the receiving instance of a message to
+blocks that are used for any_instance stub implementations. When set, the
+first yielded argument will be the receiving instance. Defaults to
+true.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|rspec|
+ rspec.mock_with:rspecdo|mocks|
+ mocks.yield_receiver_to_any_instance_implementation_blocks=false
+ end
+end
+
+
+
+
+
+
+
+
+
+
+28
+29
+30
+
+
+
# File 'lib/rspec/mocks/configuration.rb', line 28
+
+defyield_receiver_to_any_instance_implementation_blocks=(value)
+ @yield_receiver_to_any_instance_implementation_blocks=value
+end
Adds stub and should_receive to the given modules
+or classes. This is usually only necessary if you application uses some
+proxy classes that “strip themselves down” to a bare minimum set of methods
+and remove stub and should_receive in the
+process.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configuredo|rspec|
+ rspec.mock_with:rspecdo|mocks|
+ mocks.add_stub_and_should_receive_toDelegator
+ end
+end
+
+
+
+
+
+
+
+
+
+
+45
+46
+47
+48
+49
+
+
+
# File 'lib/rspec/mocks/configuration.rb', line 45
+
+defadd_stub_and_should_receive_to(*modules)
+ modules.eachdo|mod|
+ Syntax.enable_should(mod)
+ end
+end
Monkey-patch Marshal.dump to enable dumping of mocked or
+stubbed objects. By default this will not work since RSpec mocks works by
+adding singleton methods that cannot be serialized. This patch removes
+these singleton methods before serialization. Setting to falsey removes the
+patch.
+
+
This method is idempotent.
+
+
+
+
+
+
+
+
+
+
+
+
+
+133
+134
+135
+136
+137
+138
+139
+
+
+
# File 'lib/rspec/mocks/configuration.rb', line 133
+
+defpatch_marshal_to_support_partial_doubles=(val)
+ ifval
+ RSpec::Mocks::MarshalExtension.patch!
+ else
+ RSpec::Mocks::MarshalExtension.unpatch!
+ end
+end
Provides the ability to set either expect, should
+or both syntaxes. RSpec uses expect syntax by default. This is
+needed if you want to explicitly enable should syntax and/or
+explicitly disable expect syntax.
+
+
end
+
+
+
+
+
+
+
+
Examples:
+
+
+
+RSpec.configure do |rspec|
+ rspec.mock_with :rspec do |mocks|
+ mocks.syntax = [:expect, :should]
+ end
When set to true, partial mocks will be verified the same as object
+doubles. Any stubs will have their arguments checked against the original
+method, and methods that do not exist cannot be stubbed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+118
+119
+120
+
+
+
# File 'lib/rspec/mocks/configuration.rb', line 118
+
+defverify_partial_doubles=(val)
+ @verify_partial_doubles=!!val
+end
Used internally by the constant stubbing to raise a helpful error when a
+constant like “A::B::C” is stubbed and A::B is not a module (and thus,
+it's impossible to define “A::B::C” since only modules can have nested
+constants).
It's recommended that you use hide_const in your examples.
+This is an alternate public API that is provided so you can hide constants
+in other contexts (e.g. helper classes).
+
+
+
+
+
Hides a constant.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ constant_name
+
+
+ (String)
+
+
+
+ —
+
+
The fully qualified name of the constant. The current constant scoping at
+the point of call is not considered.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
Used internally by the constant stubbing to raise a helpful error when a
+constant like “A::B::C” is stubbed and A::B is not a module (and thus,
+it's impossible to define “A::B::C” since only modules can have nested
+constants).
+
+
+
+
+
+
+
+
+
+
+
+
+
+316
+317
+318
+319
+320
+321
+
+
+
# File 'lib/rspec/mocks/mutate_const.rb', line 316
+
+defself.raise_on_invalid_const
+ lambdado|const_name,failed_name|
+ raise"Cannot stub constant #{failed_name} on #{const_name}" \
+ "since #{const_name} is not a module."
+ end
+end
It's recommended that you use stub_const in your examples.
+This is an alternate public API that is provided so you can stub constants
+in other contexts (e.g. helper classes).
+
+
+
+
+
Stubs a constant.
+
+
+
+
+
+
Parameters:
+
+
+
+
+ constant_name
+
+
+ (String)
+
+
+
+ —
+
+
The fully qualified name of the constant. The current constant scoping at
+the point of call is not considered.
+
+
+
+
+
+
+ value
+
+
+ (Object)
+
+
+
+ —
+
+
The value to make the constant refer to. When the example completes, the
+constant will be restored to its prior state.
Determines what nested constants, if any, will be transferred from the
+original value of the constant to the new value of the constant. This only
+works if both the original and new values are modules (or classes).
Contains methods intended to be used from within code examples. Mix this in
+to your test context (such as a test framework base class) to use
+rspec-mocks with your test framework. If you're using rspec-core,
+it'll take care of doing this for you.
Constructs an instance of :Mocks::Double
+configured with an optional name, used for reporting in failure messages,
+and an optional hash of message/return-value pairs.
Constructs a test double against a specific class. If the given class name
+has been loaded, only class methods defined on the class are allowed to be
+stubbed. In all other ways it behaves like a double.
Constructs a test double that is optimized for use with
+have_received against a specific class. If the given class
+name has been loaded, only class methods defined on the class are allowed
+to be stubbed. With a normal double one has to stub methods in order to be
+able to spy them. An class_spy automatically spies on all class methods to
+which the class responds.
+
+
+
+
+
+
+
Overloads:
+
+
+
+
+ - (Object) class_spy(doubled_class)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ doubled_class
+
+
+ (String, Module)
+
+
+
+
+
+
+
+
+
+
+
+
+
+ - (Object) class_spy(doubled_class, stubs)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ doubled_class
+
+
+ (String, Module)
+
+
+
+
+
+
+
+ stubs
+
+
+ (Hash)
+
+
+
+ —
+
+
hash of message/return-value pairs
+
+
+
+
+
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+
+
+
+
+
+
+
ClassVerifyingDouble
+
+
+
+
+
+
+
+
+
+
+
+
+150
+151
+152
+
+
+
# File 'lib/rspec/mocks/example_methods.rb', line 150
+
+defclass_spy(*args)
+ class_double(*args).as_null_object
+end
Constructs an instance of :Mocks::Double
+configured with an optional name, used for reporting in failure messages,
+and an optional hash of message/return-value pairs.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+book=double("book",:title=>"The RSpec Book")
+book.title#=> "The RSpec Book"
+
+card=double("card",:suit=>"Spades",:rank=>"A")
+card.suit#=> "Spades"
+card.rank#=> "A"
# File 'lib/rspec/mocks/example_methods.rb', line 35
+
+defdouble(*args)
+ ExampleMethods.declare_double(Double,*args)
+end
+
+
+
+
+
+
+
+
+ - (Object) expect
+
+
+
+
+
+
+
+
+
+ Note:
+
+
This method is usually provided by rspec-expectations. However, if you use
+rspec-mocks without rspec-expectations, there's a definition of it that
+is made available here. If you disable the :expect syntax this
+method will be undefined.
+
+
+
+
+
Used to wrap an object in preparation for setting a mock expectation on it.
Verifies that the given object received the expected message during the
+course of the test. On a spy objects or as null object doubles this works
+for any method, on other objects the method must have been stubbed
+beforehand in order for messages to be verified.
+
+
Stubbing and verifying messages received in this way implements the Test
+Spy pattern.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+invitation=double('invitation',accept:true)
+user.accept_invitation(invitation)
+expect(invitation).tohave_received(:accept)
+
+# You can also use most message expectations:
+expect(invitation).tohave_received(:accept).with(mailer).once
+
+
+
Parameters:
+
+
+
+
+ method_name
+
+
+ (Symbol)
+
+
+
+ —
+
+
name of the method expected to have been called.
+
+
+
+
+
+
+
+
+
+
+
+
+
+239
+240
+241
+
+
+
# File 'lib/rspec/mocks/example_methods.rb', line 239
+
+defhave_received(method_name,&block)
+ Matchers::HaveReceived.new(method_name,&block)
+end
Constructs a test double against a specific class. If the given class name
+has been loaded, only instance methods defined on the class are allowed to
+be stubbed. In all other ways it behaves like a double.
Constructs a test double that is optimized for use with
+have_received against a specific class. If the given class
+name has been loaded, only instance methods defined on the class are
+allowed to be stubbed. With a normal double one has to stub methods in
+order to be able to spy them. An instance_spy automatically spies on all
+instance methods to which the class responds.
Constructs a test double against a specific object. Only the methods the
+object responds to are allowed to be stubbed. If a String argument is
+provided, it is assumed to reference a constant object which is used for
+verification. In all other ways it behaves like a double.
Constructs a test double that is optimized for use with
+have_received against a specific object. Only instance methods
+defined on the object are allowed to be stubbed. With a normal double one
+has to stub methods in order to be able to spy them. An object_spy
+automatically spies on all methods to which the object responds.
+
+
+
+
+
+
+
Overloads:
+
+
+
+
+ - (Object) object_spy(object_or_name)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ object_or_name
+
+
+ (String, Object)
+
+
+
+
+
+
+
+
+
+
+
+
+
+ - (Object) object_spy(object_or_name, stubs)
+
+
+
+
+
+
+
+
Parameters:
+
+
+
+
+ object_or_name
+
+
+ (String, Object)
+
+
+
+
+
+
+
+ stubs
+
+
+ (Hash)
+
+
+
+ —
+
+
hash of message/return-value pairs
+
+
+
+
+
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+
+
+
+
+
+
+
ObjectVerifyingDouble
+
+
+
+
+
+
+
+
+
+
+
+
+133
+134
+135
+
+
+
# File 'lib/rspec/mocks/example_methods.rb', line 133
+
+defobject_spy(*args)
+ object_double(*args).as_null_object
+end
+
+
+
+
+
+
+
+
+ - (Object) receive
+
+
+
+
+
+
+
+
+
+ Note:
+
+
If you disable the :expect syntax this method will be
+undefined.
+
+
+
+
+
Used to specify a message that you expect or allow an object to receive.
+The object returned by receive supports the same fluent
+interface that should_receive and stub have
+always supported, allowing you to constrain the arguments or number of
+times, and configure how the object should respond to the message.
If you disable the :expect syntax this method will be
+undefined.
+
+
+
+
+
stubs/mocks a chain of messages on an object or test double.
+
+
Warning:
+
+
Chains can be arbitrarily long, which makes it quite painless to violate
+the Law of Demeter in violent ways, so you should consider any use of
+receive_message_chain a code smell. Even though not all code
+smells indicate real problems (think fluent interfaces),
+receive_message_chain still results in brittle examples. For
+example, if you write allow(foo).to receive_message_chain(:bar, :baz
+=> 37) in a spec and then the implementation calls
+foo.baz.bar, the stub will not work.
+
+
+
+
+
+
+
+
Examples:
+
+
+
+allow(double).toreceive_message_chain("foo.bar"){:baz}
+allow(double).toreceive_message_chain(:foo,:bar=>:baz)
+allow(double).toreceive_message_chain(:foo,:bar){:baz}
+
+# Given any of ^^ these three forms ^^:
+double.foo.bar# => :baz
+
+# Common use in Rails/ActiveRecord:
+allow(Article).toreceive_message_chain("recent.published"){[Article.new]}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/mocks/example_methods.rb', line 313
+
+
+
+
+
+
+
+
+
+
+ - (Object) receive_messages
+
+
+
+
+
+
+
+
+
+ Note:
+
+
If you disable the :expect syntax this method will be
+undefined.
+
+
+
+
+
Shorthand syntax used to setup message(s), and their return value(s), that
+you expect or allow an object to receive. The method takes a hash of
+messages and their respective return values. Unlike with
+receive, you cannot apply further customizations using a block
+or the fluent interface.
Constructs a test double that is optimized for use with
+have_received. With a normal double one has to stub methods in
+order to be able to spy them. A spy automatically spies on all methods.
Stubs the named constant with the given value. Like method stubs, the
+constant will be restored to its original value (or lack of one, if it was
+undefined) when the example completes.
Determines what nested constants, if any, will be transferred from the
+original value of the constant to the new value of the constant. This only
+works if both the original and new values are modules (or classes).
+
+
+
+
+
+
+
+
Returns:
+
+
+
+
+
+ (Object)
+
+
+
+ —
+
+
the stubbed value of the constant
+
+
+
+
+
+
+
+
+
+
+
+
+200
+201
+202
+
+
+
# File 'lib/rspec/mocks/example_methods.rb', line 200
+
+defstub_const(constant_name,value,options={})
+ ConstantMutator.stub(constant_name,value,options)
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-mocks/RSpec/Mocks/ExampleMethods/ExpectHost.html b/source/documentation/3.1/rspec-mocks/RSpec/Mocks/ExampleMethods/ExpectHost.html
new file mode 100644
index 000000000..fa1da83b7
--- /dev/null
+++ b/source/documentation/3.1/rspec-mocks/RSpec/Mocks/ExampleMethods/ExpectHost.html
@@ -0,0 +1,117 @@
+
+
+
+
+
+ Module: RSpec::Mocks::ExampleMethods::ExpectHost
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
# File 'lib/rspec/mocks/syntax.rb', line 181
+
+defself.default_should_syntax_host
+ # JRuby 1.7.4 introduces a regression whereby `defined?(::BasicObject) => nil`
+# yet `BasicObject` still exists and patching onto ::Object breaks things
+# e.g. SimpleDelegator expectations won't work
+#
+# See: https://github.com/jruby/jruby/issues/814
+ifdefined?(JRUBY_VERSION)&&JRUBY_VERSION=='1.7.4'&&RUBY_VERSION.to_f>1.8
+ return::BasicObject
+ end
+
+ # On 1.8.7, Object.ancestors.last == Kernel but
+# things blow up if we include `RSpec::Mocks::Methods`
+# into Kernel...not sure why.
+returnObjectunlessdefined?(::BasicObject)
+
+ # MacRuby has BasicObject but it's not the root class.
+returnObjectunlessObject.ancestors.last==::BasicObject
+
+ ::BasicObject
+end
Implements the methods needed for a pure test double. RSpec::Mocks::Double
+includes this module, and it is provided for cases where you want a pure
+test double without subclassing RSpec::Mocks::Double.
# File 'lib/rspec/mocks/test_double.rb', line 73
+
+defmethod_missing(message,*args,&block)
+ proxy=__mock_proxy
+ proxy.record_message_received(message,*args,&block)
+
+ ifproxy.null_object?
+ casemessage
+ when:to_intthenreturn0
+ when:to_a,:to_arythenreturnnil
+ when:to_strthenreturnto_s
+ elsereturnself
+ end
+ end
+
+ # Defined private and protected methods will still trigger `method_missing`
+# when called publicly. We want ruby's method visibility error to get raised,
+# so we simply delegate to `super` in that case.
+# ...well, we would delegate to `super`, but there's a JRuby
+# bug, so we raise our own visibility error instead:
+# https://github.com/jruby/jruby/issues/1398
+visibility=proxy.visibility_for(message)
+ ifvisibility==:private||visibility==:protected
+ ErrorGenerator.new(self,@name).raise_non_public_error(
+ message,visibility
+ )
+ end
+
+ # Required wrapping doubles in an Array on Ruby 1.9.2
+raiseNoMethodErrorif[:to_a,:to_ary].include?message
+ proxy.raise_unexpected_message_error(message,*args)
+end
+
+
+
+
+
+
+
+
+
+
Instance Method Details
+
+
+
+
+
+ - (Object) ==(other)
+
+
+
+
+
+
+
+
+
This allows for comparing the mock to other objects that proxy such as
+ActiveRecords belongs_to proxy objects. By making the other object run the
+comparison, we're sure the call gets delegated to the proxy target.
+
+
+
+
+
+
+
+
+
+
+
+
+
+36
+37
+38
+
+
+
# File 'lib/rspec/mocks/test_double.rb', line 36
+
+def==(other)
+ other==__mock_proxy
+end
+
+
+
+
+
+
+
+
+ - (Object) as_null_object
+
+
+
+
+
+
+
+
+
Tells the object to respond to all messages. If specific stub values are
+declared, they'll work as expected. If not, the receiver is returned.
+
+
+
+
+
+
+
+
+
+
+
+
+
+23
+24
+25
+
+
+
# File 'lib/rspec/mocks/test_double.rb', line 23
+
+defas_null_object
+ __mock_proxy.as_null_object
+end
+
+
+
+
+
+
+
+
+ - (Object) freeze
+
+
+
+
+
+
+
+
+
Override for default freeze implementation to prevent freezing of test
+doubles.
+
+
+
+
+
+
+
+
+
+
+
+
+
+67
+68
+69
+
+
+
# File 'lib/rspec/mocks/test_double.rb', line 67
+
+deffreeze
+ RSpec.warn_with("WARNING: you attempted to freeze a test double. This is explicitly a no-op as freezing doubles can lead to undesired behaviour when resetting tests.")
+end
+ This class is part of a private API.
+ You should avoid using this class if possible, as it may be removed or be changed in the future.
+
+
+
A message expectation that knows about the real implementation of the
+message being expected, so that it can verify that any expectations have
+the valid arguments.
A level of indirection is used here rather than just passing in the method
+itself, since method look up is expensive and we only want to do it if
+actually needed.
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
Returns a new instance of VerifyingMessageExpectation
+
+
+
+
+
+
+
+
+
+
+
+
+
+20
+21
+22
+
+
+
# File 'lib/rspec/mocks/verifying_message_expecation.rb', line 20
+
+definitialize(*args)
+ super
+end
+
+
+
+
+
+
+
+
+
Instance Attribute Details
+
+
+
+
+
+
+ - (Object) method_reference
+
+
+
+
+
+
+
+
+ This method is part of a private API.
+ You should avoid using this method if possible, as it may be removed or be changed in the future.
+
+
+
A level of indirection is used here rather than just passing in the method
+itself, since method look up is expensive and we only want to do it if
+actually needed.
+
+
Conceptually the method reference makes more sense as a constructor
+argument since it should be immutable, but it is significantly more
+straight forward to build the object in pieces so for now it stays as an
+accessor.
+
+
+
+
+
+
+
+
+
+
+
+
+
+18
+19
+20
+
+
+
# File 'lib/rspec/mocks/verifying_message_expecation.rb', line 18
+
+defmethod_reference
+ @method_reference
+end
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-mocks/RSpec/Mocks/Version.html b/source/documentation/3.1/rspec-mocks/RSpec/Mocks/Version.html
new file mode 100644
index 000000000..8d508a8c3
--- /dev/null
+++ b/source/documentation/3.1/rspec-mocks/RSpec/Mocks/Version.html
@@ -0,0 +1,139 @@
+
+
+
+
+
+ Module: RSpec::Mocks::Version
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Correct received messages count when used with have_received
+matcher. (Jon Rowe, #793)
+
+
Provide a clear error message when you use
+allow_any_instance_of(...) or
+expect_any_instance_of(...) with the
+have_received matcher (they are not intended to be used
+together and previously caused an odd internal failure in rspec-mocks).
+(Jon Rowe, #799).
+
+
Fix verified double with verification so that it applies to
+method stubs. (Myron Marston, #790)
Provide a clear error message when you use allow(...) with the
+have_received matcher (they are not intended to be used
+together and previously caused an odd internal failure in rspec-mocks).
+(Jon Rowe, #788).
Add spying methods (spy, ìnstance_spy,
+class_spy and object_spy) which create doubles
+as null objects for use with spying in testing. (Sam Phippen, #671)
+
+
have_received matcher will raise “does not implement” errors
+correctly when used with verifying doubles and partial doubles. (Xavier
+Shay, #722)
+
+
Allow matchers to be used in place of keyword arguments in
+with expectations. (Xavier Shay, #726)
+
+
Add thrice modifier to message expectation interface as a
+synonym for exactly(3).times. (Dennis Taylor, #753)
+
+
Add more thrice synonyms e.g. .at_least(:thrice),
+.at_most(:thrice), receive(...).thrice and
+have_received(...).thrice. (Jon Rowe, #754)
+
+
Add and_wrap_original modifier for partial doubles to mutate
+the response from a method. (Jon Rowe, #762)
+
+
+
Bugfixes:
+
+
Remove any_number_of_times from any_instance
+recorders that were erroneously causing mention of the method in
+documentation. (Jon Rowe, #760)
+
+
Prevent included modules being detected as prepended modules on Ruby 2.0.
+(Eugene Kenny, #771)
Fix edge case that triggered “can't add a new key into hash during
+iteration” during mock verification. (Sam Phippen, Myron Marston, #711)
+
+
Fix verifying doubles so that when they accidentally leak into another
+example, they provide the same clear error message that normal doubles do.
+(Myron Marston, #718)
+
+
Make ordered work with exact receive counts. (Sam Phippen,
+#713)
Fix module prepend detection to work properly on ruby 2.0 for a case where
+a module is extended onto itself. (Myron Marston)
+
+
Fix transfer_nested_constants option so that transferred
+constants get properly reset at the end of the example. (Myron Marston)
+
+
Fix config.transfer_nested_constants = true so that you
+don't erroneously get errors when stubbing a constant that is not a
+module or a class. (Myron Marston)
+
+
Fix regression that caused double(:class => SomeClass) to
+later trigger infinite recursion. (Myron Marston)
+
+
Fix bug in have_received(...).with(...).ordered where it was
+not taking the args into account when checking the order. (Myron Marston)
+
+
Fix bug in have_received(...).ordered where it was wrongly
+considering stubs when checking the order. (Myron Marston)
+
+
Message expectation matchers now show descriptions from argument matchers
+when their expectations aren't met. (Jon Rowe)
+
+
Display warning when encountering TypeError during instance
+method staging on 2.0.0-p195, suffers from bugs.ruby-lang.org/issues/8686
+too. (Cezar Halmagean).
Make monkey-patch of Marshal to support dumping of stubbed objects opt-in.
+(Xavier Shay)
+
+
+
Enhancements:
+
+
Instead of crashing when cleaning up stub methods on a frozen object, it
+now issues a warning explaining that it's impossible to clean up the
+stubs. (Justin Coyne and Sam Phippen)
+
+
Add meaningful descriptions to anything,
+duck_type and instance_of argument matchers.
+(Jon Rowe)
+
+
+
Bug Fixes:
+
+
Fix regression introduced in 3.0.0.beta2 that caused
+double.as_null_object.to_str to return the double rather than
+a string. (Myron Marston)
+
+
Fix bug in expect(dbl).to receive_message_chain(:foo, :bar)
+where it was not setting an expectation for the last message in the chain.
+(Jonathan del Strother)
+
+
Allow verifying partial doubles to have private methods stubbed. (Xavier
+Shay)
+
+
Fix bug with allowing/expecting messages on Class objects which have had
+their singleton class prepended to. (Jon Rowe)
+
+
Fix an issue with 1.8.7 not running implementation blocks on partial
+doubles. (Maurício Linhares)
+
+
Prevent StackLevelTooDeep errors when stubbing an
+any_instance method that's accessed in
+inspect by providing our own inspect output. (Jon Rowe)
+
+
Fix bug in any_instance logic that did not allow you to mock
+or stub private methods if verify_partial_doubles was
+configured. (Oren Dobzinski)
+
+
Include useful error message when trying to observe an unimplemented method
+on an any instance. (Xavier Shay)
+
+
Fix and_call_original to work properly when multiple classes
+in an inheritance hierarchy have been stubbed with the same method. (Myron
+Marston)
+
+
Fix any_instance so that it updates existing instances that
+have already been stubbed. (Myron Marston)
+
+
Fix verified doubles so that their class name is included in failure
+messages. (Myron Marston)
+
+
Fix expect_any_instance_of so that when the message is
+received on an individual instance that has been directly stubbed, it
+still satisfies the expectation. (Sam Phippen, Myron Marston)
+
+
Explicitly disallow using any_instance to mock or stub a
+method that is defined on a module prepended onto the class. This
+triggered SystemStackError before and is very hard to support
+so we are not supporting it at this time. (Myron Marston)
Rename RSpec::Mocks::Mock to
+RSpec::Mocks::Double. (Myron Marston)
+
+
Change how to integrate rspec-mocks in other test frameworks. You now need
+to include RSpec::Mocks::ExampleMethods in your test context.
+(Myron Marston)
+
+
Prevent RSpec mocks' doubles and partial doubles from being used
+outside of the per-test lifecycle (e.g. from a before(:all)
+hook). (Sam Phippen)
+
+
Remove the host argument of RSpec::Mocks.setup.
+Instead RSpec::Mocks::ExampleMethods should be included
+directly in the scope where RSpec's mocking capabilities are used.
+(Sam Phippen)
+
+
Make test doubles raise errors if you attempt to use them after they get
+reset, to help surface issues when you accidentally retain references to
+test doubles and attempt to reuse them in another example. (Myron Marston)
+
+
Remove support for and_return { value } and
+and_return without arguments. (Yuji Nakayama)
+
+
+
Enhancements:
+
+
Add receive_message_chain which provides the functionality of
+the old stub_chain for the new allow/expect syntax. Use it
+like so: allow(...).to receive_message_chain(:foo, :bar,
+:bazz). (Sam Phippen).
+
+
Change argument matchers to use === as their primary matching
+protocol, since their semantics mirror that of a case or rescue statement
+(which uses === for matching). (Myron Marston)
+
+
Add RSpec::Mocks.with_temporary_scope, which allows you to
+create temporary rspec-mocks scopes in arbitrary places (such as a
+before(:all) hook). (Myron Marston)
+
+
Support keyword arguments when checking arity with verifying doubles.
+(Xavier Shay)
+
+
+
Bug Fixes:
+
+
Fix regression in 3.0.0.beta1 that caused
+double("string_name" => :value) to stop working.
+(Xavier Shay)
+
+
Fix the way rspec-mocks and rspec-core interact so that if users define a
+let with the same name as one of the methods from
+RSpec::Mocks::ArgumentMatchers, the user's
+let takes precedence. (Michi Huber, Myron Marston)
+
+
Fix verified doubles so that their methods match the visibility (public,
+protected or private) of the interface they verify against. (Myron
+Marston)
+
+
Fix verified null object doubles so that they do not wrongly report that
+they respond to anything. They only respond to methods available on the
+interface they verify against. (Myron Marston)
+
+
Fix deprecation warning for use of old :should syntax w/o
+explicit config so that it no longer is silenced by an extension gem such
+as rspec-rails when it calls
+config.add_stub_and_should_receive_to. (Sam Phippen)
+
+
Fix expect syntax so that it does not wrongly emit a
+“You're overriding a previous implementation for this stub” warning
+when you are not actually doing that. (Myron Marston)
+
+
Fix any_instance.unstub when used on sub classes for whom the
+super class has had any_instance.stub invoked on. (Jon Rowe)
+
+
Fix regression in
+stub_chain/receive_message_chain that caused it
+to raise an ArgumentError when passing args to the stubbed
+methods. (Sam Phippen)
+
+
Correct stub of undefined parent modules all the way down when stubbing a
+nested constant. (Xavier Shay)
+
+
Raise VerifyingDoubleNotDefinedError when a constant is not
+defined for a verifying class double. (Maurício Linhares)
+
+
Remove Double#to_str, which caused confusing raise
+some_double behavior. (Maurício Linhares)
Raise an explicit error if should_not_receive(...).and_return
+is used. (Sam Phippen)
+
+
Remove 1.8.6 workarounds. (Jon Rowe)
+
+
Remove stub! and unstub!. (Sam Phippen)
+
+
Remove mock(name, methods) and stub(name,
+methods), leaving double(name, methods) for creating
+test doubles. (Sam Phippen, Michi Huber)
+
+
Remove any_number_of_times since
+should_receive(:msg).any_number_of_times is really a stub in
+a mock's clothing. (Sam Phippen)
+
+
Remove support for re-using the same null-object test double in multiple
+examples. Test doubles are designed to only live for one example. (Myron
+Marston)
+
+
Make at_least(0) raise an error. (Sam Phippen)
+
+
Remove support for require 'spec/mocks' which had been
+kept in place for backwards compatibility with RSpec 1. (Myron Marston)
+
+
Blocks provided to with are always used as implementation.
+(Xavier Shay)
+
+
The config option (added in 2.99) to yield the receiver to
+any_instance implementation blocks now defaults to “on”. (Sam
+Phippen)
+
+
+
Enhancements:
+
+
Allow the have_received matcher to use a block to set further
+expectations on arguments. (Tim Cowlishaw)
+
+
Provide instance_double and class_double to
+create verifying doubles, ported from rspec-fire. (Xavier
+Shay)
+
+
as_null_object on a verifying double only responds to defined
+methods. (Xavier Shay)
+
+
Provide object_double to create verified doubles of specific
+object instances. (Xavier Shay)
+
+
Provide verify_partial_doubles configuration that provides
+object_double like verification behaviour on partial doubles.
+(Xavier Shay)
+
+
Improved performance of double creation, particularly those with many
+attributes. (Xavier Shay)
+
+
Default value of transfer_nested_constants option for constant
+stubbing can be configured. (Xavier Shay)
+
+
Messages can be allowed or expected on in bulk via
+receive_messages(:message => :value). (Jon Rowe)
+
+
allow(Klass.any_instance) and
+expect(Klass.any_instance) now print a warning. This is
+usually a mistake, and users usually want
+allow_any_instance_of or expect_any_instance_of
+instead. (Sam Phippen)
+
+
instance_double and class_double raise
+ArgumentError if the underlying module is loaded and the
+arity of the method being invoked does not match the arity of the method
+as it is actually implemented. (Andy Lindeman)
+
+
Spies can now check their invocation ordering is correct. (Jon Rowe)
+
+
+
Deprecations:
+
+
Using the old :should syntax without explicitly configuring it
+is deprecated. It will continue to work but will emit a deprecation
+warning in RSpec 3 if you do not explicitly enable it. (Sam Phippen)
+
+
+
Bug Fixes:
+
+
Fix and_call_original to handle a complex edge case involving
+singleton class ancestors. (Marc-André Lafortune, Myron Marston)
+
+
When generating an error message for unexpected arguments, use
+#inspect rather than #description if
+#description returns nil or
+'' so that you still get a useful message. (Nick
+DeLuca)
Deprecate RSpec::Mocks::Mock in favor of
+RSpec::Mocks::Double. (Myron Marston)
+
+
Deprecate the host argument of
+RSpec::Mocks.setup. Instead
+RSpec::Mocks::ExampleMethods should be included directly in
+the scope where RSpec's mocking capabilities are used. (Sam Phippen)
+
+
Deprecate using any of rspec-mocks' features outside the per-test
+lifecycle (e.g. from a before(:all) hook). (Myron Marston)
+
+
Deprecate re-using a test double in another example. (Myron Marston)
+
+
Deprecate and_return { value } and and_return
+without arguments. (Yuji Nakayama)
Expecting to use lambdas or other strong arity implementations for stub
+methods with mis-matched arity is deprecated and support for them will be
+removed in 3.0. Either provide the right amount of arguments or use a weak
+arity implementation (methods with splats or procs). (Jon Rowe)
+
+
Using the same test double instance in multiple examples is deprecated.
+Test doubles are only meant to live for one example. The mocks and stubs
+have always been reset between examples; however, in 2.x the
+as_null_object state was not reset and some users relied on
+this to have a null object double that is used for many examples. This
+behavior will be removed in 3.0. (Myron Marston)
+
+
Print a detailed warning when an any_instance implementation
+block is used when the new
+yield_receiver_to_any_instance_implementation_blocks config
+option is not explicitly set, as RSpec 3.0 will default to enabling this
+new feature. (Sam Phippen)
+
+
+
Enhancements:
+
+
Add a config option to yield the receiver to any_instance
+implementation blocks. (Sam Phippen)
Fix regression that caused block implementations to not receive all args
+on 1.8.7 if the block also receives a block, due to Proc#arity reporting
+1 no matter how many args the block receives if it receives a
+block, too. (Myron Marston)
Restore double.as_null_object behavior from 2.13 and earlier:
+a double's nullness persisted between examples in earlier examples.
+While this is not an intended use case (test doubles are meant to live for
+only one example), we don't want to break behavior users rely on in a
+minor relase. This will be deprecated in 2.99 and removed in 3.0. (Myron
+Marston)
Document test spies in the readme. (Adarsh Pandit)
+
+
Add an array_including matcher. (Sam Phippen)
+
+
Add a syntax-agnostic API for mocking or stubbing a method. This is
+intended for use by libraries such as rspec-rails that need to mock or
+stub a method, and work regardless of the syntax the user has configured
+(Paul Annesley, Myron Marston and Sam Phippen).
+
+
+
Bug Fixes:
+
+
Fix double so that it sets up passed stubs correctly
+regardless of the configured syntax (Paul Annesley).
+
+
Allow a block implementation to be used in combination with
+and_yield, and_raise, and_return or
+and_throw. This got fixed in 2.13.1 but failed to get merged
+into master for the 2.14.0.rc1 release (Myron Marston).
+
+
Marshal.dump does not unnecessarily duplicate objects when
+rspec-mocks has not been fully initialized. This could cause errors when
+using spork or similar preloading gems (Andy Lindeman).
Refactor internals so that the mock proxy methods and state are held
+outside of the mocked object rather than inside it. This paves the way for
+future syntax enhancements and removes the need for some hacky work
+arounds for any_instance dup'ing and YAML
+serialization, among other things. Note that the code now relies upon
+__id__ returning a unique, consistent value for any object
+you want to mock or stub (Myron Marston).
+
+
Add support for test spies. This allows you to verify a message was
+received afterwards using the have_received matcher. Note
+that you must first stub the method or use a null double. (Joe Ferris and
+Joël Quenneville)
+
+
Make at_least and at_most style receive
+expectations print that they were expecting at least or at most some
+number of calls, rather than just the number of calls given in the
+expectation (Sam Phippen)
+
+
Make with style receive expectations print the args they were
+expecting, and the args that they got (Sam Phippen)
+
+
Fix some warnings seen under ruby 2.0.0p0 (Sam Phippen).
+
+
Add a new :expect syntax for message expectations (Myron
+Marston and Sam Phippen).
+
+
+
Bug fixes
+
+
Fix any_instance so that a frozen object can be
+dup'd when methods have been stubbed on that type using
+any_instance (Jon Rowe).
+
+
Fix and_call_original so that it properly raises an
+ArgumentError when the wrong number of args are passed (Jon
+Rowe).
+
+
Fix double on 1.9.2 so you can wrap them in an Array using
+Array(my_double) (Jon Rowe).
+
+
Fix stub_const and hide_const to handle constants
+that redefine send (Sam Phippen).
+
+
Fix Marshal.dump extension so that it correctly handles nil.
+(Luke Imhoff, Jon Rowe)
+
+
Fix isolation of allow_message_expectations_on_nil (Jon Rowe)
+
+
Use inspect to format actual arguments on expectations in failure messages
+(#280, Ben Langfeld)
+
+
Protect against improperly initialised test doubles (#293) (Joseph
+Shraibman and Jon Rowe)
+
+
+
Deprecations
+
+
Deprecate stub and mock as aliases for
+double. double is the best term for creating a
+test double, and it reduces confusion to have only one term (Michi Huber).
+
+
Deprecate stub! and unstub! in favor of
+stub and unstub (Jon Rowe).
+
+
Deprecate at_least(0).times and
+any_number_of_times (Michi Huber).
Fix bug that caused weird behavior when a method that had previously been
+stubbed with multiple return values (e.g.
+obj.stub(:foo).and_return(1, 2)) was later mocked with a
+single return value (e.g.
+obj.should_receive(:foo).once.and_return(1)). (Myron Marston)
+
+
Fix bug related to a mock expectation for a method that already had
+multiple stubs with different with constraints. Previously,
+the first stub was used, even though it may not have matched the passed
+args. The fix defers this decision until the message is received so that
+the proper stub response can be chosen based on the passed arguments
+(Myron Marston).
+
+
Do not call nil? extra times on a mocked object, in case
+nil? itself is expected a set number of times (Myron
+Marston).
+
+
Fix missing_default_stub_error message so array args are
+handled properly (Myron Marston).
Fix any_instance stubbing so that it works with
+Delegator subclasses (Myron Marston).
+
+
Fix and_call_original so that it works with
+Delegator subclasses (Myron Marston).
+
+
Fix any_instance.should_not_receive when
+any_instance.should_receive is used on the same class in the
+same example. Previously it would wrongly report a failure even when the
+message was not received (Myron Marston).
Fix and_call_original to work properly for methods defined on
+a module extended onto an object instance (Myron Marston).
+
+
Fix stub_const with an undefined constnat name to work
+properly with constant strings that are prefixed with :: –
+and edge case I missed in the bug fix in the 2.12.1 release (Myron
+Marston).
+
+
Ensure method visibility on a partial mock is restored after reseting
+method stubs, even on a singleton module (created via extend
+self) when the method visibility differs between the instance and
+singleton versions (Andy Lindeman).
and_raise can accept an exception class and message, more
+closely matching Kernel#raise (e.g.,
+foo.stub(:bar).and_raise(RuntimeError, "message"))
+(Bas Vodde)
+
+
Add and_call_original, which will delegate the message to the
+original method (Myron Marston).
+
+
+
Deprecations:
+
+
Add deprecation warning when using and_return with
+should_not_receive (Neha Kumari)
Fix should_receive so that when it is called on an
+as_null_object double with no implementation, and there is a
+previous explicit stub for the same method, the explicit stub remains
+(rather than being overriden with the null object
+implementation–return self). (Myron Marston)
supports use by 3rd party mock frameworks like Surrogate
+
+
+
Add stub_const API to stub constants for the duration of an
+example (Myron Marston).
+
+
+
Bug fixes
+
+
Fix regression of edge case behavior. double.should_receive(:foo) { a
+} was causing a NoMethodError when
+double.stub(:foo).and_return(a, b) had been setup before
+(Myron Marston).
+
+
Infinite loop generated by using any_instance and
+dup. (Sidu Ponnappa @kaiwren)
+
+
double.should_receive(:foo).at_least(:once).and_return(a)
+always returns a even if :foo is already stubbed.
+
+
Prevent infinite loop when interpolating a null double into a string as an
+integer ("%i" % double.as_null_object). (Myron
+Marston)
+
+
Fix should_receive so that null object behavior (e.g.
+returning self) is preserved if no implementation is given (Myron
+Marston).
+
+
Fix and_raise so that it raises RuntimeError
+rather than Exception by default, just like ruby does.
+(Andrew Marshall)
Copyright (c) 2012 David Chelimsky, Myron Marston Copyright (c) 2006 David Chelimsky, The RSpec Development Team Copyright (c) 2005 Steven Baker
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+
+
+
\ No newline at end of file
diff --git a/source/documentation/3.1/rspec-mocks/file.README.html b/source/documentation/3.1/rspec-mocks/file.README.html
new file mode 100644
index 000000000..3ec295cf9
--- /dev/null
+++ b/source/documentation/3.1/rspec-mocks/file.README.html
@@ -0,0 +1,471 @@
+
+
+
+
+
+ File: README
+
+ — Documentation by YARD 0.8.7.6
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
rspec-mocks is a test-double framework for rspec with support for method
+stubs, fakes, and message expectations on generated test-doubles and real
+objects alike.
+
+
Install
+
+
geminstallrspec# for rspec-core, rspec-expectations, rspec-mocks
+geminstallrspec-mocks# for rspec-mocks only
+
+
Test Doubles
+
+
A test double is an object that stands in for another object in your system
+during a code example. Use the double method, passing in an
+optional identifier, to create one:
+
+
book=double("book")
+
+
+
Most of the time you will want some confidence that your doubles resemble
+an existing object in your system. Verifying doubles are provided for this
+purpose. If the existing object is available, they will prevent you from
+adding stubs and expectations for methods that do not exist or that have an
+invalid number of parameters.
+
+
book=instance_double("Book",:pages=>250)
+
+
+
Verifying doubles have some clever tricks to enable you to both test in
+isolation without your dependencies loaded while still being able to
+validate them against real objects. More detail is available in their
+documentation.
+
+
Method Stubs
+
+
A method stub is an implementation that returns a pre-determined value.
+Method stubs can be declared on test doubles or real objects using the same
+syntax. rspec-mocks supports 3 forms for declaring method stubs:
+
+
allow(book).toreceive(:title){"The RSpec Book"}
+allow(book).toreceive(:title).and_return("The RSpec Book")
+allow(book).toreceive_messages(
+ :title=>"The RSpec Book",
+ :subtitle=>"Behaviour-Driven Development with RSpec, Cucumber, and Friends")
+
+
+
You can also use this shortcut, which creates a test double and declares a
+method stub in one statement:
+
+
book=double("book",:title=>"The RSpec Book")
+
+
+
The first argument is a name, which is used for documentation and appears
+in failure messages. If you don't care about the name, you can leave it
+out, making the combined instantiation/stub declaration very terse:
+
+
double(:foo=>'bar')
+
+
+
This is particularly nice when providing a list of test doubles to a method
+that iterates through them:
When a stub might be invoked more than once, you can provide additional
+arguments to and_return. The invocations cycle through the
+list. The last value is returned for any subsequent invocations:
A message expectation is an expectation that the test double will receive a
+message some time before the example ends. If the message is received, the
+expectation is satisfied. If not, the example fails.
Verifies the given object received the expected message during the course
+of the test. For a message to be verified, the given object must be setup
+to spy on it, either by having it explicitly stubbed or by being a null
+object double (e.g. double(...).as_null_object). Convenience
+methods are provided to easily create null object doubles for this purpose:
+
+
spy("invitation")# => same as `double("invitation").as_null_object`
+instance_spy("Invitation")# => same as `instance_double("Invitation").as_null_object`
+class_spy("Invitation")# => same as `class_double("Invitation").as_null_object`
+object_spy("Invitation")# => same as `object_double("Invitation").as_null_object`
+
+
+
Stubbing and verifying messages received in this way implements the Test
+Spy pattern.
+
+
invitation=spy('invitation')
+
+user.accept_invitation(invitation)
+
+expect(invitation).tohave_received(:accept)
+
+# You can also use other common message expectations. For example:
+expect(invitation).tohave_received(:accept).with(mailer)
+expect(invitation).tohave_received(:accept).twice
+expect(invitation).to_nothave_received(:accept).with(mailer)
+
+# One can specify a return value on the spy the same way one would a double.
+invitation=spy('invitation',:accept=>true)
+expect(invitation).tohave_received(:accept).with(mailer)
+expect(invitation.accept).toeq(true)
+
+
+
Nomenclature
+
+
Mock Objects and Test Stubs
+
+
The names Mock Object and Test Stub suggest specialized Test Doubles. i.e.
+a Test Stub is a Test Double that only supports method stubs, and a Mock
+Object is a Test Double that supports message expectations and method
+stubs.
+
+
There is a lot of overlapping nomenclature here, and there are many
+variations of these patterns (fakes, spies, etc). Keep in mind that most of
+the time we're talking about method-level concepts that are variations
+of method stubs and message expectations, and we're applying to them to
+one generic kind of object: a Test Double.
+
+
Test-Specific Extension
+
+
a.k.a. Partial Double, a Test-Specific Extension is an extension of a real
+object in a system that is instrumented with test-double like behaviour in
+the context of a test. This technique is very common in Ruby because we
+often see class objects acting as global namespaces for methods. For
+example, in Rails:
In this case we're instrumenting Person to return the person object
+we've defined whenever it receives the find message. We
+can also set a message expectation so that the example fails if
+find is not called:
RSpec replaces the method we're stubbing or mocking with its own
+test-double-like method. At the end of the example, RSpec verifies any
+message expectations, and then restores the original methods.
Arguments that are passed to with are compared with actual
+arguments received using ==. In cases in which you want to specify things
+about the arguments rather than the arguments themselves, you can use any
+of the matchers that ship with rspec-expectations. They don't all make
+syntactic sense (they were primarily designed for use with
+RSpec::Expectations), but you are free to create your own custom
+RSpec::Matchers.
+
+
rspec-mocks also adds some keyword Symbols that you can use to specify
+certain kinds of arguments:
+
+
expect(double).toreceive(:msg).with(no_args())
+expect(double).toreceive(:msg).with(any_args())
+expect(double).toreceive(:msg).with(1,kind_of(Numeric),"b")#2nd argument can be any kind of Numeric
+expect(double).toreceive(:msg).with(1,boolean(),"b")#2nd argument can be true or false
+expect(double).toreceive(:msg).with(1,/abc/,"b")#2nd argument can be any String matching the submitted Regexp
+expect(double).toreceive(:msg).with(1,anything(),"b")#2nd argument can be anything at all
+expect(double).toreceive(:msg).with(1,duck_type(:abs,:div),"b")#2nd argument can be object that responds to #abs and #div
+expect(double).toreceive(:msg).with(hash_including(:a=>5))# first arg is a hash with a: 5 as one of the key-values
+expect(double).toreceive(:msg).with(array_including(5))# first arg is an array with 5 as one of the key-values
+expect(double).toreceive(:msg).with(hash_excluding(:a=>5))# first arg is a hash without a: 5 as one of the key-values
+
Whether you are setting a message expectation or a method stub, you can
+tell the object precisely how to respond. The most generic way is to pass a
+block to receive:
+
+
expect(double).toreceive(:msg){value}
+
+
+
When the double receives the msg message, it evaluates the
+block and returns the result.
+
+
expect(double).toreceive(:msg).and_return(value)
+expect(double).toreceive(:msg).exactly(3).times.and_return(value1,value2,value3)
+ # returns value1 the first time, value2 the second, etc
+expect(double).toreceive(:msg).and_raise(error)
+ # error can be an instantiated object or a class
+# if it is a class, it must be instantiable with no args
+expect(double).toreceive(:msg).and_throw(:msg)
+expect(double).toreceive(:msg).and_yield(values,to,yield)
+expect(double).toreceive(:msg).and_yield(values,to,yield).and_yield(some,other,values,this,time)
+ # for methods that yield to a block multiple times
+
+
+
Any of these responses can be applied to a stub as well
Once in a while you'll find that the available expectations don't
+solve the particular problem you are trying to solve. Imagine that you
+expect the message to come with an Array argument that has a specific
+length, but you don't care what is in it. You could do this:
When working with a partial mock object, you may occasionally want to set a
+message expecation without interfering with how the object responds to the
+message. You can use and_call_original to achieve this:
+
+
expect(Person).toreceive(:find).and_call_original
+Person.find# => executes the original find method and returns the result
+
+
+
Combining Expectation Details
+
+
Combining the message name with specific arguments, receive counts and
+responses you can get quite a bit of detail in your expectations:
While this is a good thing when you really need it, you probably don't
+really need it! Take care to specify only the things that matter to the
+behavior of your code.
Stubs in before(:context) are not supported. The reason is
+that all stubs and mocks get cleared out after each example, so any stub
+that is set in before(:context) would work in the first
+example that happens to run in that group, but not for any others.
+
+
Instead of before(:context), use
+before(:example).
+
+
Settings mocks or stubs on any instance of a class
+
+
rspec-mocks provides two methods, allow_any_instance_of and
+expect_any_instance_of, that will allow you to stub or mock
+any instance of a class. They are used in place of allow or
+expect:
These methods add the appropriate stub or expectation to all instances of
+Widget.
+
+
This feature is sometimes useful when working with legacy code, though in
+general we discourage its use for a number of reasons:
+
+
The rspec-mocks API is designed for individual object
+instances, but this feature operates on entire classes of objects. As a
+result there are some sematically confusing edge cases. For example in
+expect_any_instance_of(Widget).to receive(:name).twice it
+isn't clear whether each specific instance is expected to receive
+name twice, or if two receives total are expected. (It's
+the former.)
+
+
Using this feature is often a design smell. It may be that your test is
+trying to do too much or that the object under test is too complex.
+
+
It is the most complicated feature of rspec-mocks, and has
+historically received the most bug reports. (None of the core team
+actively use it, which doesn't help.)
+
+
+
Further Reading
+
+
There are many different viewpoints about the meaning of mocks and stubs.
+If you are interested in learning more, here is some recommended reading:
rspec-mocks is a test-double framework for rspec with support for method
+stubs, fakes, and message expectations on generated test-doubles and real
+objects alike.
+
+
Install
+
+
geminstallrspec# for rspec-core, rspec-expectations, rspec-mocks
+geminstallrspec-mocks# for rspec-mocks only
+
+
Test Doubles
+
+
A test double is an object that stands in for another object in your system
+during a code example. Use the double method, passing in an
+optional identifier, to create one:
+
+
book=double("book")
+
+
+
Most of the time you will want some confidence that your doubles resemble
+an existing object in your system. Verifying doubles are provided for this
+purpose. If the existing object is available, they will prevent you from
+adding stubs and expectations for methods that do not exist or that have an
+invalid number of parameters.
+
+
book=instance_double("Book",:pages=>250)
+
+
+
Verifying doubles have some clever tricks to enable you to both test in
+isolation without your dependencies loaded while still being able to
+validate them against real objects. More detail is available in their
+documentation.
+
+
Method Stubs
+
+
A method stub is an implementation that returns a pre-determined value.
+Method stubs can be declared on test doubles or real objects using the same
+syntax. rspec-mocks supports 3 forms for declaring method stubs:
+
+
allow(book).toreceive(:title){"The RSpec Book"}
+allow(book).toreceive(:title).and_return("The RSpec Book")
+allow(book).toreceive_messages(
+ :title=>"The RSpec Book",
+ :subtitle=>"Behaviour-Driven Development with RSpec, Cucumber, and Friends")
+
+
+
You can also use this shortcut, which creates a test double and declares a
+method stub in one statement:
+
+
book=double("book",:title=>"The RSpec Book")
+
+
+
The first argument is a name, which is used for documentation and appears
+in failure messages. If you don't care about the name, you can leave it
+out, making the combined instantiation/stub declaration very terse:
+
+
double(:foo=>'bar')
+
+
+
This is particularly nice when providing a list of test doubles to a method
+that iterates through them:
When a stub might be invoked more than once, you can provide additional
+arguments to and_return. The invocations cycle through the
+list. The last value is returned for any subsequent invocations:
A message expectation is an expectation that the test double will receive a
+message some time before the example ends. If the message is received, the
+expectation is satisfied. If not, the example fails.
Verifies the given object received the expected message during the course
+of the test. For a message to be verified, the given object must be setup
+to spy on it, either by having it explicitly stubbed or by being a null
+object double (e.g. double(...).as_null_object). Convenience
+methods are provided to easily create null object doubles for this purpose:
+
+
spy("invitation")# => same as `double("invitation").as_null_object`
+instance_spy("Invitation")# => same as `instance_double("Invitation").as_null_object`
+class_spy("Invitation")# => same as `class_double("Invitation").as_null_object`
+object_spy("Invitation")# => same as `object_double("Invitation").as_null_object`
+
+
+
Stubbing and verifying messages received in this way implements the Test
+Spy pattern.
+
+
invitation=spy('invitation')
+
+user.accept_invitation(invitation)
+
+expect(invitation).tohave_received(:accept)
+
+# You can also use other common message expectations. For example:
+expect(invitation).tohave_received(:accept).with(mailer)
+expect(invitation).tohave_received(:accept).twice
+expect(invitation).to_nothave_received(:accept).with(mailer)
+
+# One can specify a return value on the spy the same way one would a double.
+invitation=spy('invitation',:accept=>true)
+expect(invitation).tohave_received(:accept).with(mailer)
+expect(invitation.accept).toeq(true)
+
+
+
Nomenclature
+
+
Mock Objects and Test Stubs
+
+
The names Mock Object and Test Stub suggest specialized Test Doubles. i.e.
+a Test Stub is a Test Double that only supports method stubs, and a Mock
+Object is a Test Double that supports message expectations and method
+stubs.
+
+
There is a lot of overlapping nomenclature here, and there are many
+variations of these patterns (fakes, spies, etc). Keep in mind that most of
+the time we're talking about method-level concepts that are variations
+of method stubs and message expectations, and we're applying to them to
+one generic kind of object: a Test Double.
+
+
Test-Specific Extension
+
+
a.k.a. Partial Double, a Test-Specific Extension is an extension of a real
+object in a system that is instrumented with test-double like behaviour in
+the context of a test. This technique is very common in Ruby because we
+often see class objects acting as global namespaces for methods. For
+example, in Rails:
In this case we're instrumenting Person to return the person object
+we've defined whenever it receives the find message. We
+can also set a message expectation so that the example fails if
+find is not called:
RSpec replaces the method we're stubbing or mocking with its own
+test-double-like method. At the end of the example, RSpec verifies any
+message expectations, and then restores the original methods.
Arguments that are passed to with are compared with actual
+arguments received using ==. In cases in which you want to specify things
+about the arguments rather than the arguments themselves, you can use any
+of the matchers that ship with rspec-expectations. They don't all make
+syntactic sense (they were primarily designed for use with
+RSpec::Expectations), but you are free to create your own custom
+RSpec::Matchers.
+
+
rspec-mocks also adds some keyword Symbols that you can use to specify
+certain kinds of arguments:
+
+
expect(double).toreceive(:msg).with(no_args())
+expect(double).toreceive(:msg).with(any_args())
+expect(double).toreceive(:msg).with(1,kind_of(Numeric),"b")#2nd argument can be any kind of Numeric
+expect(double).toreceive(:msg).with(1,boolean(),"b")#2nd argument can be true or false
+expect(double).toreceive(:msg).with(1,/abc/,"b")#2nd argument can be any String matching the submitted Regexp
+expect(double).toreceive(:msg).with(1,anything(),"b")#2nd argument can be anything at all
+expect(double).toreceive(:msg).with(1,duck_type(:abs,:div),"b")#2nd argument can be object that responds to #abs and #div
+expect(double).toreceive(:msg).with(hash_including(:a=>5))# first arg is a hash with a: 5 as one of the key-values
+expect(double).toreceive(:msg).with(array_including(5))# first arg is an array with 5 as one of the key-values
+expect(double).toreceive(:msg).with(hash_excluding(:a=>5))# first arg is a hash without a: 5 as one of the key-values
+
Whether you are setting a message expectation or a method stub, you can
+tell the object precisely how to respond. The most generic way is to pass a
+block to receive:
+
+
expect(double).toreceive(:msg){value}
+
+
+
When the double receives the msg message, it evaluates the
+block and returns the result.
+
+
expect(double).toreceive(:msg).and_return(value)
+expect(double).toreceive(:msg).exactly(3).times.and_return(value1,value2,value3)
+ # returns value1 the first time, value2 the second, etc
+expect(double).toreceive(:msg).and_raise(error)
+ # error can be an instantiated object or a class
+# if it is a class, it must be instantiable with no args
+expect(double).toreceive(:msg).and_throw(:msg)
+expect(double).toreceive(:msg).and_yield(values,to,yield)
+expect(double).toreceive(:msg).and_yield(values,to,yield).and_yield(some,other,values,this,time)
+ # for methods that yield to a block multiple times
+
+
+
Any of these responses can be applied to a stub as well
Once in a while you'll find that the available expectations don't
+solve the particular problem you are trying to solve. Imagine that you
+expect the message to come with an Array argument that has a specific
+length, but you don't care what is in it. You could do this:
When working with a partial mock object, you may occasionally want to set a
+message expecation without interfering with how the object responds to the
+message. You can use and_call_original to achieve this:
+
+
expect(Person).toreceive(:find).and_call_original
+Person.find# => executes the original find method and returns the result
+
+
+
Combining Expectation Details
+
+
Combining the message name with specific arguments, receive counts and
+responses you can get quite a bit of detail in your expectations:
While this is a good thing when you really need it, you probably don't
+really need it! Take care to specify only the things that matter to the
+behavior of your code.
Stubs in before(:context) are not supported. The reason is
+that all stubs and mocks get cleared out after each example, so any stub
+that is set in before(:context) would work in the first
+example that happens to run in that group, but not for any others.
+
+
Instead of before(:context), use
+before(:example).
+
+
Settings mocks or stubs on any instance of a class
+
+
rspec-mocks provides two methods, allow_any_instance_of and
+expect_any_instance_of, that will allow you to stub or mock
+any instance of a class. They are used in place of allow or
+expect:
These methods add the appropriate stub or expectation to all instances of
+Widget.
+
+
This feature is sometimes useful when working with legacy code, though in
+general we discourage its use for a number of reasons:
+
+
The rspec-mocks API is designed for individual object
+instances, but this feature operates on entire classes of objects. As a
+result there are some sematically confusing edge cases. For example in
+expect_any_instance_of(Widget).to receive(:name).twice it
+isn't clear whether each specific instance is expected to receive
+name twice, or if two receives total are expected. (It's
+the former.)
+
+
Using this feature is often a design smell. It may be that your test is
+trying to do too much or that the object under test is too complex.
+
+
It is the most complicated feature of rspec-mocks, and has
+historically received the most bug reports. (None of the core team
+actively use it, which doesn't help.)
+
+
+
Further Reading
+
+
There are many different viewpoints about the meaning of mocks and stubs.
+If you are interested in learning more, here is some recommended reading:
