.TH ct 3erl "common_test 1.24.0.3" "Ericsson AB" "Erlang Module Definition"
.SH NAME
ct \- Main user interface for the Common Test framework.
.SH DESCRIPTION
.LP
Main user interface for the \fICommon Test\fR\& framework\&.
.LP
This module implements the command-line interface for running tests and basic functions for \fICommon Test\fR\& 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 is to be used to retrieve information from the \fIConfig\fR\& variable sent to all test cases\&. It is used with two arguments; the first is the name of the configuration variable to retrieve, 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
.LP
.TP 2
*
\fIpriv_dir\fR\& - Scratch file directory
.LP
.TP 2
*
Whatever added by \fIinit_per_suite/1\fR\& or \fIinit_per_testcase/2\fR\& in the test suite\&.
.LP
.RE

.SH DATA TYPES
.nf

.B
handle() = pid()
.br
.fi
.RS
.LP
The identity (handle) of a connection\&.
.RE

.nf

.B
config_key() = atom()
.br
.fi
.RS
.LP
A configuration key which exists in a configuration file
.RE

.nf

.B
target_name() = atom()
.br
.fi
.RS
.LP
A name and association to configuration data introduced through a require statement, or a call to \fIct:require/2\fR\&, for example, \fIct:require(mynodename,{node,[telnet]})\fR\&\&.
.RE

.nf

.B
key_or_name() = config_key() | target_name()
.br
.fi
.nf

.B
conn_log_options() = [conn_log_option()]
.br
.fi
.RS
.LP
Options that can be given to the \fIcth_conn_log\fR\& hook, which is used for logging of NETCONF and Telnet connections\&. See ct_netconfc or ct_telnet for description and examples of how to use this hook\&.
.RE

.nf

.B
conn_log_option() = {log_type,conn_log_type()} | {hosts,[key_or_name()]}
.br
.fi
.nf

.B
conn_log_type() = raw | pretty | html | silent
.br
.fi
.nf

.B
conn_log_mod() = ct_netconfc | ct_telnet
.br
.fi
.SH EXPORTS
.LP
.B
abort_current_testcase(Reason) -> ok | {error, ErrorReason}
.br
.RS
.LP
Types:

.RS 3
Reason = term()
.br
ErrorReason = no_testcase_running | parallel_group
.br
.RE
.RE
.RS
.LP
Aborts the currently executing test case\&. The user must know with certainty which test case is currently executing\&. The function is therefore only safe to call from a function that has been called (or synchronously invoked) by the test case\&.
.LP
\fIReason\fR\&, the reason for aborting the test case, is printed in the test case log\&.
.RE

.LP
.B
add_config(Callback, Config) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Callback = atom()
.br
Config = string()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Loads configuration variables using the specified callback module and configuration string\&. The callback module is to be either loaded or present in the code path\&. Loaded configuration variables can later be removed using function \fIct:remove_config/2\fR\&\&.
.RE

.LP
.B
break(Comment) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Comment = string()
.br
Reason = {multiple_cases_running, TestCases} | \&'enable break with release_shell option\&'
.br
TestCases = [atom()]
.br
.RE
.RE
.RS
.LP
Cancels any active timetrap and pauses the execution of the current test case until the user calls function \fIcontinue/0\fR\&\&. The user can then interact with the Erlang node running the tests, for example, for debugging purposes or for manually executing a part of the test case\&. If a parallel group is executing, \fIct:break/2\fR\& is to be called instead\&.
.LP
A cancelled timetrap is not automatically reactivated after the break, but must be started explicitly with \fIct:timetrap/1\fR\&\&.
.LP
In order for the break/continue functionality to work, \fICommon Test\fR\& must release the shell process controlling \fIstdin\fR\&\&. This is done by setting start option \fIrelease_shell\fR\& to \fItrue\fR\&\&. For details, see section Running Tests from the Erlang Shell or from an Erlang Program in the User\&'s Guide\&.
.RE

.LP
.B
break(TestCase, Comment) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
TestCase = atom()
.br
Comment = string()
.br
Reason = \&'test case not running\&' | \&'enable break with release_shell option\&'
.br
.RE
.RE
.RS
.LP
Works the same way as \fIct:break/1\fR\&, only argument \fITestCase\fR\& makes it possible to pause a test case executing in a parallel group\&. Function \fIct:continue/1\fR\& is to be used to resume execution of \fITestCase\fR\&\&.
.LP
For details, see \fIct:break/1\fR\&\&.
.RE

.LP
.B
capture_get() -> ListOfStrings
.br
.RS
.LP
Types:

.RS 3
ListOfStrings = [string()]
.br
.RE
.RE
.RS
.LP
Equivalent to ct:capture_get([default])\&.
.RE

.LP
.B
capture_get(ExclCategories) -> ListOfStrings
.br
.RS
.LP
Types:

.RS 3
ExclCategories = [atom()]
.br
ListOfStrings = [string()]
.br
.RE
.RE
.RS
.LP
Returns and purges the list of text strings buffered during the latest session of capturing printouts to \fIstdout\fR\&\&. Log categories that are to be ignored in \fIListOfStrings\fR\& can be specified with \fIExclCategories\fR\&\&. If \fIExclCategories = []\fR\&, no filtering takes place\&.
.LP
See also \fIct:capture_start/0\fR\&, \fIct:capture_stop/0\fR\&, \fIct:log/3\fR\&\&.
.RE

