vcr 2.1.1 → 2.2.0

data/lib/vcr.rb

@@ -3,6 +3,7 @@ require 'vcr/util/variable_args_block_caller'
 
 require 'vcr/cassette'
 require 'vcr/cassette/serializers'
+require 'vcr/cassette/persisters'
 require 'vcr/configuration'
 require 'vcr/deprecations'
 require 'vcr/errors'
@@ -80,12 +81,19 @@ module VCR
   # @option options :allow_playback_repeats [Boolean] Whether or not to
   #  allow a single HTTP interaction to be played back multiple times.
   #  Defaults to false.
+  # @options options :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.
   # @option options :exclusive [Boolean] Whether or not to use only this
   #  cassette and to completely ignore any cassettes in the cassettes stack.
   #  Defaults to false.
   # @option options :serialize_with [Symbol] Which serializer to use.
   #  Valid values are :yaml, :syck, :psych, :json or any registered
   #  custom serializer. Defaults to :yaml.
+  # @option options :persist_with [Symbol] Which cassette persister to
+  #  use. Defaults to :file_system. You can also register and use a
+  #  custom persister.
   # @option options :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`.
@@ -292,6 +300,11 @@ module VCR
     @cassette_serializers ||= Cassette::Serializers.new
   end
 
+  # @private
+  def cassette_persisters
+    @cassette_persisters ||= Cassette::Persisters.new
+  end
+
   # @private
   def record_http_interaction(interaction)
     return unless cassette = current_cassette

data/lib/vcr/cassette.rb

@@ -1,8 +1,5 @@
-require 'fileutils'
-require 'erb'
-
 require 'vcr/cassette/http_interaction_list'
-require 'vcr/cassette/reader'
+require 'vcr/cassette/erb_renderer'
 require 'vcr/cassette/serializers'
 
 module VCR
@@ -46,35 +43,14 @@ module VCR
     # @param (see VCR#insert_cassette)
     # @see VCR#insert_cassette
     def initialize(name, options = {})
-      options = VCR.configuration.default_cassette_options.merge(options)
-      invalid_options = options.keys - [
-        :record, :erb, :match_requests_on, :re_record_interval, :tag, :tags,
-        :update_content_length_header, :allow_playback_repeats, :exclusive,
-        :serialize_with, :preserve_exact_body_bytes, :decode_compressed_response
-      ]
-
-      if invalid_options.size > 0
-        raise ArgumentError.new("You passed the following invalid options to VCR::Cassette.new: #{invalid_options.inspect}.")
-      end
-
-      @name                         = name
-      @record_mode                  = options[:record]
-      @erb                          = options[:erb]
-      @match_requests_on            = options[:match_requests_on]
-      @re_record_interval           = options[:re_record_interval]
-      @tags                         = Array(options.fetch(:tags) { options[:tag] })
-      @tags                         << :update_content_length_header if options[:update_content_length_header]
-      @tags                         << :preserve_exact_body_bytes if options[:preserve_exact_body_bytes]
-      @tags                         << :decode_compressed_response if options[:decode_compressed_response]
-      @allow_playback_repeats       = options[:allow_playback_repeats]
-      @exclusive                    = options[:exclusive]
-      @serializer                   = VCR.cassette_serializers[options[:serialize_with]]
-      @record_mode                  = :all if should_re_record?
-      @parent_list                  = @exclusive ? HTTPInteractionList::NullList : VCR.http_interactions
+      @name    = name
+      @options = VCR.configuration.default_cassette_options.merge(options)
 
+      assert_valid_options!
+      extract_options
       raise_error_unless_valid_record_mode
 
-      log "Initialized with options: #{options.inspect}"
+      log "Initialized with options: #{@options.inspect}"
     end
 
     # Ejects the current cassette. The cassette will no longer be used.
@@ -82,6 +58,7 @@ module VCR
     # disk.
     def eject
       write_recorded_interactions_to_disk
+      http_interactions.assert_no_unused_interactions! unless @allow_unused_http_interactions
     end
 
     # @private
@@ -106,17 +83,21 @@ module VCR
     end
 
     # @return [String] The file for this cassette.
