class VCR::Configuration
Stores the VCR configuration.
Attributes
Determines how VCR treats HTTP requests that are made when no VCR cassette is in use. When set to `true`, requests made when there is no VCR cassette in use will be allowed. When set to `false` (the default), an {VCR::Errors::UnhandledHTTPRequestError} will be raised for any HTTP request made when there is no cassette in use.
@overload #allow_http_connections_when_no_cassette?
@return [Boolean] whether or not HTTP connections are allowed when there is no cassette.
@overload #allow_http_connections_when_no_cassette=
@param value [Boolean] sets whether or not to allow HTTP connections when there is no cassette.
An object to log debug output to.
@overload #debug_logger
@return [#puts] the logger
@overload #debug_logger=(logger)
@param logger [#puts] the logger @return [void]
@example
VCR.configure do |c| c.debug_logger = $stderr end
@example
VCR.configure do |c| c.debug_logger = File.open('vcr.log', 'w') end
Default options to apply to every cassette.
@overload #default_cassette_options
@return [Hash] default options to apply to every cassette
@overload #default_cassette_options=(options)
@param options [Hash] default options to apply to every cassette @return [void]
@example
VCR.configure do |c| c.default_cassette_options = { :record => :new_episodes } end
@note {VCR#insert_cassette} for the list of valid options.
Sets a parser for VCR to use when parsing URIs. The new parser must implement a method `parse` that returns an instance of the URI object. This URI object must implement the following interface:
-
`scheme # => String`
-
`host # => String`
-
`port # => Fixnum`
-
`path # => String`
-
`query # => String`
-
`#port=`
-
`#query=`
-
`#to_s # => String`
-
`#== # => Boolean`
The `#==` method must return true if both URI objects represent the same URI.
This defaults to `URI` from the ruby standard library.
@overload #uri_parser
@return [#parse] the current URI parser object
@overload #uri_parser=
@param value [#parse] sets the uri_parser
Public Class Methods
# File lib/vcr/configuration.rb, line 444 def initialize @allow_http_connections_when_no_cassette = nil @default_cassette_options = { :record => :once, :match_requests_on => RequestMatcherRegistry::DEFAULT_MATCHERS, :allow_unused_http_interactions => true, :serialize_with => :yaml, :persist_with => :file_system } self.uri_parser = URI self.debug_logger = NullDebugLogger register_built_in_hooks end
Public Instance Methods
Adds a callback that will be called with each HTTP request after it is complete.
@example
VCR.configure do |c| c.after_http_request(:ignored?) do |request, response| puts "Request: #{request.method} #{request.uri}" puts "Response: #{response.status.code}" end end
@param filters [optional splat of to_proc] one or more filters to apply.
The objects provided will be converted to procs using `#to_proc`. If provided, the callback will only be invoked if these procs all return `true`.
@yield the callback @yieldparam request [VCR::Request::Typed] the request that is being made @yieldparam response [VCR::Response] the response from the request @see before_http_request @see around_http_request
# File lib/vcr/configuration.rb, line 340 def after_http_request(*filters) super(*filters.map { |f| request_filter_from(f) }) end
@private (documented above)
# File lib/vcr/configuration.rb, line 123 def allow_http_connections_when_no_cassette? !!@allow_http_connections_when_no_cassette end
Adds a callback that will be executed around each HTTP request.
@example
VCR.configure do |c| c.around_http_request(lambda {|r| r.uri =~ /api.geocoder.com/}) do |request| # extract an address like "1700 E Pine St, Seattle, WA" # from a query like "address=1700+E+Pine+St%2C+Seattle%2C+WA" address = CGI.unescape(URI(request.uri).query.split('=').last) VCR.use_cassette("geocoding/#{address}", &request) end end
@yield the callback @yieldparam request [VCR::Request::FiberAware] the request that is being made @raise [VCR::Errors::NotSupportedError] if the fiber library cannot be loaded. @param filters [optional splat of to_proc] one or more filters to apply.
The objects provided will be converted to procs using `#to_proc`. If provided, the callback will only be invoked if these procs all return `true`.
@note This method can only be used on ruby interpreters that support
fibers (i.e. 1.9+). On 1.8 you can use separate `before_http_request` and `after_http_request` hooks.
@note You must call `request.proceed` or pass the request as a proc on to a
method that yields to a block (i.e. `some_method(&request)`).
@see before_http_request @see after_http_request
# File lib/vcr/configuration.rb, line 369 def around_http_request(*filters, &block) require 'fiber' rescue LoadError raise Errors::NotSupportedError.new "VCR::Configuration#around_http_request requires fibers, " + "which are not available on your ruby intepreter." else fiber, hook_allowed, hook_decaration = nil, false, caller.first before_http_request(*filters) do |request| hook_allowed = true fiber = start_new_fiber_for(request, block) end after_http_request(lambda { hook_allowed }) do |request, response| resume_fiber(fiber, response, hook_decaration) end end
Adds a callback that will be called before a previously recorded HTTP interaction is loaded for playback.
@example
VCR.configure do |c| # Don't playback transient 5xx errors c.before_playback do |interaction| interaction.ignore! if interaction.response.status.code >= 500 end # Change a response header for playback c.before_playback(:twilio) do |interaction| interaction.response.headers['X-Foo-Bar'] = 'Bazz' end end
@param tag [(optional) Symbol] Used to apply this hook to only cassettes that match
the given tag.
@yield the callback @yieldparam interaction [VCR::HTTPInteraction::HookAware] The interaction that is being
loaded.
@yieldparam cassette [(optional) VCR::Cassette] The current cassette. @see before_record
# File lib/vcr/configuration.rb, line 299 def before_playback(tag = nil, &block) super(tag_filter_from(tag), &block) end
Adds a callback that will be called before the recorded HTTP interactions are serialized and written to disk.
@example
VCR.configure do |c| # Don't record transient 5xx errors c.before_record do |interaction| interaction.ignore! if interaction.response.status.code >= 500 end # Modify the response body for cassettes tagged with :twilio c.before_record(:twilio) do |interaction| interaction.response.body.downcase! end end
@param tag [(optional) Symbol] Used to apply this hook to only cassettes that match
the given tag.
@yield the callback @yieldparam interaction [VCR::HTTPInteraction::HookAware] The interaction that will be
serialized and written to disk.
@yieldparam cassette [(optional) VCR::Cassette] The current cassette. @see before_playback
# File lib/vcr/configuration.rb, line 271 def before_record(tag = nil, &block) super(tag_filter_from(tag), &block) end
Gets the directory to read cassettes from and write cassettes to.
@return [String] the directory to read cassettes from and write cassettes to
# File lib/vcr/configuration.rb, line 14 def cassette_library_dir VCR.cassette_persisters[:file_system].storage_location end
Sets the directory to read cassettes from and writes cassettes to.
@example
VCR.configure do |c| c.cassette_library_dir = 'spec/cassettes' end
@param dir [String] the directory to read cassettes from and write cassettes to @return [void] @note This is only necessary if you use the `:file_system`
cassette persister (the default).
# File lib/vcr/configuration.rb, line 29 def cassette_library_dir=(dir) VCR.cassette_persisters[:file_system].storage_location = dir end
Gets the registry of cassette persisters. Use it to register a custom persister.
@example
VCR.configure do |c| c.cassette_persisters[:my_custom_persister] = my_custom_persister end
@return [VCR::Cassette::Persisters] the cassette persister registry object. @note Custom persisters must implement the following interface:
* `persister[storage_key]` # returns previously persisted content * `persister[storage_key] = content` # persists given content
# File lib/vcr/configuration.rb, line 243 def cassette_persisters VCR.cassette_persisters end
Gets the registry of cassette serializers. Use it to register a custom serializer.
@example
VCR.configure do |c| c.cassette_serializers[:my_custom_serializer] = my_custom_serializer end
@return [VCR::Cassette::Serializers] the cassette serializer registry object. @note Custom serializers must implement the following interface:
* %xfile_extension # => String` * %xserialize(Hash) # => String` * %xdeserialize(String) # => Hash`
# File lib/vcr/configuration.rb, line 227 def cassette_serializers VCR.cassette_serializers end
Sets the default options that apply to every cassette.
# File lib/vcr/configuration.rb, line 48 def default_cassette_options=(overrides) @default_cassette_options.merge!(overrides) end
Sets up a {#before_record} and a {#before_playback} hook that will insert a placeholder string in the cassette in place of another string. You can use this as a generic way to interpolate a variable into the cassette for a unique string. It's particularly useful for unique sensitive strings like API keys and passwords.
@example
VCR.configure do |c| # Put "<GITHUB_API_KEY>" in place of the actual API key in # our cassettes so we don't have to commit to source control. c.filter_sensitive_data('<GITHUB_API_KEY>') { GithubClient.api_key } # Put a "<USER_ID>" placeholder variable in our cassettes tagged with # :user_cassette since it can be different for different test runs. c.define_cassette_placeholder('<USER_ID>', :user_cassette) { User.last.id } end
@param placeholder [String] The placeholder string. @param tag [Symbol] Set this to apply this only to cassettes
with a matching tag; otherwise it will apply to every cassette.
@yield block that determines what string to replace @yieldparam interaction [(optional) VCR::HTTPInteraction::HookAware] the HTTP interaction @yieldreturn the string to replace
# File lib/vcr/configuration.rb, line 199 def define_cassette_placeholder(placeholder, tag = nil, &block) before_record(tag) do |interaction| orig_text = call_block(block, interaction) log "before_record: replacing #{orig_text.inspect} with #{placeholder.inspect}" interaction.filter!(orig_text, placeholder) end before_playback(tag) do |interaction| orig_text = call_block(block, interaction) log "before_playback: replacing #{placeholder.inspect} with #{orig_text.inspect}" interaction.filter!(placeholder, orig_text) end end
Configures which libraries VCR will hook into to intercept HTTP requests.
@example
VCR.configure do |c| c.hook_into :fakeweb, :typhoeus end
@param hooks [Array<Symbol>] List of libraries. Valid values are
`:fakeweb`, `:webmock`, `:typhoeus`, `:excon` and `:faraday`.
@raise [ArgumentError] when given an unsupported library name. @raise [VCR::Errors::LibraryVersionTooLowError] when the version
of a library you are using is too low for VCR to support.
@note `:fakeweb` and `:webmock` cannot both be used since they both monkey patch
`Net::HTTP`. Otherwise, you can use any combination of these.
# File lib/vcr/configuration.rb, line 66 def hook_into(*hooks) hooks.each { |a| load_library_hook(a) } invoke_hook(:after_library_hooks_loaded) end
Specifies host(s) that VCR should ignore.
@param hosts [Array<String>] List of hosts to ignore @see ignore_localhost= @see ignore_request
# File lib/vcr/configuration.rb, line 76 def ignore_hosts(*hosts) VCR.request_ignorer.ignore_hosts(*hosts) end
Sets whether or not VCR should ignore localhost requests.
@param value [Boolean] the value to set @see ignore_hosts @see ignore_request
# File lib/vcr/configuration.rb, line 86 def ignore_localhost=(value) VCR.request_ignorer.ignore_localhost = value end
Defines what requests to ignore using a block.
@example
VCR.configure do |c| c.ignore_request do |request| uri = URI(request.uri) # ignore only localhost requests to port 7500 uri.host == 'localhost' && uri.port == 7500 end end
@yield the callback @yieldparam request [VCR::Request] the HTTP request @yieldreturn [Boolean] whether or not to ignore the request
# File lib/vcr/configuration.rb, line 104 def ignore_request(&block) VCR.request_ignorer.ignore_request(&block) end
@return [Boolean] whether or not the body of the given HTTP message should
be base64 encoded during serialization in order to preserve the bytes exactly.
@param http_message [#body, headers] the `VCR::Request` or `VCR::Response` object being serialized @see preserve_exact_body_bytes
# File lib/vcr/configuration.rb, line 438 def preserve_exact_body_bytes_for?(http_message) invoke_hook(:preserve_exact_body_bytes, http_message, VCR.current_cassette).any? end
Registers a request matcher for later use.
@example
VCR.configure do |c| c.register_request_matcher :port do |request_1, request_2| URI(request_1.uri).port == URI(request_2.uri).port end end VCR.use_cassette("my_cassette", :match_requests_on => [:method, :host, :port]) do # ... end
@param name [Symbol] the name of the request matcher @yield the request matcher @yieldparam request_1 [VCR::Request] One request @yieldparam request_2 [VCR::Request] The other request @yieldreturn [Boolean] whether or not these two requests should be considered
equivalent
# File lib/vcr/configuration.rb, line 172 def register_request_matcher(name, &block) VCR.request_matchers.register(name, &block) end
Private Instance Methods
# File lib/vcr/configuration.rb, line 460 def load_library_hook(hook) file = "vcr/library_hooks/#{hook}" require file rescue LoadError => e raise e unless e.message.include?(file) # in case FakeWeb/WebMock/etc itself is not available raise ArgumentError.new("#{hook.inspect} is not a supported VCR HTTP library hook.") end
# File lib/vcr/configuration.rb, line 506 def log_prefix "[VCR::Configuration] " end
# File lib/vcr/configuration.rb, line 492 def register_built_in_hooks before_playback(:update_content_length_header) do |interaction| interaction.response.update_content_length_header end before_record(:decode_compressed_response) do |interaction| interaction.response.decompress if interaction.response.compressed? end preserve_exact_body_bytes do |http_message, cassette| cassette && cassette.tags.include?(:preserve_exact_body_bytes) end end
# File lib/vcr/configuration.rb, line 487 def request_filter_from(object) return object unless object.is_a?(Symbol) lambda { |arg| arg.send(object) } end
# File lib/vcr/configuration.rb, line 468 def resume_fiber(fiber, response, hook_declaration) fiber.resume(response) rescue FiberError raise Errors::AroundHTTPRequestHookError.new "Your around_http_request hook declared at #{hook_declaration}" + " must call #proceed on the yielded request but did not." end
# File lib/vcr/configuration.rb, line 476 def start_new_fiber_for(request, block) Fiber.new(&block).tap do |fiber| fiber.resume(Request::FiberAware.new(request)) end end
# File lib/vcr/configuration.rb, line 482 def tag_filter_from(tag) return lambda { true } unless tag lambda { |_, cassette| cassette.tags.include?(tag) } end