.LP
.B
capture_start() -> ok
.br
.RS
.LP
Starts capturing all text strings printed to \fIstdout\fR\& during execution of the test case\&.
.LP
See also \fIct:capture_get/1\fR\&, \fIct:capture_stop/0\fR\&\&.
.RE

.LP
.B
capture_stop() -> ok
.br
.RS
.LP
Stops capturing text strings (a session started with \fIcapture_start/0\fR\&)\&.
.LP
See also \fIct:capture_get/1\fR\&, \fIct:capture_start/0\fR\&\&.
.RE

.LP
.B
comment(Comment) -> ok
.br
.RS
.LP
Types:

.RS 3
Comment = term()
.br
.RE
.RE
.RS
.LP
Prints the specified \fIComment\fR\& in the comment field in the table on the test suite result page\&.
.LP
If called several times, only the last comment is printed\&. The test case return value \fI{comment,Comment}\fR\& overwrites the string set by this function\&.
.RE

.LP
.B
comment(Format, Args) -> ok
.br
.RS
.LP
Types:

.RS 3
Format = string()
.br
Args = list()
.br
.RE
.RE
.RS
.LP
Prints the formatted string in the comment field in the table on the test suite result page\&.
.LP
Arguments \fIFormat\fR\& and \fIArgs\fR\& are used in a call to \fIio_lib:format/2\fR\& to create the comment string\&. The behavior of \fIcomment/2\fR\& is otherwise the same as function \fIct:comment/1\fR\&\&.
.RE

.LP
.B
continue() -> ok
.br
.RS
.LP
This function must be called to continue after a test case (not executing in a parallel group) has called function \fIct:break/1\fR\&\&.
.RE

.LP
.B
continue(TestCase) -> ok
.br
.RS
.LP
Types:

.RS 3
TestCase = atom()
.br
.RE
.RE
.RS
.LP
This function must be called to continue after a test case has called \fIct:break/2\fR\&\&. If the paused test case, \fITestCase\fR\&, executes in a parallel group, this function, rather than \fIcontinue/0\fR\&, must be used to let the test case proceed\&.
.RE

.LP
.B
decrypt_config_file(EncryptFileName, TargetFileName) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
EncryptFileName = string()
.br
TargetFileName = string()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Decrypts \fIEncryptFileName\fR\&, previously generated with \fIct:encrypt_config_file/2,3\fR\&\&. The original file contents is saved in the target file\&. The encryption key, a string, must be available in a text file named \fI\&.ct_config\&.crypt\fR\&, either in the current directory, or the home directory of the user (it is searched for in that order)\&.
.RE

.LP
.B
decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
EncryptFileName = string()
.br
TargetFileName = string()
.br
KeyOrFile = {key, string()} | {file, string()}
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Decrypts \fIEncryptFileName\fR\&, previously generated with \fIct:encrypt_config_file/2,3\fR\&\&. The original file contents is saved in the target file\&. The key must have the same value as that used for encryption\&.
.RE

.LP
.B
encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
SrcFileName = string()
.br
EncryptFileName = string()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Encrypts the source configuration file with DES3 and saves the result in file \fIEncryptFileName\fR\&\&. The key, a string, must be available in a text file named \fI\&.ct_config\&.crypt\fR\&, either in the current directory, or the home directory of the user (it is searched for in that order)\&.
.LP
For information about using encrypted configuration files when running tests, see section Encrypted Configuration Files in the User\&'s Guide\&.
.LP
For details on DES3 encryption/decryption, see application \fICrypto\fR\&\&.
.RE

.LP
.B
encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
SrcFileName = string()
.br
EncryptFileName = string()
.br
KeyOrFile = {key, string()} | {file, string()}
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Encrypts the source configuration file with DES3 and saves the result in the target file \fIEncryptFileName\fR\&\&. The encryption key to use is either the value in \fI{key,Key}\fR\& or the value stored in the file specified by \fI{file,File}\fR\&\&.
.LP
For information about using encrypted configuration files when running tests, see section Encrypted Configuration Files in the User\&'s Guide\&.
.LP
For details on DES3 encryption/decryption, see application \fICrypto\fR\&\&.
.RE

.LP
.B
fail(Reason) -> ok
.br
.RS
.LP
Types:

.RS 3
Reason = term()
.br
.RE
.RE
.RS
.LP
Terminates a test case with the specified error \fIReason\fR\&\&.
.RE

.LP
.B
fail(Format, Args) -> ok
.br
.RS
.LP
Types:

.RS 3
Format = string()
.br
Args = list()
.br
.RE
.RE
.RS
.LP
Terminates a test case with an error message specified by a format string and a list of values (used as arguments to \fIio_lib:format/2\fR\&)\&.
.RE

.LP
.B
get_config(Required) -> Value
.br
.RS
.LP
Equivalent to \fIct:get_config(Required, undefined, [])\fR\&\&.
.RE

.LP
.B
get_config(Required, Default) -> Value
.br
.RS
.LP
Equivalent to \fIct:get_config(Required, Default, [])\fR\&\&.
.RE

.LP
.B
get_config(Required, Default, Opts) -> ValueOrElement
.br
.RS
.LP
Types:

