# 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

    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.

# Contents of Betamax’s Documentation

Narrative Documentation

- Getting Started
  - Installation
  - Configuration
  - Recording Your First Cassette
  - Recording More Complex Cassettes
- Long Term Usage Patterns
  - Adding New Requests to a Cassette
    - Option 1: Re-recording the Cassette
    - Option 2: Changing the Record Mode
  - Known Issues
    - Tests Periodically Slow Down
- Configuring Betamax
  - Global Configuration
    - Setting the Directory in which Betamax Should Store Cassette Files
    - Setting Default Cassette Options
    - Filtering Sensitive Data
    - Setting default serializer
  - Per-Use Configuration
    - Setting the Directory in which Betamax Should Store Cassette Files
    - Setting Default Cassette Options
    - Filtering Sensitive Data
  - Mixing and Matching
- Record Modes
  - All
  - New Episodes
  - None
  - Once
- Third-Party Packages
  - Request Matchers
  - Cassette Serializers
- Usage Patterns
  - Configuring Betamax in py.test’s conftest.py
    - An Example from github3.py
  - Using Human Readable JSON Cassettes
    - Updating Existing Betamax Cassettes to be Human Readable
- Integrating Betamax with Test Frameworks
  - PyTest Integration
  - Unittest Integration

API Documentation

- API
  - `Betamax`
  - `use_cassette()`
  - `Configuration`
  - `betamax_session()`
  - `BetamaxTestCase`
  - Examples
  - Opinions at Work
  - Forcing bytes to be preserved
- What is a cassette?
- What is a cassette library?
- Implementation Details
  - Gzip Content-Encoding
  - Class Details
- Matchers
  - Default Matchers
  - Specifying Matchers
  - Making Your Own Matcher
- Serializers
  - Creating Your Own Serializer

## Indices and tables

- Index

- Module Index

- Search Page