*************
Test executor
*************
**Module:** ``typhoon.api.test_executor``

Test executor module provides and option to run a number of test sequentially and integrate all test results in a common html report. 
Module also provide an option to customize certain report sections according to the needs.

In order to be able to execute a test file from the Test executor module, it must comply to the following format:

    * there must be TEST_NAME and TEST_DESCRIPTION variables (strings) defined at the module scope

        Example::

            TEST_NAME = "Test name"
            TEST_DESCRIPTION = "Test description"

    * Test function must be named 'test' and it should accept two arguments.
        First arguments is collection of parameters wrapped in a list, while second arguments
        is a collection of named parameters wrapped in a dictionary.

        Example::

            def test(*parameters, *namedparameters):
                ...

        The test function returns boolean value (True or False) which defines the test result.

Example test file::
    
    """
    This example test file ilustrates the test file format
    """
    import time
    import random
    from typhoon.api.schematic_editor import model

    # Every test must have test name and test description
    TEST_NAME = "Test1"
    TEST_DESCRIPTION = "This test is testing ..."

    def test(*parameters, **namedparameters):

        model.load("RLC_Filter.tse")
        model.compile()
        print "Parameters are {0}".format(parameters)
        
        time.sleep(random.choice([8,7,5,4]))
        print "This is example test"
        print "Sum of list [1,2,3,4,5] is {0}".format(sum([1,2,3,4,5]))
        print "Calling helper function on numbers 2 4 => {0}".format(helper_function(2,4))

        result = random.choice([True, False])
    
        return result

    def helper_function(a,b):
        """
        This is helper function

        Arguments:
            * a,b - two numbers to calculate difference

        Returns:
            diference between two numbers
        """
        return a-b

If previous test file is saved under name test.py, the following example will demonstrate
how to run the test from Test executor::

    """
    Executing test in file test.py
    """
    from typhoon.api.test_executor import execute_tests

    if __name__ == "__main__":
        execute_tests(["test.py",12,33])


`Report customization`_
_______________________

Report can be customized through optional report_info argument. 
Customizable sections are defined in a special ``Report`` class.


.. figure:: img/example.png


Customized report examples are shown below::


    from typhoon.api import test_executor as te
    from typhoon.api.test_executor.reporting import Report


    # customize reports to your needs by using 'Report' class
    reportData = Report(# logo shown on the top of page
                        logo = "./img/logo.jpg",
                        # title shown below logo image
                        title = "Standard Typhoon Test Executor example",
                        # description text
                        description = """
                                      Description text of your tests group
                                      """
                        )


    te.execute_tests(["./test.py"],report_info = reportData)


::

    from typhoon.api import test_executor as te
    from typhoon.api.test_executor.reporting import Report


    # customize reports to your needs by using 'Report' class
    reportData = Report()

    # logo shown on the top of page
    reportData.logo         = "./img/logo.jpg"

    # title shown below logo image
    reportData.title        = "Standard Typhoon Test Executor example"

    # description text
    reportData.description  = """
                              Description text of your tests group
                              """


    te.execute_tests(["./test.py"],report_info = reportData)

`API reference`_
________________

.. automodule:: typhoon.api.test_executor
   :members: