.TH ct_suite 3erl "common_test 1.24.0.3" "Ericsson AB" "Erlang Module Definition"
.SH NAME
ct_suite \- -behaviour(ct_suite).
  
.SH DESCRIPTION
.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 Writing Test Suites in the User\&'s Guide\&.
.SH DATA TYPES
.nf

\fBct_testname()\fR\& = atom()
.br
.fi
.RS
.LP
The name of the testcase function\&.
.RE

.nf

\fBct_groupname()\fR\& = atom()
.br
.fi
.RS
.LP
The name of the test group\&.
.RE

.nf

\fBct_config()\fR\& = [{Key :: atom(), Value :: term()}]
.br
.fi
.RS
.LP
The configuration data that can be modified\&.
.RE

.nf

\fBct_status()\fR\& = ok | skipped | failed
.br
.fi
.RS
.LP
The status value for a nested subgroup\&.
.RE

.nf

.B
ct_group_def()
.br
.fi
.RS
.LP
The test group definition, as returned by \fIModule:groups/0\fR\&\&.
.RE

.nf

.B
ct_test_def()
.br
.fi
.RS
.LP
The test suite definition, as returned by \fIModule:all/0\fR\&\&.
.RE

.nf

.B
ct_info()
.br
.fi
.RS
.LP
The test suite information, as returned by \fIModule:suite/0\fR\&, \fIModule:group/1\fR\& and \fIModule:Testcase/0\fR\&\&.
.RE

.SH "CALLBACK FUNCTIONS"

.LP
The following functions are to be exported from a \fIct_suite\fR\& callback module in order to define the callback interface for a test suite\&.
.SH EXPORTS
.LP
.B
Module:all() -> [ct_test_def()] | {skip, Reason}
.br
.RS
.LP
Types:

.RS 3
ct_test_def() = TestCase | {group, GroupName} | {group, GroupName, Properties} | {group, GroupName, Properties, SubGroups}
.br
TestCase = ct_testname()
.br
GroupName = ct_groupname()
.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, or a \fItestcase\fR\& tuple indicating that the test case shall be repeated\&. A test case group is represented by a \fIgroup\fR\& tuple, where \fIGroupName\fR\&, an atom, is the name of the group (defined in \fIModule:groups/0\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 \fIModule:groups/0\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 Test Case Groups in the User\&'s Guide\&.
.RE

.LP
.B
Module:groups() -> [ct_group_def()]
.br
.RS
.LP
Types:

.RS 3
ct_group_def() = {GroupName, Properties, GroupsAndTestCases}
.br
GroupName = ct_groupname()
.br
Properties = [parallel | sequence | Shuffle | {RepeatType, N}]
.br
GroupsAndTestCases = [Group | {group, GroupName} | TestCase]
.br
TestCase = ct_testname()
.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 Test Case Groups in the User\&'s Guide\&.
.RE

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

.RS 3
ct_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
CTHPriority = integer()
.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 \fIModule:init_per_testcase/2\fR\& and \fIModule:end_per_testcase/2\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 Timetrap Time-Outs 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 function \fIct:require/1,2\fR\&\&.
.LP
With \fIuserdata\fR\&, the user can specify any test suite-related information, which can be read by calling \fIct:userdata/2\fR\&\&.
.LP
Tag \fIct_hooks\fR\& specifies the Common Test Hooks 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 Test Suite Information Function 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 = ct_config()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL; if this function is defined, then \fIModule:end_per_suite/1\fR\& must also be defined\&.
.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 Saving Configuration Data 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 = ct_config()
.br
.RE
.RE
.RS
.LP
OPTIONAL; if this function is defined, then \fIModule:init_per_suite/1\fR\& must also be defined\&.
.LP
This function is called as the last test case in the suite\&. It is meant to be used for cleaning up after \fIModule:init_per_suite/1\fR\&\&.
.LP
For information on \fIsave_config\fR\&, see section Saving Configuration Data in the User\&'s Guide\&.
.RE

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

.RS 3
GroupName = ct_groupname()
.br
ct_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
CTHPriority = integer()
.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 \fIModule:group/1\fR\& override properties with the same key that have been set previously by \fIModule:suite/0\fR\&\&.
.LP
Tag \fItimetrap\fR\& sets the maximum time that each test case is allowed to execute (including \fIModule:init_per_testcase/2\fR\& and \fIModule:end_per_testcase/2\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 Timetrap Time-Outs 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 \fIct:require/1,2\fR\&\&.
.LP
With \fIuserdata\fR\&, the user can specify any test case group related information that can be read by calling \fIct:userdata/2\fR\&\&.
.LP
Tag \fIct_hooks\fR\& specifies the Common Test Hooks 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 Group Information Function in the User\&'s Guide\&.
.RE

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

.RS 3
GroupName = ct_groupname()
.br
Config = NewConfig = ct_config()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL; if this function is defined, then \fIModule:end_per_group/2\fR\& must also be defined\&.
.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 \fIModule:groups/0\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 Test Case Groups 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 = ct_groupname()
.br
Config = ct_config()
.br
Status = ct_status()
.br
.RE
.RE
.RS
.LP
OPTIONAL; if this function is defined, then \fIModule:init_per_group/2\fR\& must also be defined\&.
.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 \fIModule:init_per_group/2\fR\&\&. A status value for a nested subgroup can be returned with \fI{return_group_result, Status}\fR\&\&. The status can be retrieved in \fIModule:end_per_group/2\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 Test Case Groups 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 = ct_testname()
.br
Config = NewConfig = ct_config()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL; if this function is defined, then \fIModule:end_per_testcase/2\fR\& must also be defined\&.
.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 = ct_testname()
.br
Config = SaveConfig = ct_config()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
OPTIONAL; if this function is defined, then \fIModule:init_per_testcase/2\fR\& must also be defined\&.
.LP
This function is called after each test case, and can be used to clean up after \fIModule:init_per_testcase/2\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 Saving Configuration Data in the User\&'s Guide\&.
.RE

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

.RS 3
ct_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
CTHPriority = integer()
.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 \fIModule:Testcase/0\fR\& override properties set previously for the test case by \fIModule:group/1\fR\& or \fIModule:suite/0\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\&\&. \fIModule:init_per_testcase/2\fR\& and \fIModule:end_per_testcase/2\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 Timetrap Time-Outs 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 \fIct:require/1,2\fR\&\&.
.LP
If \fItimetrap\fR\& or \fIrequire\fR\& is not set, the default values specified by \fIModule:suite/0\fR\& (or \fIModule:group/1\fR\&) are used\&.
.LP
With \fIuserdata\fR\&, the user can specify any test case-related information that can be read by calling \fIct:userdata/3\fR\&\&.
.LP
Other tuples than the ones defined are ignored\&.
.LP
For details about the test case information function, see section Test Case Information Function 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 = ct_config()
.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 \fIct:fail/1,2\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 Test Cases in the User\&'s Guide\&.
.LP
For information on \fIsave_config\fR\& and \fIskip_and_save\fR\&, see section Saving Configuration Data in the User\&'s Guide\&.
.RE