Getting Started

The first step is to make sure Betamax is right for you. Let’s start by answering the following questions

• Are you using Requests?

  If you’re not using Requests, Betamax is not for you. You should checkout VCRpy.

• Are you using Sessions or are you using the functional API (e.g., requests.get)?

  If you’re using the functional API, and aren’t willing to use Sessions, Betamax is not yet for you.

So if you’re using Requests and you’re using Sessions, you’re in the right place.

Betamax officially supports py.test and unittest but it should integrate well with nose as well.

Installation

$ pip install betamax

Configuration

When starting with Betamax, you need to tell it where to store the cassettes that it creates. There’s two ways to do this:

1. If you’re using Betamax or use_cassette you can pass the cassette_library_dir option. For example,

   import betamax
   import requests
   
   session = requests.Session()
   recorder = betamax.Betamax(session, cassette_library_dir='cassettes')
   with recorder.use_cassette('introduction'):
       # ...
   

2. You can do it once, globally, for your test suite.

   import betamax
   
   with betamax.Betamax.configure() as config:
       config.cassette_library_dir = 'cassettes'
   

Note

If you don’t set a cassette directory, Betamax won’t save cassettes to disk

There are other configuration options that can be provided, but this is the only one that is required.

Recording Your First Cassette

Let’s make a file named our_first_recorded_session.py. Let’s add the following to our file:

If we then run our script, we’ll see that a new file is created in our specified cassette directory. It should look something like:

Now, each subsequent time that we run that script, we will use the recorded interaction instead of talking to the internet over and over again.

Recording More Complex Cassettes

Most times we cannot isolate our tests to a single request at a time, so we’ll have cassettes that make multiple requests. Betamax can handle these with ease, let’s take a look at an example.

Before we run this example, we have to install a new package: betamax-serializers, e.g., pip install betamax-serializers.

If we now run our new example, we’ll see a new file appear in our examples/cassettes/ directory named more-complicated-cassettes.json. This cassette will be much larger as a result of making 3 requests and receiving 3 responses. You’ll also notice that we imported betamax_serializers.pretty_json and called register_serializer() with PrettyJSONSerializer. Then we added a keyword argument to our invocation of use_cassette(), serialize_with='prettyjson'. PrettyJSONSerializer is a class provided by the betamax-serializers package on PyPI that can serialize and deserialize cassette data into JSON while allowing it to be easily human readable and pretty. Let’s see the results:

This makes the cassette easy to read and helps us recognize that requests and responses are paired together. We’ll explore cassettes more a bit later.