API

config

class vcr.config.VCR(path_transformer=None, before_record_request=None, custom_patches=(), filter_query_parameters=(), ignore_hosts=(), record_mode=RecordMode.ONCE, ignore_localhost=False, filter_headers=(), before_record_response=None, filter_post_data_parameters=(), filter_nested_post_data_parameters=False, match_on=('method', 'scheme', 'host', 'port', 'path', 'query'), before_record=None, inject_cassette=False, serializer='yaml', cassette_library_dir=None, func_path_generator=None, decode_compressed_response=False, record_on_exception=True, drop_unused_requests=False, filter_sensitive_data=(), before_save_interaction=None, after_load_interaction=None, skip_patchers=())

__init__(path_transformer=None, before_record_request=None, custom_patches=(), filter_query_parameters=(), ignore_hosts=(), record_mode=RecordMode.ONCE, ignore_localhost=False, filter_headers=(), before_record_response=None, filter_post_data_parameters=(), filter_nested_post_data_parameters=False, match_on=('method', 'scheme', 'host', 'port', 'path', 'query'), before_record=None, inject_cassette=False, serializer='yaml', cassette_library_dir=None, func_path_generator=None, decode_compressed_response=False, record_on_exception=True, drop_unused_requests=False, filter_sensitive_data=(), before_save_interaction=None, after_load_interaction=None, skip_patchers=())

static ensure_suffix(suffix)

get_merged_config(**kwargs)

static is_test_method(method_name, function)

register_matcher(name, matcher)

register_persister(persister)

register_serializer(name, serializer)

test_case(predicate=None)

use_cassette(path=None, **kwargs)

cassette

class vcr.cassette.Cassette(path, serializer=None, persister=None, record_mode=RecordMode.ONCE, match_on=(<function uri>, <function method>), before_record_request=None, before_record_response=None, custom_patches=(), inject=False, allow_playback_repeats=False, drop_unused_requests=False, filter_sensitive_data=(), before_save_interaction=None, after_load_interaction=None, skip_patchers=())

A container for recorded requests and responses

__init__(path, serializer=None, persister=None, record_mode=RecordMode.ONCE, match_on=(<function uri>, <function method>), before_record_request=None, before_record_response=None, custom_patches=(), inject=False, allow_playback_repeats=False, drop_unused_requests=False, filter_sensitive_data=(), before_save_interaction=None, after_load_interaction=None, skip_patchers=())

property all_played

Returns True if all responses have been played, False otherwise.

append(request, response)

Add a request, response pair to this cassette

can_play_response_for(request)

filter_request(request)

find_requests_with_most_matches(request)

Get the most similar request(s) stored in the cassette of a given request as a list of tuples like this: - the request object - the successful matchers as string - the failed matchers and the related assertion message with the difference details as strings tuple

This is useful when a request failed to be found, we can get the similar request(s) in order to know what have changed in the request parts.

get_metadata(key, default)

Return the value stored in the cassette under key.

If the cassette has no such value, store default and return it, or raise MissingMetadataError if the record mode doesn’t allow changing the cassette.

classmethod load(**kwargs)

Instantiate and load the cassette stored at the specified path.

property path

The path the cassette is saved to and loaded from.

property play_count

play_response(request)

Get the response corresponding to a request, but only if it hasn’t been played back before, and mark it as played

property requests

property responses

responses_of(request)

Find the responses corresponding to a request. This function isn’t actually used by VCR internally, but is provided as an external API.

rewind()

classmethod use(**kwargs)

classmethod use_arg_getter(arg_getter)

property write_protected

class vcr.cassette.CassetteContextDecorator(cls, args_getter)

Context manager/decorator that handles installing the cassette and removing cassettes.

This class defers the creation of a new cassette instance until the point at which it is installed by context manager or decorator. The fact that a new cassette is used with each application prevents the state of any cassette from interfering with another.

Instances of this class are NOT reentrant as context managers. However, functions that are decorated by CassetteContextDecorator instances ARE reentrant. See the implementation of __call__ on this class for more details. There is also a guard against attempts to reenter instances of this class as a context manager in __exit__.

__init__(cls, args_getter)

classmethod from_args(cassette_class, **kwargs)

static get_function_name(function)

matchers

vcr.matchers.body(r1, r2)

vcr.matchers.get_assertion_message(assertion_details)

Get a detailed message about the failing matcher.

vcr.matchers.get_matchers_results(r1, r2, matchers)

Get the comparison results of two requests as two list. The first returned list represents the matchers names that passed. The second list is the failed matchers as a string with failed assertion details if any.

vcr.matchers.headers(r1, r2)

vcr.matchers.host(r1, r2)

vcr.matchers.method(r1, r2)

vcr.matchers.path(r1, r2)

vcr.matchers.port(r1, r2)

vcr.matchers.query(r1, r2)

vcr.matchers.raw_body(r1, r2)

