.TH common_test 3erl "common_test 1.13" "Ericsson AB" "Erlang Module Definition"
.SH NAME
common_test \- A framework for automated testing of any target nodes.
.SH DESCRIPTION
.LP
The \fICommon Test\fR\& framework is an environment for implementing and performing automatic and semi-automatic execution of test cases\&.
.LP
In brief, \fICommon Test\fR\& supports:
.RS 2
.TP 2
*
Automated execution of test suites (sets of test cases)
.LP
.TP 2
*
Logging of events during execution
.LP
.TP 2
*
HTML presentation of test suite results
.LP
.TP 2
*
HTML presentation of test suite code
.LP
.TP 2
*
Support functions for test suite authors
.LP
.TP 2
*
Step-by-step execution of test cases
.LP
.RE

.LP
The following section describes the mandatory and optional test suite functions that \fICommon Test\fR\& calls during test execution\&. For more details, see section \fBWriting Test Suites\fR\& in the User\&'s Guide\&.
.SH "TEST CASE CALLBACK FUNCTIONS"

.LP
The following functions define the callback interface for a test suite\&.
.SH EXPORTS
.LP
.B
Module:all() -> Tests | {skip,Reason} 
.br
.RS
.LP
Types:

.RS 3
Tests = [TestCase | {group,GroupName} | {group,GroupName,Properties} | {group,GroupName,Properties,SubGroups}]
.br
TestCase = atom()
.br
GroupName = atom()
.br
Properties = [parallel | sequence | Shuffle | {RepeatType,N}] | default
.br
SubGroups = [{GroupName,Properties} | {GroupName,Properties,SubGroups}]
.br
Shuffle = shuffle | {shuffle,Seed}
.br
Seed = {integer(),integer(),integer()}
.br
RepeatType = repeat | repeat_until_all_ok | repeat_until_all_fail | repeat_until_any_ok | repeat_until_any_fail
.br
N = integer() | forever
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
MANDATORY
.LP
Returns the list of all test cases and test case groups in the test suite module to be executed\&. This list also specifies the order the cases and groups are executed by \fICommon Test\fR\&\&. A test case is represented by an atom, the name of the test case function\&. A test case group is represented by a \fIgroup\fR\& tuple, where \fIGroupName\fR\&, an atom, is the name of the group (defined in \fB\fIgroups/0\fR\&\fR\&)\&. Execution properties for groups can also be specified, both for a top-level group and for any of its subgroups\&. Group execution properties specified here override properties in the group definition (see \fB\fIgroups/0\fR\&\fR\&)\&. (With value \fIdefault\fR\&, the group definition properties are used)\&.
.LP
If \fI{skip,Reason}\fR\& is returned, all test cases in the module are skipped and \fIReason\fR\& is printed on the HTML result page\&.
.LP
For details on groups, see section \fBTest Case Groups\fR\& in the User\&'s Guide\&.
.RE

.LP
.B
Module:groups() -> GroupDefs
.br
.RS
.LP
Types:

.RS 3
GroupDefs = [Group]
.br
Group = {GroupName,Properties,GroupsAndTestCases}
.br
GroupName = atom()
.br
Properties = [parallel | sequence | Shuffle | {RepeatType,N}]
.br
GroupsAndTestCases = [Group | {group,GroupName} | TestCase]
.br
TestCase = atom()
.br
Shuffle = shuffle | {shuffle,Seed}
.br
Seed = {integer(),integer(),integer()}
.br
RepeatType = repeat | repeat_until_all_ok | repeat_until_all_fail | repeat_until_any_ok | repeat_until_any_fail
.br
N = integer() | forever
.br
.RE
.RE
.RS
.LP
OPTIONAL
.LP
Defines test case groups\&. For details, see section \fBTest Case Groups\fR\& in the User\&'s Guide\&.
.RE

.LP
.B
Module:suite() -> [Info] 
.br
.RS
.LP
Types:

.RS 3
Info = {timetrap,Time} | {require,Required} | {require,Name,Required} | {userdata,UserData} | {silent_connections,Conns} | {stylesheet,CSSFile} | {ct_hooks, CTHs}
.br
Time = TimeVal | TimeFunc
.br
TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} | {hours,integer()}
.br
TimeFunc = {Mod,Func,Args} | Fun
.br
MilliSec = integer()
.br
Mod = atom()
.br
Func = atom()
.br
Args = list()
.br
Fun = fun()
.br
Required = Key | {Key,SubKeys} | {Key,SubKey} | {Key,SubKey,SubKeys}
.br
Key = atom()
.br
SubKeys = SubKey | [SubKey]
.br
SubKey = atom()
.br
Name = atom()
.br
UserData = term()
.br
Conns = [atom()]
.br
CSSFile = string()
.br
CTHs = [CTHModule |
.br
 {CTHModule, CTHInitArgs} |
.br
 {CTHModule, CTHInitArgs, CTHPriority}]
