.TH common_test 6 "common_test  1.3.2" "Ericsson AB" "ERLANG APPLICATION DEFINITION"
.SH APPLICATION
Common Test \- A framework for automatic testing of a variety of target nodes
.SH DESCRIPTION
.LP
The \fICommon Test \fR framework is an environment for writing and executing automatic and semi-automatic test cases\&. The framework is based on the underlying implementation as is used with great success in the Visual Test Server (AXD301) and by Erlang/OTP\&. The main function in this framework is the test server which runs all the test cases\&.
.LP
In brief the test server supports:
.RS 2
.TP 2
*
Running multiple test suites
.TP 2
*
Logging of the events in a test suite, on both suite and case levels
.TP 2
*
HTML presentation of test suite results
.TP 2
*
HTML presentation of test suite code
.TP 2
*
Support functions for test suite authors
.TP 2
*
Step by step execution
.RE
.LP
The following sections describes the callback functions the test server expects to find in a test suite\&. For more details see Common Test 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() -> TestCases | {skip,Reason} 
.br
.RS
.TP
Types
TestCases = [atom() | {sequence, SeqName}]
.br
Reason = term()
.br
SeqName = atom()
.br
.RE
.RS
.LP
MANDATORY 
.LP
This function must return the list of all test cases in the test suite module\&. Each test case is represented by an atom, the name of the test case function\&.
.LP
If \fI{skip, Reason}\fR is returned, all test cases in the module will be skipped, and the \fIReason\fR will be printed on the HTML result page\&.
.LP
For details on sequences, see Dependencies between Test Cases and Suites in the User\&'s Guide\&.
.RE
.LP
.B
Module:sequences() -> Sequences 
.br
.RS
.TP
Types
Sequences = [{SeqName, Testcases}]
.br
SeqName = atom()
.br
Testcases = [atom()]
.br
.RE
.RS
.LP
OPTIONAL 
.LP
See Dependencies between Test Cases and Suites in the User\&'s Guide for details\&.
.RE
.LP
.B
Module:suite() -> [Info] 
.br
.RS
.TP
Types
 Info = {timetrap, Time} | {require, Required} | {require, Name, Required} | {userdata, UserData} | {silent_connections, Conns} | {stylesheet, CSSFile}
.br
 Time = MilliSec | {seconds, integer()} | {minutes, integer()} | {hours, integer()}
.br
 MilliSec = integer()
.br
 Required = Key | {Key, SubKeys}
.br
 Key = atom()
.br
 SubKeys = SubKey | [SubKey]
.br
 SubKey = atom()
.br
 Name = atom()
.br
 UserData = term()
.br
 Conns = [atom()]
.br
 CSSFile = string()
.br
.RE
.RS
.LP
OPTIONAL 
.LP
Use this function to set default data for the test suite\&.
.RE
.LP
.B
Module:init_per_suite(Config) -> NewConfig | {skip,Reason} | {skip_and_save,Reason,Config}
.br
.RS
.TP
Types
 Config = NewConfig = [{Key, Value}]
.br
 Key = atom()
.br
 Value = term()
.br
 Reason = term()
.br
.RE
.RS
.LP
OPTIONAL 
.LP
This function is called as the first test case in the suite\&. It typically contains initialization which is common for all test cases in the suite, and which shall only be done once\&. The \fIConfig\fR parameter is the configuration which can be modified here\&. Whatever is returned from this function is given as \fIConfig\fR to all test cases in the suite\&. If \fI{skip, Reason}\fR is returned, all test cases in the suite will be skipped and \fIReason\fR printed in the overview log for the suite\&.
.LP
For information on \fIsave_config\fR and \fIskip_and_save\fR, please see Dependencies between Test Cases and Suites in the User\&'s Guide\&.
.RE
.LP
.B
Module:end_per_suite(Config) -> void() | {save_config,Config}
.br
.RS
.TP
Types
 Config = [{Key, Value}]
.br
 Key = atom()
.br
 Value = term()