.RS 3
Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}
.br
KeyOrName = atom()
.br
SubKey = atom()
.br
Default = term()
.br
Opts = [Opt] | []
.br
Opt = element | all
.br
ValueOrElement = term() | Default
.br
.RE
.RE
.RS
.LP
Reads configuration data values\&.
.LP
Returns the matching values or configuration elements, given a configuration variable key or its associated name (if one has been specified with \fIct:require/2\fR\& or a \fIrequire\fR\& statement)\&.
.LP
\fIExample:\fR\&
.LP
Given the following configuration file:
.LP
.nf

 {unix,[{telnet,IpAddr},
        {user,[{username,Username},
               {password,Password}]}]}.
.fi
.LP
Then:
.LP
.nf

 ct:get_config(unix,Default) -> [{telnet,IpAddr}, 
  {user, [{username,Username}, {password,Password}]}]
 ct:get_config({unix,telnet},Default) -> IpAddr
 ct:get_config({unix,user,username},Default) -> Username
 ct:get_config({unix,ftp},Default) -> Default
 ct:get_config(unknownkey,Default) -> Default
.fi
.LP
If a configuration variable key has been associated with a name (by \fIct:require/2\fR\& or a \fIrequire\fR\& statement), the name can be used instead of the key to read the value:
.LP
.nf

 ct:require(myuser,{unix,user}) -> ok.
 ct:get_config(myuser,Default) -> [{username,Username}, {password,Password}]
.fi
.LP
If a configuration variable is defined in multiple files, use option \fIall\fR\& to access all possible values\&. The values are returned in a list\&. The order of the elements corresponds to the order that the configuration files were specified at startup\&.
.LP
If configuration elements (key-value tuples) are to be returned as result instead of values, use option \fIelement\fR\&\&. The returned elements are then on the form \fI{Required,Value}\fR\&\&.
.LP
See also \fIct:get_config/1\fR\&, \fIct:get_config/2\fR\&, \fIct:require/1\fR\&, \fIct:require/2\fR\&\&.
.RE

.LP
.B
get_event_mgr_ref() -> EvMgrRef
.br
.RS
.LP
Types:

.RS 3
EvMgrRef = atom()
.br
.RE
.RE
.RS
.LP
Gets a reference to the \fICommon Test\fR\& event manager\&. The reference can be used to, for example, add a user-specific event handler while tests are running\&.
.LP
\fIExample:\fR\&
.LP
.nf

 gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])
.fi
.RE

.LP
.B
get_progname() -> string()
.br
.RS
.LP
Returns the command used to start this Erlang instance\&. If this information could not be found, the string \fI"no_prog_name"\fR\& is returned\&.
.RE

.LP
.B
get_status() -> TestStatus | {error, Reason} | no_tests_running
.br
.RS
.LP
Types:

.RS 3
TestStatus = [StatusElem]
.br
StatusElem = {current, TestCaseInfo} | {successful, Successful} | {failed, Failed} | {skipped, Skipped} | {total, Total}
.br
TestCaseInfo = {Suite, TestCase} | [{Suite, TestCase}]
.br
Suite = atom()
.br
TestCase = atom()
.br
Successful = integer()
.br
Failed = integer()
.br
Skipped = {UserSkipped, AutoSkipped}
.br
UserSkipped = integer()
.br
AutoSkipped = integer()
.br
Total = integer()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Returns status of ongoing test\&. The returned list contains information about which test case is executing (a list of cases when a parallel test case group is executing), as well as counters for successful, failed, skipped, and total test cases so far\&.
.RE

.LP
.B
get_target_name(Handle) -> {ok, TargetName} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Handle = handle()
.br
TargetName = target_name()
.br
.RE
.RE
.RS
.LP
Returns the name of the target that the specified connection belongs to\&.
.RE

.LP
.B
get_testspec_terms() -> TestSpecTerms | undefined
.br
.RS
.LP
Types:

.RS 3
TestSpecTerms = [{Tag, Value}]
.br
Value = [term()]
.br
.RE
.RE
.RS
.LP
Gets a list of all test specification terms used to configure and run this test\&.
.RE

.LP
.B
get_testspec_terms(Tags) -> TestSpecTerms | undefined
.br
.RS
.LP
Types:

.RS 3
Tags = [Tag] | Tag
.br
Tag = atom()
.br
TestSpecTerms = [{Tag, Value}] | {Tag, Value}
.br
Value = [{Node, term()}] | [term()]
.br
Node = atom()
.br
.RE
.RE
.RS
.LP
Reads one or more terms from the test specification used to configure and run this test\&. \fITag\fR\& is any valid test specification tag, for example, \fIlabel\fR\&, \fIconfig\fR\&, or \fIlogdir\fR\&\&. User-specific terms are also available to read if option \fIallow_user_terms\fR\& is set\&.
.LP
All value tuples returned, except user terms, have the node name as first element\&.
.LP
To read test terms, use \fITag = tests\fR\& (rather than \fIsuites\fR\&, \fIgroups\fR\&, or \fIcases\fR\&)\&. \fIValue\fR\& is then the list of \fIall\fR\& tests on the form \fI[{Node,Dir,[{TestSpec,GroupsAndCases1},\&.\&.\&.]},\&.\&.\&.]\fR\&, where \fIGroupsAndCases = [{Group,[Case]}] | [Case]\fR\&\&.
.RE

