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/library_hooks.rb,
lib/vcr/configuration.rb,
lib/vcr/request_handler.rb,
lib/vcr/request_ignorer.rb,
lib/vcr/middleware/rack.rb,
lib/vcr/cassette/migrator.rb,
lib/vcr/middleware/faraday.rb,
lib/vcr/library_hooks/excon.rb,
lib/vcr/cassette/persisters.rb,
lib/vcr/cassette/serializers.rb,
lib/vcr/util/version_checker.rb,
lib/vcr/cassette/erb_renderer.rb,
lib/vcr/library_hooks/fakeweb.rb,
lib/vcr/test_frameworks/rspec.rb,
lib/vcr/library_hooks/faraday.rb,
lib/vcr/library_hooks/webmock.rb,
lib/vcr/library_hooks/typhoeus.rb,
lib/vcr/util/internet_connection.rb,
lib/vcr/request_matcher_registry.rb,
lib/vcr/test_frameworks/cucumber.rb,
lib/vcr/cassette/serializers/yaml.rb,
lib/vcr/cassette/serializers/syck.rb,
lib/vcr/cassette/serializers/json.rb,
lib/vcr/library_hooks/typhoeus_0.4.rb,
lib/vcr/cassette/serializers/psych.rb,
lib/vcr/extensions/net_http_response.rb,
lib/vcr/cassette/http_interaction_list.rb,
lib/vcr/util/variable_args_block_caller.rb,
lib/vcr/cassette/persisters/file_system.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, Request, RequestMatcherRegistry, Response, ResponseStatus

Instance Method Summary (collapse)

Instance Method Details

- (Object) config

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

- (VCR::Configuration) configuration

The VCR configuration.

Returns:



190
191
192
 
# File 'lib/vcr.rb', line 190

def configuration
  @configuration ||= Configuration.new
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:



185
186
187
 
# File 'lib/vcr.rb', line 185

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:



207
208
209
210
 
# File 'lib/vcr.rb', line 207

def cucumber_tags(&block)
  main_object = eval('self', block.binding)
  yield VCR::CucumberTags.new(main_object)
end

- (nil, VCR::Cassette) current_cassette

The currently active cassette.

Returns:

  • (nil, VCR::Cassette) —

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



38
39
40
 
# File 'lib/vcr.rb', line 38

def current_cassette
  cassettes.last
end

- (VCR::Cassette?) eject_cassette

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

Returns:



134
135
136
137
138
139
140
 
# File 'lib/vcr.rb', line 134

def eject_cassette
  cassette = cassettes.last
  cassette.eject if cassette
  cassette
ensure
  cassettes.pop
end

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

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 cassete'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.

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

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



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# 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

- (RequestMatcherRegistry) request_matchers

The request matcher registry

Returns:



287
288
289
 
# File 'lib/vcr.rb', line 287

def request_matchers
  @request_matchers ||= RequestMatcherRegistry.new
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:



240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# 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

- turn_on!

This method returns an undefined value.

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

See Also:



260
261
262
 
# File 'lib/vcr.rb', line 260

def turn_on!
  @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:



220
221
222
223
224
225
226
227
228
 
# File 'lib/vcr.rb', line 220

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

  begin
    yield
  ensure
    turn_on!
  end
end

- (Boolean) turned_on?

Note:

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

Whether or not VCR is turned on

Returns:

  • (Boolean) —

    whether or not VCR is turned on

See Also:



270
271
272
 
# File 'lib/vcr.rb', line 270

def turned_on?
  !@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.

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

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



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
 
# 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

- (String) 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] List of the version parts.

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 = '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