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
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 is to be used to re-
trieve information from the Config 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 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() = pid()
The identity (handle) of a connection.
config_key() = atom()
A configuration key which exists in a configuration file
target_name() = atom()
A name and association to configuration data introduced through
a require statement, or a call to ct:require/2, for example,
ct:require(mynodename,{node,[telnet]}).
key_or_name() = config_key() | target_name()
conn_log_options() = [conn_log_option()]
Options that can be given to the cth_conn_log hook, which is
used for logging of NETCONF and Telnet connections. See ct_net-
confc or ct_telnet for description and examples of how to use
this hook.
conn_log_option() = {log_type,conn_log_type()} | {hosts,[key_or_name()]}
conn_log_type() = raw | pretty | html | silent
conn_log_mod() = ct_netconfc | ct_telnet
EXPORTS
abort_current_testcase(Reason) -> ok | {error, ErrorReason}
Types:
Reason = term()
ErrorReason = no_testcase_running | parallel_group
Aborts the currently executing test case. The user must know
with certainty which test case is currently executing. The func-
tion is therefore only safe to call from a function that 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.
add_config(Callback, Config) -> ok | {error, Reason}
Types:
Callback = atom()
Config = string()
Reason = term()
Loads configuration variables using the specified callback mod-
ule and configuration string. The callback module is to be ei-
ther loaded or present in the code part. Loaded configuration
variables can later be removed using function ct:remove_con-
fig/2.
break(Comment) -> ok | {error, Reason}
Types:
Comment = string()
Reason = {multiple_cases_running, TestCases} | 'enable break
with release_shell option'
TestCases = [atom()]
Cancels any active timetrap and pauses the execution of the cur-
rent test case until the user calls function continue/0. 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,
ct:break/2 is to be called instead.
A cancelled timetrap is not automatically reactivated after the
break, but must be started exlicitly with ct:timetrap/1.
In order for the break/continue functionality to work, Common
Test must release the shell process controlling stdin. This is
done by setting start option release_shell to true. For details,
see section Running Tests from the Erlang Shell or from an Er-
lang Program in the User's Guide.
break(TestCase, Comment) -> ok | {error, Reason}
Types:
TestCase = atom()
Comment = string()
Reason = 'test case not running' | 'enable break with re-
lease_shell option'
Works the same way as ct:break/1, only argument TestCase makes
it possible to pause a test case executing in a parallel group.
Function ct:continue/1 is to be used to resume execution of
TestCase.
For details, see ct:break/1.
capture_get() -> ListOfStrings
Types:
ListOfStrings = [string()]
Equivalent to ct:capture_get([default]).
capture_get(ExclCategories) -> ListOfStrings
Types:
ExclCategories = [atom()]
ListOfStrings = [string()]
Returns and purges the list of text strings buffered during the
latest session of capturing printouts to stdout. Log categories
that are to be ignored in ListOfStrings can be specified with
ExclCategories. If ExclCategories = [], no filtering takes
place.
See also ct:capture_start/0, ct:capture_stop/0, ct:log/3.
capture_start() -> ok
Starts capturing all text strings printed to stdout during exe-
cution of the test case.
See also ct:capture_get/1, ct:capture_stop/0.
capture_stop() -> ok
Stops capturing text strings (a session started with cap-
ture_start/0).
See also ct:capture_get/1, ct:capture_start/0.
comment(Comment) -> ok
Types:
Comment = term()
Prints the specified 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.
comment(Format, Args) -> ok
Types:
Format = string()
Args = list()
Prints the formatted string in the comment field in the table on
the test suite result page.
Arguments Format and Args are used in a call to io_lib:format/2
to create the comment string. The behavior of comment/2 is oth-
erwise the same as function ct:comment/1.
continue() -> ok
This function must be called to continue after a test case (not
executing in a parallel group) has called function ct:break/1.
continue(TestCase) -> ok
Types:
TestCase = atom()
This function must be called to continue after a test case has
called ct:break/2. If the paused test case, TestCase, executes
in a parallel group, this function, rather than continue/0, must
be used to let the test case proceed.
decrypt_config_file(EncryptFileName, TargetFileName) -> ok | {error,
Reason}
Types:
EncryptFileName = string()
TargetFileName = string()
Reason = term()
Decrypts EncryptFileName, previously generated with ct:en-
crypt_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, either in the current di-
rectory, or the home directory of the user (it is searched for
in that order).
decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> ok |
{error, Reason}
Types:
EncryptFileName = string()
TargetFileName = string()
KeyOrFile = {key, string()} | {file, string()}
Reason = term()
Decrypts EncryptFileName, previously generated with ct:en-
crypt_config_file/2,3. The original file contents is saved in
the target file. The key must have the same value as that used
for encryption.
encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error, Rea-
son}
Types:
SrcFileName = string()
EncryptFileName = string()
Reason = term()
Encrypts the source configuration 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, either in the
current directory, or the home directory of the user (it is
searched for in that order).
For information about using encrypted configuration files when
running tests, see section Encrypted Configuration Files in the
User's Guide.
For details on DES3 encryption/decryption, see application
Crypto.
encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -> ok |
{error, Reason}
Types:
SrcFileName = string()
EncryptFileName = string()
KeyOrFile = {key, string()} | {file, string()}
Reason = term()
Encrypts the source configuration 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}.
For information about using encrypted configuration files when
running tests, see section Encrypted Configuration Files in the
User's Guide.
For details on DES3 encryption/decryption, see application
Crypto.
fail(Reason) -> ok
Types:
Reason = term()
Terminates a test case with the specified error Reason.
fail(Format, Args) -> ok
Types:
Format = string()
Args = list()
Terminates a test case with an error message specified by a for-
mat string and a list of values (used as arguments to
io_lib:format/2).
get_config(Required) -> Value
Equivalent to ct:get_config(Required, undefined, []).
get_config(Required, Default) -> Value
Equivalent to ct:get_config(Required, Default, []).
get_config(Required, Default, Opts) -> ValueOrElement
Types:
Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, Sub-
Key, SubKey}
KeyOrName = atom()
SubKey = atom()
Default = term()
Opts = [Opt] | []
Opt = element | all
ValueOrElement = term() | Default
Reads configuration data values.
Returns the matching values or configuration elements, given a
configuration variable key or its associated name (if one has
been specified with ct:require/2 or a require statement).
Example:
Given the following configuration file:
{unix,[{telnet,IpAddr},
{user,[{username,Username},
{password,Password}]}]}.
Then:
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
If a configuration variable key has been associated with a name
(by ct:require/2 or a require statement), the name can be used
instead of the key to read the value:
ct:require(myuser,{unix,user}) -> ok.
ct:get_config(myuser,Default) -> [{username,Username}, {password,Password}]
If a configuration variable is defined in multiple files, use
option all to access all possible values. The values are re-
turned in a list. The order of the elements corresponds to the
order that the configuration files were specified at startup.
If configuration elements (key-value tuples) are to be returned
as result instead of values, use option element. The returned
elements are then on the form {Required,Value}.
See also ct:get_config/1, ct:get_config/2, ct:require/1, ct:re-
quire/2.
get_event_mgr_ref() -> EvMgrRef
Types:
EvMgrRef = atom()
Gets a reference to the Common Test event manager. The reference
can be used to, for example, add a user-specific event handler
while tests are running.
Example:
gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])
get_progname() -> string()
Returns the command used to start this Erlang instance. If this
information could not be found, the string "no_prog_name" is re-
turned.
get_status() -> TestStatus | {error, Reason} | no_tests_running
Types:
TestStatus = [StatusElem]
StatusElem = {current, TestCaseInfo} | {successful, Success-
ful} | {failed, Failed} | {skipped, Skipped} | {total, Total}
TestCaseInfo = {Suite, TestCase} | [{Suite, TestCase}]
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 in-
formation about which test case is executing (a list of cases
when a parallel test case group is executing), as well as coun-
ters for successful, failed, skipped, and total test cases so
far.
get_target_name(Handle) -> {ok, TargetName} | {error, Reason}
Types:
Handle = handle()
TargetName = target_name()
Returns the name of the target that the specified connection be-
longs to.
get_testspec_terms() -> TestSpecTerms | undefined
Types:
TestSpecTerms = [{Tag, Value}]
Value = [term()]
Gets a list of all test specification terms used to configure
and run this test.
get_testspec_terms(Tags) -> TestSpecTerms | undefined
Types:
Tags = [Tag] | Tag
Tag = atom()
TestSpecTerms = [{Tag, Value}] | {Tag, Value}
Value = [{Node, term()}] | [term()]
Node = atom()
Reads one or more terms from the test specification used to con-
figure and run this test. Tag is any valid test specification
tag, for example, label, config, or logdir. User-specific terms
are also available to read if option allow_user_terms is set.
All value tuples returned, except user terms, have the node name
as first element.
To read test terms, use Tag = tests (rather than suites, groups,
or cases). Value is then the list of all tests on the form
[{Node,Dir,[{TestSpec,GroupsAndCases1},...]},...], where Group-
sAndCases = [{Group,[Case]}] | [Case].
get_timetrap_info() -> {Time, {Scaling,ScaleVal}}
Types:
Time = integer() | infinity
Scaling = true | false
ScaleVal = integer()
Reads information about the timetrap set for the current test
case. Scaling indicates if Common Test will attempt to compen-
sate timetraps automatically for runtime delays introduced by,
for example, tools like cover. ScaleVal is the value of the cur-
rent scaling multipler (always 1 if scaling is disabled). Note
the Time is not the scaled result.
get_verbosity(Category) -> Level | undefined
Types:
Category = default | atom()
Level = integer()
This function returns the verbosity level for the specified log-
ging category. See the User's Guide for details. Use the value
default to read the general verbosity level.
install(Opts) -> ok | {error, Reason}
Types:
Opts = [Opt]
Opt = {config, ConfigFiles} | {event_handler, Modules} | {de-
crypt, KeyOrFile}
ConfigFiles = [ConfigFile]
ConfigFile = string()
Modules = [atom()]
KeyOrFile = {key, Key} | {file, KeyFile}
Key = string()
KeyFile = string()
Installs configuration files and event handlers.
Run this function once before the first test.
Example:
install([{config,["config_node.ctc","config_user.ctc"]}])
This function is automatically run by program ct_run.
listenv(Telnet) -> [Env]
Types:
Telnet = term()
Env = {Key, Value}
Key = string()
Value = string()
Performs command listenv on the specified Telnet connection and
returns the result as a list of key-value pairs.
log(Format) -> ok
Equivalent to ct:log(default, 50, Format, [], []).
log(X1, X2) -> ok
Types:
X1 = Category | Importance | Format
X2 = Format | FormatArgs
Equivalent to ct:log(Category, Importance, Format, FormatArgs,
[]).
log(X1, X2, X3) -> ok
Types:
X1 = Category | Importance
X2 = Importance | Format
X3 = Format | FormatArgs | Opts
Equivalent to ct:log(Category, Importance, Format, FormatArgs,
Opts).
log(X1, X2, X3, X4) -> ok
Types:
X1 = Category | Importance
X2 = Importance | Format
X3 = Format | FormatArgs
X4 = FormatArgs | Opts
Equivalent to ct:log(Category, Importance, Format, FormatArgs,
Opts).
log(Category, Importance, Format, FormatArgs, Opts) -> ok
Types:
Category = atom()
Importance = integer()
Format = string()
FormatArgs = list()
Opts = [Opt]
Opt = {heading,string()} | no_css | esc_chars
Prints 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, default Importance is ?STD_IMPOR-
TANCE, and default value for FormatArgs is [].
For details on Category, Importance and the no_css option, see
section Logging - Categories and Verbosity Levels in the User's
Guide.
Common Test will not escape special HTML characters (<, > and &)
in the text printed with this function, unless the esc_chars op-
tion is used.
make_priv_dir() -> ok | {error, Reason}
Types:
Reason = term()
If the test is started with option create_priv_dir set to man-
ual_per_tc, in order for the test case to use the private direc-
tory, it must first create it by calling this function.
notify(Name, Data) -> ok
Types:
Name = atom()
Data = term()
Sends an asynchronous notification of type Name with Datato the
Common Test event manager. This can later be caught by any in-
stalled event manager.
See also gen_event(3erl).
pal(Format) -> ok
Equivalent to ct:pal(default, 50, Format, [], []).
pal(X1, X2) -> ok
Types:
X1 = Category | Importance | Format
X2 = Format | FormatArgs
Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
[]).
pal(X1, X2, X3) -> ok
Types:
X1 = Category | Importance
X2 = Importance | Format
X3 = Format | FormatArgs | Opts
Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
Opts).
pal(X1, X2, X3, X4) -> ok
Types:
X1 = Category | Importance
X2 = Importance | Format
X3 = Format | FormatArgs
X4 = FormatArgs | Opts
Equivalent to ct:pal(Category, Importance, Format, FormatArgs,
Opts).
pal(Category, Importance, Format, FormatArgs, Opts) -> ok
Types:
Category = atom()
Importance = integer()
Format = string()
FormatArgs = list()
Opts = [Opt]
Opt = {heading,string()} | no_css
Prints and logs 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, default Importance is ?STD_IMPOR-
TANCE, and default value for FormatArgs is [].
For details on Category and Importance, see section Logging -
Categories and Verbosity Levels in the User's Guide.
Note that special characters in the text (<, > and &) will be
escaped by Common Test before the text is printed to the log
file.
parse_table(Data) -> {Heading, Table}
Types:
Data = [string()]
Heading = tuple()
Table = [tuple()]
Parses the printout from an SQL table and returns a list of tu-
ples.
The printout to parse is typically the result of a select com-
mand 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.
print(Format) -> ok
Equivalent to ct:print(default, 50, Format, [], []).
print(X1, X2) -> ok
Types:
X1 = Category | Importance | Format
X2 = Format | FormatArgs
Equivalent to ct:print(Category, Importance, Format, FormatArgs,
[]).
print(X1, X2, X3) -> ok
Types:
X1 = Category | Importance
X2 = Importance | Format
X3 = Format | FormatArgs | Opts
Equivalent to ct:print(Category, Importance, Format, FormatArgs,
Opts).
print(X1, X2, X3, X4) -> ok
Types:
X1 = Category | Importance
X2 = Importance | Format
X3 = Format | FormatArgs
X4 = FormatArgs | Opts
Equivalent to ct:print(Category, Importance, Format, FormatArgs,
Opts).
print(Category, Importance, Format, FormatArgs, Opts) -> ok
Types:
Category = atom()
Importance = integer()
Format = string()
FormatArgs = list()
Opts = [Opt]
Opt = {heading,string()}
Prints 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, default Importance is ?STD_IMPOR-
TANCE, and default value for FormatArgs is [].
For details on Category and Importance, see section Logging -
Categories and Verbosity Levels in the User's Guide.
reload_config(Required) -> ValueOrElement | {error, Reason}
Types:
Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, Sub-
Key, SubKey}
KeyOrName = atom()
SubKey = atom()
ValueOrElement = term()
Reloads configuration file containing specified configuration
key.
This function updates the configuration data from which the
specified configuration variable was read, and returns the (pos-
sibly) new value of this variable.
If some variables were present in the configuration, but are not
loaded using this function, they are removed from the configura-
tion table together with their aliases.
remaining_test_procs() -> {TestProcs,SharedGL,OtherGLs}
Types:
TestProcs = [{pid(),GL}]
GL = pid()
SharedGL = pid()
OtherGLs = [pid()]
This function will return the identity of test- and group leader
processes that are still running at the time of this call. Test-
Procs are processes in the system that have a Common Test IO
process as group leader. SharedGL is the central Common Test IO
process, responsible for printing to log files for configuration
functions and sequentially executing test cases. OtherGLs are
Common Test IO processes that print to log files for test cases
in parallel test case groups.
The process information returned by this function may be used to
locate and terminate remaining processes after tests have fin-
ished executing. The function would typically by called from
Common Test Hook functions.
Note that processes that execute configuration functions or test
cases are never included in TestProcs. 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 TestProcs that have the current
group leader process as its group leader.
Note also that the shared group leader (SharedGL) must never be
terminated by the user, only by Common Test. Group leader pro-
cesses for parallel test case groups (OtherGLs) may however be
terminated in post_end_per_group hook functions.
remove_config(Callback, Config) -> ok
Types:
Callback = atom()
Config = string()
Reason = term()
Removes configuration variables (together wih their aliases)
that were loaded with specified callback module and configura-
tion string.
require(Required) -> ok | {error, Reason}
Types:
Required = Key | {Key, SubKeys} | {Key, SubKey, SubKeys}
Key = atom()
SubKeys = SubKey | [SubKey]
SubKey = atom()
Checks if the required configuration is available. Arbitrarily
deep tuples can be specified as Required. Only the last element
of the tuple can be a list of SubKeys.
Example 1. Require the variable myvar:
ok = ct:require(myvar).
In this case the configuration file must at least contain:
{myvar,Value}.
Example 2. Require key myvar with subkeys sub1 and sub2:
ok = ct:require({myvar,[sub1,sub2]}).
In this case the configuration file must at least contain:
{myvar,[{sub1,Value},{sub2,Value}]}.
Example 3. Require key myvar with subkey sub1 with subsub1:
ok = ct:require({myvar,sub1,sub2}).
In this case the configuration file must at least contain:
{myvar,[{sub1,[{sub2,Value}]}]}.
See also ct:get_config/1, ct:get_config/2, ct:get_config/3,
ct:require/2.
require(Name, Required) -> ok | {error, Reason}
Types:
Name = atom()
Required = Key | {Key, SubKey} | {Key, SubKey, SubKey}
SubKey = Key
Key = atom()
Checks if the required configuration is available and gives it a
name. The semantics for Required is the same as in ct:require/1
except that a list of SubKeys cannot be specified.
If the requested data is available, the subentry is associated
with Name so that the value of the element can be read with
ct:get_config/1,2 provided Name is used instead of the whole Re-
quired term.
Example:
Require one node with a Telnet connection and an FTP connection.
Name the node a:
ok = ct:require(a,{machine,node}).
All references to this node can then use the node name. For ex-
ample, a file over FTP is fetched like follows:
ok = ct:ftp_get(a,RemoteFile,LocalFile).
For this to work, the configuration file must at least contain:
{machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.
Note:
The behavior of this function changed radically in Common Test
1.6.2. To keep some backwards compatability, it is still possi-
ble to do:
ct:require(a,{node,[telnet,ftp]}).
This associates the name a with the top-level node entry. For
this to work, the configuration file must at least contain:
{node,[{telnet,IpAddr},{ftp,IpAddr}]}.
See also ct:get_config/1, ct:get_config/2, ct:get_config/3,
ct:require/1.
run(TestDirs) -> Result
Types:
TestDirs = TestDir | [TestDir]
Runs all test cases in all suites in the specified directories.
See also ct:run/3.
run(TestDir, Suite) -> Result
Runs all test cases in the specified suite.
See also ct:run/3.
run(TestDir, Suite, Cases) -> Result
Types:
TestDir = string()
Suite = atom()
Cases = atom() | [atom()]
Result = [TestResult] | {error, Reason}
Runs the specified test cases.
Requires that ct:install/1 has been run first.
Suites (*_SUITE.erl) files must be stored in TestDir or Test-
Dir/test. All suites are compiled when the test is run.
run_test(Opts) -> Result
Types:
Opts = [OptTuples]
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_time-
traps, M} | {scale_timetraps, Bool} | {repeat, N} | {dura-
tion, DurTime} | {until, StopTime} | {force_stop, ForceStop}
| {decrypt, DecryptKeyOrFile} | {refresh_logs, LogDir} | {lo-
gopts, LogOpts} | {verbosity, VLevels} | {basic_html, Bool} |
{esc_chars, Bool} | {keep_logs,KeepSpec} | {ct_hooks, CTHs} |
{enable_builtin_hooks, Bool} | {release_shell, Bool}
TestDirs = [string()] | string()
Suites = [string()] | [atom()] | string() | atom()
Cases = [atom()] | atom()
Groups = GroupNameOrPath | [GroupNameOrPath]
GroupNameOrPath = [atom()] | atom() | all
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)
ForceStop = skip_rest | Bool
DecryptKeyOrFile = {key, DecryptKey} | {file, DecryptFile}
DecryptKey = string()
DecryptFile = string()
LogOpts = [LogOpt]
LogOpt = no_nl | no_src
VLevels = VLevel | [{Category, VLevel}]
VLevel = integer()
Category = atom()
KeepSpec = all | pos_integer()
CTHs = [CTHModule | {CTHModule, CTHInitArgs}]
CTHModule = atom()
CTHInitArgs = term()
Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | TestRun-
nerPid | {error, Reason}
Ok = integer()
Failed = integer()
UserSkipped = integer()
AutoSkipped = integer()
TestRunnerPid = pid()
Reason = term()
Runs tests as specified by the combination of options in Opts.
The options are the same as those used with program ct_run, see
Run Tests from Command Line in the ct_run manual page.
Here a TestDir can be used to point out the path to a Suite. Op-
tion testcase corresponds to option -case in program ct_run.
Configuration files specified in Opts are installed automati-
cally at startup.
TestRunnerPid is returned if release_shell == true. For details,
see ct:break/1.
Reason indicates the type of error encountered.
run_testspec(TestSpec) -> Result
Types:
TestSpec = [term()]
Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | {error,
Reason}
Ok = integer()
Failed = integer()
UserSkipped = integer()
AutoSkipped = integer()
Reason = term()
Runs a test specified by TestSpec. The same terms are used as in
test specification files.
Reason indicates the type of error encountered.
set_verbosity(Category, Level) -> ok
Types:
Category = default | atom()
Level = integer()
Use this function to set, or modify, the verbosity level for a
logging category. See the User's Guide for details. Use the
value default to set the general verbosity level.
sleep(Time) -> ok
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 in STDLIB, suspends the
test case for a specified time. However, this function also mul-
tiplies Time with the multiply_timetraps value (if set) and un-
der certain circumstances also scales up the time automatically
if scale_timetraps is set to true (default is false).
start_interactive() -> ok
Starts Common Test 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 (for example, Telnet or FTP) using "required
configuration data" are to be called from the Erlang shell, con-
figuration 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 ...",...]}
step(TestDir, Suite, Case) -> Result
Types:
Case = atom()
Steps through a test case with the debugger.
See also ct:run/3.
step(TestDir, Suite, Case, Opts) -> Result
Types:
Case = atom()
Opts = [Opt] | []
Opt = config | keep_inactive
Steps through a test case with the debugger. If option config
has been specifed, breakpoints are also set on the configuration
functions in Suite.
See also ct:run/3.
stop_interactive() -> ok
Exits the interactive mode.
See also ct:start_interactive/0.
sync_notify(Name, Data) -> ok
Types:
Name = atom()
Data = term()
Sends a synchronous notification of type Name with Data to the
Common Test event manager. This can later be caught by any in-
stalled event manager.
See also gen_event(3erl).
testcases(TestDir, Suite) -> Testcases | {error, Reason}
Types:
TestDir = string()
Suite = atom()
Testcases = list()
Reason = term()
Returns all test cases in the specified suite.
timetrap(Time) -> ok
Types:
Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} |
Millisecs | infinity | Func
Hours = integer()
Mins = integer()
Secs = integer()
Millisecs = integer()
Func = {M, F, A} | function()
M = atom()
F = atom()
A = list()
Sets a new timetrap for the running test case.
If the argument is Func, the timetrap is triggered when this
function returns. Func can also return a new Time value, which
in that case is the value for the new timetrap.
userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}
Types:
TestDir = string()
Suite = atom()
SuiteUserData = [term()]
Reason = term()
Returns any data specified with tag userdata in the list of tu-
ples returned from suite/0.
userdata(TestDir, Suite, Case::GroupOrCase) -> TCUserData | {error,
Reason}
Types:
TestDir = string()
Suite = atom()
GroupOrCase = {group, GroupName} | atom()
GroupName = atom()
TCUserData = [term()]
Reason = term()
Returns any data specified with tag userdata in the list of tu-
ples returned from Suite:group(GroupName) or Suite:Case().
Ericsson AB common_test 1.19 ct(3erl)