From 02e8dc98b5327712f4ae00ac9fcf5feb1d856ba0 Mon Sep 17 00:00:00 2001 From: Peter Andersson Date: Tue, 28 Aug 2012 17:38:15 +0200 Subject: Update the documentation for R15B02 OTP-10050 OTP-10069 OTP-10072 OTP-10087 OTP-9865 OTP-10049 OTP-10089 OTP-10145 OTP-9896 OTP-10135 OTP-10067 OTP-9625 OTP-10127 OTP-10172 OTP-10248 OTP-9625 OTP-10086 --- lib/common_test/src/ct.erl | 238 ++++++++++++++++++++++++--------------------- 1 file changed, 127 insertions(+), 111 deletions(-) (limited to 'lib/common_test/src') diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl index aa8813c391..455fd1e4f1 100644 --- a/lib/common_test/src/ct.erl +++ b/lib/common_test/src/ct.erl @@ -25,24 +25,24 @@ %%% %%%

Test Suite Support Macros

%%% -%%%

The config macro is defined in ct.hrl. This +%%%

The config macro is defined in ct.hrl. This %%% macro should be used to retrieve information from the -%%% Config variable sent to all test cases. It is used with two +%%% Config variable sent to all test cases. It is used with two %%% arguments, where the first is the name of the configuration -%%% variable you wish to retrieve, and the second is the Config +%%% variable you wish to retrieve, and the second is the Config %%% variable supplied to the test case.

%%% %%%

Possible configuration variables include:

%%% %%% @type var_name() = atom(). A variable name which is specified when -%%% ct:require/2 is called, -%%% e.g. ct:require(mynodename,{node,[telnet]}) +%%% ct:require/2 is called, +%%% e.g. ct:require(mynodename,{node,[telnet]}) %%% %%% @type target_name() = var_name(). The name of a target. %%% @@ -99,10 +99,10 @@ %%%

Run this function once before first test.

%%% %%%

Example:
-%%% install([{config,["config_node.ctc","config_user.ctc"]}]).

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

%%% %%%

Note that this function is automatically run by the -%%% ct_run program.

+%%% ct_run program.

install(Opts) -> ct_run:install(Opts). @@ -115,10 +115,10 @@ install(Opts) -> %%% %%% @doc Run the given test case(s). %%% -%%%

Requires that ct:install/1 has been run first.

+%%%

Requires that ct:install/1 has been run first.

%%% %%%

Suites (*_SUITE.erl) files must be stored in -%%% TestDir or TestDir/test. All suites +%%% TestDir or TestDir/test. All suites %%% will be compiled when test is run.

run(TestDir,Suite,Cases) -> ct_run:run(TestDir,Suite,Cases). @@ -201,25 +201,32 @@ run(TestDirs) -> %%% AutoSkipped = integer() %%% TestRunnerPid = pid() %%% Reason = term() -%%% @doc

Run tests as specified by the combination of options in Opts. +%%% @doc

Run tests as specified by the combination of options in Opts. %%% The options are the same as those used with the -%%% ct_run program. -%%% Note that here a TestDir can be used to point out the path to -%%% a Suite. Note also that the option testcase -%%% corresponds to the -case option in the ct_run -%%% program. Configuration files specified in Opts will be +%%% ct_run program. +%%% Note that here a TestDir can be used to point out the path to +%%% a Suite. Note also that the option testcase +%%% corresponds to the -case option in the ct_run +%%% program. Configuration files specified in Opts will be %%% installed automatically at startup.

-%%%

