.TH ct 3 "common_test  1.3.2" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
ct \- Main user interface for the Common Test framework\&.
.SH DESCRIPTION
.LP
Main user interface for the Common Test framework\&.
.LP
This module implements the command line interface for running tests and some basic functions for common test case issues such as configuration and logging\&. 
.LP
\fITest Suite Support Macros\fR
.LP
The \fIconfig\fR macro is defined in \fIct\&.hrl\fR\&. This macro should be used to retrieve information from the \fIConfig\fR variable sent to all test cases\&. It is used with two arguments, where the first is the name of the configuration variable you wish to retrieve, and the second is the \fIConfig\fR variable supplied to the test case\&.
.LP
Possible configuration variables include:
.RS 2
.TP 2
*
\fIdata_dir\fR - Data file directory\&.
.TP 2
*
\fIpriv_dir\fR - Scratch file directory\&.
.TP 2
*
Whatever added by \fIinit_per_suite/1\fR or \fIinit_per_testcase/2\fR in the test suite\&.
.RE

.SH DATA TYPES
.RS 2
.TP 4
.B
\fIhandle() = handle() (see module ct_gen_conn) | term()\fR:

.RS 4
.LP
The identity of a specific connection\&.
.LP

.RE
.TP 4
.B
\fItarget_name() = var_name()\fR:

.RS 4
.LP
The name of a target\&. 
.LP

.RE
.TP 4
.B
\fIvar_name() = atom()\fR:

.RS 4
.LP
A variable name which is specified when \fIct:require/2\fR is called, e\&.g\&. \fIct:require(mynodename, {node, [telnet]})\fR 
.LP

.RE
.RE
.SH EXPORTS
.LP
.B
comment(Comment) -> void()
.br
.RS
.TP
Types
Comment = term()
.br
.RE
.RS
.LP
Print the given \fIComment\fR in the comment field of the table on the test suite result page\&.
.LP
If called several times, only the last comment is printed\&. \fIcomment/1\fR is also overwritten by the return value \fI{comment, Comment}\fR or by the function \fIfail/1\fR (which prints \fIReason\fR as a comment)\&.
.RE
.LP
.B
fail(Reason) -> void()
.br
.RS
.TP
Types
Reason = term()
.br
.RE
.RS
.LP
Terminate a test case with the given error \fIReason\fR\&.
.RE
.LP
.B
get_config(Required) -> Value
.br
.RS
.LP
Equivalent to get_config(Required, undefined)\&.
.RE
.LP
.B
get_config(Required, Default) -> Value
.br
.RS
.TP
Types
Required = KeyOrName | {KeyOrName, SubKey}
.br
KeyOrName = atom()
.br
SubKey = atom()
.br
Default = term()
.br
Value = term() | Default
.br
.RE
.RS
.LP
Get the value of config data\&.
.LP
This function returns the value of the requested config element\&.
.LP
Example, given the following config file:

.nf
   {unix,[{telnet,IpAddr},
          {username,Username},
          {password,Password}]}\&.
.fi
.LP
\fIget_config(unix, Default) -> [{telnet, IpAddr}, {username, Username}, {password, Password}]\fR
.br
 \fIget_config({unix, telnet}, Default) -> IpAddr\fR
.br
 \fIget_config({unix, ftp}, Default) -> Default\fR
.br
 \fIget_config(unknownkey, Default) -> Default\fR
.LP
If you want to access a config variable which has been given a name by \fIrequire/2\fR, the name must be used instead of the key when reading the value:
.LP
\fIrequire(myhost, unix) -> ok\fR
.br
 \fIget_config(myhost, Default) -> [{telnet, IpAddr}, {username, Username}, {password, Password}]\fR
.LP
\fISee also:\fR get_config/1, require/1, require/2\&.
.RE
.LP
.B
get_status() -> TestStatus | {error, Reason}
.br
.RS
.TP
Types
TestDir = term()
.br
Reason = term()
.br
.RE
.RS
.LP
Returns status of ongoing tests\&.
.RE
.LP
.B
get_target_name(Handle) -> {ok, TargetName} | {error, Reason}
.br
.RS
.TP
Types
Handle = handle()
.br
TargetName = target_name()
.br
.RE
.RS
.LP
Return the name of the target that the given connection belongs to\&.
.RE
.LP
.B
install(Opts) -> ok | {error, Reason}
.br
.RS
.TP
Types
Opts = [Opt]
.br
Opt = {config, ConfigFiles} | {event_handler, Modules}
.br
ConfigFiles = [ConfigFile]
.br
ConfigFile = string()
.br
Modules = [atom()]
.br
.RE
.RS
.LP
Install config files and event handlers\&.
.LP
Run this function once before first test\&.
.LP
Example:
.br
 \fIinstall([{config, ["config_node\&.ctc", "config_user\&.ctc"]}])\fR\&.
