Mirroring/vcrpy
1
0
Fork 0
mirror of https://github.com/kevin1024/vcrpy.git synced 2025-12-09 09:13:23 +00:00
Code Releases Activity

Merge pull request #65 from msabramo/patch-1

Browse Source 
README.md: minor formatting, add links
This commit is contained in:
Kevin McCarthy
2014-03-08 19:18:14 -10:00
parent d0e6f9c047 f003e3e4ab
commit c0b88c2201
1 changed files with 20 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
README.md
View File

@@ -1,4 +1,4 @@
#VCR.py # VCR.py
![vcr.py](https://raw.github.com/kevin1024/vcrpy/master/vcr.png) ![vcr.py](https://raw.github.com/kevin1024/vcrpy/master/vcr.png)
@@ -6,7 +6,7 @@ This is a Python version of [Ruby's VCR library](https://github.com/myronmarston
[![Build Status](https://secure.travis-ci.org/kevin1024/vcrpy.png?branch=master)](http://travis-ci.org/kevin1024/vcrpy) [![Build Status](https://secure.travis-ci.org/kevin1024/vcrpy.png?branch=master)](http://travis-ci.org/kevin1024/vcrpy)
##What it does ## What it does
Simplify and speed up testing HTTP by recording all HTTP interactions and saving them to Simplify and speed up testing HTTP by recording all HTTP interactions and saving them to
"cassette" files, which are yaml files containing the contents of your "cassette" files, which are yaml files containing the contents of your
requests and responses. Then when you run your tests again, they all requests and responses. Then when you run your tests again, they all
@@ -17,12 +17,12 @@ If the server you are testing against ever changes its API, all you need
to do is delete your existing cassette files, and run your tests again. to do is delete your existing cassette files, and run your tests again.
All of the mocked responses will be updated with the new API. All of the mocked responses will be updated with the new API.
##Compatibility Notes ## Compatibility Notes
This should work with Python 2.6 and 2.7, and [pypy](http://pypy.org). This should work with Python 2.6 and 2.7, and [pypy](http://pypy.org).
Currently I've only tested this with urllib2, urllib3, and requests. It's known to *NOT WORK* with urllib. Currently I've only tested this with urllib2, urllib3, and requests. It's known to *NOT WORK* with urllib.
##Usage ## Usage
```python ```python
import vcr import vcr
import urllib2 import urllib2
@@ -32,7 +32,7 @@ with vcr.use_cassette('fixtures/vcr_cassettes/synopsis.yaml'):
assert 'Example domains' in response assert 'Example domains' in response
``` ```
Run this test once, and VCR.py will record the http request to Run this test once, and VCR.py will record the HTTP request to
`fixtures/vcr_cassettes/synopsis.yml`. Run it again, and VCR.py will replay the `fixtures/vcr_cassettes/synopsis.yml`. Run it again, and VCR.py will replay the
response from iana.org when the http request is made. This test is now fast (no response from iana.org when the http request is made. This test is now fast (no
real HTTP requests are made anymore), deterministic (the test will continue to real HTTP requests are made anymore), deterministic (the test will continue to
@@ -42,7 +42,7 @@ real request).
You can also use VCR.py as a decorator. The same request above would look like this: You can also use VCR.py as a decorator. The same request above would look like this:
``` ```python
@vcr.use_cassette('fixtures/vcr_cassettes/synopsis.yaml'): @vcr.use_cassette('fixtures/vcr_cassettes/synopsis.yaml'):
def test_iana(): def test_iana():
response = urllib2.urlopen('http://www.iana.org/domains/reserved').read() response = urllib2.urlopen('http://www.iana.org/domains/reserved').read()
@@ -54,7 +54,7 @@ All of the parameters and configuration works the same for the decorator version
## Configuration ## Configuration
If you don't like VCR's defaults, you can set options by instantiating a If you don't like VCR's defaults, you can set options by instantiating a
VCR class and setting the options on it. `VCR` class and setting the options on it.
```python ```python
@@ -164,7 +164,7 @@ with vcr.use_cassette('fixtures/vcr_cassettes/synopsis.yaml') as cass:
assert cass.requests[0].url == 'http://www.zombo.com/' assert cass.requests[0].url == 'http://www.zombo.com/'
``` ```
The Cassette object exposes the following properties which I consider The `Cassette` object exposes the following properties which I consider
part of the API. The fields are as follows: part of the API. The fields are as follows:
* `requests`: A list of vcr.Request objects containing the requests made * `requests`: A list of vcr.Request objects containing the requests made
@@ -175,7 +175,7 @@ part of the API. The fields are as follows:
played back played back
* `responses_of(request)`: Access the responses that match a given request * `responses_of(request)`: Access the responses that match a given request
The Request object has the following properties The `Request` object has the following properties
* `URL`: The full url of the request, including the protocol. Example: "http://www.google.com/" * `URL`: The full url of the request, including the protocol. Example: "http://www.google.com/"
* `path`: The path of the request. For example "/" or "/home.html" * `path`: The path of the request. For example "/" or "/home.html"
@@ -228,8 +228,8 @@ Create your own method with the following signature
def my_matcher(r1, r2): def my_matcher(r1, r2):
``` ```
Your method receives the two requests and must return True if they Your method receives the two requests and must return `True` if they
match, False if they don't. match, `False` if they don't.
Finally, register your method with VCR to use your Finally, register your method with VCR to use your
new request matcher. new request matcher.
@@ -255,27 +255,27 @@ with my_vcr.use_cassette('test.yml'):
``` ```
##Installation ## Installation
VCR.py is a package on PyPI, so you can `pip install vcrpy` (first you may need to `brew install libyaml` [[Homebrew](http://mxcl.github.com/homebrew/)]) VCR.py is a package on PyPI, so you can `pip install vcrpy` (first you may need to `brew install libyaml` [[Homebrew](http://mxcl.github.com/homebrew/)])
##Ruby VCR compatibility ## Ruby VCR compatibility
I'm not trying to match the format of the Ruby VCR YAML files. Cassettes generated by I'm not trying to match the format of the Ruby VCR YAML files. Cassettes generated by
Ruby's VCR are not compatible with VCR.py. Ruby's VCR are not compatible with VCR.py.
##Running VCR's test suite ## Running VCR's test suite
The tests are all run automatically on Travis, but you can also run them yourself using py.test and Tox. Tox will automatically run them in all environments VCR.py supports. The test suite is pretty big and slow, but you can tell tox to only run specific tests like this: The tests are all run automatically on [Travis CI](https://travis-ci.org/kevin1024/vcrpy), but you can also run them yourself using [py.test](http://pytest.org/) and [Tox](http://tox.testrun.org/). Tox will automatically run them in all environments VCR.py supports. The test suite is pretty big and slow, but you can tell tox to only run specific tests like this:
`tox -e py27requests -- -v -k "'test_status_code or test_gzip'"` `tox -e py27requests -- -v -k "'test_status_code or test_gzip'"`
This will run only tests that look like `test_status_code` or `test_gzip` in the test suite, and only in the python 2.7 environment that has requests installed. This will run only tests that look like `test_status_code` or `test_gzip` in the test suite, and only in the python 2.7 environment that has `requests` installed.
##Known Issues ## Known Issues
This library is a work in progress, so the API might change on you. This library is a work in progress, so the API might change on you.
There are probably some [bugs](https://github.com/kevin1024/vcrpy/issues?labels=bug&page=1&state=open) floating around too. There are probably some [bugs](https://github.com/kevin1024/vcrpy/issues?labels=bug&page=1&state=open) floating around too.
##Changelog ## Changelog
* 0.6.0: Store response headers as a list since a HTTP response can have the same header twice (happens with set-cookie sometimes). This has the added benefit of preserving the order of headers. Thanks @smallcode for the bug report leading to this change. I have made an effort to ensure backwards compatibility with the old cassettes' header storage mechanism, but if you want to upgrade to the new header storage, you should delete your cassettes and re-record them. Also this release adds better error messages (thanks @msabramo) and adds support for using VCR as a decorator (thanks @smallcode for the motivation) * 0.6.0: Store response headers as a list since a HTTP response can have the same header twice (happens with set-cookie sometimes). This has the added benefit of preserving the order of headers. Thanks @smallcode for the bug report leading to this change. I have made an effort to ensure backwards compatibility with the old cassettes' header storage mechanism, but if you want to upgrade to the new header storage, you should delete your cassettes and re-record them. Also this release adds better error messages (thanks @msabramo) and adds support for using VCR as a decorator (thanks @smallcode for the motivation)
* 0.5.0: Change the `response_of` method to `responses_of` since cassettes can now contain more than one response for a request. Since this changes the API, I'm bumping the version. Also includes 2 bugfixes: a better error message when attempting to overwrite a cassette file, and a fix for a bug with requests sessions (thanks @msabramo) * 0.5.0: Change the `response_of` method to `responses_of` since cassettes can now contain more than one response for a request. Since this changes the API, I'm bumping the version. Also includes 2 bugfixes: a better error message when attempting to overwrite a cassette file, and a fix for a bug with requests sessions (thanks @msabramo)
* 0.4.0: Change default request recording behavior for multiple requests. If you make the same request multiple times to the same URL, the response might be different each time (maybe the response has a timestamp in it or something), so this will make the same request multiple times and save them all. Then, when you are replaying the cassette, the responses will be played back in the same order in which they were received. If you were making multiple requests to the same URL in a cassette before version 0.4.0, you might need to regenerate your cassette files. Also, removes support for the cassette.play_count counter API, since individual requests aren't unique anymore. A cassette might contain the same request several times. Also removes secure overwrite feature since that was breaking overwriting files in Windows, and fixes a bug preventing request's automatic body decompression from working. * 0.4.0: Change default request recording behavior for multiple requests. If you make the same request multiple times to the same URL, the response might be different each time (maybe the response has a timestamp in it or something), so this will make the same request multiple times and save them all. Then, when you are replaying the cassette, the responses will be played back in the same order in which they were received. If you were making multiple requests to the same URL in a cassette before version 0.4.0, you might need to regenerate your cassette files. Also, removes support for the cassette.play_count counter API, since individual requests aren't unique anymore. A cassette might contain the same request several times. Also removes secure overwrite feature since that was breaking overwriting files in Windows, and fixes a bug preventing request's automatic body decompression from working.
@@ -315,7 +315,7 @@ There are probably some [bugs](https://github.com/kevin1024/vcrpy/issues?labels=
* 0.0.2: Add support for requests / urllib3 * 0.0.2: Add support for requests / urllib3
* 0.0.1: Initial Release * 0.0.1: Initial Release
##Similar libraries in Python ## Similar libraries in Python
Neither of these really implement the API I want, but I have cribbed some code Neither of these really implement the API I want, but I have cribbed some code
from them. from them.
* https://github.com/bbangert/Dalton * https://github.com/bbangert/Dalton
@@ -327,5 +327,5 @@ These were created after I created VCR.py but do something similar:
* https://github.com/kanzure/python-requestions * https://github.com/kanzure/python-requestions
* https://github.com/uber/cassette * https://github.com/uber/cassette
#License # License
This library uses the MIT license. See [LICENSE.txt](LICENSE.txt) for more details This library uses the MIT license. See [LICENSE.txt](LICENSE.txt) for more details