ct(3erl)

📦
version 25.3.2.8 · 4 versions
, in ubuntu noble

🌸 NAME 🌸

Okay bestie, this is the ct(3erl) page from the Erlang Module Definition set — the manual name is literally ct(3erl), and this is the main user interface for the Common Test framework. 👑

✨ DESCRIPTION ✨

This module implements the command-line interface for running tests and basic functions for Common Test case issues, such as configuration and logging. It's giving main character energy for your test runs. 💅

🎀 Test Suite Support Macros 🎀

The config macro is defined in ct.hrl. This macro is to be used to retrieve 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_netconfc 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 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.

🧩 add_config(Callback, Config) -> ok | {error, Reason}

Types:

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.

⏸️ 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 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.

⏸️ break(TestCase, Comment) -> ok | {error, Reason}

Types:

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.

📥 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 execution 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 capture_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 otherwise 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: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).

🔓 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: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.

🔐 encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error, Reason}

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 format 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, 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:

Okay so here's what those ct:get_config calls actually hand back depending on what you feed them 👇

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 config key has been given a name (via ct:require/2 or a require statement), you can use that name instead of the key to read the value — bestie, it's giving shortcuts 💅

ct:require(myuser,{unix,user}) -> ok.
ct:get_config(myuser,Default) -> [{username,Username}, {password,Password}]

If the same config variable is defined in multiple files, use option all to grab every possible value. You get them back in a list, and the order matches the order the config files were specified at startup ✨

If you want the config elements (the key-value tuples) back instead of just the 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.

get_event_mgr_ref() -> EvMgrRef 💫

Types:

EvMgrRef = atom()

Gets a reference to the Common Test event manager. Lowkey the most useful thing ever — you can use it to, for example, add your own user-specific event handler while tests are running 🔥

Example, iconic behavior:

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 that info couldn't be found, you just get the string "no_prog_name" back. No cap, that's the fallback 🫠

get_status() -> TestStatus | {error, Reason} | no_tests_running 👑

Types:

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 the status of the ongoing test. The list tells you which test case is currently executing (a list of cases when a parallel test case group is running, iykyk) plus the counters 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 belongs to. Cute and simple 🫶

get_testspec_terms() -> TestSpecTerms | undefined 🎀

Types:

TestSpecTerms = [{Tag, Value}]
Value = [term()]

Gets a list of all the test specification terms that were used to configure and run this test. Literally the whole receipts file 📜

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 spec that configured and ran this test. Tag is any valid test specification tag — for example label, config, or logdir. User-specific terms are also readable if option allow_user_terms is set ✨

Every value tuple returned, except user terms, has the node name as the first element.

To read test terms, use Tag = tests (not suites, groups, or cases). Value is then the list of all tests on the form [{Node,Dir,[{TestSpec,GroupsAndCases1},...]},...], where GroupsAndCases = [{Group,[Case]}] | [Case] 🌈

get_timetrap_info() -> {Time, {Scaling,ScaleVal}} ⏰

Types:

Time = integer() | infinity
Scaling = true | false
ScaleVal = integer()

Reads info about the timetrap set for the current test case. Scaling tells you if Common Test will try to auto-compensate timetraps for runtime delays introduced by stuff like cover. ScaleVal is the value of the current scaling multiplier (always 1 if scaling is disabled).

Careful bestie: Time is not the scaled result 💀

get_verbosity(Category) -> Level | undefined 🔊

Types:

Category = default | atom()
Level = integer()

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 👑

install(Opts) -> ok | {error, Reason} 💖

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()

Installs configuration files and event handlers. Run this function once, before your first test — like setting up your dorm room before the semester starts 🛋️

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()

Runs the command listenv on the specified Telnet connection and returns the result as a list of key-value pairs. Slay 🧚

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 straight into the log file. This one is meant for printing a string directly from a test case to the test case log file, periodt 📄

Default Category is default, default Importance is ?STD_IMPORTANCE, and the default value for FormatArgs is [].

For the deets on Category, Importance, and the no_css option, see section Logging - Categories and Verbosity Levels in the User's Guide.

Heads up: Common Test will not escape special HTML characters (<, > and &) in text printed with this function, unless the esc_chars option is used. Don't come crying when your log looks cursed 💀

make_priv_dir() -> ok | {error, Reason} 🗂️

Types:

