Module: VCR

Extended by:
VCR
Includes:
Errors
Included in:
VCR
Defined in:
lib/vcr.rb,
lib/vcr/errors.rb,
lib/vcr/structs.rb,
lib/vcr/version.rb,
lib/vcr/cassette.rb,
lib/vcr/util/hooks.rb,
lib/vcr/util/logger.rb,
lib/vcr/deprecations.rb,
lib/vcr/configuration.rb,
lib/vcr/library_hooks.rb,
lib/vcr/linked_cassette.rb,
lib/vcr/middleware/rack.rb,
lib/vcr/request_handler.rb,
lib/vcr/request_ignorer.rb,
lib/vcr/middleware/excon.rb,
lib/vcr/cassette/migrator.rb,
lib/vcr/middleware/faraday.rb,
lib/vcr/cassette/persisters.rb,
lib/vcr/library_hooks/excon.rb,
lib/vcr/cassette/serializers.rb,
lib/vcr/util/version_checker.rb,
lib/vcr/cassette/erb_renderer.rb,
lib/vcr/library_hooks/faraday.rb,
lib/vcr/library_hooks/webmock.rb,
lib/vcr/test_frameworks/rspec.rb,
lib/vcr/library_hooks/typhoeus.rb,
lib/vcr/request_matcher_registry.rb,
lib/vcr/test_frameworks/cucumber.rb,
lib/vcr/util/internet_connection.rb,
lib/vcr/cassette/serializers/json.rb,
lib/vcr/cassette/serializers/syck.rb,
lib/vcr/cassette/serializers/yaml.rb,
lib/vcr/cassette/serializers/psych.rb,
lib/vcr/cassette/http_interaction_list.rb,
lib/vcr/cassette/persisters/file_system.rb,
lib/vcr/cassette/serializers/compressed.rb,
lib/vcr/middleware/excon/legacy_methods.rb,
lib/vcr/util/variable_args_block_caller.rb

Overview

Note:

This module is extended onto itself; thus, the methods listed here as instance methods are available directly off of VCR.

The main entry point for VCR.

Defined Under Namespace

Modules: Errors, Middleware, RSpec Classes: Cassette, Configuration, CucumberTags, HTTPInteraction, LinkedCassette, Request, RequestMatcherRegistry, Response, ResponseStatus

Constant Summary collapse

CassetteMutex =

Mutex to synchronize access to cassettes in a threaded environment

Mutex.new
MainThread =

The main thread in which VCR was loaded

Thread.current

Instance Method Summary collapse

Instance Method Details

#cassettes(context = current_context) ⇒ Enumerable

Returns list of all cassettes currently being used.

Returns:

  • (Enumerable) —

    list of all cassettes currently being used



362
363
364
365
366
367
 
# 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 ⇒ Object

Deprecated.

Use #configure instead.

See Also:



4
5
6
7
 
# 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 ⇒ VCR::Configuration

Returns the VCR configuration.

Returns:



239
240
241
 
# File 'lib/vcr.rb', line 239

def configuration
  @configuration
end

#configure {|config| ... }

This method returns an undefined value.

Used to configure VCR.

Examples:

VCR.configure do |c|
  c.some_config_option = true
end

Yields:

  • the configuration block

Yield Parameters:



234
235
236
 
# File 'lib/vcr.rb', line 234

def configure
  yield configuration
end

#cucumber_tags {|t| ... }

This method returns an undefined value.

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

Examples:

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

Yields:

  • the cucumber tags configuration block

Yield Parameters:

See Also:



256
257
258
259
 
# 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 ⇒ nil, VCR::Cassette

The currently active cassette.

Returns:

  • (nil, VCR::Cassette) —

    The current cassette or nil if there is no current cassette.



48
49
50
 
# File 'lib/vcr.rb', line 48

def current_cassette
  cassettes.last
end

#eject_cassette(options = {}) ⇒ VCR::Cassette?

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

Parameters:

  • options (Hash) (defaults to: {}) —

    Eject options.

