# 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.

Note

There is no need to write any other code to replay your cassettes. Each time you run that session with the cassette in place, Betamax does all the heavy lifting for you.

## 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.