Tutorial: A Step by Step example

The Smallest Test

Mago uses extends unittest (more exactly testtools) and uses nose (Nose Documentation) 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 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
2. XLib

from mago import TestCase
import ldtp

class TestHelloWorld(TestCase):
    """Test Class"""

    launcher = 'gedit'
    launcher_args = []
    window_name = 'frm*gedit'
    setupOnce = True

    def test_helloworld(self):
        """Test Method

        Change the content of the edit buffer of gedit marking it dirty
        The close action triggered in the teardown will popup the
        "unsaved changes" dialog.

        The application should close after 30 seconds.
        """

        txt = """Hello World!

A dialog will popup and ask you:
    "Save changes to document "Untitled Document 1" before closing?"

Don't close it but wait 60 seconds and it should close automatically.
If it does not please report a bug against mago.
        """
        ldtp.settextvalue(self.window_name, 'txt1', txt)
        ldtp.wait(2)

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:

[hello]
hello=Hello World
goodbye=Good bye

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.

from mago import TestCase, magoConfig
import os

class TestConfiguration(TestCase):
    """Test Class"""

    launcher = 'gedit'
    window_name = 'frm*gedit'

    def test_showconfig(self):
        """Load the main and test configurations and display it in gedit"""

        localconf = ".".join(os.path.basename(__file__).split('.')[:-1])
        str1 = "The main configuration file for mago is '~/.magorc' and its content is:\n\
            %s\n" % magoConfig.items('mago')
        str2 = "The configuration file for the test is '%s.ini' and its content is:\n\
            %s\n" % (localconf, self.testConfig.items('hello'))
        str3 = "* The values read from the test configuration file are:"
        str4 = self.testConfig.get('hello', 'hello')
        str5 = self.testConfig.get('hello', 'goodbye')
        str6 = "\n* This value is not in the configuration file:"
        str7 = self.testConfig.get('hello', 'aurevoir', vars={'aurevoir':'Au Revoir'})

        str = '\n'.join((str1, str2, str3, str4, str5, str6, str7))
        self.application.context.settextvalue('txt1', str)

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