Reason = term()

If the test was started with option create_priv_dir set to manual_per_tc, then for the test case to use its private directory, it has to create it first by calling this function. DIY vibes 💅

notify(Name, Data) -> ok 📣

Types:

Name = atom()
Data = term()

Sends an asynchronous notification of type Name with Data to the Common Test event manager. This can later be caught by any installed event manager — like passing a note in class and hoping someone catches it 🙈

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 one is for printing a string from a test case both to the test case log file and to the console — the "post it on your story AND tell your bestie" of logging functions 💖

Default Category is default, default Importance is ?STD_IMPORTANCE, and the 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. Responsible queen behavior ✨

parse_table(Data) -> {Heading, Table} 🧾

Types:

Data = [string()]
Heading = tuple()
Table = [tuple()]

Parses the printout from an SQL table and returns a list of tuples. The printout you 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. Iconic data wrangling, honestly 👑

Equivalent to ct:print(default, 50, Format, [], []).

Types:

X1 = Category | Importance | Format
X2 = Format | FormatArgs

Equivalent to ct:print(Category, Importance, Format, FormatArgs, []).

Types:

X1 = Category | Importance
X2 = Importance | Format
X3 = Format | FormatArgs | Opts

Equivalent to ct:print(Category, Importance, Format, FormatArgs, Opts).

Types:

X1 = Category | Importance
X2 = Importance | Format
X3 = Format | FormatArgs
X4 = FormatArgs | Opts

Equivalent to ct:print(Category, Importance, Format, FormatArgs, Opts).

Types:

Category = atom()
Importance = integer()
Format = string()
FormatArgs = list()
Opts = [Opt]
Opt = {heading,string()}

Prints from a test case to the console — literally its whole job. 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.

reload_config(Required) -> ValueOrElement | {error, Reason}

Types:

Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName,
SubKey, 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 (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.

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. 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 be 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.

remove_config(Callback, Config) -> ok

Types:

Callback = atom()
Config = string()
Reason = term()

Removes configuration variables (together with their aliases) that were loaded with specified callback module and configuration 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 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 Test 1.6.2. To keep some backwards compatibility, it is still possible 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 TestDir/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_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}
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}} |
TestRunnerPid | {error, Reason}
Ok = integer()
Failed = integer()
UserSkipped = integer()
AutoSkipped = integer()
TestRunnerPid = pid()
Reason = term()

Okay so this one runs tests exactly as the combo of options in Opts says. ✨ The options are the same ones you'd use with the program ct_run — peep Run Tests from Command Line in the ct_run manual page, iykyk.

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. 😭

run_testspec(TestSpec) -> Result

Types:

TestSpec = [term()]
Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | {error, Reason}
Ok = integer()
Failed = integer()
UserSkipped = integer()
AutoSkipped = integer()
Reason = term()

This bad boy runs a test specified by TestSpec — same terms as in test specification files, bestie. 🫶 Reason tells you what kind of error showed up.

set_verbosity(Category, Level) -> ok

Types:

Category = default | atom()
Level = integer()

Use this to set — or tweak — the verbosity level for a logging category. 👑 Check the User's Guide for the deets. Set it to default and you're setting 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()

Similar energy to timer:sleep/1 in STDLIB: it suspends the test case for a specified time. But plot twist 😭 — it also multiplies Time with the multiply_timetraps value (if that's set), and under certain circumstances it 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 here, all test case support functions can be executed straight from the Erlang shell. You can also start interactive mode from the OS command line with ct_run -shell [-config File...].

If you're gonna call any functions from the Erlang shell that use "required configuration data" (think Telnet or FTP, no cap), you gotta require that config data first 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

Same debugger step-through vibe, but with Opts. If you specify option config, breakpoints are also set on the configuration functions in Suite. 🔥 See also ct:run/3.

stop_interactive() -> ok

Exits interactive mode. Bye bestie 👋 — 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. You can catch it later with any installed 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. That's it, that's the function. 💖

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 triggers when this function returns. Func can also return a new Time value — and in that case, boom, that's 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 tuples 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 tuples returned from Suite:group(GroupName) or Suite:Case(). 🌸

That's the whole vibe, bestie 💖 — brought to you by Ericsson AB, common_test 1.24.0.1, and the ct(3erl) page (yes, that's the footer energy).

📦 where this page comes from