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

#allow_http_connections_when_no_cassette? ⇒ Boolean (writeonly) #allow_http_connections_when_no_cassette= ⇒ Object (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:

  • #allow_http_connections_when_no_cassette? ⇒ Boolean

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

  • #allow_http_connections_when_no_cassette= ⇒ Object

    Parameters:

    • value (Boolean) —

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



118
119
120
 
# File 'lib/vcr/configuration.rb', line 118

def allow_http_connections_when_no_cassette=(value)
  @allow_http_connections_when_no_cassette = value
end

#cassette_library_dir ⇒ String #cassette_library_dir=(dir)

The directory to read cassettes from and write cassettes to.

Examples:

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

Overloads:

  • #cassette_library_dir ⇒ String

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

    Returns:

    • (String) —

      the directory to read cassettes from and write cassettes to

  • #cassette_library_dir=(dir)

    This method returns an undefined value.

    Parameters:

    • dir (String) —

      the directory to read cassettes from and write cassettes to



22
23
24
 
# File 'lib/vcr/configuration.rb', line 22

def cassette_library_dir
  @cassette_library_dir
end

#debug_logger ⇒ #puts #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:

  • #debug_logger ⇒ #puts

    Returns the logger.

    Returns:

    • (#puts) —

      the logger

  • #debug_logger=(logger)

    This method returns an undefined value.

    Parameters:

    • logger (#puts) —

      the logger



360
361
362
 
# File 'lib/vcr/configuration.rb', line 360

def debug_logger
  @debug_logger
end

#default_cassette_options ⇒ Hash #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:

  • #default_cassette_options ⇒ Hash

    Returns 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



42
43
44
 
# File 'lib/vcr/configuration.rb', line 42

def default_cassette_options
  @default_cassette_options
end

Instance Method Details

#around_http_request(*filters) {|request| ... } ⇒ Object

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:

  • #before_http_request
  • #after_http_request


321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/vcr/configuration.rb', line 321

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

#before_playback(tag = nil, &block) ⇒ Object 



254
255
256
 
# File 'lib/vcr/configuration.rb', line 254

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

#before_record(tag = nil, &block) ⇒ Object 



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

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

#cassette_serializers ⇒ VCR::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:



198
199
200
 
# File 'lib/vcr/configuration.rb', line 198

def cassette_serializers
  VCR.cassette_serializers
end

#configure_rspec_metadata! ⇒ Object

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



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

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

#define_cassette_placeholder(placeholder, tag = nil) {|interaction| ... } ⇒ Object 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 apply this to 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



170
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'lib/vcr/configuration.rb', line 170

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

#hook_into(*hooks) ⇒ Object

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:



63
64
65
66
 
# File 'lib/vcr/configuration.rb', line 63

def hook_into(*hooks)
  hooks.each { |a| load_library_hook(a) }
  invoke_hook(:after_library_hooks_loaded)
end

#ignore_hosts(*hosts) ⇒ Object Also known as: ignore_host

Specifies host(s) that VCR should ignore.

Parameters:

  • hosts (Array<String>) —

    List of hosts to ignore

See Also:



73
74
75
 
# File 'lib/vcr/configuration.rb', line 73

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

#ignore_localhost=(value) ⇒ Object

Sets whether or not VCR should ignore localhost requests.

Parameters:

  • value (Boolean) —

    the value to set

See Also:



83
84
85
 
# File 'lib/vcr/configuration.rb', line 83

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

#ignore_request {|request| ... } ⇒ Object

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



101
102
103
 
# File 'lib/vcr/configuration.rb', line 101

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:



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

define_hook :preserve_exact_body_bytes

#preserve_exact_body_bytes_for?(http_message) ⇒ Boolean

Returns 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:



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

def preserve_exact_body_bytes_for?(http_message)
  invoke_hook(:preserve_exact_body_bytes, http_message, VCR.current_cassette).any?
end

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

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



143
144
145
 
# File 'lib/vcr/configuration.rb', line 143

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

#stub_with(*adapters) ⇒ Object

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