Record Modes
============

Betamax, like `VCR`_, has four modes that it can use to record cassettes:

- ``'all'``
- ``'new_episodes'``
- ``'none'``
- ``'once'``

You can only ever use one record mode. Below are explanations and examples of
each record mode. The explanations are blatantly taken from VCR's own `Record
Modes documentation`_.

All
---

The ``'all'`` record mode will:

- Record new interactions.
- Never replay previously recorded interactions.

This can be temporarily used to force VCR to re-record a cassette (i.e., to
ensure the responses are not out of date) or can be used when you simply want
to log all HTTP requests.

Given our file, ``examples/record_modes/all/example.py``,

.. literalinclude:: ../../examples/record_modes/all/example.py
    :language: python

Every time we run it, our cassette 
(``examples/record_modes/all/all-example.json``) will be updated with new 
values.

New Episodes
------------

The ``'new_episodes'`` record mode will:

- Record new interactions.
- Replay previously recorded interactions.

It is similar to the ``'once'`` record mode, but will always record new
interactions, even if you have an existing recorded one that is similar
(but not identical, based on the :match_request_on option).

Given our file, ``examples/record_modes/new_episodes/example_original.py``, 
with which we have already recorded 
``examples/record_modes/new_episodes/new-episodes-example.json``

.. literalinclude:: ../../examples/record_modes/new_episodes/example_original.py
    :language: python

If we then run ``examples/record_modes/new_episodes/example_updated.py``

.. literalinclude:: ../../examples/record_modes/new_episodes/example_updated.py
    :language: python

The new request at the end of the file will be added to the cassette without 
updating the other interactions that were already recorded.

None
----

The ``'none'`` record mode will:

- Replay previously recorded interactions.
- Cause an error to be raised for any new requests.

This is useful when your code makes potentially dangerous HTTP requests. The
``'none'`` record mode guarantees that no new HTTP requests will be made.

Given our file, ``examples/record_modes/none/example_original.py``, with a 
cassette that already has interactions recorded in 
``examples/record_modes/none/none-example.json``

.. literalinclude:: ../../examples/record_modes/none/example_original.py
    :language: python

If we then run ``examples/record_modes/none/example_updated.py``

.. literalinclude:: ../../examples/record_modes/none/example_updated.py
    :language: python

We'll see an exception indicating that new interactions were prevented:

.. literalinclude:: ../../examples/record_modes/none/example_updated.traceback
    :language: pytb

Once
----

The ``'once'`` record mode will:

- Replay previously recorded interactions.
- Record new interactions if there is no cassette file.
- Cause an error to be raised for new requests if there is a cassette file.

It is similar to the ``'new_episodes'`` record mode, but will prevent new,
unexpected requests from being made (i.e. because the request URI changed
or whatever).

``'once'`` is the default record mode, used when you do not set one.

If we have a file, ``examples/record_modes/once/example_original.py``,

.. literalinclude:: ../../examples/record_modes/once/example_original.py
    :language: python

And we run it, we'll see a cassette named 
``examples/record_modes/once/once-example.json`` has been created.

If we then run ``examples/record_modes/once/example_updated.py``,

.. literalinclude:: ../../examples/record_modes/once/example_updated.py
    :language: python

We'll see an exception similar to the one we see when using the ``'none'`` 
record mode.

.. literalinclude:: ../../examples/record_modes/once/example_updated.traceback
    :language: pytb



.. _VCR: https://relishapp.com/vcr/vcr
.. _Record Modes documentation:
    https://relishapp.com/vcr/vcr/v/2-9-3/docs/record-modes/
