mustwin-vcr 2.9.3

data/lib/vcr.rb

@@ -0,0 +1,347 @@
+require 'vcr/util/logger'
+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'
+require 'vcr/library_hooks'
+require 'vcr/request_ignorer'
+require 'vcr/request_matcher_registry'
+require 'vcr/structs'
+require 'vcr/version'
+
+# The main entry point for VCR.
+# @note This module is extended onto itself; thus, the methods listed
+#  here as instance methods are available directly off of VCR.
+module VCR
+  include VariableArgsBlockCaller
+  include Errors
+
+  extend self
+
+  autoload :CucumberTags,       'vcr/test_frameworks/cucumber'
+  autoload :InternetConnection, 'vcr/util/internet_connection'
+
+  module RSpec
+    autoload :Metadata,              'vcr/test_frameworks/rspec'
+    autoload :Macros,                'vcr/deprecations'
+  end
+
+  module Middleware
+    autoload :Faraday,           'vcr/middleware/faraday'
+    autoload :Rack,              'vcr/middleware/rack'
+  end
+
+  # The currently active cassette.
+  #
+  # @return [nil, VCR::Cassette] The current cassette or nil if there is
+  #  no current cassette.
+  def current_cassette
+    cassettes.last
+  end
+
+  # 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.
+  #
+  # @example
+  #   VCR.insert_cassette('twitter', :record => :new_episodes)
+  #
+  #   # ...later, after making an HTTP request:
+  #
+  #   VCR.eject_cassette
+  #
+  # @param name [#to_s] The name of the cassette. VCR will sanitize
+  #                     this to ensure it is a valid file name.
+  # @param options [Hash] The cassette options. The given options will
+  #  be merged with the configured default_cassette_options.
+  # @option options :record [:all, :none, :new_episodes, :once] The record mode.
+  # @option options :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.
+  # @option options :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.
+  # @option options :re_record_interval [Integer] When given, the
+  #  cassette will be re-recorded at the given interval, in seconds.
+  # @option options :tag [Symbol] Used to apply tagged `before_record`
+  #  and `before_playback` hooks to the cassette.
+  # @option options :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.
+  # @option options :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.
+  # @option options :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.
+  # @option options :allow_playback_repeats [Boolean] Whether or not to
+  #  allow a single HTTP interaction to be played back multiple times.
+  #  Defaults to false.
+  # @option 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. 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).
+  # @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`.
+  #
+  # @return [VCR::Cassette] the inserted cassette
+  #
+  # @raise [ArgumentError] when the given cassette is already being used.
+  # @raise [VCR::Errors::TurnedOffError] when VCR has been turned off
+  #  without using the :ignore_cassettes option.
+  # @raise [VCR::Errors::MissingERBVariableError] when the `:erb` option
+  #  is used and the ERB template requires variables that you did not provide.
+  #
+  # @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.
+  #
+  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
+
+  # Ejects the current cassette. The cassette will no longer be used.
+  # In addition, any newly recorded HTTP interactions will be written to
+  # disk.
+  #
+  # @param options [Hash] Eject options.
+  # @option options :skip_no_unused_interactions_assertion [Boolean]
+  #  If `true` is given, this will skip the "no unused HTTP interactions"
+  #  assertion enabled by the `:allow_unused_http_interactions => false`
+  #  cassette option. This is intended for use when your test has had
+  #  an error, but your test framework has already handled it.
+  # @return [VCR::Cassette, nil] the ejected cassette if there was one
+  def eject_cassette(options = {})
+    cassette = cassettes.last
+    cassette.eject(options) if cassette
+    cassette
+  ensure
+    cassettes.pop
+  end
+
+  # Inserts a cassette using the given name and options, runs the given
+  # block, and ejects the cassette.
+  #
+  # @example
+  #   VCR.use_cassette('twitter', :record => :new_episodes) do
+  #     # make an HTTP request
+  #   end
+  #
+  # @param (see #insert_cassette)
+  # @option (see #insert_cassette)
+  # @yield Block to run while this cassette is in use.
+  # @yieldparam cassette [(optional) VCR::Cassette] the cassette that has
+  #  been inserted.
+  # @raise (see #insert_cassette)
+  # @return [void]
+  # @see #insert_cassette
+  # @see #eject_cassette
+  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
+
+  # Used to configure VCR.
+  #
+  # @example
+  #    VCR.configure do |c|
+  #      c.some_config_option = true
+  #    end
+  #
+  # @yield the configuration block
+  # @yieldparam config [VCR::Configuration] the configuration object
+  # @return [void]
+  def configure
+    yield configuration
+  end
+
+  # @return [VCR::Configuration] the VCR configuration.
+  def configuration
+    @configuration ||= Configuration.new
+  end
+
+  # Sets up `Before` and `After` cucumber hooks in order to
+  # use VCR with particular cucumber tags.
+  #
+  # @example
+  #   VCR.cucumber_tags do |t|
+  #     t.tags "tag1", "tag2"
+  #     t.tag "@some_other_tag", :record => :new_episodes
+  #   end
+  #
+  # @yield the cucumber tags configuration block
+  # @yieldparam t [VCR::CucumberTags] Cucumber tags config object
+  # @return [void]
+  # @see VCR::CucumberTags#tags
+  def cucumber_tags(&block)
+    main_object = eval('self', block.binding)
+    yield VCR::CucumberTags.new(main_object)
+  end
+
+  # Turns VCR off for the duration of a block.
+  #
+  # @param (see #turn_off!)
+  # @return [void]
+  # @raise (see #turn_off!)
+  # @see #turn_off!
+  # @see #turn_on!
+  # @see #turned_on?
+  def turned_off(options = {})
+    turn_off!(options)
+
+    begin
+      yield
+    ensure
+      turn_on!
+    end
+  end
+
+  # Turns VCR off, so that it no longer handles every HTTP request.
+  #
+  # @param options [Hash] hash of options
+  # @option 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.
+  #
+  # @return [void]
+  # @raise [VCR::Errors::CassetteInUseError] if there is currently a cassette in use
+  # @raise [ArgumentError] if you pass an invalid option
+  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
+
+  # Turns on VCR, if it has previously been turned off.
+  # @return [void]
+  # @see #turn_off!
+  # @see #turned_off
+  # @see #turned_on?
+  def turn_on!
+    @turned_off = false
+  end
+
+  # @return whether or not VCR is turned on
+  # @note Normally VCR is _always_ turned on; it will only be off if you have
+  #  explicitly turned it off.
+  # @see #turn_on!
+  # @see #turn_off!
+  # @see #turned_off
+  def turned_on?
+    !@turned_off
+  end
+
+  # @private
+  def http_interactions
+    return current_cassette.http_interactions if current_cassette
+    VCR::Cassette::HTTPInteractionList::NullList
+  end
+
+  # @private
+  def real_http_connections_allowed?
+    return current_cassette.recording? if current_cassette
+    !!(configuration.allow_http_connections_when_no_cassette? || @turned_off)
+  end
+
+  # @return [RequestMatcherRegistry] the request matcher registry
+  def request_matchers
+    @request_matchers ||= RequestMatcherRegistry.new
+  end
+
+  # @private
+  def request_ignorer
+    @request_ignorer ||= RequestIgnorer.new
+  end
+
+  # @private
+  def library_hooks
+    @library_hooks ||= LibraryHooks.new
+  end
+
+  # @private
+  def cassette_serializers
+    @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
+    return if VCR.request_ignorer.ignore?(interaction.request)
+
+    cassette.record_http_interaction(interaction)
+  end
+
+private
+
+  def ignore_cassettes?
+    @ignore_cassettes
+  end
+
+  def cassettes
+    @cassettes ||= []
+  end
+
+  def initialize_ivars
+    @turned_off = false
+  end
+
+  initialize_ivars # to avoid warnings
+end

