A VCR imitation for python-requests
Project description
betamax
=======
Betamax is a VCR_ imitation for requests. This will make mocking out requests
much easier. It is tested on `Travis CI`_.
Put in a more humorous way: "Betamax records your HTTP interactions so the NSA
does not have to."
Example Use
-----------
.. code-block:: python
from betamax import Betamax
from requests import Session
from unittest import TestCase
with Betamax.configure() as config:
config.cassette_library_dir = 'tests/fixtures/cassettes'
class TestGitHubAPI(TestCase):
def setUp(self):
self.session = Session()
self.headers.update(...)
# Set the cassette in a line other than the context declaration
def test_user(self):
with Betamax(self.session) as vcr:
vcr.use_cassette('user')
resp = self.session.get('https://api.github.com/user',
auth=('user', 'pass'))
assert resp.json()['login'] is not None
# Set the cassette in line with the context declaration
def test_repo(self):
with Betamax(self.session).use_cassette('repo'):
resp = self.session.get(
'https://api.github.com/repos/sigmavirus24/github3.py'
)
assert resp.json()['owner'] != {}
What does it even do?
---------------------
If you are unfamiliar with VCR_, you might need a better explanation of what
Betamax does.
Betamax intercepts every request you make and attempts to find a matching
request that has already been intercepted and recorded. Two things can then
happen:
1. If there is a matching request, it will return the response that is
associated with it.
2. If there is **not** a matching request and it is allowed to record new
responses, it will make the request, record the response and return the
response.
Recorded requests and corresponding responses - also known as interactions -
are stored in files called cassettes. (An example cassette can be seen in
the `examples section of the documentation`_.) The directory you store your
cassettes in is called your library, or your `cassette library`_.
VCR Cassette Compatibility
--------------------------
Betamax can use any VCR-recorded cassette as of this point in time. The only
caveat is that python-requests returns a URL on each response. VCR does not
store that in a cassette now but we will. Any VCR-recorded cassette used to
playback a response will unfortunately not have a URL attribute on responses
that are returned. This is a minor annoyance but not something that can be
fixed.
Contributing
------------
You can check out the project board on waffle.io_ to see what the status of
each issue is.
.. _VCR: https://github.com/vcr/vcr
.. _Travis CI: https://travis-ci.org/sigmavirus24/betamax
.. _waffle.io: https://waffle.io/sigmavirus24/betamax
.. _examples section of the documentation:
http://betamax.readthedocs.org/en/latest/api.html#examples
.. _cassette library:
http://betamax.readthedocs.org/en/latest/cassettes.html
History
=======
0.5.0 - 2015-07-15
------------------
- Add unittest integration in ``betamax.fixtures.unittest``
- Add pytest integration in ``betamax.fixtures.pytest``
- Add a decorator as a short cut for ``use_cassette``
- Fix bug where body bytes were not always encoded on Python 3.2+
Fixed by @bboe
0.4.2 - 2015-04-18
------------------
- Fix issue #58 reported by @bboe
Multiple cookies were not being properly stored or replayed after being
recorded.
- @leighlondon converted ``__all__`` to a tuple
0.4.1 - 2014-09-24
------------------
- Fix issue #39 reported by @buttscicles
This bug did not properly parse the Set-Cookie header with multiple cookies
when replaying a recorded response.
0.4.0 - 2014-07-29
------------------
- Allow the user to pass placeholders to ``Betamax#use_cassette``.
- Include Betamax's version number in cassettes
0.3.2 - 2014-06-05
------------------
- Fix request and response bodies courtesy of @dgouldin
0.3.1 - 2014-05-28
------------------
- Fix GitHub Issue #35 - Placeholders were not being properly applied to
request bodies. This release fixes that so placeholders are now behave as
expected with recorded request bodies.
0.3.0 - 2014-05-23
------------------
- Add ``Betamax#start`` and ``Betamax#stop`` to allow users to start recording
and stop without using a context-manager.
- Add ``digest-auth`` matcher to help users match the right request when using
requests' ``HTTPDigestAuth``.
- Reorganize and refactor the cassettes, matchers, and serializers modules.
- Refactor some portions of code a bit.
- ``Cassette.cassette_name`` no longer is the relative path to the file in
which the cassette is saved. To access that information use
``Cassette.cassette_path``. The ``cassette_name`` attribute is now the name
that you pass to ``Betamax#use_cassette``.
0.2.0 - 2014-04-12
------------------
- Fix bug where new interactions recorded under ``new_episodes`` or ``all``
were not actually saved to disk.
- Match URIs in a far more intelligent way.
- Use the Session's original adapters when making new requests
In the event the Session has a custom adapter mounted, e.g., the SSLAdapter
in requests-toolbelt, then we should probably use that.
- Add ``on_init`` hook to ``BaseMatcher`` so matcher authors can customize
initialization
- Add support for custom Serialization formats. See the docs for more info.
- Add support for preserving exact body bytes.
- Deprecate ``serialize`` keyword to ``Betamax#use_cassette`` in preference
for ``serialize_with`` (to be more similar to VCR).
0.1.6 - 2013-12-07
------------------
- Fix how global settings and per-invocation options are persisted and
honored. (#10)
- Support ``match_requests_on`` as a parameter sent to
``Betamax#use_cassette``. (No issue)
0.1.5 - 2013-09-27
------------------
- Make sure what we pass to ``base64.b64decode`` is a bytes object
0.1.4 - 2013-09-27
------------------
- Do not try to sanitize something that may not exist.
0.1.3 - 2013-09-27
------------------
- Fix issue when response has a Content-Encoding of gzip and we need to
preserve the original bytes of the message.
0.1.2 - 2013-09-21
------------------
- Fix issues with how requests parses cookies out of responses
- Fix unicode issues with ``Response#text`` (trying to use ``Response#json``
raises exception because it cannot use string decoding on a unicode string)
0.1.1 - 2013-09-19
------------------
- Fix issue where there is a unicode character not in ``range(128)``
0.1.0 - 2013-09-17
------------------
- Initial Release
- Support for VCR generated cassettes (JSON only)
- Support for ``re_record_interval``
- Support for the ``once``, ``all``, ``new_episodes``, ``all`` cassette modes
- Support for filtering sensitive data
- Support for the following methods of request matching:
- Method
- URI
- Host
- Path
- Query String
- Body
- Headers
=======
Betamax is a VCR_ imitation for requests. This will make mocking out requests
much easier. It is tested on `Travis CI`_.
Put in a more humorous way: "Betamax records your HTTP interactions so the NSA
does not have to."
Example Use
-----------
.. code-block:: python
from betamax import Betamax
from requests import Session
from unittest import TestCase
with Betamax.configure() as config:
config.cassette_library_dir = 'tests/fixtures/cassettes'
class TestGitHubAPI(TestCase):
def setUp(self):
self.session = Session()
self.headers.update(...)
# Set the cassette in a line other than the context declaration
def test_user(self):
with Betamax(self.session) as vcr:
vcr.use_cassette('user')
resp = self.session.get('https://api.github.com/user',
auth=('user', 'pass'))
assert resp.json()['login'] is not None
# Set the cassette in line with the context declaration
def test_repo(self):
with Betamax(self.session).use_cassette('repo'):
resp = self.session.get(
'https://api.github.com/repos/sigmavirus24/github3.py'
)
assert resp.json()['owner'] != {}
What does it even do?
---------------------
If you are unfamiliar with VCR_, you might need a better explanation of what
Betamax does.
Betamax intercepts every request you make and attempts to find a matching
request that has already been intercepted and recorded. Two things can then
happen:
1. If there is a matching request, it will return the response that is
associated with it.
2. If there is **not** a matching request and it is allowed to record new
responses, it will make the request, record the response and return the
response.
Recorded requests and corresponding responses - also known as interactions -
are stored in files called cassettes. (An example cassette can be seen in
the `examples section of the documentation`_.) The directory you store your
cassettes in is called your library, or your `cassette library`_.
VCR Cassette Compatibility
--------------------------
Betamax can use any VCR-recorded cassette as of this point in time. The only
caveat is that python-requests returns a URL on each response. VCR does not
store that in a cassette now but we will. Any VCR-recorded cassette used to
playback a response will unfortunately not have a URL attribute on responses
that are returned. This is a minor annoyance but not something that can be
fixed.
Contributing
------------
You can check out the project board on waffle.io_ to see what the status of
each issue is.
.. _VCR: https://github.com/vcr/vcr
.. _Travis CI: https://travis-ci.org/sigmavirus24/betamax
.. _waffle.io: https://waffle.io/sigmavirus24/betamax
.. _examples section of the documentation:
http://betamax.readthedocs.org/en/latest/api.html#examples
.. _cassette library:
http://betamax.readthedocs.org/en/latest/cassettes.html
History
=======
0.5.0 - 2015-07-15
------------------
- Add unittest integration in ``betamax.fixtures.unittest``
- Add pytest integration in ``betamax.fixtures.pytest``
- Add a decorator as a short cut for ``use_cassette``
- Fix bug where body bytes were not always encoded on Python 3.2+
Fixed by @bboe
0.4.2 - 2015-04-18
------------------
- Fix issue #58 reported by @bboe
Multiple cookies were not being properly stored or replayed after being
recorded.
- @leighlondon converted ``__all__`` to a tuple
0.4.1 - 2014-09-24
------------------
- Fix issue #39 reported by @buttscicles
This bug did not properly parse the Set-Cookie header with multiple cookies
when replaying a recorded response.
0.4.0 - 2014-07-29
------------------
- Allow the user to pass placeholders to ``Betamax#use_cassette``.
- Include Betamax's version number in cassettes
0.3.2 - 2014-06-05
------------------
- Fix request and response bodies courtesy of @dgouldin
0.3.1 - 2014-05-28
------------------
- Fix GitHub Issue #35 - Placeholders were not being properly applied to
request bodies. This release fixes that so placeholders are now behave as
expected with recorded request bodies.
0.3.0 - 2014-05-23
------------------
- Add ``Betamax#start`` and ``Betamax#stop`` to allow users to start recording
and stop without using a context-manager.
- Add ``digest-auth`` matcher to help users match the right request when using
requests' ``HTTPDigestAuth``.
- Reorganize and refactor the cassettes, matchers, and serializers modules.
- Refactor some portions of code a bit.
- ``Cassette.cassette_name`` no longer is the relative path to the file in
which the cassette is saved. To access that information use
``Cassette.cassette_path``. The ``cassette_name`` attribute is now the name
that you pass to ``Betamax#use_cassette``.
0.2.0 - 2014-04-12
------------------
- Fix bug where new interactions recorded under ``new_episodes`` or ``all``
were not actually saved to disk.
- Match URIs in a far more intelligent way.
- Use the Session's original adapters when making new requests
In the event the Session has a custom adapter mounted, e.g., the SSLAdapter
in requests-toolbelt, then we should probably use that.
- Add ``on_init`` hook to ``BaseMatcher`` so matcher authors can customize
initialization
- Add support for custom Serialization formats. See the docs for more info.
- Add support for preserving exact body bytes.
- Deprecate ``serialize`` keyword to ``Betamax#use_cassette`` in preference
for ``serialize_with`` (to be more similar to VCR).
0.1.6 - 2013-12-07
------------------
- Fix how global settings and per-invocation options are persisted and
honored. (#10)
- Support ``match_requests_on`` as a parameter sent to
``Betamax#use_cassette``. (No issue)
0.1.5 - 2013-09-27
------------------
- Make sure what we pass to ``base64.b64decode`` is a bytes object
0.1.4 - 2013-09-27
------------------
- Do not try to sanitize something that may not exist.
0.1.3 - 2013-09-27
------------------
- Fix issue when response has a Content-Encoding of gzip and we need to
preserve the original bytes of the message.
0.1.2 - 2013-09-21
------------------
- Fix issues with how requests parses cookies out of responses
- Fix unicode issues with ``Response#text`` (trying to use ``Response#json``
raises exception because it cannot use string decoding on a unicode string)
0.1.1 - 2013-09-19
------------------
- Fix issue where there is a unicode character not in ``range(128)``
0.1.0 - 2013-09-17
------------------
- Initial Release
- Support for VCR generated cassettes (JSON only)
- Support for ``re_record_interval``
- Support for the ``once``, ``all``, ``new_episodes``, ``all`` cassette modes
- Support for filtering sensitive data
- Support for the following methods of request matching:
- Method
- URI
- Host
- Path
- Query String
- Body
- Headers
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
betamax-0.5.0.tar.gz
(22.9 kB
view hashes)
Built Distributions
betamax-0.5.0-py2-none-any.whl
(38.1 kB
view hashes)
Close
Hashes for betamax-0.5.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 582fcef349c091481a46b1f7b6a498014b735edaeb91722f5cc12ae28b62ec97 |
|
MD5 | 4ab501505dbaae20892c8372b9804099 |
|
BLAKE2b-256 | 7807b2b1858db5b8875ac727155540abf7cc770415152b7d8329ee1e3ff81798 |