.br
.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 \fIinit_per_suite\fR\&. For information on \fIsave_config\fR, please see Dependencies between Test Cases and Suites in the User\&'s Guide\&.
.RE
.LP
.B
Module:init_per_testcase(TestCase, Config) -> NewConfig | {skip,Reason}
.br
.RS
.TP
Types
 Config = NewConfig = [{Key, Value}]
.br
 Key = atom()
.br
 Value = term()
.br
 Reason = term()
.br
.RE
.RS
.LP
OPTIONAL
.LP
This function is called before each test case\&. The \fITestCase\fR argument is the name of the test case, and \fIConfig\fR is the configuration which can be modified here\&. Whatever is returned from this function is given as \fIConfig\fR to the test case\&. If \fI{skip, Reason}\fR is returned, the test case will be skipped and \fIReason\fR printed in the overview log for the suite\&.
.RE
.LP
.B
Module:end_per_testcase(TestCase, Config) -> void() | {save_config,Config}
.br
.RS
.TP
Types
Config = [{Key, Value}]
.br
 Key = atom()
.br
 Value = term()
.br
.RE
.RS
.LP
OPTIONAL 
.LP
This function is called after each test case, and can be used to clean up whatever the test case has done\&. The return value is ignored\&. For information on \fIsave_config\fR, please see Dependencies between Test Cases and Suites in the User\&'s Guide
.RE
.LP
.B
Module:testcase() -> [Info] 
.br
.RS
.TP
Types
 Info = {timetrap, Time} | {require, Required} | {require, Name, Required} | {userdata, UserData} | {silent_connections, Conns}
.br
 Time = MilliSec | {seconds, integer()} | {minutes, integer()} | {hours, integer()}
.br
 MilliSec = integer()
.br
 Required = Key | {Key, SubKeys}
.br
 Key = atom()
.br
 SubKeys = SubKey | [SubKey]
.br
 SubKey = atom()
.br
 Name = atom()
.br
 UserData = term()
.br
 Conns = [atom()]
.br
.RE
.RS
.LP
OPTIONAL
.LP
This is the test case info function\&. It shall return a list of tagged tuples that specify various properties regarding the test case\&.
.LP
The \fItimetrap\fR tag sets the maximum time the test case is allowed to take\&. If the timetrap time is exceeded, the test case fails with reason \fItimetrap_timeout\fR\&. \fIinit_per_testcase\fR and \fIend_per_testcase\fR are included in the timetrap time\&.
.LP
The \fIrequire\fR tag specifies configuration variables that are required by the test case\&. If the required configuration variables are not found in any of the configuration files, the test case is skipped\&. For more information about the \&'require\&' functionality, see the reference manual for the function \fIct:require/[1, 2]\fR\&.
.LP
If \fItimetrap\fR and/or \fIrequire\fR is not set, the default values specified in the \fIsuite/0\fR return list will be used\&.
.LP
Apart from the above mentioned tags, there is no limitation for which tags that can be specified in the test case info function\&.
.RE
.LP
.B
Module:testcase(Config) -> ok | {skip,Reason} | {comment,Comment} | {save_config,Config} | {skip_and_save,Reason,Config} | exit() 
.br
.RS
.TP
Types
Config = [{Key, Value}]
.br
 Key = atom()
.br
 Value = term()
.br
.RE
.RS
.LP
MANDATORY 
.LP
This is the implementation of a test case\&. Here you must call the functions you want to test, and do whatever you need to check the result\&. If someting fails, make sure the process crashes or call \fIct:fail/[0, 1]\fR (which also will cause the process to crash)\&.
.LP
Elements from the \fIConfig\fR parameter can be read with the \fI?config\fR macro\&. The \fIconfig\fR macro is defined in \fIct\&.hrl\fR
.LP
You can return \fI{skip, Reason}\fR if you decide not to run the test case after all\&. \fIReason\fR will then be printed in \&'Comment\&' field on the HTML result page\&.
.LP
You can return \fI{comment, Comment}\fR if you wish to print some information in the \&'Comment\&' field on the HTML result page\&.
.LP
If the function returns anything else, it is considered a success\&.
.LP
For information on \fIsave_config\fR and \fIskip_and_save\fR, please see Dependencies between Test Cases and Suites in the User\&'s Guide\&.
.RE