Options Hash (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.

Returns:



159
160
161
162
163
164
165
 
# 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

#insert_cassette(name, options = {}) ⇒ VCR::Cassette

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.

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.

Examples:

VCR.insert_cassette('twitter', :record => :new_episodes)

# ...later, after making an HTTP request:

VCR.eject_cassette

Parameters:

  • name (#to_s) —

    The name of the cassette. VCR will sanitize this to ensure it is a valid file name.

  • options (Hash) (defaults to: {}) —

    The cassette options. The given options will be merged with the configured default_cassette_options.

Options Hash (options):

  • :record (:all, :none, :new_episodes, :once) —

    The record mode.

  • :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.

  • :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.

  • :re_record_interval (Integer) —

    When given, the cassette will be re-recorded at the given interval, in seconds.

  • :tag (Symbol) —

    Used to apply tagged before_record and before_playback hooks to the cassette.

  • :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.

  • :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.

  • :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.

  • :allow_playback_repeats (Boolean) —

    Whether or not to allow a single HTTP interaction to be played back multiple times. Defaults to false.

  • :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).

  • :exclusive (Boolean) —

    Whether or not to use only this cassette and to completely ignore any cassettes in the cassettes stack. Defaults to false.

  • :serialize_with (Symbol) —

    Which serializer to use. Valid values are :yaml, :syck, :psych, :json or any registered custom serializer. Defaults to :yaml.

  • :persist_with (Symbol) —

    Which cassette persister to use. Defaults to :file_system. You can also register and use a custom persister.

  • :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.
  • :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.

Returns:

Raises:



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# 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

#request_matchers ⇒ RequestMatcherRegistry

Returns the request matcher registry.

Returns:



357
358
359
 
# File 'lib/vcr.rb', line 357

def request_matchers
  @request_matchers
end

#turn_off!(options = {})

This method returns an undefined value.

Turns VCR off, so that it no longer handles every HTTP request.

Parameters:

  • options (Hash) (defaults to: {}) —

    hash of options

Options Hash (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.

Raises:



290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# 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!

This method returns an undefined value.

Turns on VCR, if it has previously been turned off.

See Also:



327
328
329
 
# File 'lib/vcr.rb', line 327

def turn_on!
  set_context_value(:turned_off, false)
end

#turned_off(options = {})

This method returns an undefined value.

Turns VCR off for the duration of a block.

Parameters:

  • options (Hash) (defaults to: {}) —

    hash of options

Raises:

See Also:



270
271
272
273
274
275
276
277
278
 
# File 'lib/vcr.rb', line 270

def turned_off(options = {})
  turn_off!(options)

  begin
    yield
  ensure
    turn_on!
  end
end

#turned_on(options = {})

This method returns an undefined value.

Turns on VCR, for the duration of a block.

Parameters:

  • options (Hash) (defaults to: {}) —

    hash of options

See Also:



311
312
313
314
315
316
317
318
319
 
# File 'lib/vcr.rb', line 311

def turned_on(options = {})
  turn_on!

  begin
    yield
  ensure
    turn_off!(options)
  end
end

#turned_on? ⇒ Boolean

Note:

Normally VCR is always turned on; it will only be off if you have explicitly turned it off.

Returns whether or not VCR is turned on.

Returns:

  • (Boolean) —

    whether or not VCR is turned on

See Also:



337
338
339
340
341
342
 
# 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 = {}) {|cassette| ... }

This method returns an undefined value.

Inserts a cassette using the given name and options, runs the given block, and ejects the cassette.

Examples:

VCR.use_cassette('twitter', :record => :new_episodes) do
  # make an HTTP request
end

Parameters:

  • name (#to_s) —

    The name of the cassette. VCR will sanitize this to ensure it is a valid file name.

  • options (Hash) (defaults to: {}) —

    The cassette options. The given options will be merged with the configured default_cassette_options.

Options Hash (options):

  • :record (:all, :none, :new_episodes, :once) —

    The record mode.

  • :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.

  • :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.

  • :re_record_interval (Integer) —

    When given, the cassette will be re-recorded at the given interval, in seconds.

  • :tag (Symbol) —

    Used to apply tagged before_record and before_playback hooks to the cassette.

  • :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.

  • :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.

  • :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.

  • :allow_playback_repeats (Boolean) —

    Whether or not to allow a single HTTP interaction to be played back multiple times. Defaults to false.

  • :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).

  • :exclusive (Boolean) —

    Whether or not to use only this cassette and to completely ignore any cassettes in the cassettes stack. Defaults to false.

  • :serialize_with (Symbol) —

    Which serializer to use. Valid values are :yaml, :syck, :psych, :json or any registered custom serializer. Defaults to :yaml.

  • :persist_with (Symbol) —

    Which cassette persister to use. Defaults to :file_system. You can also register and use a custom persister.

  • :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.
  • :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.

Yields:

  • Block to run while this cassette is in use.

Yield Parameters:

  • cassette ((optional) VCR::Cassette) —

    the cassette that has been inserted.

Raises:

See Also:



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# 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) ⇒ Object

Inserts multiple cassettes the given names

Examples:

cassettes = [
 { name: 'github' },
 { name: 'apple', options: { erb: true } }
]
VCR.use_cassettes(cassettes) do
  # make multiple HTTP requests
end


213
214
215
216
217
218
219
220
221
222
 
# 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 ⇒ String

Note:

This string also has singleton methods:

  • major [Integer] The major version.
  • minor [Integer] The minor version.
  • patch [Integer] The patch version.
  • parts [Array] List of the version parts.

Returns the current VCR version.

Returns:

  • (String) —

    the current VCR version.



11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/vcr/version.rb', line 11

def version
  @version ||= begin
    string = +'6.1.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.freeze
  end
end