vcr.matchers.requests_match(r1, r2, matchers)

vcr.matchers.scheme(r1, r2)

vcr.matchers.uri(r1, r2)

filters

vcr.filters.decode_response(response)

If the response is compressed with any supported compression (gzip, deflate, br if available):

1. decompress the response body

2. delete the content-encoding header

3. update content-length header to decompressed length

vcr.filters.decompress_deflate(body)

vcr.filters.decompress_gzip(body)

vcr.filters.remove_headers(request, headers_to_remove)

Wrap replace_headers() for API backward compatibility.

vcr.filters.remove_post_data_parameters(request, post_data_parameters_to_remove)

Wrap replace_post_data_parameters() for API backward compatibility.

vcr.filters.remove_query_parameters(request, query_parameters_to_remove)

Wrap replace_query_parameters() for API backward compatibility.

vcr.filters.replace_body_parameters(request, replacements, recursive=False)

Replace body parameters in request–either form data or json–according to replacements.

The replacements should be a list of (key, value) pairs where the value can be any of:

1. A simple replacement string value.

2. None to remove the given header.

3. A callable which accepts (key, value, request) and returns a string value or None.

If recursive is true, keys are also replaced in objects nested in JSON and dict bodies, including objects in lists.

vcr.filters.replace_headers(request, replacements)

Replace headers in request according to replacements. The replacements should be a list of (key, value) pairs where the value can be any of: 1. A simple replacement string value. 2. None to remove the given header. 3. A callable which accepts (key, value, request) and returns a string value or None.

vcr.filters.replace_post_data_parameters(request, replacements, recursive=False)

Wrap replace_body_parameters() for API backward compatibility: only filters POST requests.

vcr.filters.replace_query_parameters(request, replacements)

Replace query parameters in request according to replacements.

The replacements should be a list of (key, value) pairs where the value can be any of:

1. A simple replacement string value.

2. None to remove the given header.

3. A callable which accepts (key, value, request) and returns a string value or None.

vcr.filters.replace_text(obj, text, replacement)

Return a copy of obj with every occurrence of text replaced by replacement.

Replaces in strings and bytes (encoded as UTF-8), and in the keys and values of dicts and the items of lists and tuples, at any depth. Anything else is returned unchanged.

vcr.filters.sensitive_data_hooks(sensitive_data)

Build the interaction hooks that implement filter_sensitive_data.

sensitive_data maps placeholders to the values they stand for, as a dict or as (placeholder, value) pairs. A value can be a function of the interaction’s request and response. Returns (hide, restore): hide replaces values with their placeholders, for before_save_interaction, and restore puts the values back, for after_load_interaction.

request

class vcr.request.HeadersDict(data=None, **kwargs)

There is a weird quirk in HTTP. You can send the same header twice. For this reason, headers are represented by a dict, with lists as the values. However, it appears that HTTPlib is completely incapable of sending the same header twice. This puts me in a weird position: I want to be able to accurately represent HTTP headers in cassettes, but I don’t want the extra step of always having to do [0] in the general case, i.e. request.headers[‘key’][0]

In addition, some servers sometimes send the same header more than once, and httplib can deal with this situation.

Furthermore, I wanted to keep the request and response cassette format as similar as possible.

For this reason, in cassettes I keep a dict with lists as keys, but once deserialized into VCR, I keep them as plain, naked dicts.

class vcr.request.Request(method, uri, body, headers)

VCR’s representation of a request.

__init__(method, uri, body, headers)

add_header(key, value)

property body

property body_bytes

The body materialized as a single bytes object (or None).

Used when forwarding to a real server so http.client sets a Content-Length instead of chunk-encoding a file-like/iterator body (which some servers, including the wsgiref-based test server, reject).

property headers

property host

property path

property port

property protocol

property query

property scheme

property uri

property url

serialize

vcr.serialize.CASSETTE_FORMAT_VERSION = 1

Just a general note on the serialization philosophy here: I prefer cassettes to be human-readable if possible. Yaml serializes bytestrings to !!binary, which isn’t readable, so I would like to serialize to strings and from strings, which yaml will encode as utf-8 automatically. All the internal HTTP stuff expects bytestrings, so this whole serialization process feels backwards.

Serializing: bytestring -> string (yaml persists to utf-8) Deserializing: string (yaml converts from utf-8) -> bytestring

vcr.serialize.deserialize(cassette_string, serializer)

vcr.serialize.serialize(cassette_dict, serializer)

patch

Utilities for patching in cassettes

class vcr.patch.CassettePatcherBuilder(cassette)

__init__(cassette)

build()

class vcr.patch.ConnectionRemover(connection_class)

__init__(connection_class)

add_connection_to_pool_entry(pool, connection)

vcr.patch.force_reset()

Temporarily put back the real classes a cassette replaced.

vcr.patch.reset_patchers()

vcr.patch.validate_skip_patchers(skip_patchers)