=======
Testing
=======

Every Castellan code submission is automatically tested against a number
of gating jobs to prevent regressions. Castellan developers should have a
habit of running tests locally to ensure the code works as intended before
submission.

For your convenience we provide the ability to run all tests through
the ``tox`` utility. If you are unfamiliar with tox please see
refer to the `tox documentation`_ for assistance.

.. _`tox documentation`: https://tox.readthedocs.org/en/latest/

Unit Tests
----------

Currently, we provide tox environments for a variety of different Python
versions. By default all available test environments within the tox
configuration will execute when calling ``tox``. If you want to run an
independent version, you can do so with the following command:

.. code-block:: bash

    # Executes tests on Python 2.7
    $ tox -e py27


.. note::

    Other available environments are py35 and pep8.

    If you do not have the appropriate Python versions available, consider
    setting up PyEnv to install multiple versions of Python. See the
    documentation regarding `Setting up a Barbican development environment`_
    for more information.

Functional Tests
----------------

Unlike running unit tests, the functional tests require Barbican and
Keystone services to be running in order to execute. For more
information on this please see `Setting up a Barbican development environment`_
and `Using Keystone Middleware with Barbican`_

.. _`Setting up a Barbican development environment`: https://docs.openstack.org/barbican/latest/contributor/dev.html
.. _`Using Keystone Middleware with Barbican`: https://docs.openstack.org/barbican/latest/configuration/keystone.html

Castellan uses either ``/etc/castellan/castellan-functional.conf`` or ``./etc/castellan/castellan-functional.conf``
in order to run functional tests. A sample file can be generated by running:

.. code-block:: bash

    # Generate a sample configuration file
    $ tox -e genconfig

``castellan/etc/castellan/castellan-functional.conf.sample`` is generated.
It must be renamed to ``castellan-functional.conf`` and placed in
``/etc/castellan`` or ``./etc/castellan``.

The file should look something like the following:

.. code-block:: bash

    [DEFAULT]

    [identity]
    username = 'admin'
    password = 'openstack'
    project_name = 'admin'
    auth_url = 'http://localhost/identity/v3'

Once you have the appropriate services running and configured you can execute
the functional tests through tox.

.. code-block:: bash

    # Execute Barbican Functional Tests
    $ tox -e functional


By default, the functional tox job will use ``testr`` to execute the
functional tests.

Debugging
---------

In order to be able to debug code in Castellan, you must use the Python
Debugger. This can be done by adding ``import pdb; pdb.set_trace()``
to set the breakpoint. Then run the following command to hit the breakpoint:

.. code-block:: bash

    # hit the pdb breakpoint
    $ tox -e debug

Once in the Python Debugger, you can use the commands as stated in the
`Debugger Commands` section here: https://docs.python.org/2/library/pdb.html

Pep8 Check
----------

Pep8 is a style guide for Python code. Castellan code should be have proper
style before submission. In order to ensure that pep8 tests can be run through
tox as follows:

.. code-block:: bash

    # Checks python code style
    $ tox -e pep8

Any comments on bad coding style will output to the terminal.
