From 68d7535fe0cccd50622884f704edeb9d8bb47430 Mon Sep 17 00:00:00 2001 From: tmanevik Date: Fri, 18 Dec 2015 12:21:32 +0100 Subject: Common Test: Editorial changes 3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reference Manual files from Pär Wennstad added --- lib/common_test/doc/src/ct.xml | 1386 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1386 insertions(+) create mode 100644 lib/common_test/doc/src/ct.xml (limited to 'lib/common_test/doc/src/ct.xml') diff --git a/lib/common_test/doc/src/ct.xml b/lib/common_test/doc/src/ct.xml new file mode 100644 index 0000000000..ed3d76061a --- /dev/null +++ b/lib/common_test/doc/src/ct.xml @@ -0,0 +1,1386 @@ + + + + +
+ + 20102012 + Ericsson AB. All Rights Reserved. + + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + + + ct + + + + + + + A + ct.xml +
+ ct + 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.

+ +

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.

 + + 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]}).

 + + +
+ + + + abort_current_testcase(Reason) -> ok | {error, ErrorReason} + Aborts the currently executing test case. + + 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} + Loads configuration variables using the specified callback + module and configuration string. + + 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 part. Loaded configuration variables can later + be removed using function + ct:remove_config/2. +

+ + + + + break(Comment) -> ok | {error, Reason} + Cancels any active timetrap and pause the execution of the + current test case until the user calls function continue/0. + + 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 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 Erlang Program + in the User's Guide.

+ + + + + break(TestCase, Comment) -> ok | {error, Reason} + Works the same way as break/1, only argument TestCase makes it + possible to pause a test case executing in a parallel group. + + 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 + Equivalent to capture_get([default]). + + ListOfStrings = [string()] + + +

Equivalent to + ct:capture_get([default]).

+ + + + + capture_get(ExclCategories) -> ListOfStrings + Returns and purges the list of text strings buffered during + the latest session of capturing printouts to stdout. + + 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. + +

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). + +

Stops capturing text strings (a session started with + capture_start/0).

+ +

See also + ct:capture_get/1, + ct:capture_start/0.

+ + + + + comment(Comment) -> ok + Prints the specified Comment in the comment field in the + table on the test suite result page. + + 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 + Prints the formatted string in the comment field in the + table on the test suite result page. + + 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 break/1. + +

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 + This function must be called to continue after a test case + has called break/2. + + 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} + Decrypts EncryptFileName, previously generated with + encrypt_config_file/2,3. + + 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} + Decrypts EncryptFileName, previously generated with + encrypt_config_file/2,3. + + 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} + Encrypts the source configuration file with DES3 and saves the + result in file EncryptFileName. + + 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} + Encrypts the source configuration file with DES3 and saves the + result in the target file EncryptFileName. + + 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 + Terminates a test case with the specified error + Reason. + + Reason = term() + + +

Terminates a test case with the specified error Reason.

+ + + + + fail(Format, Args) -> ok + 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). + + 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 get_config(Required, undefined, []). + +

Equivalent to ct:get_config(Required, + undefined, []).

+ + + + + get_config(Required, Default) -> Value + Equivalent to get_config(Required, Default, []). + +

Equivalent to ct:get_config(Required, + Default, []).

+ + + + + get_config(Required, Default, Opts) -> ValueOrElement + Reads configuration data values. + + 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) -> 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 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.

+ + + + + get_event_mgr_ref() -> EvMgrRef + Gets a reference to the Common Test event manager. + + 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_status() -> TestStatus | {error, Reason} | no_tests_running + Returns status of ongoing test. + + 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.

+ + + + + get_target_name(Handle) -> {ok, TargetName} | {error, Reason} + Returns the name of the target that the specified connection + belongs to. + + Handle = handle() + TargetName = target_name() + + +

Returns the name of the target that the specified connection + belongs to.

+ + + + + get_testspec_terms() -> TestSpecTerms | undefined + Gets a list of all test specification terms used to + configure and run this test. + + 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 + Reads one or more terms from the test specification used to + configure and run this test. + + 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].

+ + + + + get_timetrap_info() -> {Time, Scale} + Reads information about the timetrap set for the current + test case. + + Time = integer() | infinity + Scale = true | false + + +

Reads information about the timetrap set for the current test + case. Scale indicates if Common Test will attempt + to compensate timetraps automatically for runtime delays + introduced by, for example, tools like cover.

+ + + + + install(Opts) -> ok | {error, Reason} + Installs configuration files and event handlers. + + 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 the first test.

+ +

Example:

+ + 
+ install([{config,["config_node.ctc","config_user.ctc"]}])
+ +

This function is automatically run by program ct_run.

+ + + + + listenv(Telnet) -> [Env] + Performs command listenv on the specified Telnet connection + and returns the result as a list of key-value pairs. + + 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 log(default, 50, Format, []). + +

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

+ + + + + log(X1, X2) -> ok + Equivalent to log(Category, Importance, Format, + Args). + + X1 = Category | Importance | Format + X2 = Format | Args + + +

Equivalent to ct:log(Category, + Importance, Format, Args).

+ + + + + log(X1, X2, X3) -> ok + Equivalent to log(Category, Importance, Format, + Args). + + X1 = Category | Importance + X2 = Importance | Format + X3 = Format | Args + + +

