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

CassetteMutex

Mutex to synchronize access to cassettes in a threaded environment

MainThread

The main thread in which VCR was loaded

Public Class Methods

const_missing(const) click to toggle source

@private

Calls superclass method
# 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

Public Instance Methods

cassette_persisters() click to toggle source

@private

# File lib/vcr.rb, line 385
def cassette_persisters
  @cassette_persisters
end
cassette_serializers() click to toggle source

@private

# File lib/vcr.rb, line 380
def cassette_serializers
  @cassette_serializers
end
cassettes(context = current_context) click to toggle source

@return [Enumerable] list of all cassettes currently being used

# File lib/vcr.rb, line 362
def cassettes(context = current_context)
  linked_context = context[:linked_context]
  linked_cassettes = cassettes(linked_context) if linked_context

  LinkedCassette.list(context[:cassettes], Array(linked_cassettes))
end
config() { |c| ... } click to toggle source

@deprecated Use configure instead. @see configure

# File lib/vcr/deprecations.rb, line 4
def config
  warn "WARNING: `VCR.config` is deprecated.  Use VCR.configure instead."
  configure { |c| yield c }
end
configuration() click to toggle source

@return [VCR::Configuration] the VCR configuration.

# File lib/vcr.rb, line 239
def configuration
  @configuration
end
configure() { |configuration| ... } click to toggle source

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]

# File lib/vcr.rb, line 234
def configure
  yield configuration
end
cucumber_tags() { |cucumber_tags| ... } click to toggle source

