Class: VCR::Cassette

Inherits:
Object
  • Object
show all
Includes:
Logger::Mixin
Defined in:
lib/vcr/cassette.rb,
lib/vcr/cassette/migrator.rb,
lib/vcr/cassette/persisters.rb,
lib/vcr/cassette/serializers.rb,
lib/vcr/cassette/erb_renderer.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

Overview

The media VCR uses to store HTTP interactions for later re-use.

Defined Under Namespace

Modules: EncodingErrorHandling, SyntaxErrorHandling Classes: ERBRenderer, HTTPInteractionList, Migrator, Persisters, Serializers

Constant Summary collapse

VALID_RECORD_MODES =

The supported record modes.

* :all -- Record every HTTP interactions; do not play any back.
* :none -- Do not record any HTTP interactions; play them back.
* :new_episodes -- Playback previously recorded HTTP interactions and record new ones.
* :once -- Record the HTTP interactions if the cassette has not already been recorded;
           otherwise, playback the HTTP interactions.

[:all, :none, :new_episodes, :once]

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Logger::Mixin

#log, #response_summary

Constructor Details

#initialize(name, options = {}) ⇒ Cassette

Returns a new instance of 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.

See Also:



58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/vcr/cassette.rb', line 58

def initialize(name, options = {})
  @name    = name
  @options = VCR.configuration.default_cassette_options.merge(options)
  @mutex   = Mutex.new

  assert_valid_options!
  extract_options
  raise_error_unless_valid_record_mode

  log "Initialized with options: #{@options.inspect}"
end

Instance Attribute Details

#clean_outdated_http_interactions ⇒ Boolean? (readonly)

Returns Should outdated interactions be recorded back to file.

Returns:

  • (Boolean, nil) —

    Should outdated interactions be recorded back to file



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

def clean_outdated_http_interactions
  @clean_outdated_http_interactions
end

#drop_unused_requests ⇒ Boolean (readonly)

Returns Should unused requests be dropped from the cassette?.

Returns:

  • (Boolean) —

    Should unused requests be dropped from the cassette?



50
51
52
 
# File 'lib/vcr/cassette.rb', line 50

def drop_unused_requests
  @drop_unused_requests
end

#erb ⇒ Boolean, Hash (readonly)

Returns The cassette’s ERB option. The file will be treated as an ERB template if this has a truthy value. A hash, if provided, will be used as local variables for the ERB template.

Returns:

  • (Boolean, Hash) —

    The cassette’s ERB option. The file will be treated as an ERB template if this has a truthy value. A hash, if provided, will be used as local variables for the ERB template.



41
42
43
 
# File 'lib/vcr/cassette.rb', line 41

def erb
  @erb
end

#match_requests_on ⇒ Array<Symbol, #call> (readonly)

Returns List of request matchers. Used to find a response from an existing HTTP interaction to play back.