data/lib/vcr/cassette.rb

@@ -0,0 +1,291 @@
+require 'vcr/cassette/http_interaction_list'
+require 'vcr/cassette/erb_renderer'
+require 'vcr/cassette/serializers'
+
+module VCR
+  # The media VCR uses to store HTTP interactions for later re-use.
+  class Cassette
+    include Logger::Mixin
+
+    # 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.
+    VALID_RECORD_MODES = [:all, :none, :new_episodes, :once]
+
+    # @return [#to_s] The name of the cassette. Used to determine the cassette's file name.
+    # @see #file
+    attr_reader :name
+
+    # @return [Symbol] The record mode. Determines whether the cassette records HTTP interactions,
+    #  plays them back, or does both.
+    attr_reader :record_mode
+
+    # @return [Array<Symbol, #call>] List of request matchers. Used to find a response from an
+    #  existing HTTP interaction to play back.
+    attr_reader :match_requests_on
+
+    # @return [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.
+    attr_reader :erb
+
+    # @return [Integer, nil] How frequently (in seconds) the cassette should be re-recorded.
+    attr_reader :re_record_interval
+
+    # @return [Array<Symbol>] If set, {VCR::Configuration#before_record} and
+    #  {VCR::Configuration#before_playback} hooks with a corresponding tag will apply.
+    attr_reader :tags
+
+    # @param (see VCR#insert_cassette)
+    # @see VCR#insert_cassette
+    def initialize(name, options = {})
+      @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}"
+    end
+
+    # Ejects the current cassette. The cassette will no longer be used.
+    # In addition, any newly recorded HTTP interactions will be written to
+    # disk.
+    #
+    # @note This is not intended to be called directly. Use `VCR.eject_cassette` instead.
+    #
+    # @param (see VCR#eject_casssette)
+    # @see VCR#eject_cassette
+    def eject(options = {})
+      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
+
+    # @private
+    def http_interactions
+      @http_interactions ||= HTTPInteractionList.new \
+        should_stub_requests? ? previously_recorded_interactions : [],
+        match_requests_on,
+        @allow_playback_repeats,
+        @parent_list,
+        log_prefix
+    end
+
+    # @private
+    def record_http_interaction(interaction)
+      log "Recorded HTTP interaction #{request_summary(interaction.request)} => #{response_summary(interaction.response)}"
+      new_recorded_interactions << interaction
+    end
+
+    # @private
+    def new_recorded_interactions
+      @new_recorded_interactions ||= []
+    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
+      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; raw_cassette_bytes.to_s.empty?
+        else true
+      end
+    end
+
+    # @return [Hash] The hash that will be serialized when the cassette is written to disk.
+    def serializable_hash
+      {
+        "http_interactions" => interactions_to_record.map(&:to_hash),
+        "recorded_with"     => "VCR #{VCR.version}"
+      }
+    end
+
+    # @return [Time, nil] The `recorded_at` time of the first HTTP interaction
+    #                     or nil if the cassette has no prior HTTP interactions.
+    #
+    # @example
+    #
+    #   VCR.use_cassette("some cassette") do |cassette|
+    #     Timecop.freeze(cassette.originally_recorded_at || Time.now) do
+    #       # ...
+    #     end
+    #   end
+    def originally_recorded_at
+      @originally_recorded_at ||= previously_recorded_interactions.map(&:recorded_at).min
+    end
+
+  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 !raw_cassette_bytes.to_s.empty?
+        deserialized_hash['http_interactions'].map { |h| HTTPInteraction.from_hash(h) }.tap do |interactions|
+          invoke_hook(:before_playback, interactions)
+
+          interactions.reject! do |i|
+            i.request.uri.is_a?(String) && VCR.request_ignorer.ignore?(i.request)
+          end
+        end
+      else
+        []
+      end
+    end
+
+    def storage_key
+      @storage_key ||= [name, @serializer.file_extension].join('.')
+    end
+
+    def raise_error_unless_valid_record_mode
+      unless VALID_RECORD_MODES.include?(record_mode)
+        raise ArgumentError.new("#{record_mode} is not a valid cassette record mode.  Valid modes are: #{VALID_RECORD_MODES.inspect}")
+      end
+    end
+
+    def should_re_record?
+      return false unless @re_record_interval
+      return false unless originally_recorded_at
+
+      now = Time.now
+
+      (originally_recorded_at + @re_record_interval < now).tap do |value|
+        info = "previously recorded at: '#{originally_recorded_at}'; now: '#{now}'; interval: #{@re_record_interval} seconds"
+
+        if !value
+          log "Not re-recording since the interval has not elapsed (#{info})."
+        elsif InternetConnection.available?
+          log "re-recording (#{info})."
+        else
+          log "Not re-recording because no internet connection is available (#{info})."
+          return false
+        end
+      end
+    end
+
+    def should_stub_requests?
+      record_mode != :all
+    end
+
+    def should_remove_matching_existing_interactions?
+      record_mode == :all
+    end
+
+    def should_assert_no_unused_interactions?
+      !(@allow_unused_http_interactions || $!)
+    end
+
+    def raw_cassette_bytes
+      @raw_cassette_bytes ||= VCR::Cassette::ERBRenderer.new(@persister[storage_key], erb, name).render
+    end
+
+    def merged_interactions
+      old_interactions = previously_recorded_interactions
+
+      if should_remove_matching_existing_interactions?
+        new_interaction_list = HTTPInteractionList.new(new_recorded_interactions, match_requests_on)
+        old_interactions = old_interactions.reject do |i|
+          new_interaction_list.response_for(i.request)
+        end
+      end
+
+      old_interactions + new_recorded_interactions
+    end
+
+    def interactions_to_record
+      # We deep-dup the interactions by roundtripping them to/from a hash.
+      # This is necessary because `before_record` can mutate the interactions.
+      merged_interactions.map { |i| HTTPInteraction.from_hash(i.to_hash) }.tap do |interactions|
+        invoke_hook(:before_record, interactions)
+      end
+    end
+
+    def write_recorded_interactions_to_disk
+      return if new_recorded_interactions.none?
+      hash = serializable_hash
+      return if hash["http_interactions"].none?
+
+      @persister[storage_key] = @serializer.serialize(hash)
+    end
+
+    def invoke_hook(type, interactions)
+      interactions.delete_if do |i|
+        i.hook_aware.tap do |hw|
+          VCR.configuration.invoke_hook(type, hw, self)
+        end.ignored?
+      end
+    end
+
+    def deserialized_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. " +
+            "VCR 1.x cassettes are not valid with VCR 2.0. When upgrading from " +
+            "VCR 1.x, it is recommended that you delete all your existing cassettes and " +
+            "re-record them, or use the provided vcr:migrate_cassettes rake task to migrate " +
+            "them. For more info, see the VCR upgrade guide."
+        end
+      end
+    end
+
+    def log_prefix
+      @log_prefix ||= "[Cassette: '#{name}'] "
+    end
+
+    def request_summary(request)
+      super(request, match_requests_on)
+    end
+  end
+end