TestRunnerPid is returned if release_shell == true -%%% (see the User's Guide for details).

-%%%

Reason indicates what type of error has been encountered.

+%%%

TestRunnerPid is returned if release_shell == true +%%% (see break/1 for details).

+%%%

Reason indicates what type of error has been encountered.

run_test(Opts) -> ct_run:run_test(Opts). %%%----------------------------------------------------------------- %%% @spec run_testspec(TestSpec) -> Result %%% TestSpec = [term()] -%%% @doc Run test specified by TestSpec. The terms are +%%% Result = {Ok,Failed,{UserSkipped,AutoSkipped}} | {error,Reason} +%%% Ok = integer() +%%% Failed = integer() +%%% UserSkipped = integer() +%%% AutoSkipped = integer() +%%% Reason = term() +%%% @doc Run test specified by TestSpec. The terms are %%% the same as those used in test specification files. +%%%

Reason indicates what type of error has been encountered.

run_testspec(TestSpec) -> ct_run:run_testspec(TestSpec). @@ -239,8 +246,8 @@ step(TestDir,Suite,Case) -> %%% Opt = config | keep_inactive %%% %%% @doc Step through a test case with the debugger. If the -%%% config option has been given, breakpoints will -%%% be set also on the configuration functions in Suite. +%%% config option has been given, breakpoints will +%%% be set also on the configuration functions in Suite. %%% @see run/3 step(TestDir,Suite,Case,Opts) -> ct_run:step(TestDir,Suite,Case,Opts). @@ -252,20 +259,20 @@ step(TestDir,Suite,Case,Opts) -> %%% %%%

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

+%%% started from the OS command line with ct_run -shell +%%% [-config File...].

%%% %%%

If any functions using "required config data" (e.g. telnet or %%% ftp functions) are to be called from the erlang shell, config data -%%% must first be required with ct:require/2.

+%%% 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 ...",...]}

+%%% > ct:require(unix_telnet, unix).
+%%% ok
+%%% > ct_telnet:open(unix_telnet).
+%%% {ok,<0.105.0>}
+%%% > ct_telnet:cmd(unix_telnet, "ls .").
+%%% {ok,["ls","file1 ...",...]}

start_interactive() -> ct_util:start(interactive). @@ -292,21 +299,21 @@ stop_interactive() -> %%% to specify arbitrarily deep tuples as Required. Note that it is %%% only the last element of the tuple which can be a list of SubKeys. %%% -%%%

Example 1: require the variable myvar:

+%%%

Example 1: require the variable myvar:

%%% 
ok = ct:require(myvar).
%%% %%%

In this case the config file must at least contain:

%%% 
{myvar,Value}.
%%% -%%%

Example 2: require the key myvar with -%%% subkeys sub1 and sub2:

+%%%

Example 2: require the key myvar with +%%% subkeys sub1 and sub2:

%%% 
ok = ct:require({myvar,[sub1,sub2]}).
%%% %%%

In this case the config file must at least contain:

%%% 
{myvar,[{sub1,Value},{sub2,Value}]}.
%%% -%%%

Example 3: require the key myvar with -%%% subkey sub1 with subsub1:

+%%%

Example 3: require the key myvar with +%%% subkey sub1 with subsub1:

%%% 
ok = ct:require({myvar,sub1,sub2}).
%%% %%%

In this case the config file must at least contain:

@@ -332,12 +339,12 @@ require(Required) -> %%% of SubKeys. %%% %%%

If the requested data is available, the sub entry will be -%%% associated with Name so that the value of the element -%%% can be read with get_config/1,2 provided -%%% Name instead of the whole Required term.

+%%% associated with Name so that the value of the element +%%% can be read with get_config/1,2 provided +%%% Name instead of the whole Required term.

%%% %%%

Example: Require one node with a telnet connection and an -%%% ftp connection. Name the node a: +%%% ftp connection. Name the node a: %%% 

ok = ct:require(a,{machine,node}).
%%% All references to this node may then use the node name. %%% E.g. you can fetch a file over ftp like this:

@@ -386,7 +393,7 @@ get_config(Required,Default) -> %%% %%%

This function returns the matching value(s) or config element(s), %%% given a config variable key or its associated name -%%% (if one has been specified with require/2 or a +%%% (if one has been specified with require/2 or a %%% require statement).

%%% %%%

Example, given the following config file:

@@ -394,33 +401,33 @@ get_config(Required,Default) -> %%% {unix,[{telnet,IpAddr}, %%% {user,[{username,Username}, %%% {password,Password}]}]}. -%%%

ct:get_config(unix,Default) -> +%%%

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

+%%% {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 variable key has been associated with a name (by -%%% means of require/2 or a require statement), the name +%%% means of require/2 or a require statement), the name %%% may be used instead of the key to read the value:

%%% -%%%

ct:require(myuser,{unix,user}) -> ok.
-%%% ct:get_config(myuser,Default) -> +%%%

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

+%%% {password,Password}]

%%% %%%

If a config variable is defined in multiple files and you want to -%%% access all possible values, use the all option. The +%%% access all possible values, use the all option. The %%% values will be returned in a list and the order of the elements %%% corresponds to the order that the config files were specified at %%% startup.

%%% %%%

If you want config elements (key-value tuples) returned as result -%%% instead of values, use the element option. -%%% The returned elements will then be on the form {Required,Value}

+%%% instead of values, use the element option. +%%% The returned elements will then be on the form {Required,Value}

%%% %%% @see get_config/1 %%% @see get_config/2 @@ -493,11 +500,11 @@ log(X1,X2,X3) -> %%%

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

-%%%

Please see the User's Guide for details on Category -%%% and Importance.

+%%%

Default Category is default, +%%% default Importance is ?STD_IMPORTANCE, +%%% and default value for Args is [].

+%%%

Please see the User's Guide for details on Category +%%% and Importance.

log(Category,Importance,Format,Args) -> ct_logs:tc_log(Category,Importance,Format,Args). @@ -547,11 +554,11 @@ print(X1,X2,X3) -> %%%

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

-%%%

Please see the User's Guide for details on Category -%%% and Importance.

+%%%

Default Category is default, +%%% default Importance is ?STD_IMPORTANCE, +%%% and default value for Args is [].

+%%%

Please see the User's Guide for details on Category +%%% and Importance.

print(Category,Importance,Format,Args) -> ct_logs:tc_print(Category,Importance,Format,Args). @@ -601,11 +608,11 @@ pal(X1,X2,X3) -> %%%

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

-%%%

Please see the User's Guide for details on Category -%%% and Importance.

+%%%

Default Category is default, +%%% default Importance is ?STD_IMPORTANCE, +%%% and default value for Args is [].

+%%%

Please see the User's Guide for details on Category +%%% and Importance.

pal(Category,Importance,Format,Args) -> ct_logs:tc_pal(Category,Importance,Format,Args). @@ -624,7 +631,7 @@ capture_start() -> %%% @spec capture_stop() -> ok %%% %%% @doc Stop capturing text strings (a session started with -%%% capture_start/0). +%%% capture_start/0). %%% %%% @see capture_start/0 %%% @see capture_get/1 @@ -647,9 +654,9 @@ capture_get() -> %%% %%% @doc Return and purge the list of text strings buffered %%% during the latest session of capturing printouts to stdout. -%%% With ExclCategories it's possible to specify -%%% log categories that should be ignored in ListOfStrings. -%%% If ExclCategories = [], no filtering takes place. +%%% With ExclCategories it's possible to specify +%%% log categories that should be ignored in ListOfStrings. +%%% If ExclCategories = [], no filtering takes place. %%% %%% @see capture_start/0 %%% @see capture_stop/0 @@ -674,7 +681,7 @@ capture_get([]) -> %%% Reason = term() %%% %%% @doc Terminate a test case with the given error -%%% Reason. +%%% Reason. fail(Reason) -> try exit({test_case_failed,Reason}) @@ -694,7 +701,7 @@ fail(Reason) -> %%% %%% @doc Terminate a test case with an error message specified %%% by a format string and a list of values (used as arguments to -%%% io_lib:format/2). +%%% io_lib:format/2). fail(Format, Args) -> try io_lib:format(Format, Args) of Str -> @@ -717,11 +724,11 @@ fail(Format, Args) -> %%% @spec comment(Comment) -> void() %%% Comment = term() %%% -%%% @doc Print the given Comment in the comment field in +%%% @doc Print the given Comment in the comment field in %%% the table on the test suite result page. %%% %%%

