Event Handling

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

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:

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.

    #event.name = test_start
    #event.data = {StartTime,LogDir}
    StartTime = {date(), time()}
    LogDir = string()
  
    #event.name = test_done
    #event.data = EndTime
    EndTime = {date(), time()}
  
    #event.name = start_make
    #event.data = Dir
    Dir = string()
  
    #event.name = finished_make
    #event.data = Dir
    Dir = string()
  
    #event.name = tc_start
    #event.data = {Suite,Case}
    Suite = atom()
    Case = atom()
  
    #event.name = tc_done
    #event.data = {Suite,Case,Result}
    Suite = atom()
    Case = atom()
    Result = ok | {skipped,Reason} | {failed,Reason}
    Reason = term()
  
    #event.name = tc_user_skip
    #event.data = {Suite,Case,Comment}
    Suite = atom()
    Case = atom()
    Comment = string()
  
    #event.name = tc_auto_skip
    #event.data = {Suite,Case,Comment}
    Suite = atom()
    Case = atom()
    Comment = string()
  
    #event.name = test_stats
    #event.data = {Ok,Failed,Skipped}
    Ok = Failed = Skipped = integer()
  
    #event.name = start_logging
    #event.data = CtRunDir
    CtRunDir = string()
  
    #event.name = stop_logging
    #event.data = []
  
    #event.name = start_write_file
    #event.data = FullNameFile
    FullNameFile = string()
  
    #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()]

    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.

10 Event Handling

10.1 General

10.2 Usage