.LP
.B
get_timetrap_info() -> {Time, {Scaling,ScaleVal}}
.br
.RS
.LP
Types:

.RS 3
Time = integer() | infinity
.br
Scaling = true | false
.br
ScaleVal = integer()
.br
.RE
.RE
.RS
.LP
Reads information about the timetrap set for the current test case\&. \fIScaling\fR\& indicates if \fICommon Test\fR\& will attempt to compensate timetraps automatically for runtime delays introduced by, for example, tools like cover\&. \fIScaleVal\fR\& is the value of the current scaling multiplier (always 1 if scaling is disabled)\&. Note the \fITime\fR\& is not the scaled result\&.
.RE

.LP
.B
get_verbosity(Category) -> Level | undefined
.br
.RS
.LP
Types:

.RS 3
Category = default | atom()
.br
Level = integer()
.br
.RE
.RE
.RS
.LP
This function returns the verbosity level for the specified logging category\&. See the  User\&'s Guide for details\&. Use the value \fIdefault\fR\& to read the general verbosity level\&.
.RE

.LP
.B
install(Opts) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Opts = [Opt]
.br
Opt = {config, ConfigFiles} | {event_handler, Modules} | {decrypt, KeyOrFile}
.br
ConfigFiles = [ConfigFile]
.br
ConfigFile = string()
.br
Modules = [atom()]
.br
KeyOrFile = {key, Key} | {file, KeyFile}
.br
Key = string()
.br
KeyFile = string()
.br
.RE
.RE
.RS
.LP
Installs configuration files and event handlers\&.
.LP
Run this function once before the first test\&.
.LP
\fIExample:\fR\&
.LP
.nf

 install([{config,["config_node.ctc","config_user.ctc"]}])
.fi
.LP
This function is automatically run by program \fIct_run\fR\&\&.
.RE

.LP
.B
listenv(Telnet) -> [Env]
.br
.RS
.LP
Types:

.RS 3
Telnet = term()
.br
Env = {Key, Value}
.br
Key = string()
.br
Value = string()
.br
.RE
.RE
.RS
.LP
Performs command \fIlistenv\fR\& on the specified Telnet connection and returns the result as a list of key-value pairs\&.
.RE

.LP
.B
log(Format) -> ok
.br
.RS
.LP
Equivalent to \fIct:log(default, 50, Format, [], [])\fR\&\&.
.RE

.LP
.B
log(X1, X2) -> ok
.br
.RS
.LP
Types:

.RS 3
X1 = Category | Importance | Format
.br
X2 = Format | FormatArgs
.br
.RE
.RE
.RS
.LP
Equivalent to \fIct:log(Category, Importance, Format, FormatArgs, [])\fR\&\&.
.RE

.LP
.B
log(X1, X2, X3) -> ok
.br
.RS
.LP
Types:

.RS 3
X1 = Category | Importance
.br
X2 = Importance | Format
.br
X3 = Format | FormatArgs | Opts
.br
.RE
.RE
.RS
.LP
Equivalent to \fIct:log(Category, Importance, Format, FormatArgs, Opts)\fR\&\&.
.RE

.LP
.B
log(X1, X2, X3, X4) -> ok
.br
.RS
.LP
Types:

.RS 3
X1 = Category | Importance
.br
X2 = Importance | Format
.br
X3 = Format | FormatArgs
.br
X4 = FormatArgs | Opts
.br
.RE
.RE
.RS
.LP
Equivalent to \fIct:log(Category, Importance, Format, FormatArgs, Opts)\fR\&\&.
.RE

.LP
.B
log(Category, Importance, Format, FormatArgs, Opts) -> ok
.br
.RS
.LP
Types:

.RS 3
Category = atom()
.br
Importance = integer()
.br
Format = string()
.br
FormatArgs = list()
.br
Opts = [Opt]
.br
Opt = {heading,string()} | no_css | esc_chars
.br
.RE
.RE
.RS
.LP
Prints from a test case to the log file\&.
.LP
This function is meant for printing a string directly from a test case to the test case log file\&.
.LP
Default \fICategory\fR\& is \fIdefault\fR\&, default \fIImportance\fR\& is \fI?STD_IMPORTANCE\fR\&, and default value for \fIFormatArgs\fR\& is \fI[]\fR\&\&.
.LP
For details on \fICategory\fR\&, \fIImportance\fR\& and the \fIno_css\fR\& option, see section  Logging - Categories and Verbosity Levels in the User\&'s Guide\&.
.LP
Common Test will not escape special HTML characters (<, > and &) in the text printed with this function, unless the \fIesc_chars\fR\& option is used\&.
.RE

.LP
.B
make_priv_dir() -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Reason = term()
.br
.RE
.RE
.RS
.LP
If the test is started with option \fIcreate_priv_dir\fR\& set to \fImanual_per_tc\fR\&, in order for the test case to use the private directory, it must first create it by calling this function\&.
.RE

.LP
.B
notify(Name, Data) -> ok
.br
.RS
.LP
Types:

.RS 3
Name = atom()
.br
Data = term()
.br
.RE
.RE
.RS
.LP
Sends an asynchronous notification of type \fIName\fR\& with \fIData\fR\&to the Common Test event manager\&. This can later be caught by any installed event manager\&.
.LP
See also \fIgen_event(3erl)\fR\&\&.
.RE

.LP
.B
pal(Format) -> ok
.br
.RS
.LP
Equivalent to \fIct:pal(default, 50, Format, [], [])\fR\&\&.
.RE

.LP
.B
pal(X1, X2) -> ok
.br
.RS
.LP
Types:

.RS 3
X1 = Category | Importance | Format
.br
X2 = Format | FormatArgs
.br
.RE
.RE
.RS
.LP
Equivalent to \fIct:pal(Category, Importance, Format, FormatArgs, [])\fR\&\&.
.RE

.LP
.B
pal(X1, X2, X3) -> ok
.br
.RS
.LP
Types:

.RS 3
X1 = Category | Importance
.br
X2 = Importance | Format
.br
X3 = Format | FormatArgs | Opts
.br
.RE
.RE
.RS
.LP
Equivalent to \fIct:pal(Category, Importance, Format, FormatArgs, Opts)\fR\&\&.
.RE

.LP
.B
pal(X1, X2, X3, X4) -> ok
.br
.RS
.LP
Types:

.RS 3
X1 = Category | Importance
.br
X2 = Importance | Format
.br
X3 = Format | FormatArgs
.br
X4 = FormatArgs | Opts
.br
.RE
.RE
.RS
.LP
Equivalent to \fIct:pal(Category, Importance, Format, FormatArgs, Opts)\fR\&\&.
.RE

.LP
.B
pal(Category, Importance, Format, FormatArgs, Opts) -> ok
.br
.RS
.LP
Types:

.RS 3
Category = atom()
.br
Importance = integer()
.br
Format = string()
.br
FormatArgs = list()
.br
Opts = [Opt]
.br
Opt = {heading,string()} | no_css
.br
.RE
.RE
.RS
.LP
Prints and logs from a test case\&.
.LP
This function is meant for printing a string from a test case, both to the test case log file and to the console\&.
.LP
Default \fICategory\fR\& is \fIdefault\fR\&, default \fIImportance\fR\& is \fI?STD_IMPORTANCE\fR\&, and default value for \fIFormatArgs\fR\& is \fI[]\fR\&\&.
.LP
For details on \fICategory\fR\& and \fIImportance\fR\&, see section Logging - Categories and Verbosity Levels in the User\&'s Guide\&.
.LP
Note that special characters in the text (<, > and &) will be escaped by Common Test before the text is printed to the log file\&.
.RE

.LP
.B
parse_table(Data) -> {Heading, Table}
.br
.RS
.LP
Types:

.RS 3
Data = [string()]
.br
Heading = tuple()
.br
Table = [tuple()]
.br
.RE
.RE
.RS
.LP
Parses the printout from an SQL table and returns a list of tuples\&.
.LP
The printout to parse is typically 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 \fIct:print(default, 50, Format, [], [])\fR\&\&.
.RE

.LP
.B
print(X1, X2) -> ok
.br
.RS
.LP
Types:

.RS 3
X1 = Category | Importance | Format
.br
X2 = Format | FormatArgs
.br
.RE
.RE
.RS
.LP
Equivalent to \fIct:print(Category, Importance, Format, FormatArgs, [])\fR\&\&.
.RE

.LP
.B
print(X1, X2, X3) -> ok
.br
.RS
.LP
Types:

.RS 3
X1 = Category | Importance
.br
X2 = Importance | Format
.br
X3 = Format | FormatArgs | Opts
.br
.RE
.RE
.RS
.LP
Equivalent to \fIct:print(Category, Importance, Format, FormatArgs, Opts)\fR\&\&.
.RE

.LP
.B
print(X1, X2, X3, X4) -> ok
.br
.RS
.LP
Types:

.RS 3
X1 = Category | Importance
.br
X2 = Importance | Format
.br
X3 = Format | FormatArgs
.br
X4 = FormatArgs | Opts
.br
.RE
.RE
.RS
.LP
Equivalent to \fIct:print(Category, Importance, Format, FormatArgs, Opts)\fR\&\&.
.RE

.LP
.B
print(Category, Importance, Format, FormatArgs, Opts) -> ok
.br
.RS
.LP
Types:

.RS 3
Category = atom()
.br
Importance = integer()
.br
Format = string()
.br
FormatArgs = list()
.br
Opts = [Opt]
.br
Opt = {heading,string()}
.br
.RE
.RE
.RS
.LP
Prints from a test case to the console\&.
.LP
This function is meant for printing a string from a test case to the console\&.
.LP
Default \fICategory\fR\& is \fIdefault\fR\&, default \fIImportance\fR\& is \fI?STD_IMPORTANCE\fR\&, and default value for \fIFormatArgs\fR\& is \fI[]\fR\&\&.
.LP
For details on \fICategory\fR\& and \fIImportance\fR\&, see section Logging - Categories and Verbosity Levels in the User\&'s Guide\&.
.RE

.LP
.B
reload_config(Required) -> ValueOrElement | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}
.br
KeyOrName = atom()
.br
SubKey = atom()
.br
ValueOrElement = term()
.br
.RE
.RE
.RS
.LP
Reloads configuration file containing specified configuration key\&.
.LP
This function updates the configuration data from which the specified configuration variable was read, and returns the (possibly) new value of this variable\&.
.LP
If some variables were present in the configuration, but are not loaded using this function, they are removed from the configuration table together with their aliases\&.
.RE

