table of contents
other versions
- wheezy 1:15.b.1-dfsg-4+deb7u1
- wheezy-backports 1:17.3-dfsg-4~bpo70+1
- jessie 1:17.3-dfsg-4+deb8u1
- jessie-backports 1:19.2.1+dfsg-2~bpo8+1
- testing 1:19.2.1+dfsg-2
- unstable 1:19.2.1+dfsg-2
- experimental 1:19.3.1+dfsg-1
other sections
ct(3erl) | Erlang Module Definition | ct(3erl) |
NAME¶
ct - Main user interface for the Common Test framework.DESCRIPTION¶
Main user interface for the Common Test framework. This module implements the command line interface for running tests and some basic functions for common test case issues such as configuration and logging. Test Suite Support Macros The config macro is defined in ct.hrl. This macro should be used to retrieve information from the Config 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 Config variable supplied to the test case. Possible configuration variables include:- *
- data_dir - Data file directory.
- *
- priv_dir - Scratch file directory.
- *
- Whatever added by init_per_suite/1 or init_per_testcase/2 in the test suite.
DATA TYPES¶
- handle() = handle() (see module ct_gen_conn) | term():
-
The identity of a specific connection.
- target_name() = var_name():
-
The name of a target.
- var_name() = atom():
-
A variable name which is specified when ct:require/2 is called, e.g.
ct:require(mynodename,{node,[telnet]})
EXPORTS¶
abort_current_testcase(Reason) -> ok | {error, no_testcase_running}
Types:
Reason = term()
When calling this function, the currently executing test case will be aborted.
It is the user's responsibility to know for sure which test case is currently
executing. The function is therefore only safe to call from a function which
has been called (or synchronously invoked) by the test case.
Reason, the reason for aborting the test case, is printed in the test
case log.
Types:
Callback = atom()
Config = string()
Reason = term()
This function loads configuration variables using the given callback module and
configuration string. Callback module should be either loaded or present in
the code part. Loaded configuration variables can later be removed using
remove_config/2 function.
Types:
ListOfStrings = [string()]
Equivalent to capture_get([default]).
Types:
ExclCategories = [atom()]
ListOfStrings = [string()]
Return and purge the list of text strings buffered during the latest session of
capturing printouts to stdout. With ExclCategories it's possible to
specify log categories that should be ignored in ListOfStrings. If
ExclCategories = [], no filtering takes place.
See also: capture_start/0, capture_stop/0,
log/3.
Start capturing all text strings printed to stdout during execution of the test
case.
See also: capture_get/1, capture_stop/0.
Stop capturing text strings (a session started with capture_start/0).
See also: capture_get/1, capture_start/0.
Types:
Comment = term()
Print the given Comment in the comment field in the table on the test
suite result page.
If called several times, only the last comment is printed. The test case return
value {comment,Comment} overwrites the string set by this
function.
Types:
Format = string()
Args = list()
Print the formatted string in the comment field in the table on the test suite
result page.
The Format and Args arguments are used in call to
io_lib:format/2 in order to create the comment string. The behaviour of
comment/2 is otherwise the same as the comment/1 function (see
above for details).
Types:
EncryptFileName = string()
TargetFileName = string()
Reason = term()
This function decrypts EncryptFileName, previously generated with
encrypt_config_file/2/3. The original file contents is saved in the
target file. The encryption key, a string, must be available in a text file
named .ct_config.crypt in the current directory, or the home directory
of the user (it is searched for in that order).
Types:
EncryptFileName = string()
TargetFileName = string()
KeyOrFile = {key, string()} | {file, string()}
Reason = term()
This function decrypts EncryptFileName, previously generated with
encrypt_config_file/2/3. The original file contents is saved in the
target file. The key must have the the same value as that used for
encryption.
Types:
SrcFileName = string()
EncryptFileName = string()
Reason = term()
This function encrypts the source config file with DES3 and saves the result in
file EncryptFileName. The key, a string, must be available in a text
file named .ct_config.crypt in the current directory, or the home
directory of the user (it is searched for in that order).
See the Common Test User's Guide for information about using encrypted config
files when running tests.
See the crypto application for details on DES3
encryption/decryption.
Types:
SrcFileName = string()
EncryptFileName = string()
KeyOrFile = {key, string()} | {file, string()}
Reason = term()
This function encrypts the source config file with DES3 and saves the result in
the target file EncryptFileName. The encryption key to use is either
the value in {key,Key} or the value stored in the file specified by
{file,File}.
See the Common Test User's Guide for information about using encrypted config
files when running tests.
See the crypto application for details on DES3
encryption/decryption.
Types:
Reason = term()
Terminate a test case with the given error Reason.
Types:
Format = string()
Args = list()
Terminate a test case with an error message specified by a format string and a
list of values (used as arguments to io_lib:format/2).
Equivalent to get_config(Required, undefined, []).
Equivalent to get_config(Required, Default, []).
Types:
Required = KeyOrName | {KeyOrName, SubKey}
KeyOrName = atom()
SubKey = atom()
Default = term()
Opts = [Opt] | []
Opt = element | all
ValueOrElement = term() | Default
Read config data values.
This function returns the matching value(s) or config element(s), given a config
variable key or its associated name (if one has been specified with
require/2 or a require statement).
Example, given the following config file:
get_config({unix,telnet},Default) -> IpAddr
get_config({unix,ftp},Default) -> Default
get_config(unknownkey,Default) -> Default
If a config variable key has been associated with a name (by means of
require/2 or a require statement), the name may be used instead of the
key to read the value:
require(myhost,unix) -> ok
get_config(myhost,Default) -> [{telnet,IpAddr}, {username,Username},
{password,Password}]
If a config variable is defined in multiple files and you want to access all
possible values, use the all option. The values will be returned in a
list and the order of the elements corresponds to the order that the config
files were specified at startup.
If you want config elements (key-value tuples) returned as result instead of
values, use the element option. The returned elements will then be on
the form {KeyOrName,Value}, or (in case a subkey has been specified)
{{KeyOrName,SubKey},Value}
See also: get_config/1, get_config/2, require/1,
require/2.
{unix,[{telnet,IpAddr}, {username,Username}, {password,Password}]}.get_config(unix,Default) -> [{telnet,IpAddr}, {username,Username}, {password,Password}]
Types:
TestStatus = [StatusElem]
StatusElem = {current, {Suite, TestCase}} | {successful, Successful} | {failed,
Failed} | {skipped, Skipped} | {total, Total}
Suite = atom()
TestCase = atom()
Successful = integer()
Failed = integer()
Skipped = {UserSkipped, AutoSkipped}
UserSkipped = integer()
AutoSkipped = integer()
Total = integer()
Reason = term()
Returns status of ongoing test. The returned list contains info about which test
case is currently executing, as well as counters for successful, failed,
skipped, and total test cases so far.
Types:
Handle = handle()
TargetName = target_name()
Return the name of the target that the given connection belongs to.
Types:
Time = integer() | infinity
Scale = true | false
Read info about the timetrap set for the current test case. Scale
indicates if Common Test will attempt to automatically compensate timetraps
for runtime delays introduced by e.g. tools like cover.
Types:
Opts = [Opt]
Opt = {config, ConfigFiles} | {event_handler, Modules} | {decrypt, KeyOrFile}
ConfigFiles = [ConfigFile]
ConfigFile = string()
Modules = [atom()]
KeyOrFile = {key, Key} | {file, KeyFile}
Key = string()
KeyFile = string()
Install config files and event handlers.
Run this function once before first test.
Example:
install([{config,["config_node.ctc","config_user.ctc"]}]).
Note that this function is automatically run by the ct_run program.
Types:
Telnet = term()
Env = {Key, Value}
Key = string()
Value = string()
Performs the listenv command on the given telnet connection and returns the
result as a list of Key-Value pairs.
Equivalent to log(default, Format, []).
Types:
X1 = Category | Format
X2 = Format | Args
Equivalent to log(Category, Format, Args).
Types:
Category = atom()
Format = string()
Args = list()
Printout from a test case to the log file.
This function is meant for printing a string directly from a test case to the
test case log file.
Default Category is default and default Args is
[].
Types:
Reason = term()
If the test has been started with the create_priv_dir option set to
manual_per_tc, in order for the test case to use the private directory, it
must first create it by calling this function.
Equivalent to pal(default, Format, []).
Types:
X1 = Category | Format
X2 = Format | Args
Equivalent to pal(Category, Format, Args).
Types:
Category = atom()
Format = string()
Args = list()
Print and log from a test case.
This function is meant for printing a string from a test case, both to the test
case log file and to the console.
Default Category is default and default Args is
[].
Types:
Data = [string()]
Heading = tuple()
Table = [tuple()]
Parse the printout from an SQL table and return a list of tuples.
The printout to parse would typically be the result of a select command
in SQL. The returned Table is a list of tuples, where each tuple is a
row in the table.
Heading is a tuple of strings representing the headings of each column in
the table.
Equivalent to print(default, Format, []).
Equivalent to print(Category, Format, Args).
Types:
Category = atom()
Format = string()
Args = list()
Printout from a test case to the console.
This function is meant for printing a string from a test case to the console.
Default Category is default and default Args is
[].
Types:
Required = KeyOrName | {KeyOrName, SubKey}
KeyOrName = atom()
SubKey = atom()
ValueOrElement = term()
Reload config file which contains specified configuration key.
This function performs updating of the configuration data from which the given
configuration variable was read, and returns the (possibly) new value of this
variable.
Note that if some variables were present in the configuration but are not loaded
using this function, they will be removed from the configuration table
together with their aliases.
Types:
Callback = atom()
Config = string()
Reason = term()
This function removes configuration variables (together with their aliases)
which were loaded with specified callback module and configuration
string.
Types:
Required = Key | {Key, SubKeys}
Key = atom()
SubKeys = SubKey | [SubKey]
SubKey = atom()
Check if the required configuration is available.
Example: require the variable myvar:
ok = ct:require(myvar)
In this case the config file must at least contain:
ok = ct:require({myvar,sub1})
In this case the config file must at least contain:
{myvar,Value}.Example: require the variable myvar with subvariable sub1:
{myvar,[{sub1,Value}]}.See also: get_config/1, get_config/2, get_config/3, require/2.
Types:
Name = atom()
Required = Key | {Key, SubKeys}
Key = atom()
SubKeys = SubKey | [SubKey]
SubKey = atom()
Check if the required configuration is available, and give it a name.
If the requested data is available, the main entry will be associated with
Name so that the value of the element can be read with
get_config/1,2 provided Name instead of the Key.
Example: Require one node with a telnet connection and an ftp connection. Name
the node a:
ok = ct:require(a,{node,[telnet,ftp]}).
All references to this node may then use the node name. E.g. you can fetch a
file over ftp like this:
ok = ct:ftp_get(a,RemoteFile,LocalFile).
For this to work, the config file must at least contain:
{node,[{telnet,IpAddr}, {ftp,IpAddr}]}.See also: get_config/1, get_config/2, get_config/3, require/1.
Types:
TestDirs = TestDir | [TestDir]
Run all test cases in all suites in the given directories.
See also: run/3.
Run all test cases in the given suite.
See also: run/3.
Types:
TestDir = string()
Suite = atom()
Cases = atom() | [atom()]
Result = [TestResult] | {error, Reason}
Run the given test case(s).
Requires that ct:install/1 has been run first.
Suites (*_SUITE.erl) files must be stored in TestDir or
TestDir/test. All suites will be compiled when test is run.
Types:
Opts = [OptTuples]
OptTuples = {dir, TestDirs} | {suite, Suites} | {group, Groups} | {testcase,
Cases} | {spec, TestSpecs} | {label, Label} | {config, CfgFiles} |
{userconfig, UserConfig} | {allow_user_terms, Bool} | {logdir, LogDir} |
{silent_connections, Conns} | {stylesheet, CSSFile} | {cover, CoverSpecFile} |
{step, StepOpts} | {event_handler, EventHandlers} | {include, InclDirs} |
{auto_compile, Bool} | {create_priv_dir, CreatePrivDir} | {multiply_timetraps,
M} | {scale_timetraps, Bool} | {repeat, N} | {duration, DurTime} | {until,
StopTime} | {force_stop, Bool} | {decrypt, DecryptKeyOrFile} | {refresh_logs,
LogDir} | {logopts, LogOpts} | {basic_html, Bool} | {ct_hooks, CTHs} |
{enable_builtin_hooks, Bool}
TestDirs = [string()] | string()
Suites = [string()] | [atom()] | string() | atom()
Cases = [atom()] | atom()
Groups = [atom()] | atom()
TestSpecs = [string()] | string()
Label = string() | atom()
CfgFiles = [string()] | string()
UserConfig = [{CallbackMod, CfgStrings}] | {CallbackMod, CfgStrings}
CallbackMod = atom()
CfgStrings = [string()] | string()
LogDir = string()
Conns = all | [atom()]
CSSFile = string()
CoverSpecFile = string()
StepOpts = [StepOpt] | []
StepOpt = config | keep_inactive
EventHandlers = EH | [EH]
EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}
InitArgs = [term()]
InclDirs = [string()] | string()
CreatePrivDir = auto_per_run | auto_per_tc | manual_per_tc
M = integer()
N = integer()
DurTime = string(HHMMSS)
StopTime = string(YYMoMoDDHHMMSS) | string(HHMMSS)
DecryptKeyOrFile = {key, DecryptKey} | {file, DecryptFile}
DecryptKey = string()
DecryptFile = string()
LogOpts = [LogOpt]
LogOpt = no_nl | no_src
CTHs = [CTHModule | {CTHModule, CTHInitArgs}]
CTHModule = atom()
CTHInitArgs = term()
Result = [TestResult] | {error, Reason}
Run tests as specified by the combination of options in Opts. The options
are the same as those used with the ct_run program. Note that
here a TestDir can be used to point out the path to a Suite.
Note also that the option testcase corresponds to the -case
option in the ct_run program. Configuration files specified in
Opts will be installed automatically at startup.
Types:
TestSpec = [term()]
Run test specified by TestSpec. The terms are the same as those used in
test specification files.
Types:
Time = {hours, Hours} | {minutes, Mins} |
{seconds, Secs} | Millisecs | infinity
Hours = integer()
Mins = integer()
Secs = integer()
Millisecs = integer() | float()
This function, similar to timer:sleep/1, suspends the test case for
specified time. However, this function also multiplies Time with the
'multiply_timetraps' value (if set) and under certain circumstances also
scales up the time automatically if 'scale_timetraps' is set to true (default
is false).
Start CT in interactive mode.
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 ct_run -shell [-config File...].
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 ct:require/2.
Example:
> ct:require(unix_telnet, unix).
ok
> ct_telnet:open(unix_telnet).
{ok,<0.105.0>}
> ct_telnet:cmd(unix_telnet, "ls .").
{ok,["ls","file1 ...",...]}
Types:
Case = atom()
Step through a test case with the debugger.
See also: run/3.
Types:
Case = atom()
Opts = [Opt] | []
Opt = config | keep_inactive
Step through a test case with the debugger. If the config option has been
given, breakpoints will be set also on the configuration functions in
Suite.
See also: run/3.
Exit the interactive mode.
See also: start_interactive/0.
Types:
TestDir = string()
Suite = atom()
Testcases = list()
Reason = term()
Returns all test cases in the specified suite.
Types:
Time = {hours, Hours} | {minutes, Mins} |
{seconds, Secs} | Millisecs | infinity | Func
Hours = integer()
Mins = integer()
Secs = integer()
Millisecs = integer() | float()
Func = {M, F, A} | function()
M = atom()
F = atom()
A = list()
Use this function to set a new timetrap for the running test case. If the
argument is Func, the timetrap will be triggered when this function
returns. Func may also return a new Time value, which in that
case will be the value for the new timetrap.
Types:
TestDir = string()
Suite = atom()
SuiteUserData = [term()]
Reason = term()
Returns any data specified with the tag userdata in the list of tuples
returned from Suite:suite/0.
Types:
TestDir = string()
Suite = atom()
GroupOrCase = {group, GroupName} | atom()
GroupName = atom()
TCUserData = [term()]
Reason = term()
Returns any data specified with the tag userdata in the list of tuples
returned from Suite:group(GroupName) or Suite:Case().
AUTHORS¶
common_test 1.6.1 |