.br
CTHModule = atom()
.br
CTHInitArgs = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL
.LP
The test suite information function\&. Returns a list of tagged tuples specifying various properties related to the execution of this test suite (common for all test cases in the suite)\&.
.LP
Tag \fItimetrap\fR\& sets the maximum time that each test case is allowed to execute (including \fB\fIinit_per_testcase/2\fR\&\fR\& and \fB\fIend_per_testcase/2\fR\&\fR\&)\&. If the timetrap time is exceeded, the test case fails with reason \fItimetrap_timeout\fR\&\&. A \fITimeFunc\fR\& function can be used to set a new timetrap by returning a \fITimeVal\fR\&\&. It can also be used to trigger a timetrap time-out by, at some point, returning a value other than a \fITimeVal\fR\&\&. For details, see section \fBTimetrap Time-Outs\fR\& in the User\&'s Guide\&.
.LP
Tag \fIrequire\fR\& specifies configuration variables required by test cases (or configuration functions) in the suite\&. If the required configuration variables are not found in any of the configuration files, all test cases are skipped\&. For details about the \fIrequire\fR\& functionality, see funtion \fB\fIct:require/1,2\fR\&\fR\&\&.
.LP
With \fIuserdata\fR\&, the user can specify any test suite-related information, which can be read by calling \fB\fIct:userdata/2\fR\&\fR\&\&.
.LP
Tag \fIct_hooks\fR\& specifies the \fBCommon Test Hooks\fR\& to be run with this suite\&.
.LP
Other tuples than the ones defined are ignored\&.
.LP
For details about the test suite information function, see section \fBTest Suite Information Function\fR\& in the User\&'s Guide\&.
.RE

.LP
.B
Module:init_per_suite(Config) -> NewConfig | {skip,Reason} | {skip_and_save,Reason,SaveConfig}
.br
.RS
.LP
Types:

.RS 3
Config = NewConfig = SaveConfig = [{Key,Value}]
.br
Key = atom()
.br
Value = term()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL
.LP
This configuration function is called as the first function in the suite\&. It typically contains initializations that are common for all test cases in the suite, and that must only be done once\&. Parameter \fIConfig\fR\& is the configuration data that can be modified\&. Whatever is returned from this function is specified as \fIConfig\fR\& to all configuration functions and test cases in the suite\&.
.LP
If \fI{skip,Reason}\fR\& is returned, all test cases in the suite are skipped and \fIReason\fR\& is printed in the overview log for the suite\&.
.LP
For information on \fIsave_config\fR\& and \fIskip_and_save\fR\&, see section \fBSaving Configuration Data\fR\& in the User\&'s Guide\&.
.RE

.LP
.B
Module:end_per_suite(Config) -> term() | {save_config,SaveConfig}
.br
.RS
.LP
Types:

.RS 3
Config = SaveConfig = [{Key,Value}]
.br
Key = atom()
.br
Value = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL
.LP
This function is called as the last test case in the suite\&. It is meant to be used for cleaning up after \fB\fIinit_per_suite/1\fR\&\fR\&\&.
.LP
For information on \fIsave_config\fR\&, see section \fBSaving Configuration Data\fR\& in the User\&'s Guide\&.
.RE

.LP
.B
Module:group(GroupName) -> [Info] 
.br
.RS
.LP
Types:

.RS 3
Info = {timetrap,Time} | {require,Required} | {require,Name,Required} | {userdata,UserData} | {silent_connections,Conns} | {stylesheet,CSSFile} | {ct_hooks, CTHs}
.br
Time = TimeVal | TimeFunc
.br
TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} | {hours,integer()}
.br
TimeFunc = {Mod,Func,Args} | Fun
.br
MilliSec = integer()
.br
Mod = atom()
.br
Func = atom()
.br
Args = list()
.br
Fun = fun()
.br
Required = Key | {Key,SubKeys} | {Key,Subkey} | {Key,Subkey,SubKeys}
.br
Key = atom()
.br
SubKeys = SubKey | [SubKey]
.br
SubKey = atom()
.br
Name = atom()
.br
UserData = term()
.br
Conns = [atom()]
.br
CSSFile = string()
.br
CTHs = [CTHModule |
.br
 {CTHModule, CTHInitArgs} |
.br
 {CTHModule, CTHInitArgs, CTHPriority}]