+    # @raise [NotImplementedError] if the configured cassette persister
+    #  does not support resolving file paths.
     # @note VCR will take care of sanitizing the cassette name to make it a valid file name.
     def file
-      return nil unless VCR.configuration.cassette_library_dir
-      File.join(VCR.configuration.cassette_library_dir, "#{sanitized_name}.#{@serializer.file_extension}")
+      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
 
     # @return [Boolean] Whether or not the cassette is recording.
     def recording?
       case record_mode
         when :none; false
-        when :once; file.nil? || !File.size?(file)
+        when :once; raw_cassette_bytes.to_s.empty?
         else true
       end
     end
@@ -131,8 +112,44 @@ module VCR
 
   private
 
+    def assert_valid_options!
+      invalid_options = @options.keys - [
+        :record, :erb, :match_requests_on, :re_record_interval, :tag, :tags,
+        :update_content_length_header, :allow_playback_repeats, :allow_unused_http_interactions,
+        :exclusive, :serialize_with, :preserve_exact_body_bytes, :decode_compressed_response,
+        :persist_with
+      ]
+
+      if invalid_options.size > 0
+        raise ArgumentError.new("You passed the following invalid options to VCR::Cassette.new: #{invalid_options.inspect}.")
+      end
+    end
+
+    def extract_options
+      [:erb, :match_requests_on, :re_record_interval,
+       :allow_playback_repeats, :allow_unused_http_interactions, :exclusive].each do |name|
+        instance_variable_set("@#{name}", @options[name])
+      end
+
+      assign_tags
+
+      @record_mode = @options[:record]
+      @serializer  = VCR.cassette_serializers[@options[:serialize_with]]
+      @persister   = VCR.cassette_persisters[@options[:persist_with]]
+      @record_mode = :all if should_re_record?
+      @parent_list = @exclusive ? HTTPInteractionList::NullList : VCR.http_interactions
+    end
+
+    def assign_tags
+      @tags = Array(@options.fetch(:tags) { @options[:tag] })
+
+      [:update_content_length_header, :preserve_exact_body_bytes, :decode_compressed_response].each do |tag|
+        @tags << tag if @options[tag]
+      end
+    end
+
     def previously_recorded_interactions
-      @previously_recorded_interactions ||= if file && File.size?(file)
+      @previously_recorded_interactions ||= if !raw_cassette_bytes.to_s.empty?
         deserialized_hash['http_interactions'].map { |h| HTTPInteraction.from_hash(h) }.tap do |interactions|
           invoke_hook(:before_playback, interactions)
 
@@ -145,8 +162,8 @@ module VCR
       end
     end
 
-    def sanitized_name
-      name.to_s.gsub(/[^\w\-\/]+/, '_')
+    def storage_key
+      @storage_key ||= [name, @serializer.file_extension].join('.')
     end
 
     def raise_error_unless_valid_record_mode
@@ -159,7 +176,6 @@ module VCR
       return false unless @re_record_interval
       previously_recorded_at = earliest_interaction_recorded_at
       return false unless previously_recorded_at
-      return false unless File.exist?(file)
 
       now = Time.now
 
@@ -189,8 +205,8 @@ module VCR
       record_mode == :all
     end
 
-    def raw_yaml_content
-      VCR::Cassette::Reader.new(file, erb).read
+    def raw_cassette_bytes
+      @raw_cassette_bytes ||= VCR::Cassette::ERBRenderer.new(@persister[storage_key], erb, name).render
     end
 
     def merged_interactions
@@ -213,14 +229,11 @@ module VCR
     end
 
     def write_recorded_interactions_to_disk
-      return unless VCR.configuration.cassette_library_dir
       return if new_recorded_interactions.none?
       hash = serializable_hash
       return if hash["http_interactions"].none?
 
-      directory = File.dirname(file)
-      FileUtils.mkdir_p directory unless File.exist?(directory)
-      File.open(file, 'w') { |f| f.write @serializer.serialize(hash) }
+      @persister[storage_key] = @serializer.serialize(hash)
     end
 
     def invoke_hook(type, interactions)