.LP
.B
remaining_test_procs() -> {TestProcs,SharedGL,OtherGLs}
.br
.RS
.LP
Types:

.RS 3
TestProcs = [{pid(),GL}]
.br
GL = pid()
.br
SharedGL = pid()
.br
OtherGLs = [pid()]
.br
.RE
.RE
.RS
.LP
This function will return the identity of test- and group leader processes that are still running at the time of this call\&. \fITestProcs\fR\& are processes in the system that have a Common Test IO process as group leader\&. \fISharedGL\fR\& is the central Common Test IO process, responsible for printing to log files for configuration functions and sequentially executing test cases\&. \fIOtherGLs\fR\& are Common Test IO processes that print to log files for test cases in parallel test case groups\&.
.LP
The process information returned by this function may be used to locate and terminate remaining processes after tests have finished executing\&. The function would typically by called from Common Test Hook functions\&.
.LP
Note that processes that execute configuration functions or test cases are never included in \fITestProcs\fR\&\&. It is therefore safe to use post configuration hook functions (such as post_end_per_suite, post_end_per_group, post_end_per_testcase) to terminate all processes in \fITestProcs\fR\& that have the current group leader process as its group leader\&.
.LP
Note also that the shared group leader (\fISharedGL\fR\&) must never be terminated by the user, only by Common Test\&. Group leader processes for parallel test case groups (\fIOtherGLs\fR\&) may however be terminated in post_end_per_group hook functions\&.
.RE

.LP
.B
remove_config(Callback, Config) -> ok
.br
.RS
.LP
Types:

.RS 3
Callback = atom()
.br
Config = string()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Removes configuration variables (together with their aliases) that were loaded with specified callback module and configuration string\&.
.RE

.LP
.B
require(Required) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Required = Key | {Key, SubKeys} | {Key, SubKey, SubKeys}
.br
Key = atom()
.br
SubKeys = SubKey | [SubKey]
.br
SubKey = atom()
.br
.RE
.RE
.RS
.LP
Checks if the required configuration is available\&. Arbitrarily deep tuples can be specified as \fIRequired\fR\&\&. Only the last element of the tuple can be a list of \fISubKey\fR\&s\&.
.LP
\fIExample 1\&.\fR\& Require the variable \fImyvar\fR\&:
.LP
.nf

 ok = ct:require(myvar).
.fi
.LP
In this case the configuration file must at least contain:
.LP
.nf

 {myvar,Value}.
.fi
.LP
\fIExample 2\&.\fR\& Require key \fImyvar\fR\& with subkeys \fIsub1\fR\& and \fIsub2\fR\&:
.LP
.nf

 ok = ct:require({myvar,[sub1,sub2]}).
.fi
.LP
In this case the configuration file must at least contain:
.LP
.nf

 {myvar,[{sub1,Value},{sub2,Value}]}.
.fi
.LP
\fIExample 3\&.\fR\& Require key \fImyvar\fR\& with subkey \fIsub1\fR\& with \fIsubsub1\fR\&:
.LP
.nf

 ok = ct:require({myvar,sub1,sub2}).
.fi
.LP
In this case the configuration file must at least contain:
.LP
.nf

 {myvar,[{sub1,[{sub2,Value}]}]}.
.fi
.LP
See also \fIct:get_config/1\fR\&, \fIct:get_config/2\fR\&, \fIct:get_config/3\fR\&, \fIct:require/2\fR\&\&.
.RE

.LP
.B
require(Name, Required) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Name = atom()
.br
Required = Key | {Key, SubKey} | {Key, SubKey, SubKey}
.br
SubKey = Key
.br
Key = atom()
.br
.RE
.RE
.RS
.LP
Checks if the required configuration is available and gives it a name\&. The semantics for \fIRequired\fR\& is the same as in \fIct:require/1\fR\& except that a list of \fISubKey\fR\&s cannot be specified\&.
.LP
If the requested data is available, the subentry is associated with \fIName\fR\& so that the value of the element can be read with \fIct:get_config/1,2\fR\& provided \fIName\fR\& is used instead of the whole \fIRequired\fR\& term\&.
.LP
\fIExample:\fR\&
.LP
Require one node with a Telnet connection and an FTP connection\&. Name the node \fIa\fR\&:
.LP
.nf

 ok = ct:require(a,{machine,node}).
.fi
.LP
All references to this node can then use the node name\&. For example, a file over FTP is fetched like follows:
.LP
.nf

 ok = ct:ftp_get(a,RemoteFile,LocalFile).