Equivalent to ct:log(Category, + Importance, Format, Args).

+ + + + + log(Category, Importance, Format, Args) -> ok + Prints from a test case to the log file. + + Category = atom() + Importance = integer() + Format = string() + Args = list() + + +

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 Args is [].

+ +

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

+ + + + + make_priv_dir() -> ok | {error, Reason} + If the test has been 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. + + 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.

+ + + + + notify(Name, Data) -> ok + Sends an asynchronous notification of type Name with Data + to the Common Test event manager. + + 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 installed event manager.

+ +

See also + stdlib:gen_event(3).

+ + + + + pal(Format) -> ok + Equivalent to pal(default, 50, Format, []). + +

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

+ + + + + pal(X1, X2) -> ok + Equivalent to pal(Category, Importance, Format, + Args). + + X1 = Category | Importance | Format + X2 = Format | Args + + +

Equivalent to ct:pal(Category, + Importance, Format, Args).

+ + + + + pal(X1, X2, X3) -> ok + Equivalent to pal(Category, Importance, Format, + Args). + + X1 = Category | Importance + X2 = Importance | Format + X3 = Format | Args + + +

Equivalent to ct:pal(Category, + Importance, Format, Args).

+ + + + + pal(Category, Importance, Format, Args) -> ok + Prints and logs from a test case. + + Category = atom() + Importance = integer() + Format = string() + Args = list() + + +

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 Args is [].

+ +

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

+ + + + + parse_table(Data) -> {Heading, Table} + Parses the printout from an SQL table and returns a list of + tuples. + + 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.

+ + + + + print(Format) -> ok + Equivalent to print(default, 50, Format, []). + +

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

+ + + + + print(X1, X2) -> ok + Equivalent to print(Category, Importance, Format, + Args). + + X1 = Category | Importance | Format + X2 = Format | Args + + +

Equivalent to ct:print(Category, + Importance, Format, Args).

+ + + + + print(X1, X2, X3) -> ok + Equivalent to print(Category, Importance, Format, + Args). + + X1 = Category | Importance + X2 = Importance | Format + X3 = Format | Args + + +

Equivalent to ct:print(Category, + Importance, Format, Args).

+ + + + + print(Category, Importance, Format, Args) -> ok + Prints from a test case to the console. + + Category = atom() + Importance = integer() + Format = string() + Args = list() + + +

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 Args is [].

+ +

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

+ + + + + reload_config(Required) -> ValueOrElement + Reloads configuration file containing specified configuration + key. + + 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.

+ + + + + remove_config(Callback, Config) -> ok + Removes configuration variables (together with + their aliases) that were loaded with specified callback module and + configuration string. + + Callback = atom() + Config = string() + Reason = term() + + +

Removes configuration variables (together wih their aliases) + that were loaded with specified callback module and configuration + string.

+ + + + + require(Required) -> ok | {error, Reason} + Checks if the required configuration is available. + + 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} + Checks if the required configuration is available and gives + it a name. + + 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}]}]}.
+ +

The behavior of this function changed radically in + Common Test 1.6.2. To keep some backwards compatability, + 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 + Runs all test cases in all suites in the specified + directories. + + 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. + +

Runs all test cases in the specified suite.

+ +

See also ct:run/3.

+ + + + + run(TestDir, Suite, Cases) -> Result + Runs the specified test cases. + + 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 + Runs tests as specified by the combination of options in + Opts. + + 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} | {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() + 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() + + +

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.

+ + + + + run_testspec(TestSpec) -> Result + Runs a test specified by TestSpec. + + 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.

+ + + + + sleep(Time) -> ok + This function, similar to timer:sleep/1, suspends the + test case for a specified time. + + 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).

+ + + + + start_interactive() -> ok + Starts Common Test in interactive mode. + +

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  ...",...]}
+ + + + + step(TestDir, Suite, Case) -> Result + Steps through a test case with the debugger. + + Case = atom() + + +

Steps through a test case with the debugger.

+ +

See also ct:run/3.

+ + + + + step(TestDir, Suite, Case, Opts) -> Result + Steps through a test case with the debugger. + + 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. + +

Exits the interactive mode.

+ +

See also + ct:start_interactive/0. +

+ + + + + sync_notify(Name, Data) -> ok + Sends a synchronous notification of type Name with Data to + the Common Test event manager. + + 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 installed event manager.

+ +

See also + stdlib:gen_event(3). +

+ + + + + testcases(TestDir, Suite) -> Testcases | {error, Reason} + Returns all test cases in the specified suite. + + TestDir = string() + Suite = atom() + Testcases = list() + Reason = term() + + +

Returns all test cases in the specified suite.

+ + + + + timetrap(Time) -> ok + Sets a new timetrap for the running test case. + + Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity | Func + Hours = integer() + Mins = integer() + Secs = integer() + Millisecs = integer() | float() + Func = {M, F, A} | function() + M = atom() + F = atom() + A = list() + + +

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} + Returns any data specified with tag userdata in the list of + tuples returned from Suite:suite/0. + + 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} + Returns any data specified with tag userdata in the list of + tuples returned from Suite:group(GroupName) or Suite:Case(). + + 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().

+ + + + + + + -- cgit v1.2.3