Class: VCR::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/vcr/configuration.rb,
lib/vcr/deprecations.rb

Overview

Stores the VCR configuration.

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Instance Attribute Details

- (Boolean) allow_http_connections_when_no_cassette? (writeonly) - (Object) allow_http_connections_when_no_cassette= (writeonly)

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 Errors::UnhandledHTTPRequestError will be raised for any HTTP request made when there is no cassette in use.

Overloads:

  • - (Boolean) allow_http_connections_when_no_cassette?

    Whether or not HTTP connections are allowed when there is no cassette.

    Returns:

    • (Boolean) —

      whether or not HTTP connections are allowed when there is no cassette.

  • - (Object) allow_http_connections_when_no_cassette=

    Parameters:

    • value (Boolean) —

      sets whether or not to allow HTTP connections when there is no cassette.



121
122
123
 
# File 'lib/vcr/configuration.rb', line 121

def allow_http_connections_when_no_cassette=(value)
  @allow_http_connections_when_no_cassette = value
end

- (#puts) debug_logger - debug_logger=(logger)

An object to log debug output to.

Examples:

VCR.configure do |c|
  c.debug_logger = $stderr
end
VCR.configure do |c|
  c.debug_logger = File.open('vcr.log', 'w')
end

Overloads:

  • - (#puts) debug_logger

    The logger

    Returns:

    • (#puts) —

      the logger

  • - debug_logger=(logger)

    This method returns an undefined value.

    Parameters:

    • logger (#puts) —

      the logger



408
409
410
 
# File 'lib/vcr/configuration.rb', line 408

def debug_logger
  @debug_logger
end

- (Hash) default_cassette_options - default_cassette_options=(options)

Note:

VCR#insert_cassette for the list of valid options.

Default options to apply to every cassette.

Examples:

VCR.configure do |c|
  c.default_cassette_options = { :record => :new_episodes }
end

Overloads:

  • - (Hash) default_cassette_options

    Default options to apply to every cassette

    Returns:

    • (Hash) —

      default options to apply to every cassette

  • - default_cassette_options=(options)

    This method returns an undefined value.

    Parameters:

    • options (Hash) —

      default options to apply to every cassette



45
46
47
 
# File 'lib/vcr/configuration.rb', line 45

def default_cassette_options
  @default_cassette_options
end

- (#parse) uri_parser - (Object) uri_parser=

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.

Overloads:

  • - (#parse) uri_parser

    The current URI parser object

    Returns:

    • (#parse) —

      the current URI parser object

  • - (Object) uri_parser=

    Parameters:

    • value (#parse) —

      sets the uri_parser



151
152
153
 
# File 'lib/vcr/configuration.rb', line 151

def uri_parser
  @uri_parser
end

Instance Method Details

- (Object) after_http_request(*filters) {|request, response| ... }

Adds a callback that will be called with each HTTP request after it is complete.

Examples:

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

Parameters:

  • 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.

Yields:

  • the callback

Yield Parameters:

See Also:



340
341
342
 
# File 'lib/vcr/configuration.rb', line 340

def after_http_request(*filters)
  super(*filters.map { |f| request_filter_from(f) })
end

- (Object) around_http_request(*filters) {|request| ... }

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)).

Adds a callback that will be executed around each HTTP request.

Examples:

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

Parameters:

  • 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.

Yields:

  • the callback

Yield Parameters:

Raises:

See Also:



369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
 
# 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

- (Object) before_playback(tag = nil) {|interaction, cassette| ... }

Adds a callback that will be called before a previously recorded HTTP interaction is loaded for playback.

Examples:

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

Parameters:

  • tag ((optional) Symbol) (defaults to: nil) —

    Used to apply this hook to only cassettes that match the given tag.

Yields:

  • the callback

Yield Parameters:

See Also:



299
300
301
 
# File 'lib/vcr/configuration.rb', line 299

def before_playback(tag = nil, &block)
  super(tag_filter_from(tag), &block)
end

- (Object) before_record(tag = nil) {|interaction, cassette| ... }

Adds a callback that will be called before the recorded HTTP interactions are serialized and written to disk.

Examples:

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

Parameters:

  • tag ((optional) Symbol) (defaults to: nil) —

    Used to apply this hook to only cassettes that match the given tag.

Yields:

  • the callback

Yield Parameters:

See Also:



271
272
273
 
# File 'lib/vcr/configuration.rb', line 271

def before_record(tag = nil, &block)
  super(tag_filter_from(tag), &block)
end

- (String) cassette_library_dir

Gets the directory to read cassettes from and write cassettes to.

Returns:

  • (String) —

    the directory to read cassettes from and write cassettes to



14
15
16
 
# File 'lib/vcr/configuration.rb', line 14

def cassette_library_dir
  VCR.cassette_persisters[:file_system].storage_location
end

- cassette_library_dir=(dir)

Note:

This is only necessary if you use the :file_system cassette persister (the default).

This method returns an undefined value.

Sets the directory to read cassettes from and writes cassettes to.

Examples:

VCR.configure do |c|
  c.cassette_library_dir = 'spec/cassettes'
end

Parameters:

  • dir (String) —

    the directory to read cassettes from and write cassettes to



29
30
31
 
# File 'lib/vcr/configuration.rb', line 29

def cassette_library_dir=(dir)
  VCR.cassette_persisters[:file_system].storage_location = dir
end

- (VCR::Cassette::Persisters) cassette_persisters

Note:

Custom persisters must implement the following interface:

  • persister[storage_key] # returns previously persisted content
  • persister[storage_key] = content # persists given content

Gets the registry of cassette persisters. Use it to register a custom persister.

Examples:

VCR.configure do |c|
  c.cassette_persisters[:my_custom_persister] = my_custom_persister
end

Returns:



243
244
245
 
# File 'lib/vcr/configuration.rb', line 243

def cassette_persisters
  VCR.cassette_persisters
end

- (VCR::Cassette::Serializers) cassette_serializers

Note:

Custom serializers must implement the following interface:

  • file_extension # => String
  • serialize(Hash) # => String
  • deserialize(String) # => Hash

Gets the registry of cassette serializers. Use it to register a custom serializer.

Examples:

VCR.configure do |c|
  c.cassette_serializers[:my_custom_serializer] = my_custom_serializer
end

Returns:



227
228
229
 
# File 'lib/vcr/configuration.rb', line 227

def cassette_serializers
  VCR.cassette_serializers
end

- (Object) configure_rspec_metadata!

Configures RSpec to use a VCR cassette for any example tagged with :vcr.



389
390
391
 
# File 'lib/vcr/configuration.rb', line 389

def configure_rspec_metadata!
  VCR::RSpec::Metadata.configure!
end

- (Object) define_cassette_placeholder(placeholder, tag = nil) {|interaction| ... } Also known as: filter_sensitive_data

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.

Examples:

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

Parameters:

  • placeholder (String) —

    The placeholder string.

  • tag (Symbol) (defaults to: nil) —

    Set this to apply this only to cassettes with a matching tag; otherwise it will apply to every cassette.

Yields:

  • block that determines what string to replace

Yield Parameters:

Yield Returns:

  • the string to replace



199
200
201
202
203
204
205
206
207
208
209
210
211
 
# 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

- (Object) hook_into(*hooks)

Note:

:fakeweb and :webmock cannot both be used since they both monkey patch Net::HTTP. Otherwise, you can use any combination of these.

Configures which libraries VCR will hook into to intercept HTTP requests.

Examples:

VCR.configure do |c|
  c.hook_into :fakeweb, :typhoeus
end

Parameters:

  • hooks (Array<Symbol>) —

    List of libraries. Valid values are :fakeweb, :webmock, :typhoeus, :excon and :faraday.

Raises:



66
67
68
69
 
# 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

- (Object) ignore_hosts(*hosts) Also known as: ignore_host

Specifies host(s) that VCR should ignore.

Parameters:

  • hosts (Array<String>) —

    List of hosts to ignore

See Also:



76
77
78
 
# File 'lib/vcr/configuration.rb', line 76

def ignore_hosts(*hosts)
  VCR.request_ignorer.ignore_hosts(*hosts)
end

- (Object) ignore_localhost=(value)

Sets whether or not VCR should ignore localhost requests.

Parameters:

  • value (Boolean) —

    the value to set

See Also:



86
87
88
 
# File 'lib/vcr/configuration.rb', line 86

def ignore_localhost=(value)
  VCR.request_ignorer.ignore_localhost = value
end

- (Object) ignore_request {|request| ... }

Defines what requests to ignore using a block.

Examples:

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

Yields:

  • the callback

Yield Parameters:

Yield Returns:

  • (Boolean) —

    whether or not to ignore the request



104
105
106
 
# File 'lib/vcr/configuration.rb', line 104

def ignore_request(&block)
  VCR.request_ignorer.ignore_request(&block)
end

- preserve_exact_body_bytes {|http_message, cassette| ... }

Note:

This is usually only necessary when the HTTP server returns a response with a non-standard encoding or with a body containing invalid bytes for the given encoding. Note that when you set this, and the block returns true, you sacrifice the human readability of the data in the cassette.

This method returns an undefined value.

Sets a callback that determines whether or not to base64 encode the bytes of a request or response body during serialization in order to preserve them exactly.

Examples:

VCR.configure do |c|
  c.preserve_exact_body_bytes do |http_message|
    http_message.body.encoding.name == 'ASCII-8BIT' ||
    !http_message.body.valid_encoding?
  end
end

Yields:

  • the callback

Yield Parameters:

  • http_message (#body, #headers) —

    the VCR::Request or VCR::Response object being serialized

  • cassette (VCR::Cassette) —

    the cassette the http message belongs to

Yield Returns:

  • (Boolean) —

    whether or not to preserve the exact bytes for the body of the given HTTP message

See Also:



432
 
# File 'lib/vcr/configuration.rb', line 432

define_hook :preserve_exact_body_bytes

- (Boolean) preserve_exact_body_bytes_for?(http_message)

Whether or not the body of the given HTTP message should be base64 encoded during serialization in order to preserve the bytes exactly.

Parameters:

  • http_message (#body, #headers) —

    the VCR::Request or VCR::Response object being serialized

Returns:

  • (Boolean) —

    whether or not the body of the given HTTP message should be base64 encoded during serialization in order to preserve the bytes exactly.

See Also:



438
439
440
 
# 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

- (Object) register_request_matcher(name) {|request_1, request_2| ... }

Registers a request matcher for later use.

Examples:

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

Parameters:

  • name (Symbol) —

    the name of the request matcher

Yields:

  • the request matcher

Yield Parameters:

Yield Returns:

  • (Boolean) —

    whether or not these two requests should be considered equivalent



172
173
174
 
# File 'lib/vcr/configuration.rb', line 172

def register_request_matcher(name, &block)
  VCR.request_matchers.register(name, &block)
end

- (Object) stub_with(*adapters)

Deprecated.

Use #hook_into instead.

See Also:



26
27
28
29
 
# File 'lib/vcr/deprecations.rb', line 26

def stub_with(*adapters)
  warn "WARNING: `VCR.config { |c| c.stub_with ... }` is deprecated. Use `VCR.configure { |c| c.hook_into ... }` instead."
  hook_into(*adapters)
end