===========================
The ``run_tests.sh`` Script
===========================

Horizon ships with a script called ``run_tests.sh`` at the root of the
repository. This script provides many crucial functions for the project,
and also makes several otherwise complex tasks trivial for you as a
developer.

First Run
=========

If you start with a clean copy of the Horizon repository, the first thing
you should do is to run ``./run_tests.sh`` from the root of the repository.
This will do three things for you:

    #. Set up a virtual environment for ``openstack-dashboard`` using
       ``openstack-dashboard/tools/install_venv.py``.
    #. Set up an environment for ``horizon`` using
       ``horizon/bootstrap.py`` and ``horizon/bin/buildout``.
    #. Run the tests for both ``horizon`` and ``openstack-dashboard`` using
       their respective environments and verify that evreything is working.

Setting up both environments the first time can take several minutes, but only
needs to be done once. If dependencies are added in the future, updating the
environments will be necessary but not necessarily as time consuming.

I just want to run the tests!
=============================

Running the full set of unit tests quickly and easily is the main goal of this
script. All you need to do is::

    ./run_tests.sh

Yep, that's it. However, for a quicker test run you can skip the Selenium
tests by using the ``--skip-selenium`` flag::

    ./run_tests.sh --skip-selenium

This isn't recommended, but can be a timesaver when you only need to run
the code tests and not the frontend tests during development.

Give me metrics!
================

You can generate various reports and metrics using command line arguments
to ``run_tests.sh``.

Coverage
--------

To run coverage reports::

    ./run_tests.sh --coverage

The reports are saved to ``./reports/`` and ``./coverage.xml``.

PEP8
----

You can check for PEP8 violations as well::

    ./run_tests.sh --pep8

The results are saved to ``./pep8.txt``.

PyLint
------

For more detailed code analysis you can run::

    ./run_tests.sh --pylint

The output will be saved in ``./pylint.txt``.

Running the development server
==============================

As an added bonus, you can run Django's development server directly from
the root of the repository with ``run_tests.sh`` like so::

    ./run_tests.sh --runserver

This is effectively just an alias for::

    ./openstack-dashboard/tools/with_venv.sh ./openstack-dashboard/dashboard/manage.py runserver

Generating the documentation
============================

You can build Horizon's documentation automatically by running::

    ./run_tests.sh --docs

The output is stored in ``./docs/build/html/``.

Starting clean
==============

If you ever want to start clean with a new environment for Horizon, you can
run::

    ./run_tests.sh --force

That will blow away the existing environments and create new ones for you.