Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Automatically mock your HTTP interactions to simplify and speed up testing

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.

This is a proof-of-concept start at a Python version of Ruby's VCR library.

Build Status

What it is supposed to do

Simplify testing by recording all HTTP interactions and saving them to "cassette" files, which are just yaml files. Then when you run your tests again, they all just hit the text files instead of the internet. This speeds up your tests and lets you work offline.

Compatibility Notes

This should work with Python 2.6 and 2.7. It also seems to work with pypy. There aren't any context managers in 2.5 so I'm not bothering with that.

Currently I've only tested this (a little bit) with urllib2. It's known to NOT WORK with urllib.

How to use it

import vcr
import urllib2

with vcr.use_cassette('fixtures/vcr_cassettes/synopsis.yaml'):
    response = urllib2.urlopen('').read()
    assert 'Example Domains' in response

Run this test once, and will record the http request to fixtures/vcr_cassettes/synopsis.yml. Run it again, and will replay the response from when the http request is made. This test is now fast (no real HTTP requests are made anymore), deterministic (the test will continue to pass, even if you are offline, or goes down for maintenance) and accurate (the response will contain the same headers and body you get from a real request).

Ruby VCR compatibility

I'm not trying to match the format of the YAML files. Cassettes generated by Ruby's VCR are not compatible with The API is similar but doesn't have nearly as many features.

Known Issues

  • Probably only works with urllib2.
  • requests kinda works as long as you just do HTTP GETS and don't get too fancy.
  • Loading a HTTPS url and then a HTTP url in the same cassette will cause the second load to use the data from the HTTPS version of the URL: Issue #3
  • Loading urls that do a 301/302 redirect don't work: Issue #4
  • I haven't tested PUT/DELETE requests

Similar libraries in Python

Neither of these really implement the API I want, but I have cribbed some code from them.


This library uses the MIT license

Something went wrong with that request. Please try again.