View Source ct (common_test v1.27)
Main user interface for the Common Test framework.
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.
The framework stores configuration values in a property list usually named
Config. The list contains information about the test run added by the
framework itself and may also contain user-provided values. The configuration is
passed into individual test cases as well as support functions if defined.
Possible configuration variables include:
data_dir- Data file directorypriv_dir- Scratch file directory- Whatever added by
init_per_suite/1orinit_per_testcase/2in the test suite.
Warning
The
?configmacro, used to receive individual config values from theConfigproperty list, is deprecated. Please useproplists:get_value/2-3instead.
Summary
Types
A configuration key which exists in a configuration file
Options that can be given to the cth_conn_log 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.
The identity (handle) of a connection.
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]}).
Functions
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.
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 ct:remove_config/2.
Cancels any active timetrap and pauses the execution of the current 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.
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.
Equivalent to [ct:capture_get([default])](capture_get/1).
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.
Starts capturing all text strings printed to stdout during execution of the
test case.
Stops capturing text strings (a session started with capture_start/0).
Prints the specified Comment in the comment field in the table on the test
suite result page.
Prints the formatted string in the comment field in the table on the test suite result page.
This function must be called to continue after a test case (not executing in a
parallel group) has called function ct:break/1.
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.
Decrypts EncryptFileName, previously generated with
ct: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, either in the current
directory, or the home directory of the user (it is searched for in that order).
Decrypts EncryptFileName, previously generated with
ct:encrypt_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.
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).
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}.
Terminates a test case with the specified error Reason.
Terminates 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 ct:get_config(Required, undefined, []).
Reads configuration data values.
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.
Returns the command used to start this Erlang instance. If this information
could not be found, the string "no_prog_name" is returned.
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.
Returns the name of the target that the specified connection belongs to.
Gets a list of all test specification terms used to configure and run this test.
Reads one or more terms from the test specification used to configure 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.
Reads information about the timetrap set for the current test case. Scaling
indicates if Common Test will attempt to compensate timetraps automatically
for runtime delays introduced by, for example, tools like cover. ScaleVal is
the value of the current scaling multiplier (always 1 if scaling is disabled).
Note the Time is not the scaled result.
This function returns the verbosity level for the specified logging category.
See the User's Guide for details. Use the value
default to read the general verbosity level.
Installs configuration files and event handlers.
Performs command listenv on the specified Telnet connection and returns the
result as a list of key-value pairs.
Equivalent to ct:log(default, 50, Format, [], []).
Equivalent to ct:log(Category, Importance, Format, FormatArgs, []).
Prints from a test case to the log file.
If the test is started with option create_priv_dir 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.
Sends an asynchronous notification of type Name with Datato the Common Test
event manager. This can later be caught by any installed event manager.
Equivalent to ct:pal(default, 50, Format, [], []).
Equivalent to ct:pal(Category, Importance, Format, FormatArgs, []).
Prints and logs from a test case.
Parses the printout from an SQL table and returns a list of tuples.
Equivalent to ct:print(default, 50, Format, [], []).
Prints from a test case to the console.
Reloads configuration file containing specified configuration key.
This function will return the identity of test- and group leader processes that
are still running at the time of this call. TestProcs 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.
Removes configuration variables (together with their aliases) that were loaded with specified callback module and configuration string.
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.
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.
Runs all test cases in all suites in the specified directories.
Runs all test cases in the specified suite.
Runs the specified test cases.
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.
Runs a test specified by TestSpec. The same terms are used as in test
specification files.
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.
This function, similar to timer:sleep/1 in STDLIB, suspends the test case for
a 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).
Starts Common Test in interactive mode.
Steps through a test case with the debugger.
Steps through a test case with the debugger. If option config has been
specified, breakpoints are also set on the configuration functions in Suite.
Exits the interactive mode.
Sends a synchronous notification of type Name with Data to the Common Test
event manager. This can later be caught by any installed event manager.
Returns all test cases in the specified suite.
Sets a new timetrap for the running test case.
Returns any data specified with tag userdata in the list of tuples returned
from suite/0.
Returns any data specified with tag userdata in the list of tuples returned
from Suite:group(GroupName) or Suite:Case().
Types
-type config_key() :: atom().
A configuration key which exists in a configuration file
-type conn_log_mod() :: ct_netconfc | ct_telnet.
-type conn_log_option() :: {log_type, conn_log_type()} | {hosts, [key_or_name()]}.
-type 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_netconfc or
ct_telnet for description and examples of how to use
this hook.
-type conn_log_type() :: raw | pretty | html | silent.
-type handle() :: pid().
The identity (handle) of a connection.
-type key_or_name() :: config_key() | target_name().
-type 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]}).
Functions
-spec abort_current_testcase(Reason) -> ok | {error, ErrorReason} when 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 function 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.
-spec add_config(Callback, Config) -> ok | {error, Reason} when Callback :: atom(), Config :: string(), Reason :: term().
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 ct:remove_config/2.
-spec break(Comment) -> ok | {error, Reason} when 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 current 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 explicitly 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 Erlang Program
in the User's Guide.
-spec break(TestCase, Comment) -> ok | {error, Reason} when TestCase :: atom(), Comment :: string(), Reason :: 'test case not running' | 'enable break with release_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.
-spec capture_get() -> ListOfStrings when ListOfStrings :: [string()].
Equivalent to [ct:capture_get([default])](capture_get/1).
-spec capture_get(ExclCategories) -> ListOfStrings when 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.
-spec capture_start() -> ok.
Starts capturing all text strings printed to stdout during execution of the
test case.
See also ct:capture_get/1,
ct:capture_stop/0.
-spec capture_stop() -> ok.
Stops capturing text strings (a session started with capture_start/0).
See also ct:capture_get/1,
ct:capture_start/0.
-spec comment(Comment) -> ok when 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.
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 otherwise the
same as function ct:comment/1.
-spec 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.
-spec continue(TestCase) -> ok when 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.
-spec decrypt_config_file(EncryptFileName, TargetFileName) -> ok | {error, Reason} when EncryptFileName :: string(), TargetFileName :: string(), Reason :: term().
Decrypts EncryptFileName, previously generated with
ct: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, either in the current
directory, or the home directory of the user (it is searched for in that order).
-spec decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> ok | {error, Reason} when EncryptFileName :: string(), TargetFileName :: string(), KeyOrFile :: {key, string()} | {file, string()}, Reason :: term().
Decrypts EncryptFileName, previously generated with
ct:encrypt_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.
-spec encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error, Reason} when 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.
-spec encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -> ok | {error, Reason} when 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.
Terminates a test case with the specified error Reason.
Terminates 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).
-spec get_config(Required) -> Value when Required :: KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}, KeyOrName :: atom(), SubKey :: atom(), Value :: term().
Equivalent to ct:get_config(Required, undefined, []).
-spec get_config(Required, Default) -> Value when Required :: KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}, KeyOrName :: atom(), SubKey :: atom(), Default :: term(), Value :: term().
Equivalent to ct:get_config(Required, Default, []).
-spec get_config(Required, Default, Opts) -> ValueOrElement when Required :: KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, 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) -> DefaultIf 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 returned 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:require/2.
-spec get_event_mgr_ref() -> EvMgrRef when 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, [])-spec 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 returned.
-spec get_status() -> TestStatus | {error, Reason} | no_tests_running when TestStatus :: [StatusElem], StatusElem :: {current, TestCaseInfo} | {successful, Successful} | {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 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.
-spec get_target_name(Handle) -> {ok, TargetName} | {error, Reason} when Handle :: handle(), TargetName :: target_name(), Reason :: term().
Returns the name of the target that the specified connection belongs to.
-spec get_testspec_terms() -> TestSpecTerms | undefined when TestSpecTerms :: [{Tag, Value}], Tag :: atom(), Value :: [term()].
Gets a list of all test specification terms used to configure and run this test.
-spec get_testspec_terms(Tags) -> TestSpecTerms | undefined when 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 configure 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
GroupsAndCases = [{Group,[Case]}] | [Case].
-spec get_timetrap_info() -> {Time, {Scaling, ScaleVal}} when Time :: integer() | infinity, Scaling :: boolean(), ScaleVal :: integer().
Reads information about the timetrap set for the current test case. Scaling
indicates if Common Test will attempt to compensate timetraps automatically
for runtime delays introduced by, for example, tools like cover. ScaleVal is
the value of the current scaling multiplier (always 1 if scaling is disabled).
Note the Time is not the scaled result.
-spec get_verbosity(Category) -> Level | undefined when Category :: default | atom(), Level :: integer().
This function returns the verbosity level for the specified logging category.
See the User's Guide for details. Use the value
default to read the general verbosity level.
-spec install(Opts) -> ok | {error, Reason} when 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(), Reason :: term().
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.
-spec listenv(Telnet) -> {ok, [Env]} when 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.
-spec log(Format) -> ok when Format :: string().
Equivalent to ct:log(default, 50, Format, [], []).
-spec log(X1, X2) -> ok when X1 :: Category | Importance | Format, X2 :: Format | FormatArgs, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list().
Equivalent to ct:log(Category, Importance, Format, FormatArgs, []).
-spec log(X1, X2, X3) -> ok when X1 :: Category | Importance, X2 :: Importance | Format, X3 :: Format | FormatArgs | Opts, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opts :: [Opt], Opt :: {heading, string()} | no_css | esc_chars.
Equivalent to
ct:log(Category, Importance, Format, FormatArgs, Opts).
-spec log(X1, X2, X3, X4) -> ok when X1 :: Category | Importance, X2 :: Importance | Format, X3 :: Format | FormatArgs, X4 :: FormatArgs | Opts, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opts :: [Opt], Opt :: {heading, string()} | no_css | esc_chars.
Equivalent to
ct:log(Category, Importance, Format, FormatArgs, Opts).
log(Category, Importance, Format, FormatArgs, Opts)
View Source (since OTP 18.3)-spec log(Category, Importance, Format, FormatArgs, Opts) -> ok when Category :: atom() | integer() | string(), 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_IMPORTANCE, 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 option is used.
-spec make_priv_dir() -> ok | {error, Reason} when Reason :: term().
If the test is started with option create_priv_dir 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.
Sends an asynchronous notification of type Name with Datato the Common Test
event manager. This can later be caught by any installed event manager.
See also gen_event.
-spec pal(Format) -> ok when Format :: string().
Equivalent to ct:pal(default, 50, Format, [], []).
-spec pal(X1, X2) -> ok when X1 :: Category | Importance | Format, X2 :: Format | FormatArgs, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list().
Equivalent to ct:pal(Category, Importance, Format, FormatArgs, []).
-spec pal(X1, X2, X3) -> ok when X1 :: Category | Importance, X2 :: Importance | Format, X3 :: Format | FormatArgs | Opt, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opt :: {heading, string()} | no_css.
Equivalent to
ct:pal(Category, Importance, Format, FormatArgs, Opts).
-spec pal(X1, X2, X3, X4) -> ok when X1 :: Category | Importance, X2 :: Importance | Format, X3 :: Format | FormatArgs, X4 :: FormatArgs | Opts, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opts :: [Opt], Opt :: {heading, string()} | no_css.
Equivalent to
ct:pal(Category, Importance, Format, FormatArgs, Opts).
pal(Category, Importance, Format, FormatArgs, Opts)
View Source (since OTP 19.2)-spec pal(Category, Importance, Format, FormatArgs, Opts) -> ok when Category :: atom() | integer() | string(), 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_IMPORTANCE, 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.
-spec parse_table(Data) -> {Heading, Table} when Data :: [string()], Heading :: tuple(), Table :: [tuple()].
Parses the printout from an SQL table and returns a list of tuples.
The printout to parse is typically 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.
-spec print(Format) -> ok when Format :: string().
Equivalent to ct:print(default, 50, Format, [], []).
-spec print(X1, X2) -> ok when X1 :: Category | Importance | Format, X2 :: Format | FormatArgs, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list().
Equivalent to
ct:print(Category, Importance, Format, FormatArgs, []).
-spec print(X1, X2, X3) -> ok when X1 :: Category | Importance, X2 :: Importance | Format, X3 :: Format | FormatArgs | Opts, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opts :: [Opt], Opt :: {heading, string()}.
Equivalent to
ct:print(Category, Importance, Format, FormatArgs, Opts).
-spec print(X1, X2, X3, X4) -> ok when X1 :: Category | Importance, X2 :: Importance | Format, X3 :: Format | FormatArgs, X4 :: FormatArgs | Opts, Category :: atom() | integer() | string(), Importance :: integer(), Format :: string(), FormatArgs :: list(), Opts :: [Opt], Opt :: {heading, string()}.
Equivalent to
ct:print(Category, Importance, Format, FormatArgs, Opts).
print(Category, Importance, Format, FormatArgs, Opts)
View Source (since OTP 19.2)-spec print(Category, Importance, Format, FormatArgs, Opts) -> ok when Category :: atom() | integer() | string(), 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_IMPORTANCE, and
default value for FormatArgs is [].
For details on Category and Importance, see section
Logging - Categories and Verbosity Levels in
the User's Guide.
-spec reload_config(Required) -> ValueOrElement | {error, Reason} when Required :: KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}, KeyOrName :: atom(), SubKey :: atom(), ValueOrElement :: term(), Reason :: 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 (possibly) 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 configuration table together with their aliases.
-spec remaining_test_procs() -> {TestProcs, SharedGL, OtherGLs} when 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. TestProcs 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 finished 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 processes for parallel test case
groups (OtherGLs) may however be terminated in post_end_per_group hook
functions.
Removes configuration variables (together with their aliases) that were loaded with specified callback module and configuration string.
-spec require(Required) -> ok | {error, Reason} when Required :: Key | {Key, SubKeys} | {Key, SubKey, SubKeys}, Key :: atom(), SubKeys :: SubKey | [SubKey], SubKey :: atom(), Reason :: term().
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.
-spec require(Name, Required) -> ok | {error, Reason} when Name :: atom(), Required :: Key | {Key, SubKey} | {Key, SubKey, SubKey}, SubKey :: Key, Key :: atom(), Reason :: term().
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 Required 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 example, 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 Test1.6.2. To keep some backwards compatibility, it is still possible to do:ct:require(a,{node,[telnet,ftp]}).This associates the nameawith the top-levelnodeentry. 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.
-spec run(TestDirs) -> Result when TestDirs :: TestDir | [TestDir], TestDir :: string(), Result :: [TestResult] | {error, Reason}, TestResult :: term(), Reason :: term().
Runs all test cases in all suites in the specified directories.
See also ct:run/3.
-spec run(TestDir, Suite) -> Result when TestDir :: string(), Suite :: atom(), Result :: [TestResult] | {error, Reason}, TestResult :: term(), Reason :: term().
Runs all test cases in the specified suite.
See also ct:run/3.
-spec run(TestDir, Suite, Cases) -> Result when TestDir :: string(), Suite :: atom(), Cases :: atom() | [atom()], Result :: [TestResult] | {error, Reason}, TestResult :: term(), Reason :: term().
Runs the specified test cases.
Requires that ct:install/1 has been run first.
Suites (*_SUITE.erl) files must be stored in TestDir or TestDir/test. All
suites are compiled when the test is run.
-spec run_test(Opts) -> Result when Opts :: [OptTuples], OptTuples :: {dir, TestDirs} | {suite, Suites} | {group, Groups} | {testcase, Cases} | {spec, TestSpecs} | {join_specs, boolean()} | {label, Label} | {config, CfgFiles} | {userconfig, UserConfig} | {allow_user_terms, boolean()} | {logdir, LogDir} | {silent_connections, Conns} | {stylesheet, CSSFile} | {cover, CoverSpecFile} | {cover_stop, boolean()} | {step, StepOpts} | {event_handler, EventHandlers} | {include, InclDirs} | {auto_compile, boolean()} | {abort_if_missing_suites, boolean()} | {create_priv_dir, CreatePrivDir} | {multiply_timetraps, M} | {scale_timetraps, boolean()} | {repeat, N} | {duration, DurTime} | {until, StopTime} | {force_stop, ForceStop} | {decrypt, DecryptKeyOrFile} | {refresh_logs, LogDir} | {logopts, LogOpts} | {verbosity, VLevels} | {basic_html, boolean()} | {esc_chars, boolean()} | {keep_logs, KeepSpec} | {ct_hooks, CTHs} | {ct_hooks_order, CTHsOrder} | {enable_builtin_hooks, boolean()} | {release_shell, boolean()}, 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 :: HHMMSS, HHMMSS :: string(), StopTime :: YYMoMoDDHHMMSS | HHMMSS, YYMoMoDDHHMMSS :: string(), ForceStop :: skip_rest | boolean(), 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}], CTHsOrder :: atom(), CTHModule :: atom(), CTHInitArgs :: term(), Result :: {Ok, Failed, {UserSkipped, AutoSkipped}} | TestRunnerPid | {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. Option
testcase corresponds to option -case in program ct_run. Configuration
files specified in Opts are installed automatically at startup.
TestRunnerPid is returned if release_shell == true. For details, see
ct:break/1.
Reason indicates the type of error encountered.
-spec run_testspec(TestSpec) -> Result when 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.
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.
-spec sleep(Time) -> ok when 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 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).
-spec 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, configuration 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 ...",...]}-spec step(TestDir, Suite, Case) -> Result when TestDir :: string(), Suite :: atom(), Case :: atom(), Result :: term().
Steps through a test case with the debugger.
See also ct:run/3.
-spec step(TestDir, Suite, Case, Opts) -> Result when TestDir :: string(), Suite :: atom(), Case :: atom(), Opts :: [Opt], Opt :: config | keep_inactive, Result :: term().
Steps through a test case with the debugger. If option config has been
specified, breakpoints are also set on the configuration functions in Suite.
See also ct:run/3.
-spec stop_interactive() -> ok.
Exits the interactive mode.
See also ct:start_interactive/0.
Sends a synchronous notification of type Name with Data to the Common Test
event manager. This can later be caught by any installed event manager.
See also gen_event.
-spec testcases(TestDir, Suite) -> Testcases | {error, Reason} when TestDir :: string(), Suite :: atom(), Testcases :: list(), Reason :: term().
Returns all test cases in the specified suite.
-spec timetrap(Time) -> infinity | pid() when 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.
-spec userdata(TestDir, Suite) -> SuiteUserData | {error, Reason} when TestDir :: string(), Suite :: atom(), SuiteUserData :: [term()], Reason :: term().
Returns any data specified with tag userdata in the list of tuples returned
from suite/0.
-spec userdata(TestDir, Suite, Case :: GroupOrCase) -> TCUserData | {error, Reason} when 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 tuples returned
from Suite:group(GroupName) or Suite:Case().