Method: VCR#insert_cassette

Defined in:
lib/vcr.rb

#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