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_ignorer.rb,
lib/vcr/request_handler.rb,
lib/vcr/middleware/rack.rb,
lib/vcr/cassette/migrator.rb,
lib/vcr/middleware/faraday.rb,
lib/vcr/cassette/persisters.rb,
lib/vcr/library_hooks/excon.rb,
lib/vcr/util/version_checker.rb,
lib/vcr/cassette/serializers.rb,
lib/vcr/cassette/erb_renderer.rb,
lib/vcr/library_hooks/fakeweb.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/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/cassette/serializers/psych.rb,
lib/vcr/library_hooks/typhoeus_0.4.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

#configObject

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

#configurationVCR::Configuration



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

#current_cassettenil, VCR::Cassette

The currently active cassette.



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

def current_cassette
  cassettes.last
end

#eject_cassetteVCR::Cassette?

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



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

#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 cassete's :record option.

Examples:

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

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

VCR.eject_cassette

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.

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

#request_matchersRequestMatcherRegistry



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.

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.



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.

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

#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



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

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

#versionString

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.



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