.LP
Note that this function is automatically run by the \fIrun_test\fR script\&.
.RE
.LP
.B
listenv(Telnet) -> [Env]
.br
.RS
.TP
Types
Telnet = term()
.br
Env = {Key, Value}
.br
Key = string()
.br
Value = string()
.br
.RE
.RS
.LP
Performs the listenv command on the given telnet connection and returns the result as a list of Key-Value pairs\&.
.RE
.LP
.B
log(Format) -> ok
.br
.RS
.LP
Equivalent to log(default, Format, [])\&.
.RE
.LP
.B
log(X1, X2) -> ok
.br
.RS
.TP
Types
X1 = Category | Format
.br
X2 = Format | Args
.br
.RE
.RS
.LP
Equivalent to log(Category, Format, Args)\&.
.RE
.LP
.B
log(Category, Format, Args) -> ok
.br
.RS
.TP
Types
Category = atom()
.br
Format = string()
.br
Args = list()
.br
.RE
.RS
.LP
Printout from a testcase to the log\&.
.LP
This function is meant for printing stuff directly from a testcase (i\&.e\&. not from within the CT framework) in the test log\&.
.LP
Default \fICategory\fR is \fIdefault\fR and default \fIArgs\fR is \fI[]\fR\&.
.RE
.LP
.B
pal(Format) -> ok
.br
.RS
.LP
Equivalent to pal(default, Format, [])\&.
.RE
.LP
.B
pal() -> term()
.br
.RS
.LP
Equivalent to pal(Category, Format, Args)\&.
.RE
.LP
.B
pal(Category, Format, Args) -> ok
.br
.RS
.TP
Types
Category = atom()
.br
Format = string()
.br
Args = list()
.br
.RE
.RS
.LP
Print and log from a testcase\&.
.LP
This function is meant for printing stuff from a testcase both in the log and on the console\&.
.LP
Default \fICategory\fR is \fIdefault\fR and default \fIArgs\fR is \fI[]\fR\&.
.RE
.LP
.B
parse_table(Data) -> {Heading, Table}
.br
.RS
.TP
Types
Data = [string()]
.br
Heading = tuple()
.br
Table = [tuple()]
.br
.RE
.RS
.LP
Parse the printout from an SQL table and return a list of tuples\&.
.LP
The printout to parse would typically be the result of a \fIselect\fR command in SQL\&. The returned \fITable\fR is a list of tuples, where each tuple is a row in the table\&.
.LP
\fIHeading\fR is a tuple of strings representing the headings of each column in the table\&.
.RE
.LP
.B
print(Format) -> ok
.br
.RS
.LP
Equivalent to print(default, Format, [])\&.
.RE
.LP
.B
print() -> term()
.br
.RS
.LP
Equivalent to print(Category, Format, Args)\&.
.RE
.LP
.B
print(Category, Format, Args) -> ok
.br
.RS
.TP
Types
Category = atom()
.br
Format = string()
.br
Args = list()
.br
.RE
.RS
.LP
Printout from a testcase to the console\&.
.LP
This function is meant for printing stuff from a testcase on the console\&.
.LP
Default \fICategory\fR is \fIdefault\fR and default \fIArgs\fR is \fI[]\fR\&.
.RE
.LP
.B
require(Required) -> ok | {error, Reason}
.br
.RS
.TP
Types
Required = Key | {Key, SubKeys}
.br
Key = atom()
.br
SubKeys = SubKey | [SubKey]
.br
SubKey = atom()
.br
.RE
.RS
.LP
Check if the required configuration is available\&.
.LP
Example: require the variable \fImyvar\fR:
.br
 \fIok = ct:require(myvar)\fR
.LP
In this case the config file must at least contain:

.nf
   {myvar,Value}\&.
.fi
.LP
Example: require the variable \fImyvar\fR with subvariable \fIsub1\fR:
.br
 \fIok = ct:require({myvar, sub1})\fR
.LP
In this case the config file must at least contain:

.nf
   {myvar,[{sub1,Value}]}\&.
.fi
.LP
\fISee also:\fR get_config/1, get_config/2, require/2\&.
.RE
.LP
.B
require(Name, Required) -> ok | {error, Reason}
.br
.RS
.TP
Types
Name = atom()
.br
Required = Key | {Key, SubKeys}
.br
Key = atom()
.br
SubKeys = SubKey | [SubKey]
.br
SubKey = atom()
.br
.RE
.RS
.LP
Check if the required configuration is available, and give it a name\&.
.LP
If the requested data is available, the main entry will be marked as allocated\&. An allocated element can only be used if the correct name is given\&. This means that to read the value of the element with \fIget_config/1, 2\fR, you need to provide the \fIName\fR instead of the \fIKey\fR\&.
.LP
Example: Require one node with a telnet connection and an ftp connection\&. Name the node \fIa\fR:
.br
 \fIok = ct:require(a, {node, [telnet, ftp]})\&.\fR
.br
 All references to this node must then use the node name\&. E\&.g\&. you can fetch a file over ftp like this:
.br
 \fIok = ct:ftp_get(a, RemoteFile, LocalFile)\&.\fR
.LP
For this to work, the config file must at least contain:

.nf
   {node,[{telnet,IpAddr},
          {ftp,IpAddr}]}\&.
