.. _getting_started:

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

.. code-block:: bash

    $ 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 :class:`~betamax.recorder.Betamax` or
   :class:`~betamax.decorator.use_cassette` you can pass the
   ``cassette_library_dir`` option. For example,

   .. code-block:: python

       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.

   .. code-block:: python

       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:

.. literalinclude:: ../../examples/our_first_recorded_session.py
    :language: python

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:

.. literalinclude:: ../../examples/cassettes/our-first-recorded-session.json
    :language: javascript

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.

.. literalinclude:: ../../examples/more_complicated_cassettes.py
    :language: python

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
:file:`examples/cassettes/` directory named
:file:`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 :mod:`betamax_serializers.pretty_json` and called
:meth:`~betamax.Betamax.register_serializer` with
:class:`~betamax_serializers.pretty_json.PrettyJSONSerializer`. Then we added
a keyword argument to our invocation of :meth:`~betamax.Betamax.use_cassette`,
``serialize_with='prettyjson'``.
:class:`~betamax_serializers.pretty_json.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:

.. literalinclude:: ../../examples/cassettes/more-complicated-cassettes.json
    :language: javascript

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.

.. links

.. _Requests:
    http://docs.python-requests.org/
.. _VCRpy:
    https://github.com/kevin1024/vcrpy
.. _py.test:
    http://pytest.org/
.. _unittest:
    https://docs.python.org/3/library/unittest.html