.br
CTHModule = atom()
.br
CTHInitArgs = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL
.LP
The test case group information function\&. It is supposed to return a list of tagged tuples that specify various properties related to the execution of a test case group (that is, its test cases and subgroups)\&. Properties set by \fB\fIgroup/1\fR\&\fR\& override properties with the same key that have been set previously by \fB\fIsuite/0\fR\&\fR\&\&.
.LP
Tag \fItimetrap\fR\& sets the maximum time that each test case is allowed to execute (including \fB\fIinit_per_testcase/2\fR\&\fR\& and \fB\fIend_per_testcase/2\fR\&\fR\&)\&. If the timetrap time is exceeded, the test case fails with reason \fItimetrap_timeout\fR\&\&. A \fITimeFunc\fR\& function can be used to set a new timetrap by returning a \fITimeVal\fR\&\&. It can also be used to trigger a timetrap time-out by, at some point, returning a value other than a \fITimeVal\fR\&\&. For details, see section \fBTimetrap Time-Outs\fR\& in the User\&'s Guide\&.
.LP
Tag \fIrequire\fR\& specifies configuration variables required by test cases (or configuration functions) in the suite\&. If the required configuration variables are not found in any of the configuration files, all test cases in this group are skipped\&. For details about the \fIrequire\fR\& functionality, see function \fB\fIct:require/1,2\fR\&\fR\&\&.
.LP
With \fIuserdata\fR\&, the user can specify any test case group related information that can be read by calling \fB\fIct:userdata/2\fR\&\fR\&\&.
.LP
Tag \fIct_hooks\fR\& specifies the \fBCommon Test Hooks\fR\& to be run with this suite\&.
.LP
Other tuples than the ones defined are ignored\&.
.LP
For details about the test case group information function, see section \fBGroup Information Function\fR\& in the User\&'s Guide\&.
.RE

.LP
.B
Module:init_per_group(GroupName, Config) -> NewConfig | {skip,Reason}
.br
.RS
.LP
Types:

.RS 3
GroupName = atom()
.br
Config = NewConfig = [{Key,Value}]
.br
Key = atom()
.br
Value = term()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL
.LP
This configuration function is called before execution of a test case group\&. It typically contains initializations that are common for all test cases and subgroups in the group, and that must only be performed once\&. \fIGroupName\fR\& is the name of the group, as specified in the group definition (see \fB\fIgroups/0\fR\&\fR\&)\&. Parameter \fIConfig\fR\& is the configuration data that can be modified\&. The return value of this function is given as \fIConfig\fR\& to all test cases and subgroups in the group\&.
.LP
If \fI{skip,Reason}\fR\& is returned, all test cases in the group are skipped and \fIReason\fR\& is printed in the overview log for the group\&.
.LP
For information about test case groups, see section \fBTest Case Groups\fR\& in the User\&'s Guide\&.
.RE

.LP
.B
Module:end_per_group(GroupName, Config) -> term() | {return_group_result,Status}
.br
.RS
.LP
Types:

.RS 3
GroupName = atom()
.br
Config = [{Key,Value}]
.br
Key = atom()
.br
Value = term()
.br
Status = ok | skipped | failed
.br
.RE
.RE
.RS
.LP
OPTIONAL
.LP
This function is called after the execution of a test case group is finished\&. It is meant to be used for cleaning up after \fB\fIinit_per_group/2\fR\&\fR\&\&. A status value for a nested subgroup can be returned with \fI{return_group_result,Status}\fR\&\&. The status can be retrieved in \fB\fIend_per_group/2\fR\&\fR\& for the group on the level above\&. The status is also used by \fICommon Test\fR\& for deciding if execution of a group is to proceed if property \fIsequence\fR\& or \fIrepeat_until_*\fR\& is set\&.
.LP
For details about test case groups, see section \fBTest Case Groups\fR\& in the User\&'s Guide\&.
.RE

.LP
.B
Module:init_per_testcase(TestCase, Config) -> NewConfig | {fail,Reason} | {skip,Reason}
.br
.RS
.LP
Types:

.RS 3
 TestCase = atom()
.br
 Config = NewConfig = [{Key,Value}]
.br
 Key = atom()
.br
 Value = term()
.br
 Reason = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL
.LP
This function is called before each test case\&. Argument \fITestCase\fR\& is the test case name, and \fIConfig\fR\& (list of key-value tuples) is the configuration data that can be modified\&. The \fINewConfig\fR\& list returned from this function is given as \fIConfig\fR\& to the test case\&. If \fI{fail,Reason}\fR\& is returned, the test case is marked as failed without being executed\&.
.LP
If \fI{skip,Reason}\fR\& is returned, the test case is skipped and \fIReason\fR\& is printed in the overview log for the suite\&.
.RE

.LP
.B
Module:end_per_testcase(TestCase, Config) -> term() | {fail,Reason} | {save_config,SaveConfig}
.br
.RS
.LP
Types:

.RS 3
TestCase = atom()
.br
Config = SaveConfig = [{Key,Value}]
.br
Key = atom()
.br
Value = term()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL
.LP
This function is called after each test case, and can be used to clean up after \fB\fIinit_per_testcase/2\fR\&\fR\& and the test case\&. Any return value (besides \fI{fail,Reason}\fR\& and \fI{save_config,SaveConfig}\fR\&) is ignored\&. By returning \fI{fail,Reason}\fR\&, \fITestCase\fR\& is marked as faulty (even though it was successful in the sense that it returned a value instead of terminating)\&.
.LP
For information on \fIsave_config\fR\&, see section \fBSaving Configuration Data\fR\& in the User\&'s Guide\&.
.RE

.LP
.B
Module:Testcase() -> [Info] 
.br
.RS
.LP
Types:

.RS 3
Info = {timetrap,Time} | {require,Required} | {require,Name,Required} | {userdata,UserData} | {silent_connections,Conns}
.br
Time = TimeVal | TimeFunc
.br
TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} | {hours,integer()}
.br
TimeFunc = {Mod,Func,Args} | Fun
.br
MilliSec = integer()
.br
Mod = atom()
.br
Func = atom()
.br
Args = list()
.br
Fun = fun()
.br
Required = Key | {Key,SubKeys} | {Key,Subkey} | {Key,Subkey,SubKeys}
.br
Key = atom()
.br
SubKeys = SubKey | [SubKey]
.br
SubKey = atom()
.br
Name = atom()
.br
UserData = term()
.br
Conns = [atom()]
.br
.RE
.RE
.RS
.LP
OPTIONAL
.LP
The test case information function\&. It is supposed to return a list of tagged tuples that specify various properties related to the execution of this particular test case\&. Properties set by \fB\fITestcase/0\fR\&\fR\& override properties set previously for the test case by \fB\fIgroup/1\fR\&\fR\& or \fB\fIsuite/0\fR\&\fR\&\&.
.LP
Tag \fItimetrap\fR\& sets the maximum time that the test case is allowed to execute\&. If the timetrap time is exceeded, the test case fails with reason \fItimetrap_timeout\fR\&\&. \fB\fIinit_per_testcase/2\fR\&\fR\& and \fB\fIend_per_testcase/2\fR\&\fR\& are included in the timetrap time\&. A \fITimeFunc\fR\& function can be used to set a new timetrap by returning a \fITimeVal\fR\&\&. It can also be used to trigger a timetrap time-out by, at some point, returning a value other than a \fITimeVal\fR\&\&. For details, see section \fBTimetrap Time-Outs\fR\& in the User\&'s Guide\&.
.LP
Tag \fIrequire\fR\& specifies configuration variables that are required by the test case (or \fIinit_per_testcase/2\fR\& or \fIend_per_testcase/2\fR\&)\&. If the required configuration variables are not found in any of the configuration files, the test case is skipped\&. For details about the \fIrequire\fR\& functionality, see function \fB\fIct:require/1,2\fR\&\fR\&\&.
.LP
If \fItimetrap\fR\& or \fIrequire\fR\& is not set, the default values specified by \fB\fIsuite/0\fR\&\fR\& (or \fB\fIgroup/1\fR\&\fR\&) are used\&.
.LP
With \fIuserdata\fR\&, the user can specify any test case-related information that can be read by calling \fB\fIct:userdata/3\fR\&\fR\&\&.
.LP
Other tuples than the ones defined are ignored\&.
.LP
For details about the test case information function, see section \fBTest Case Information Function\fR\& in the User\&'s Guide\&.
.RE

.LP
.B
Module:Testcase(Config) -> term() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit() 
.br
.RS
.LP
Types:

.RS 3
Config = SaveConfig = [{Key,Value}]
.br
Key = atom()
.br
Value = term()
.br
Reason = term()
.br
Comment = string()
.br
.RE
.RE
.RS
.LP
MANDATORY
.LP
The implementation of a test case\&. Call the functions to test and check the result\&. If something fails, ensure the function causes a runtime error or call \fB\fIct:fail/1,2\fR\&\fR\& (which also causes the test case process to terminate)\&.
.LP
Elements from the \fIConfig\fR\& list can, for example, be read with \fIproplists:get_value/2\fR\& in STDLIB (or the macro \fI?config\fR\& defined in \fIct\&.hrl\fR\&)\&.
.LP
If you decide not to run the test case after all, return \fI{skip,Reason}\fR\&\&. \fIReason\fR\& is then printed in field \fIComment\fR\& on the HTML result page\&.
.LP
To print some information in field \fIComment\fR\& on the HTML result page, return \fI{comment,Comment}\fR\&\&.
.LP
If the function returns anything else, the test case is considered successful\&. The return value always gets printed in the test case log file\&.
.LP
For details about test case implementation, see section \fBTest Cases\fR\& in the User\&'s Guide\&.
.LP
For information on \fIsave_config\fR\& and \fIskip_and_save\fR\&, see section \fBSaving Configuration Data\fR\& in the User\&'s Guide\&.
.RE