================================
Tutorial: A Step by Step example
================================

The Smallest Test
-----------------

Mago uses extends unittest (more exactly testtools) and uses nose (`Nose Documentation <http://somethingaboutorange.com/mrl/projects/nose/1.0.0/index.html>`_) to run them. 

So you write a mago test as you would write any unittest in python. The smallest test that you can write is:

::

    from mago import TestCase

    class TestMinimal(TestCase):
        launcher = 'gcalctool'
        window_name = 'frmCalculator'

        def test_minimal(self):
            """A really simple test

            This test verifies True is True. If it fails, then reinstall your system.
            """
            self.assertTrue(True)



The mandatory elements of the test are:

- ``launcher``: This is the name of the binary that you want to test
- ``window_name``: This is the name of the main window of the application under test. It follows the LDTP naming conventions.


To run this test, open a terminal and enter the following command (mago must be in your PATH or enter the path to the executable):

::

    $ mago ./test_minimal.py


You should see output something like this:

::

    .
    ----------------------------------------------------------------------
    Ran 1 test in 11.570s

    OK
    $


Which indicates that the test has been found and ran successfully.

Mago uses nose to collect and run the test. 

For help enter:

::

    $ mago -h

Or refer to the nose `usage documentation <http://somethingaboutorange.com/mrl/projects/nose/1.0.0/usage.html>`_ to find information about the differents ways to collect and run your tests.


Hello World
-----------
This is the traditional "Hello World" example. It shows how to manipulate the application with LDTP. Mago provides 2 ways to interact with your applications:

1. `LDTP <http://ldtp.freedesktop.org/user-doc/index.html>`_
2. XLib

.. literalinclude:: ../../../tests/test_helloworld.py
    :lines: 37-
    :linenos:

This test launches ``gedit``, write some text in the editable area, then closes the application. If mago can not close the application with the ldtp ``closewindow`` method, it will force it by sending a ``SIGTERM`` then a ``SIGKILL`` if it fails.  

This examples uses ldtp, so we need to import it (line 2)

There are 2 new parameters used by mago lines 8 and 10:

- ``launcher_args``:  This argument is a list of argument to pass to the binary
- ``setupOnce``: By default the application is launched and closed for each test. If ``setupOnce`` is set to ``True``, then the application is launched once at the start of the run, all the tests are run, then the application is closes at the end.

Line 30-31, we use the ldtp method ``ldtp.settextvalue`` to set the value of the text area, then we wait for 2 seconds to let you see the result. 


Configuration Files
-------------------

mago can use external configuration files to customize mago itself and the tests. The structure is similar to the Microsoft Windows INI files. You can refer to the ConfigParser reference for further details.

Below is an example of a configuration file:

.. literalinclude:: ../../../tests/test_testconfig.ini

Additionally to the standard ConfigParser format, the configuration files support an ``include`` directive which allows to cascade configurations files.

The files included are appended to each other. If the same section and same key exist in 2 differents files, the last value included is used.



.. literalinclude:: ../../../tests/test_testconfig.py
    :lines: 34-
    :linenos:

Line 1, we import ``magoConfig``, this is the global configuration for mago. The default configuration file for mago is ``~/.magorc``.

There is also a specific configuration file for the test. It's name is the same than the test but with the extension ``.ini``. It must be located in the same directory than the same. For the purpose of the example it is evaluated line 13 and stored in ``localconf``.

Line 14-22, we load values from the global configuration file and the test configuration file, then join them together line 24.

Line 25, the text area of gedit is updated with the result. We use the ``application.context`` object to access gedit. This is an ooldtp context corresponding to the main window of the application