If called several times, only the last comment is printed. -%%% The test case return value {comment,Comment} +%%% The test case return value {comment,Comment} %%% overwrites the string set by this function.

comment(Comment) when is_list(Comment) -> Formatted = @@ -744,10 +751,10 @@ comment(Comment) -> %%% @doc Print the formatted string in the comment field in %%% the table on the test suite result page. %%% -%%%

The Format and Args arguments are -%%% used in call to io_lib:format/2 in order to create -%%% the comment string. The behaviour of comment/2 is -%%% otherwise the same as the comment/1 function (see +%%%

The Format and Args arguments are +%%% used in call to io_lib:format/2 in order to create +%%% the comment string. The behaviour of comment/2 is +%%% otherwise the same as the comment/1 function (see %%% above for details).

comment(Format, Args) when is_list(Format), is_list(Args) -> Formatted = @@ -792,11 +799,11 @@ get_target_name(Handle) -> %%% @doc Parse the printout from an SQL table and return a list of tuples. %%% %%%

The printout to parse would typically be the result of a -%%% select command in SQL. The returned -%%% Table is a list of tuples, where each tuple is a row +%%% 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 +%%%

Heading is a tuple of strings representing the %%% headings of each column in the table.

parse_table(Data) -> ct_util:parse_table(Data). @@ -868,8 +875,8 @@ make_and_load(Dir, Suite) -> %%% SuiteUserData = [term()] %%% Reason = term() %%% -%%% @doc Returns any data specified with the tag userdata -%%% in the list of tuples returned from Suite:suite/0. +%%% @doc Returns any data specified with the tag userdata +%%% in the list of tuples returned from Suite:suite/0. userdata(TestDir, Suite) -> case make_and_load(TestDir, Suite) of E = {error,_} -> @@ -904,9 +911,9 @@ get_userdata(_BadTerm, Spec) -> %%% TCUserData = [term()] %%% Reason = term() %%% -%%% @doc Returns any data specified with the tag userdata -%%% in the list of tuples returned from Suite:group(GroupName) -%%% or Suite:Case(). +%%% @doc Returns any data specified with the tag userdata +%%% in the list of tuples returned from Suite:group(GroupName) +%%% or Suite:Case(). userdata(TestDir, Suite, {group,GroupName}) -> case make_and_load(TestDir, Suite) of E = {error,_} -> @@ -986,7 +993,7 @@ get_testdata(Key) -> %%% executing. The function is therefore only safe to call from a function which %%% has been called (or synchronously invoked) by the test case.

%%% -%%%

Reason, the reason for aborting the test case, is printed +%%%

Reason, the reason for aborting the test case, is printed %%% in the test case log.

abort_current_testcase(Reason) -> test_server_ctrl:abort_current_testcase(Reason). @@ -999,13 +1006,13 @@ abort_current_testcase(Reason) -> %%% Reason = term() %%% %%% @doc

This function encrypts the source config file with DES3 and -%%% saves the result in file EncryptFileName. The key, +%%% saves the result in file EncryptFileName. The key, %%% a string, must be available in a text file named -%%% .ct_config.crypt in the current directory, or the +%%% .ct_config.crypt in the current directory, or the %%% home directory of the user (it is searched for in that order).

%%%

See the Common Test User's Guide for information about using %%% encrypted config files when running tests.

-%%%

See the crypto application for details on DES3 +%%%

See the crypto application for details on DES3 %%% encryption/decryption.

encrypt_config_file(SrcFileName, EncryptFileName) -> ct_config:encrypt_config_file(SrcFileName, EncryptFileName). @@ -1019,13 +1026,13 @@ encrypt_config_file(SrcFileName, EncryptFileName) -> %%% Reason = term() %%% %%% @doc

This function encrypts the source config file with DES3 and -%%% saves the result in the target file EncryptFileName. +%%% 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}.

