module VCR
The main entry point for VCR
. @note This module is extended onto itself; thus, the methods listed
here as instance methods are available directly off of VCR.
Constants
- Ping
Public Class Methods
Source
# File lib/vcr/deprecations.rb, line 10 def self.const_missing(const) return super unless const == :Config warn "WARNING: `VCR::Config` is deprecated. Use VCR.configuration instead." configuration end
@private
Public Instance Methods
Source
# File lib/vcr.rb, line 307 def cassette_persisters @cassette_persisters ||= Cassette::Persisters.new end
@private
Source
# File lib/vcr.rb, line 302 def cassette_serializers @cassette_serializers ||= Cassette::Serializers.new end
@private
Source
Source
# File lib/vcr.rb, line 190 def configuration @configuration ||= Configuration.new end
@return [VCR::Configuration] the VCR
configuration.
Source
# File lib/vcr.rb, line 185 def configure yield configuration end
Used to configure VCR
.
@example
VCR.configure do |c| c.some_config_option = true end
@yield the configuration block @yieldparam config [VCR::Configuration] the configuration object @return [void]
Source
# File lib/vcr.rb, line 38 def current_cassette cassettes.last end
The currently active cassette.
@return [nil, VCR::Cassette
] The current cassette or nil if there is
no current cassette.
Source
# File lib/vcr.rb, line 134 def eject_cassette cassette = cassettes.last cassette.eject if cassette cassette ensure cassettes.pop end
Ejects the current cassette. The cassette will no longer be used. In addition, any newly recorded HTTP interactions will be written to disk.
@return [VCR::Cassette, nil] the ejected cassette if there was one
Source
# File lib/vcr.rb, line 275 def http_interactions return current_cassette.http_interactions if current_cassette VCR::Cassette::HTTPInteractionList::NullList end
@private
Source
# File lib/vcr.rb, line 113 def insert_cassette(name, options = {}) if turned_on? if cassettes.any? { |c| c.name == name } raise ArgumentError.new("There is already a cassette with the same name (#{name}). You cannot nest multiple cassettes with the same name.") end cassette = Cassette.new(name, options) cassettes.push(cassette) cassette elsif !ignore_cassettes? message = "VCR is turned off. You must turn it on before you can insert a cassette. " + "Or you can use the `:ignore_cassettes => true` option to completely ignore cassette insertions." raise TurnedOffError.new(message) end end
Inserts the named cassette using the given cassette options. New HTTP interactions, if allowed by the cassette’s ‘:record` option, will be recorded to the cassette. The cassette’s existing HTTP interactions will be used to stub requests, unless prevented by the cassete’s ‘:record` option.
@example
VCR.insert_cassette('twitter', :record => :new_episodes) # ...later, after making an HTTP request: VCR.eject_cassette
@param name [#to_s] The name of the cassette. VCR
will sanitize
this to ensure it is a valid file name.
@param options [Hash] The cassette options. The given options will
be merged with the configured default_cassette_options.
@option options :record [:all, :none, :new_episodes, :once] The record mode. @option options :erb [Boolean, Hash] Whether or not to evaluate the
cassette as an ERB template. Defaults to false. A hash can be used to provide the ERB template with local variables.
@option options :match_requests_on [Array<Symbol, call>] List of request matchers
to use to determine what recorded HTTP interaction to replay. Defaults to [:method, :uri]. The built-in matchers are :method, :uri, :host, :path, :headers and :body. You can also pass the name of a registered custom request matcher or any object that responds to #call.
@option options :re_record_interval [Integer] When given, the
cassette will be re-recorded at the given interval, in seconds.
@option options :tag [Symbol] Used to apply tagged ‘before_record`
and `before_playback` hooks to the cassette.
@option options :tags [Array<Symbol>] Used to apply multiple tags to
a cassette so that tagged `before_record` and `before_playback` hooks will apply to the cassette.
@option options :update_content_length_header [Boolean] Whether or
not to overwrite the Content-Length header of the responses to match the length of the response body. Defaults to false.
@option options :decode_compressed_response [Boolean] Whether or
not to decode compressed responses before recording the cassette. This makes the cassette more human readable. Defaults to false.
@option options :allow_playback_repeats [Boolean] Whether or not to
allow a single HTTP interaction to be played back multiple times. Defaults to false.
@option options :allow_unused_http_interactions [Boolean] If set to
false, an error will be raised if a cassette is ejected before all previously recorded HTTP interactions have been used. Defaults to true.
@option options :exclusive [Boolean] Whether or not to use only this
cassette and to completely ignore any cassettes in the cassettes stack. Defaults to false.
@option options :serialize_with [Symbol] Which serializer to use.
Valid values are :yaml, :syck, :psych, :json or any registered custom serializer. Defaults to :yaml.
@option options :persist_with [Symbol] Which cassette persister to
use. Defaults to :file_system. You can also register and use a custom persister.
@option options :preserve_exact_body_bytes [Boolean] Whether or not
to base64 encode the bytes of the requests and responses for this cassette when serializing it. See also `VCR::Configuration#preserve_exact_body_bytes`.
@return [VCR::Cassette] the inserted cassette
@raise [ArgumentError] when the given cassette is already being used. @raise [VCR::Errors::TurnedOffError] when VCR
has been turned off
without using the :ignore_cassettes option.
@raise [VCR::Errors::MissingERBVariableError] when the ‘:erb` option
is used and the ERB template requires variables that you did not provide.
@note If you use this method you must call ‘eject_cassette` when you
are done. It is generally recommended that you use {#use_cassette} unless your code-under-test cannot be run as a block.
Source
# File lib/vcr.rb, line 297 def library_hooks @library_hooks ||= LibraryHooks.new end
@private
Source
# File lib/vcr.rb, line 281 def real_http_connections_allowed? return current_cassette.recording? if current_cassette configuration.allow_http_connections_when_no_cassette? || @turned_off end
@private
Source
# File lib/vcr.rb, line 312 def record_http_interaction(interaction) return unless cassette = current_cassette return if VCR.request_ignorer.ignore?(interaction.request) cassette.record_http_interaction(interaction) end
@private
Source
# File lib/vcr.rb, line 292 def request_ignorer @request_ignorer ||= RequestIgnorer.new end
@private
Source
# File lib/vcr.rb, line 287 def request_matchers @request_matchers ||= RequestMatcherRegistry.new end
@return [RequestMatcherRegistry] the request matcher registry
Source
# File lib/vcr.rb, line 240 def turn_off!(options = {}) if VCR.current_cassette raise CassetteInUseError, "A VCR cassette is currently in use (#{VCR.current_cassette.name}). " + "You must eject it before you can turn VCR off." end @ignore_cassettes = options[:ignore_cassettes] invalid_options = options.keys - [:ignore_cassettes] if invalid_options.any? raise ArgumentError.new("You passed some invalid options: #{invalid_options.inspect}") end @turned_off = true end
Turns VCR
off, so that it no longer handles every HTTP request.
@param options [Hash] hash of options @option options :ignore_cassettes [Boolean] controls what happens when a cassette is
inserted while VCR is turned off. If `true` is passed, the cassette insertion will be ignored; otherwise a {VCR::Errors::TurnedOffError} will be raised.
@return [void] @raise [VCR::Errors::CassetteInUseError] if there is currently a cassette in use @raise [ArgumentError] if you pass an invalid option
Source
# File lib/vcr.rb, line 260 def turn_on! @turned_off = false end
Turns on VCR
, if it has previously been turned off. @return [void] @see turn_off!
@see turned_off
@see turned_on?
Source
Source
# File lib/vcr.rb, line 270 def turned_on? !@turned_off end
@return whether or not VCR
is turned on @note Normally VCR
is always turned on; it will only be off if you have
explicitly turned it off.
@see turn_on!
@see turn_off!
@see turned_off
Source
# File lib/vcr.rb, line 159 def use_cassette(name, options = {}, &block) unless block raise ArgumentError, "`VCR.use_cassette` requires a block. " + "If you cannot wrap your code in a block, use " + "`VCR.insert_cassette` / `VCR.eject_cassette` instead." end cassette = insert_cassette(name, options) begin call_block(block, cassette) ensure eject_cassette end end
Inserts a cassette using the given name and options, runs the given block, and ejects the cassette.
@example
VCR.use_cassette('twitter', :record => :new_episodes) do # make an HTTP request end
@param (see insert_cassette
) @option (see insert_cassette
) @yield Block to run while this cassette is in use. @yieldparam cassette [(optional) VCR::Cassette
] the cassette that has
been inserted.
@raise (see insert_cassette
) @return [void] @see insert_cassette
@see eject_cassette
Source
# File lib/vcr/version.rb, line 11 def version @version ||= begin string = '2.3.0' def string.parts split('.').map { |p| p.to_i } end def string.major parts[0] end def string.minor parts[1] end def string.patch parts[2] end string end end
@return [String] the current VCR
version. @note This string also has singleton methods:
* `major` [Integer] The major version. * `minor` [Integer] The minor version. * `patch` [Integer] The patch version. * `parts` [Array<Integer>] List of the version parts.