## 10 Event Handling

### 10.1 General

It is possible for the operator of a Common Test system to receive event notifications continously during a test session execution. It is reported e.g. when a test case starts and stops, what the current count of succeeded, failed and skipped cases is, etc. This information can be used for different purposes such as logging progress and results on other format than HTML, saving statistics to a database for report generation and test system supervision.

Common Test has a framework for event handling which is based on the OTP event manager concept and gen_event behaviour. When the Common Test server starts, it spawns an event manager. During test execution the manager gets a notification from the server every time something of potential interest happens. Any event handler plugged into the event manager can match on event notifications, take some action or pass the information on. Event handlers are Erlang modules implemented by the Common Test user according to the gen_event behaviour (see the OTP User's Guide and Reference Manual for more information).

As already described, a Common Test server always starts an event manager. The server also plugs in a default event handler which has as its only purpose to relay notifications to a globally registered CT Master event manager (if a CT Master server is actually running in the system). The CT Master also spawns an event manager at startup. Event handlers plugged into this manager will receive the events from all the test nodes as well as information from the CT Master server itself.

### 10.2 Usage

Event handlers may be plugged in by means of test specification terms:

{event_handler, EventHandlers}, or

{event_handler, EventHandlers, InitArgs}, or

{event_handler, NodeRefs, EventHandlers}, or

{event_handler, NodeRefs, EventHandlers, InitArgs}

EventHandlers is a list of modules (each having gen_event behaviour). An event handler module must be precompiled and its location must be specified in the Erlang runtime system code path. Before a test session starts, the init function of each plugged in event handler is called (with the InitArgs list as argument or [] if no start arguments are given).

To plug a handler into the CT Master event manager, specify master as the node in NodeRefs.

For an event handler to be able to match on events, the module must include the header file ct_event.hrl. An event is a record with the following definition:

#event{name, node, data}

name is the label (type) of the event. node is the name of the node the event has originated from (only relevant for CT Master event handlers). data is data specific for the particular event.

Events:

        %% Indication that the test run is starting.
        #event.name = test_start
        #event.data = {StartTime,LogDir}
        StartTime = {date(),time()}
        LogDir = string()

        %% Initial information about the test run; the number of
        %% tests, suites and test cases. Note that if a test case
        %% group with a repeat property exists, the total number
        %% of test cases can not be calculated (unknown).
        #event.name = start_info
        #event.data = {Tests,Suites,Cases}
        Tests = Suites = integer()
        Cases = integer() | unknown

        %% Indication that the test run is finished.
        #event.name = test_done
        #event.data = EndTime
        EndTime = {date(),time()}

        %% Common Test is compiling files in specified directory.
        #event.name = start_make
        #event.data = Dir
        Dir = string()

        %% Common Test is finished with compilation.
        #event.name = finished_make
        #event.data = Dir
        Dir = string()

        %% A test case is starting. In case of a test case group
        %% configuration function, the group name and properties
        %% are also given.
        #event.name = tc_start
        #event.data = {Suite,CaseOrGroup}
        Suite = atom()
        CaseOrGroup = Case | {Conf,GroupName,GroupProperties}
        Case = atom()
        Conf = init_per_group | end_per_group
        GroupName = atom()
        GroupProperties = list()

        %% A test case is finished and this event reports the
        %% result. In case of a test case group configuration
        %% function, the group name and properties are also given.
        #event.name = tc_done
        #event.data = {Suite,CaseOrGroup,Result}
        Suite = atom()
        CaseOrGroup = Case | {Conf,GroupName,GroupProperties}
        Case = atom()
        Conf = init_per_group | end_per_group
        GroupName = atom()
        GroupProperties = list()
        Result = ok | {skipped,Reason} | {failed,Reason}
        Reason = term()

        %% A test case has been skipped by the user.
        #event.name = tc_user_skip
        #event.data = {Suite,Case,Comment}
        Suite = atom()
        Case = atom()
        Comment = string()

        %% A test case has been automatically skipped by
        %% Common Test (e.g. because of a failing configuration
        %% function or an unsuccessful require operation).
        #event.name = tc_auto_skip
        #event.data = {Suite,Case,Comment}
        Suite = atom()
        Case = atom()
        Comment = string()

        %% A statistics event with the current count of
        %% successful, skipped and failed test cases so far.
        %% This event gets sent after the end of each test case.
        #event.name = test_stats
        #event.data = {Ok,Failed,Skipped}
        Ok = Failed = Skipped = integer()

        %% Indication that the logging process of Common Test
        %% has been started successfully and is ready for IO.
        #event.name = start_logging
        #event.data = CtRunDir
        CtRunDir = string()

        %% Indication that the logging process of Common Test
        %% has been shut down at the end of the test run.
        #event.name = stop_logging
        #event.data = []

        %% Internal event used by the Common Test Master
        %% process to synchronize particular file operations.
        #event.name = start_write_file
        #event.data = FullNameFile
        FullNameFile = string()

        %% Internal event used by the Common Test Master
        %% process to synchronize particular file operations.
        #event.name = finished_write_file
        #event.data = FullNameFile
        FullNameFile = string()

The events are also documented in ct_event.erl. This module may serve as an example of what an event handler for the CT event manager can look like.

Besides the event_handler test specification terms, it is also possible to install event handlers by means of the run_test flag -event_handler, e.g:

        $ run_test -dir my_testobj -event_handler my_evh1 my_evh2

Note that it is not posible to specify start arguments to the event handlers when using the run_test script. You may however pass along start arguments if you use the ct:run_test/1 function. An event_handler tuple in the argument Opts has the following definition (see also ct:run_test/1 in the reference manual):

        {event_handler,EventHandlers}

        EventHandlers = EH | [EH]
        EH = atom() | {atom(),InitArgs} | {[atom()],InitArgs}
        InitArgs = [term()]

Example:

        1> ct:run_test([{dir,"my_testobj"},{event_handler,[my_evh1,{my_evh2,[node()]}]}]).

This will install two event handlers for the my_testobj test. Event handler my_evh1 is started with [] as argument to the init function. Event handler my_evh2 is started with the name of the current node in the init argument list.

common_test 1.4.5
Copyright © 1991-2009 Ericsson AB