+%%% {key,Key} or the value stored in the file specified +%%% by {file,File}.

%%%

See the Common Test User's Guide for information about using %%% encrypted config files when running tests.

-%%%

See the crypto application for details on DES3 +%%%

See the crypto application for details on DES3 %%% encryption/decryption.

encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -> ct_config:encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile). @@ -1037,11 +1044,11 @@ encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -> %%% TargetFileName = string() %%% Reason = term() %%% -%%% @doc

This function decrypts EncryptFileName, previously -%%% generated with encrypt_config_file/2/3. The original +%%% @doc

This function decrypts EncryptFileName, previously +%%% generated with encrypt_config_file/2/3. The original %%% file contents is saved in the target file. The encryption key, a %%% string, must be available in a text file named -%%% .ct_config.crypt in the current directory, or the +%%% .ct_config.crypt in the current directory, or the %%% home directory of the user (it is searched for in that order).

decrypt_config_file(EncryptFileName, TargetFileName) -> ct_config:decrypt_config_file(EncryptFileName, TargetFileName). @@ -1054,8 +1061,8 @@ decrypt_config_file(EncryptFileName, TargetFileName) -> %%% KeyOrFile = {key,string()} | {file,string()} %%% Reason = term() %%% -%%% @doc

This function decrypts EncryptFileName, previously -%%% generated with encrypt_config_file/2/3. The original +%%% @doc