@@ -232,7 +245,7 @@ module VCR
     end
 
     def deserialized_hash
-      @deserialized_hash ||= @serializer.deserialize(raw_yaml_content).tap do |hash|
+      @deserialized_hash ||= @serializer.deserialize(raw_cassette_bytes).tap do |hash|
         unless hash.is_a?(Hash) && hash['http_interactions'].is_a?(Array)
           raise Errors::InvalidCassetteFormatError.new \
             "#{file} does not appear to be a valid VCR 2.0 cassette. " +

data/lib/vcr/cassette/{reader.rb → erb_renderer.rb}

@@ -1,13 +1,15 @@
+require 'erb'
+
 module VCR
   class Cassette
     # @private
-    class Reader
-      def initialize(file_name, erb)
-        @file_name, @erb = file_name, erb
+    class ERBRenderer
+      def initialize(raw_template, erb, cassette_name=nil)
+        @raw_template, @erb, @cassette_name = raw_template, erb, cassette_name
       end
 
-      def read
-        return file_content unless use_erb?
+      def render
+        return @raw_template if @raw_template.nil? || !use_erb?
         binding = binding_for_variables if erb_variables
         template.result(binding)
       rescue NameError => e
@@ -20,7 +22,7 @@ module VCR
         example_hash = (erb_variables || {}).merge(e.name => 'some value')
 
         raise Errors::MissingERBVariableError.new(
-          "The ERB in the #{@file_name} cassette file references undefined variable #{e.name}.  " +
+          "The ERB in the #{@cassette_name} cassette file references undefined variable #{e.name}.  " +
           "Pass it to the cassette using :erb => #{ example_hash.inspect }."
         )
       end
@@ -33,12 +35,8 @@ module VCR
         @erb if @erb.is_a?(Hash)
       end
 
-      def file_content
-        @file_content ||= File.read(@file_name)
-      end
-
       def template
-        @template ||= ERB.new(file_content)
+        @template ||= ERB.new(@raw_template)
       end
 
       @@struct_cache = Hash.new do |hash, attributes|

data/lib/vcr/cassette/http_interaction_list.rb

@@ -54,8 +54,26 @@ module VCR
         @interactions.size
       end
 
+      # Checks if there are no unused interactions left.
+      #
+      # @raise [VCR::Errors::UnusedHTTPInteractionError] if not all interactions were played back.
+      def assert_no_unused_interactions!
+        return unless has_unused_interactions?
+
+        descriptions = @interactions.map do |i|
+          "  - #{request_summary(i.request)} => #{response_summary(i.response)}"
+        end.join("\n")
+
+        raise Errors::UnusedHTTPInteractionError, "There are unused HTTP interactions left in the cassette:\n#{descriptions}"
+      end
+
     private
 
+      # @return [Boolean] Whether or not there are unused interactions left in the list.
+      def has_unused_interactions?
+        @interactions.size > 0
+      end
+
       def request_summary(request)
         super(request, @request_matchers)
       end

data/lib/vcr/cassette/persisters.rb

@@ -0,0 +1,42 @@
+module VCR
+  class Cassette
+    # Keeps track of the cassette persisters in a hash-like object.
+    class Persisters
+      autoload :FileSystem, 'vcr/cassette/persisters/file_system'
+
+      # @private
+      def initialize
+        @persisters = {}
+      end
+
+      # Gets the named persister.
+      #
+      # @param name [Symbol] the name of the persister
+      # @return the named persister
+      # @raise [ArgumentError] if there is not a persister for the given name
+      def [](name)
+        @persisters.fetch(name) do |_|
+          @persisters[name] = case name
+            when :file_system then FileSystem
+            else raise ArgumentError, "The requested VCR cassette persister " +
+                                      "(#{name.inspect}) is not registered."
+          end
+        end
+      end
+
+      # Registers a persister.
+      #
+      # @param name [Symbol] the name of the persister
+      # @param value [#[], #[]=] the persister object. It must implement `[]` and `[]=`.
+      def []=(name, value)
+        if @persisters.has_key?(name)
+          warn "WARNING: There is already a VCR cassette persister " +
+               "registered for #{name.inspect}. Overriding it."
+        end
+
+        @persisters[name] = value
+      end
+
+    end
+  end
+end

data/lib/vcr/cassette/persisters/file_system.rb

@@ -0,0 +1,60 @@
+require 'fileutils'
+
+module VCR
+  class Cassette
+    class Persisters
+      # The only built-in cassette persister. Persists cassettes to the file system.
+      module FileSystem
+        extend self
+
+        # @private
+        attr_reader :storage_location
+
+        # @private
+        def storage_location=(dir)
+          FileUtils.mkdir_p(dir) if dir
+          @storage_location = dir ? absolute_path_for(dir) : nil
+        end
+
+        # Gets the cassette for the given storage key (file name).
+        #
+        # @param [String] file_name the file name
+        # @return [String] the cassette content
+        def [](file_name)
+          path = absolute_path_to_file(file_name)
+          return nil unless File.exist?(path)
+          File.read(path)
+        end
+
+        # Sets the cassette for the given storage key (file name).
+        #
+        # @param [String] file_name the file name
+        # @param [String] content the content to store
+        def []=(file_name, content)
+          path = absolute_path_to_file(file_name)
+          directory = File.dirname(path)
+          FileUtils.mkdir_p(directory) unless File.exist?(directory)
+          File.open(path, 'w') { |f| f.write(content) }
+        end
+
+        # @private
+        def absolute_path_to_file(file_name)
+          return nil unless storage_location
+          File.join(storage_location, sanitized_file_name_from(file_name))
+        end
+
+      private
+
+        def absolute_path_for(path)
+          Dir.chdir(path) { Dir.pwd }
+        end
+
+        def sanitized_file_name_from(file_name)
+          parts = file_name.to_s.split('.')
+          file_extension = '.' + parts.pop if parts.size > 1
+          parts.join('.').gsub(/[^\w\-\/]+/, '_') + file_extension.to_s
+        end
+      end
+    end
+  end
+end

data/lib/vcr/cassette/serializers.rb

@@ -33,7 +33,7 @@ module VCR
       #
       # @param name [Symbol] the name of the serializer
       # @param value [#file_extension, #serialize, #deserialize] the serializer object. It must implement
-      #  +file_extension()+, +serialize(Hash)+ and +deserialize(String)+.
+      #  `file_extension()`, `serialize(Hash)` and `deserialize(String)`.
       def []=(name, value)
         if @serializers.has_key?(name)
           warn "WARNING: There is already a VCR cassette serializer registered for #{name.inspect}. Overriding it."

data/lib/vcr/cassette/serializers/json.rb

@@ -36,7 +36,7 @@ module VCR
         # Deserializes the given string using `MultiJson`.
         #
         # @param [String] string the JSON string
-        # @param [Hash] hash the deserialized object
+        # @return [Hash] the deserialized object
         def deserialize(string)
           handle_encoding_errors do
             MultiJson.decode(string)

data/lib/vcr/cassette/serializers/psych.rb

@@ -35,7 +35,7 @@ module VCR
         # Deserializes the given string using Psych.
         #
         # @param [String] string the YAML string
-        # @param [Hash] hash the deserialized object
+        # @return [Hash] the deserialized object
         def deserialize(string)
           handle_encoding_errors do
             ::Psych.load(string)

data/lib/vcr/cassette/serializers/syck.rb

@@ -35,7 +35,7 @@ module VCR
         # Deserializes the given string using Syck.
         #
         # @param [String] string the YAML string
-        # @param [Hash] hash the deserialized object
+        # @return [Hash] the deserialized object
         def deserialize(string)
           handle_encoding_errors do
             using_syck { ::YAML.load(string) }

data/lib/vcr/cassette/serializers/yaml.rb

@@ -37,7 +37,7 @@ module VCR
         # Deserializes the given string using YAML.
         #
         # @param [String] string the YAML string
-        # @param [Hash] hash the deserialized object
+        # @return [Hash] the deserialized object
         def deserialize(string)
           handle_encoding_errors do
             ::YAML.load(string)