Sets up ‘Before` and `After` cucumber hooks in order to use VCR with particular cucumber tags.

@example

VCR.cucumber_tags do |t|
  t.tags "tag1", "tag2"
  t.tag "@some_other_tag", :record => :new_episodes
end

@yield the cucumber tags configuration block @yieldparam t [VCR::CucumberTags] Cucumber tags config object @return [void] @see VCR::CucumberTags#tags

# File lib/vcr.rb, line 256
def cucumber_tags(&block)
  main_object = eval('self', block.binding)
  yield VCR::CucumberTags.new(main_object)
end
current_cassette() click to toggle source

The currently active cassette.

@return [nil, VCR::Cassette] The current cassette or nil if there is

no current cassette.
# File lib/vcr.rb, line 48
def current_cassette
  cassettes.last
end
eject_cassette(options = {}) click to toggle source

Ejects the current cassette. The cassette will no longer be used. In addition, any newly recorded HTTP interactions will be written to disk.

@param options [Hash] Eject options. @option options :skip_no_unused_interactions_assertion [Boolean]

If `true` is given, this will skip the "no unused HTTP interactions"
assertion enabled by the `:allow_unused_http_interactions => false`
cassette option. This is intended for use when your test has had
an error, but your test framework has already handled it.

@return [VCR::Cassette, nil] the ejected cassette if there was one

# File lib/vcr.rb, line 159
def eject_cassette(options = {})
  cassette = cassettes.last
  cassette.eject(options) if cassette
  cassette
ensure
  context_cassettes.delete(cassette)
end
fibers_available?() click to toggle source

@private

# File lib/vcr.rb, line 408
def fibers_available?
  @fibers_available
end
http_interactions() click to toggle source

@private

# File lib/vcr.rb, line 345
def http_interactions
  return current_cassette.http_interactions if current_cassette
  VCR::Cassette::HTTPInteractionList::NullList
end
insert_cassette(name, options = {}) click to toggle source

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 cassette’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. Note that when an error has already occurred
(as indicated by the `$!` variable) unused interactions will be
allowed so that we don't silence the original error (which is almost
certainly more interesting/important).

@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 :persister_options [Hash] Pass options to the

persister specified in `persist_with`. Currently available options for the file_system persister:
  - `:downcase_cassette_names`: when `true`, names of cassettes will be
    normalized in lowercase before reading and writing, which can avoid
    confusion when using both case-sensitive and case-insensitive file
    systems.

@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.
# File lib/vcr.rb, line 132
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)
    context_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
library_hooks() click to toggle source

@private

# File lib/vcr.rb, line 375
def library_hooks
  @library_hooks
end
real_http_connections_allowed?() click to toggle source

@private

# File lib/vcr.rb, line 351
def real_http_connections_allowed?
  return current_cassette.recording? if current_cassette
  !!(configuration.allow_http_connections_when_no_cassette? || !turned_on?)
end
record_http_interaction(interaction) click to toggle source

@private

# File lib/vcr.rb, line 390
def record_http_interaction(interaction)
  return unless cassette = current_cassette
  return if VCR.request_ignorer.ignore?(interaction.request)

  cassette.record_http_interaction(interaction)
end
request_ignorer() click to toggle source

@private

# File lib/vcr.rb, line 370
def request_ignorer
  @request_ignorer
end
request_matchers() click to toggle source

@return [RequestMatcherRegistry] the request matcher registry

# File lib/vcr.rb, line 357
def request_matchers
  @request_matchers
end
turn_off!(options = {}) click to toggle source

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

# File lib/vcr.rb, line 290
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

  set_context_value(:ignore_cassettes, options.fetch(:ignore_cassettes, false))
  invalid_options = options.keys - [:ignore_cassettes]
  if invalid_options.any?
    raise ArgumentError.new("You passed some invalid options: #{invalid_options.inspect}")
  end

  set_context_value(:turned_off, true)
end
turn_on!() click to toggle source

Turns on VCR, if it has previously been turned off. @return [void] @see turn_off! @see turned_off @see turned_on? @see turned_on

# File lib/vcr.rb, line 327
def turn_on!
  set_context_value(:turned_off, false)
end
turned_off(options = {}) { || ... } click to toggle source

Turns VCR off for the duration of a block.

@param (see turn_off!) @return [void] @raise (see turn_off!) @see turn_off! @see turn_on! @see turned_on? @see turned_on

# File lib/vcr.rb, line 270
def turned_off(options = {})
  turn_off!(options)

  begin
    yield
  ensure
    turn_on!
  end
end
turned_on(options = {}) { || ... } click to toggle source

Turns on VCR, for the duration of a block. @param (see turn_off!) @return [void] @see turn_off! @see turned_off @see turned_on?

# File lib/vcr.rb, line 311
def turned_on(options = {})
  turn_on!

  begin
    yield
  ensure
    turn_off!(options)
  end
end
turned_on?() click to toggle source

@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

# File lib/vcr.rb, line 337
def turned_on?
  linked_context = current_context[:linked_context]
  return !linked_context[:turned_off] if linked_context

  !context_value(:turned_off)
end
use_cassette(name, options = {}, &block) click to toggle source

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

# File lib/vcr.rb, line 184
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)
  rescue StandardError
    cassette.run_failed!
    raise
  ensure
    eject_cassette
  end
end
use_cassettes(cassettes, &block) click to toggle source

Inserts multiple cassettes the given names

@example

cassettes = [
 { name: 'github' },
 { name: 'apple', options: { erb: true } }
]
VCR.use_cassettes(cassettes) do
  # make multiple HTTP requests
end
# File lib/vcr.rb, line 213
def use_cassettes(cassettes, &block)
  cassette = cassettes.pop
  use_cassette(cassette[:name], cassette[:options] || {}) do
    if cassettes.empty?
      block.call
    else
      use_cassettes(cassettes, &block)
    end
  end
end
version() click to toggle source

@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.
# File lib/vcr/version.rb, line 11
def version
  @version ||= begin
    string = +'6.3.1'

    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.freeze
  end
end

Private Instance Methods

context_cassettes() click to toggle source
# File lib/vcr.rb, line 448
def context_cassettes
  context_value(:cassettes)
end
context_value(name) click to toggle source
# File lib/vcr.rb, line 427
def context_value(name)
  current_context[name]
end
current_context() click to toggle source
# File lib/vcr.rb, line 413
def current_context
  get_context(Thread.current, Fiber.current)
end
dup_context(context) click to toggle source
# File lib/vcr.rb, line 435
def dup_context(context)
  {
    :turned_off => context[:turned_off],
    :ignore_cassettes => context[:ignore_cassettes],
    :cassettes => [],
    :linked_context => context
  }
end
get_context(thread_key, fiber_key = nil) click to toggle source
# File lib/vcr.rb, line 417
def get_context(thread_key, fiber_key = nil)
  context = @context[fiber_key] if fiber_key
  context ||= @context[thread_key]
  if context
    context
  else
    @context[thread_key] = dup_context(@context[MainThread])
  end
end
ignore_cassettes?() click to toggle source
# File lib/vcr.rb, line 444
def ignore_cassettes?
  context_value(:ignore_cassettes)
end
initialize_fibers() click to toggle source
# File lib/vcr.rb, line 452
def initialize_fibers
  begin
    require 'fiber'
    @fibers_available = true
  rescue LoadError
    @fibers_available = false
  end
end
initialize_ivars() click to toggle source
# File lib/vcr.rb, line 461
def initialize_ivars
  initialize_fibers
  @context = {
    MainThread => {
      :turned_off => false,
      :ignore_cassettes => false,
      :cassettes => [],
      :linked_context => nil
    }
  }
  @configuration = Configuration.new
  @request_matchers = RequestMatcherRegistry.new
  @request_ignorer = RequestIgnorer.new
  @library_hooks = LibraryHooks.new
  @cassette_serializers = Cassette::Serializers.new
  @cassette_persisters = Cassette::Persisters.new
end
set_context_value(name, value) click to toggle source
# File lib/vcr.rb, line 431
def set_context_value(name, value)
  current_context[name] = value
end