.. _topics-testing:

===================
Testing in Merengue
===================

There are two kinds of tests used in Merengue:

* Unit tests, see `testing in Django`_ for more information.

* Selenium tests, using the `Selenium web application testing system`_.

.. _`testing in Django`: http://docs.djangoproject.com/en/1.3/topics/testing/
.. _`Selenium web application testing system`: http://seleniumhq.org/


Unit Tests
==========

Unit tests are executed using the ``manage.py`` Django utility located inside
every Merengue project, like this:

.. code-block:: bash

    $ python manage.py testmerengue

This will try to execute all tests in every application defined in the
``APPS_TO_TEST`` setting.

You can also launch the test for only one application by appending the application
to the end of the command line, as follows:

.. code-block:: bash

    $ python manage.py test perms


Selenium Tests
==============

Selenium tests are very useful because they test all application layers (from
the database to the user interface). It comes with an IDE to launch and record functional
tests:

.. image:: _images/selenium_tests.png

These are the steps for installing and executing the Merengue
`Selenium tests suites`_:

1. Install the selenium IDE Firefox plugin from the `download page`_.
2. Make sure that *English* is selected as the first language used to display pages in Firefox preferences.
3. Launch the Selenium IDE in the Options menu.
4. Load the required Selenium Core extension for loading global variables, located in ``merengueproj/tests/selenium/extensions/user-extensions.js``. This is done in the ``Options`` menu in the Selenium IDE.
5. Change the ``merengueproj/tests/selenium/generic/variables.html`` file, setting the ``TEST_DATA_DIR`` variable to point to the absolute path to the ``merengueproj/tests/selenium/test-data`` directory.
6. Open any test suite (``suite.html`` file) located in the subdirectories of the ``merengueproj/tests/selenium/generic`` directory.
7. Execute it.

.. _`download page`: http://seleniumhq.org/download/
.. _`Selenium tests suites`: http://dev.merengueproject.org/browser/trunk/merengueproj/tests/selenium/generic

How to Run All Selenium Tests at Once
-------------------------------------

There is a script to execute all suites of selenium tests located in the
``merengueproj/tests/selenium/generic`` subdirectories. This script is called 
*run_suites.py* and is used as follows:

.. code-block:: bash

    $ python run_suites.py basic_url

``basic_url`` is the basic url of the domain to test (i.e.
http://localhost:8000/). All relative URL's depend on this URL.

It is necessary to run the script with the ``selenium-server.jar`` files on the same directory or to give the full path to it with the option ``--selenium-server``.

To avoid launching all the browser windows when testing in your machine and also to allow to run tests in a server it is possible to use framebuffer. Framebuffer allows the allocation of headless displays. To install it run:

.. code-block:: bash

    $ sudo apt-get install xvfb

and then, to launch it:

.. code-block:: bash

    $ sudo Xvfb :NUMBER

Finally run the test suite with a non-default display number with the option ``--display NUMBER``.

.. note::

    ``selenium-server.jar`` is a file included in Selenium application.

.. admonition:: Note for Non-English Browsers

    If your browser is configured to use a language other than English,
    Merengue will use that language by default and the tests will
    fail. You can create a english firefox profile in a directory and
    execute the ``run_suites.py`` script with the ``-f`` option::

    $ python run_suite.py http://localhost:8000/ -f ~/.mozilla/firefox/selenium

    Also, if you don't want to use other profile, a quick workaround is to
    disable the ``'django.middleware.locale.LocaleMiddleware'`` from your
    project middlewares. The setting ``PRE_MERENGUE_MIDDLEWARE_CLASSES``
    is found in the `merengue/settings.py`_ file.

    

.. _`merengue/settings.py`: http://dev.merengueproject.org/browser/trunk/merengueproj/merengue/settings.py