.fi
.LP
For this to work, the configuration file must at least contain:
.LP
.nf

 {machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.
.fi
.LP

.RS -4
.B
Note:
.RE
The behavior of this function changed radically in \fICommon Test\fR\& 1\&.6\&.2\&. To keep some backwards compatibility, it is still possible to do:
.br
\fIct:require(a,{node,[telnet,ftp]})\&.\fR\&
.br
This associates the name \fIa\fR\& with the top-level \fInode\fR\& entry\&. For this to work, the configuration file must at least contain:
.br
\fI{node,[{telnet,IpAddr},{ftp,IpAddr}]}\&.\fR\&

.LP
See also \fIct:get_config/1\fR\&, \fIct:get_config/2\fR\&, \fIct:get_config/3\fR\&, \fIct:require/1\fR\&\&.
.RE

.LP
.B
run(TestDirs) -> Result
.br
.RS
.LP
Types:

.RS 3
TestDirs = TestDir | [TestDir]
.br
.RE
.RE
.RS
.LP
Runs all test cases in all suites in the specified directories\&.
.LP
See also \fIct:run/3\fR\&\&.
.RE

.LP
.B
run(TestDir, Suite) -> Result
.br
.RS
.LP
Runs all test cases in the specified suite\&.
.LP
See also \fIct:run/3\fR\&\&.
.RE

.LP
.B
run(TestDir, Suite, Cases) -> Result
.br
.RS
.LP
Types:

.RS 3
TestDir = string()
.br
Suite = atom()
.br
Cases = atom() | [atom()]
.br
Result = [TestResult] | {error, Reason}
.br
.RE
.RE
.RS
.LP
Runs the specified test cases\&.
.LP
Requires that \fIct:install/1\fR\& has been run first\&.
.LP
Suites (\fI*_SUITE\&.erl\fR\&) files must be stored in \fITestDir\fR\& or \fITestDir/test\fR\&\&. All suites are compiled when the test is run\&.
.RE

.LP
.B
run_test(Opts) -> Result
.br
.RS
.LP
Types:

.RS 3
Opts = [OptTuples]
.br
OptTuples = {dir, TestDirs} | {suite, Suites} | {group, Groups} | {testcase, Cases} | {spec, TestSpecs} | {join_specs, Bool} | {label, Label} | {config, CfgFiles} | {userconfig, UserConfig} | {allow_user_terms, Bool} | {logdir, LogDir} | {silent_connections, Conns} | {stylesheet, CSSFile} | {cover, CoverSpecFile} | {cover_stop, Bool} | {step, StepOpts} | {event_handler, EventHandlers} | {include, InclDirs} | {auto_compile, Bool} | {abort_if_missing_suites, Bool} | {create_priv_dir, CreatePrivDir} | {multiply_timetraps, M} | {scale_timetraps, Bool} | {repeat, N} | {duration, DurTime} | {until, StopTime} | {force_stop, ForceStop} | {decrypt, DecryptKeyOrFile} | {refresh_logs, LogDir} | {logopts, LogOpts} | {verbosity, VLevels} | {basic_html, Bool} | {esc_chars, Bool} | {keep_logs,KeepSpec} | {ct_hooks, CTHs} | {enable_builtin_hooks, Bool} | {release_shell, Bool}
.br
TestDirs = [string()] | string()
.br
Suites = [string()] | [atom()] | string() | atom()
.br
Cases = [atom()] | atom()
.br
Groups = GroupNameOrPath | [GroupNameOrPath]
.br
GroupNameOrPath = [atom()] | atom() | all
.br
TestSpecs = [string()] | string()
.br
Label = string() | atom()
.br
CfgFiles = [string()] | string()
.br
UserConfig = [{CallbackMod, CfgStrings}] | {CallbackMod, CfgStrings}
.br
CallbackMod = atom()
.br
CfgStrings = [string()] | string()
.br
LogDir = string()
.br
Conns = all | [atom()]
.br
CSSFile = string()
.br
CoverSpecFile = string()
.br
StepOpts = [StepOpt] | []
.br
StepOpt = config | keep_inactive
.br
EventHandlers = EH | [EH]
.br
EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}
.br
InitArgs = [term()]
.br
InclDirs = [string()] | string()
.br
CreatePrivDir = auto_per_run | auto_per_tc | manual_per_tc
.br
M = integer()
.br
N = integer()
.br
DurTime = string(HHMMSS)
.br
StopTime = string(YYMoMoDDHHMMSS) | string(HHMMSS)
.br
ForceStop = skip_rest | Bool
.br
DecryptKeyOrFile = {key, DecryptKey} | {file, DecryptFile}
.br
DecryptKey = string()
.br
DecryptFile = string()
.br
LogOpts = [LogOpt]
.br
LogOpt = no_nl | no_src
.br
VLevels = VLevel | [{Category, VLevel}]
.br
VLevel = integer()
.br
Category = atom()
.br
KeepSpec = all | pos_integer()
.br
CTHs = [CTHModule | {CTHModule, CTHInitArgs}]
.br
CTHModule = atom()
.br
CTHInitArgs = term()
.br
Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | TestRunnerPid | {error, Reason}
.br
Ok = integer()
.br
Failed = integer()
.br
UserSkipped = integer()
.br
AutoSkipped = integer()
.br
TestRunnerPid = pid()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Runs tests as specified by the combination of options in \fIOpts\fR\&\&. The options are the same as those used with program \fIct_run\fR\&, see Run Tests from Command Line in the \fIct_run\fR\& manual page\&.
.LP
Here a \fITestDir\fR\& can be used to point out the path to a \fISuite\fR\&\&. Option \fItestcase\fR\& corresponds to option \fI-case\fR\& in program \fIct_run\fR\&\&. Configuration files specified in \fIOpts\fR\& are installed automatically at startup\&.
.LP
\fITestRunnerPid\fR\& is returned if \fIrelease_shell == true\fR\&\&. For details, see \fIct:break/1\fR\&\&.
.LP
\fIReason\fR\& indicates the type of error encountered\&.
.RE