This function decrypts EncryptFileName, previously +%%% generated with encrypt_config_file/2/3. The original %%% file contents is saved in the target file. The key must have the %%% the same value as that used for encryption.

decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> @@ -1072,7 +1079,7 @@ decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> %%% given callback module and configuration string. Callback module %%% should be either loaded or present in the code part. Loaded %%% configuration variables can later be removed using -%%% remove_config/2 function.

+%%% remove_config/2 function.

add_config(Callback, Config)-> ct_config:add_config(Callback, Config). @@ -1101,9 +1108,9 @@ remove_config(Callback, Config) -> %%% A = list() %%% %%% @doc

Use this function to set a new timetrap for the running test case. -%%% If the argument is Func, the timetrap will be triggered -%%% when this function returns. Func may also return a new -%%% Time value, which in that case will be the value for the +%%% If the argument is Func, the timetrap will be triggered +%%% when this function returns. Func may also return a new +%%% Time value, which in that case will be the value for the %%% new timetrap.

timetrap(Time) -> test_server:timetrap_cancel(), @@ -1174,13 +1181,21 @@ sync_notify(Name,Data) -> %%% 'enable break with release_shell option' %%% TestCases = [atom()] %%% -%%% @doc

This function will cancel all timetraps and pause the +%%% @doc

This function will cancel any active timetrap and pause the %%% execution of the current test case until the user calls the %%% continue/0 function. It gives the user the opportunity %%% to interact with the erlang node running the tests, e.g. for %%% debugging purposes or for manually executing a part of the %%% test case. If a parallel group is executing, break/2 %%% should be called instead.

+%%%

A cancelled timetrap will not be 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 the release_shell start option +%%% to true. See the User's Guide for more information.

+ break(Comment) -> case {ct_util:get_testdata(starter), ct_util:get_testdata(release_shell)} of @@ -1191,7 +1206,7 @@ break(Comment) -> {error,'enable break with release_shell option'}; _ -> case get_testdata(curr_tc) of - {ok,{_,TestCase}} -> + {ok,{_,_TestCase}} -> test_server:break(?MODULE, Comment); {ok,Cases} when is_list(Cases) -> {error,{'multiple cases running', @@ -1215,6 +1230,7 @@ break(Comment) -> %%% pause a test case executing in a parallel group. The %%% continue/1 function should be used to resume %%% execution of TestCase.

+%%%

See break/1 for more details.

break(TestCase, Comment) -> case {ct_util:get_testdata(starter), ct_util:get_testdata(release_shell)} of -- cgit v1.2.3