Returns:

  • (Array<Symbol, #call>) —

    List of request matchers. Used to find a response from an existing HTTP interaction to play back.



36
37
38
 
# File 'lib/vcr/cassette.rb', line 36

def match_requests_on
  @match_requests_on
end

#name ⇒ #to_s (readonly)

Returns The name of the cassette. Used to determine the cassette’s file name.

Returns:

  • (#to_s) —

    The name of the cassette. Used to determine the cassette’s file name.

See Also:



21
22
23
 
# File 'lib/vcr/cassette.rb', line 21

def name
  @name
end

#re_record_interval ⇒ Integer? (readonly)

Returns How frequently (in seconds) the cassette should be re-recorded.

Returns:

  • (Integer, nil) —

    How frequently (in seconds) the cassette should be re-recorded.



44
45
46
 
# File 'lib/vcr/cassette.rb', line 44

def re_record_interval
  @re_record_interval
end

#record_mode ⇒ Symbol (readonly)

Returns The record mode. Determines whether the cassette records HTTP interactions, plays them back, or does both.

Returns:

  • (Symbol) —

    The record mode. Determines whether the cassette records HTTP interactions, plays them back, or does both.



25
26
27
 
# File 'lib/vcr/cassette.rb', line 25

def record_mode
  @record_mode
end

#record_on_error ⇒ Boolean (readonly)

Returns The cassette’s record_on_error mode. When the code that uses the cassette raises an error (for example a test failure) and record_on_error is set to false, no cassette will be recorded. This is useful when you are TDD’ing an API integration: when an error is raised that often means your request is invalid, so you don’t want the cassette to be recorded.

Returns:

  • (Boolean) —

    The cassette’s record_on_error mode. When the code that uses the cassette raises an error (for example a test failure) and record_on_error is set to false, no cassette will be recorded. This is useful when you are TDD’ing an API integration: when an error is raised that often means your request is invalid, so you don’t want the cassette to be recorded.



32
33
34
 
# File 'lib/vcr/cassette.rb', line 32

def record_on_error
  @record_on_error
end

#tags ⇒ Array<Symbol> (readonly)

Returns If set, VCR::Configuration#before_record and VCR::Configuration#before_playback hooks with a corresponding tag will apply.

Returns:



54
55
56
 
# File 'lib/vcr/cassette.rb', line 54

def tags
  @tags
end

Class Method Details

.const_missing(const) ⇒ Object 



17
18
19
20
21
 
# File 'lib/vcr/deprecations.rb', line 17

def Cassette.const_missing(const)
  return super unless const == :MissingERBVariableError
  warn "WARNING: `VCR::Cassette::MissingERBVariableError` is deprecated.  Use `VCR::Errors::MissingERBVariableError` instead."
  Errors::MissingERBVariableError
end

Instance Method Details

#eject(options = {}) ⇒ Object

Note:

This is not intended to be called directly. Use ‘VCR.eject_cassette` instead.

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

See Also:



78
79
80
81
82
83
84
 
# File 'lib/vcr/cassette.rb', line 78

def eject(options = {})
  write_recorded_interactions_to_disk if should_write_recorded_interactions_to_disk?

  if should_assert_no_unused_interactions? && !options[:skip_no_unused_interactions_assertion]
    http_interactions.assert_no_unused_interactions!
  end
end

#file ⇒ String

Note:

VCR will take care of sanitizing the cassette name to make it a valid file name.

Returns The file for this cassette.

Returns:

  • (String) —

    The file for this cassette.

Raises:

  • (NotImplementedError) —

    if the configured cassette persister does not support resolving file paths.



132
133
134
135
136
137
 
# File 'lib/vcr/cassette.rb', line 132

def file
  unless @persister.respond_to?(:absolute_path_to_file)
    raise NotImplementedError, "The configured cassette persister does not support resolving file paths"
  end
  @persister.absolute_path_to_file(storage_key)
end

#http_interactions ⇒ Object 



102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/vcr/cassette.rb', line 102

def http_interactions
  # Without this mutex, under threaded access, an HTTPInteractionList will overwrite
  # the first.
  @mutex.synchronize do
    @http_interactions ||= HTTPInteractionList.new \
      should_stub_requests? ? previously_recorded_interactions : [],
      match_requests_on,
      @allow_playback_repeats,
      @parent_list,
      log_prefix
  end
end

#linked? ⇒ Boolean

Returns false unless wrapped with LinkedCassette.

Returns:

  • (Boolean) —

    false unless wrapped with LinkedCassette



171
172
173
 
# File 'lib/vcr/cassette.rb', line 171

def linked?
  false
end

#new_recorded_interactions ⇒ Object 



124
125
126
 
# File 'lib/vcr/cassette.rb', line 124

def new_recorded_interactions
  @new_recorded_interactions ||= []
end

#originally_recorded_at ⇒ Time?

Returns The ‘recorded_at` time of the first HTTP interaction or nil if the cassette has no prior HTTP interactions.

Examples:


VCR.use_cassette("some cassette") do |cassette|
  Timecop.freeze(cassette.originally_recorded_at || Time.now) do
    # ...
  end
end

Returns:

  • (Time, nil) —

    The ‘recorded_at` time of the first HTTP interaction or nil if the cassette has no prior HTTP interactions.



166
167
168
 
# File 'lib/vcr/cassette.rb', line 166

def originally_recorded_at
  @originally_recorded_at ||= previously_recorded_interactions.map(&:recorded_at).min
end

#record_http_interaction(interaction) ⇒ Object 



116
117
118
119
120
121
 
# File 'lib/vcr/cassette.rb', line 116

def record_http_interaction(interaction)
  VCR::CassetteMutex.synchronize do
    log "Recorded HTTP interaction #{request_summary(interaction.request)} => #{response_summary(interaction.response)}"
    new_recorded_interactions << interaction
  end
end

#recording? ⇒ Boolean

Returns Whether or not the cassette is recording.

Returns:

  • (Boolean) —

    Whether or not the cassette is recording.



140
141
142
143
144
145
146
 
# File 'lib/vcr/cassette.rb', line 140

def recording?
  case record_mode
    when :none; false
    when :once; raw_cassette_bytes.to_s.empty?
    else true
  end
end

#run_failed! ⇒ Object 



87
88
89
 
# File 'lib/vcr/cassette.rb', line 87

def run_failed!
  @run_failed = true
end

#run_failed? ⇒ Boolean

Returns:

  • (Boolean) 


92
93
94
95
 
# File 'lib/vcr/cassette.rb', line 92

def run_failed?
  @run_failed = false unless defined?(@run_failed)
  @run_failed
end

#serializable_hash ⇒ Hash

Returns The hash that will be serialized when the cassette is written to disk.

Returns:

  • (Hash) —

    The hash that will be serialized when the cassette is written to disk.



149
150
151
152
153
154
 
# File 'lib/vcr/cassette.rb', line 149

def serializable_hash
  {
    "http_interactions" => interactions_to_record.map(&:to_hash),
    "recorded_with"     => "VCR #{VCR.version}"
  }
end

#should_write_recorded_interactions_to_disk? ⇒ Boolean

Returns:

  • (Boolean) 


97
98
99
 
# File 'lib/vcr/cassette.rb', line 97

def should_write_recorded_interactions_to_disk?
  !run_failed? || record_on_error
end