.LP
.B
run_testspec(TestSpec) -> Result
.br
.RS
.LP
Types:

.RS 3
TestSpec = [term()]
.br
Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | {error, Reason}
.br
Ok = integer()
.br
Failed = integer()
.br
UserSkipped = integer()
.br
AutoSkipped = integer()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Runs a test specified by \fITestSpec\fR\&\&. The same terms are used as in test specification files\&.
.LP
\fIReason\fR\& indicates the type of error encountered\&.
.RE

.LP
.B
set_verbosity(Category, Level) -> ok
.br
.RS
.LP
Types:

.RS 3
Category = default | atom()
.br
Level = integer()
.br
.RE
.RE
.RS
.LP
Use this function to set, or modify, the verbosity level for a logging category\&. See the  User\&'s Guide for details\&. Use the value \fIdefault\fR\& to set the general verbosity level\&.
.RE

.LP
.B
sleep(Time) -> ok
.br
.RS
.LP
Types:

.RS 3
Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity
.br
Hours = integer()
.br
Mins = integer()
.br
Secs = integer()
.br
Millisecs = integer() | float()
.br
.RE
.RE
.RS
.LP
This function, similar to \fItimer:sleep/1\fR\& in STDLIB, suspends the test case for a specified time\&. However, this function also multiplies \fITime\fR\& with the \fImultiply_timetraps\fR\& value (if set) and under certain circumstances also scales up the time automatically if \fIscale_timetraps\fR\& is set to \fItrue\fR\& (default is \fIfalse\fR\&)\&.
.RE

.LP
.B
start_interactive() -> ok
.br
.RS
.LP
Starts \fICommon Test\fR\& 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 OS command line with \fIct_run -shell [-config File\&.\&.\&.]\fR\&\&.
.LP
If any functions (for example, Telnet or FTP) using "required configuration data" are to be called from the Erlang shell, configuration data must first be required with \fIct:require/2\fR\&\&.
.LP
\fIExample:\fR\&
.LP
.nf

 > ct:require(unix_telnet, unix).
 ok
 > ct_telnet:open(unix_telnet).
 {ok,<0.105.0>}
 > ct_telnet:cmd(unix_telnet, "ls .").
 {ok,["ls","file1  ...",...]}
.fi
.RE

.LP
.B
step(TestDir, Suite, Case) -> Result
.br
.RS
.LP
Types:

.RS 3
Case = atom()
.br
.RE
.RE
.RS
.LP
Steps through a test case with the debugger\&.
.LP
See also \fIct:run/3\fR\&\&.
.RE

.LP
.B
step(TestDir, Suite, Case, Opts) -> Result
.br
.RS
.LP
Types:

.RS 3
Case = atom()
.br
Opts = [Opt] | []
.br
Opt = config | keep_inactive
.br
.RE
.RE
.RS
.LP
Steps through a test case with the debugger\&. If option \fIconfig\fR\& has been specified, breakpoints are also set on the configuration functions in \fISuite\fR\&\&.
.LP
See also \fIct:run/3\fR\&\&.
.RE

.LP
.B
stop_interactive() -> ok
.br
.RS
.LP
Exits the interactive mode\&.
.LP
See also \fIct:start_interactive/0\fR\&\&.
.RE

.LP
.B
sync_notify(Name, Data) -> ok
.br
.RS
.LP
Types:

.RS 3
Name = atom()
.br
Data = term()
.br
.RE
.RE
.RS
.LP
Sends a synchronous notification of type \fIName\fR\& with \fIData\fR\& to the \fICommon Test\fR\& event manager\&. This can later be caught by any installed event manager\&.
.LP
See also \fIgen_event(3erl)\fR\&\&.
.RE

.LP
.B
testcases(TestDir, Suite) -> Testcases | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
TestDir = string()
.br
Suite = atom()
.br
Testcases = list()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Returns all test cases in the specified suite\&.
.RE

.LP
.B
timetrap(Time) -> ok
.br
.RS
.LP
Types:

.RS 3
Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity | Func
.br
Hours = integer()
.br
Mins = integer()
.br
Secs = integer()
.br
Millisecs = integer()
.br
Func = {M, F, A} | function()
.br
M = atom()
.br
F = atom()
.br
A = list()
.br
.RE
.RE
.RS
.LP
Sets a new timetrap for the running test case\&.
.LP
If the argument is \fIFunc\fR\&, the timetrap is triggered when this function returns\&. \fIFunc\fR\& can also return a new \fITime\fR\& value, which in that case is the value for the new timetrap\&.
.RE

.LP
.B
userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
TestDir = string()
.br
Suite = atom()
.br
SuiteUserData = [term()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Returns any data specified with tag \fIuserdata\fR\& in the list of tuples returned from \fIsuite/0\fR\&\&.
.RE

.LP
.B
userdata(TestDir, Suite, Case::GroupOrCase) -> TCUserData | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
TestDir = string()
.br
Suite = atom()
.br
GroupOrCase = {group, GroupName} | atom()
.br
GroupName = atom()
.br
TCUserData = [term()]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Returns any data specified with tag \fIuserdata\fR\& in the list of tuples returned from \fISuite:group(GroupName)\fR\& or \fISuite:Case()\fR\&\&.
.RE