.fi
.LP
\fISee also:\fR get_config/1, get_config/2, require/1\&.
.RE
.LP
.B
run(TestDirs) -> Result
.br
.RS
.TP
Types
TestDirs = TestDir | [TestDir]
.br
.RE
.RS
.LP
Run all testcases in all suites in the given directories\&.
.LP
\fISee also:\fR run/3\&.
.RE
.LP
.B
run(TestDir, Suite) -> Result
.br
.RS
.LP
Run all testcases in the given suite\&.
.LP
\fISee also:\fR run/3\&.
.RE
.LP
.B
run(TestDir, Suite, Cases) -> Result
.br
.RS
.TP
Types
TestDir = string()
.br
Suite = atom()
.br
Cases = atom() | [atom()]
.br
Result = [TestResult] | {error, Reason}
.br
.RE
.RS
.LP
Run the given testcase(s)\&.
.LP
Requires that \fIct:install/1\fR has been run first\&.
.LP
Suites (*_SUITE\&.erl) files must be stored in \fITestDir\fR or \fITestDir/test\fR\&. All suites will be compiled when test is run\&.
.RE
.LP
.B
run_test(Opts) -> Result
.br
.RS
.TP
Types
Opts = [OptTuples]
.br
OptTuples = {config, CfgFiles} | {dir, TestDirs} | {suite, Suites} | {testcase, Cases} | {spec, TestSpecs} | {allow_user_terms, Bool} | {logdir, LogDir} | {silent_connections, Conns} | {cover, CoverSpecFile} | {event_handler, EventHandlers} | {repeat, N} | {duration, DurTime} | {until, StopTime} | {force_stop, Bool}
.br
CfgFiles = [string()] | string()
.br
TestDirs = [string()] | string()
.br
Suites = [string()] | string()
.br
Cases = [atom()] | atom()
.br
TestSpecs = [string()] | string()
.br
LogDir = string()
.br
EventHandlers = EH | [EH]
.br
EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}
.br
InitArgs = [term()]
.br
Conns = all | [atom()]
.br
CoverSpecFile = string()
.br
N = integer()
.br
DurTime = string(HHMMSS)
.br
StopTime = string(YYMoMoDDHHMMSS) | string(HHMMSS)
.br
Result = [TestResult] | {error, Reason}
.br
.RE
.RS
.LP
Run tests as specified by the combination of options in \fIOpts\fR\&. The options are the same as those used with the \fIrun_test\fR script\&. Note that here a \fITestDir\fR can be used to point out the path to a \fISuite\fR\&. Note also that the option \fItestcase\fR corresponds to the \fI-case\fR option in the \fIrun_test\fR script\&. Configuration files specified in \fIOpts\fR will be installed automatically at startup\&.
.RE
.LP
.B
run_testspec(TestSpec) -> Result
.br
.RS
.TP
Types
TestSpec = [term()]
.br
.RE
.RS
.LP
Run test specified by \fITestSpec\fR\&. The terms are the same as those used in test specification files\&.
.RE
.LP
.B
start_interactive() -> ok
.br
.RS
.LP
Start CT in interactive mode\&.
.LP
From this mode all test case support functions can be executed directly from the erlang shell\&. The interactive mode can also be started from the unix command line with \fIrun_test -shell [-config File\&.\&.\&.]\fR\&.
.LP
If any functions using "required config data" (e\&.g\&. telnet or ftp functions) are to be called from the erlang shell, config data must first be required with \fIct:require/2\fR\&.
.LP
Example:
.br
 \fI> ct:require(a, {unix, [telnet]})\&.\fR
.br
\fIok\fR
.br
 \fI> ct:cmd(a, "ls")\&.\fR
.br
 \fI{ok, ["ls", "file1 \&.\&.\&.", \&.\&.\&.]}\fR
.RE
.LP
.B
step(TestDir, Suite, Case) -> Result
.br
.RS
.TP
Types
Case = atom()
.br
.RE
.RS
.LP
Step through a test case with the debugger\&.
.LP
\fISee also:\fR run/3\&.
.RE
.LP
.B
stop_interactive() -> ok
.br
.RS
.LP
Exit the interactive mode\&.
.LP
\fISee also:\fR start_interactive/0\&.
.RE
.LP
.B
testcases(TestDir, Suite) -> Testcases | {error, Reason}
.br
.RS
.TP
Types
TestDir = string()
.br
Suite = atom()
.br
Testcases = list()
.br
Reason = term()
.br
.RE
.RS
.LP
Returns all testcases in the specified suite\&.
.RE
.LP
.B
userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}
.br
.RS
.TP
Types
TestDir = string()
.br
Suite = atom()
.br
SuiteUserData = [term()]
.br
Reason = term()
.br
.RE
.RS
.LP
Returns any data specified with the tag \fIuserdata\fR in the list of tuples returned from \fISuite:suite/0\fR\&.
.RE
.LP
.B
userdata(TestDir, Suite, Case) -> TCUserData | {error, Reason}
.br
.RS
.TP
Types
TestDir = string()
.br
Suite = atom()
.br
Case = atom()
.br
TCUserData = [term()]
.br
Reason = term()
.br
.RE
.RS
.LP
Returns any data specified with the tag \fIuserdata\fR in the list of tuples returned from \fISuite:Case/0\fR\&.
.RE