From 2d7ba88ebbb59a473dbcefd0f9dee1f1b816935e Mon Sep 17 00:00:00 2001 From: Peter Andersson Date: Tue, 8 Jun 2010 14:44:05 +0200 Subject: Misc documentation updates --- lib/common_test/doc/src/common_test_app.xml | 4 +-- lib/common_test/doc/src/event_handler_chapter.xml | 16 +++++----- lib/common_test/doc/src/run_test_chapter.xml | 31 +++++++++++++----- lib/common_test/doc/src/write_test_chapter.xml | 38 ++++++++++++++++++++--- 4 files changed, 67 insertions(+), 22 deletions(-) (limited to 'lib') diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml index 7b52883f8a..70efe5a14b 100644 --- a/lib/common_test/doc/src/common_test_app.xml +++ b/lib/common_test/doc/src/common_test_app.xml @@ -337,7 +337,7 @@ - Module:testcase() -> [Info] + Module:Testcase() -> [Info] Test case info function. Info = {timetrap,Time} | {require,Required} | @@ -396,7 +396,7 @@ - Module:testcase(Config) -> void() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit() + Module:Testcase(Config) -> void() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit() A test case Config = SaveConfig = [{Key,Value}] diff --git a/lib/common_test/doc/src/event_handler_chapter.xml b/lib/common_test/doc/src/event_handler_chapter.xml index 35b684730e..1508b7ce33 100644 --- a/lib/common_test/doc/src/event_handler_chapter.xml +++ b/lib/common_test/doc/src/event_handler_chapter.xml @@ -68,29 +68,27 @@ Example:

$ run_test -suite test/my_SUITE -event_handler handlers/my_evh1 handlers/my_evh2 -pa $PWD/handlers

+

Use the option instead of + to pass start arguments to the event handler + init function.

All event handler modules must have gen_event behaviour. Note also that these modules must be precompiled, and that their locations must be added explicitly to the Erlang code server search path (like in the example).

-

It is not possible to specify start arguments to the event handlers when - using the run_test program. You may however pass along start arguments - if you use the ct:run_test/1 function. An event_handler tuple in the argument - Opts has the following definition (see also ct:run_test/1 in the - reference manual):

+

An event_handler tuple in the argument Opts has the following + definition (see also ct:run_test/1 in the reference manual):

     {event_handler,EventHandlers}
 
     EventHandlers = EH | [EH]
     EH = atom() | {atom(),InitArgs} | {[atom()],InitArgs}
-    InitArgs = [term()] 
-
+ InitArgs = [term()]

Example:

-    1> ct:run_test([{suite,"test/my_SUITE"},{event_handler,[my_evh1,{my_evh2,[node()]}]}]).
-
+ 1> ct:run_test([{suite,"test/my_SUITE"},{event_handler,[my_evh1,{my_evh2,[node()]}]}]).

This will install two event handlers for the my_SUITE test. Event handler my_evh1 is started with [] as argument to the init function. Event handler my_evh2 is started with the name of the current node in the init argument list.

diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml index 7fd3174e71..54e9a3174c 100644 --- a/lib/common_test/doc/src/run_test_chapter.xml +++ b/lib/common_test/doc/src/run_test_chapter.xml @@ -97,8 +97,12 @@ the option with . With automatic compilation disabled, the user is responsible for compiling the test suite modules - (and any help modules) before the test run. Common Test will only verify - that the specified test suites exist before starting the tests.

+ (and any help modules) before the test run. If the modules can not be loaded + from the local file system during startup of Common Test, the user needs to + pre-load the modules before starting the test. Common Test will only verify + that the specified test suites exist (i.e. that they are, or can be, loaded). + This is useful e.g. if the test suites are transferred and loaded as binaries via + RPC from a remote node.

@@ -139,8 +143,14 @@ Code Coverage Analysis). ]]>, to install event handlers. + ]]>, to install + event handlers including start arguments. , specifies include directories (see above). , disables the automatic test suite compilation feature (see above). + ]]>, extends timetrap + timeout values. + ]]>, enables automatic timetrap + timeout scaling. ]]>, tells Common Test to repeat the tests n times (see below). ]]>, tells Common Test to repeat the tests for duration of time (see below). ]]>, tells Common Test to repeat the tests until stop_time (see below). @@ -243,11 +253,12 @@ call ct:start_interactive/0 to start Common Test. If you use the run_test program, you may start the Erlang shell and Common Test in the same go by using the -shell and, optionally, the -config - flag: + and/or -userconfig flag. Examples:

run_test -shell - ]]> + +

If no config file is given with the run_test command, @@ -272,7 +283,8 @@ 2> ct_telnet:open(unix_telnet). {ok,<0.105.0>} 4> ct_telnet:cmd(unix_telnet, "ls ."). - {ok,["ls .","file1 ...",...]} + {ok,["ls .","file1 ...",...]} +

Everything that Common Test normally prints in the test case logs, will in the interactive mode be written to a log named @@ -362,10 +374,13 @@ chapter.

Config terms:

+      {node, NodeAlias, Node}.
+
       {init, InitOptions}.
       {init, [NodeAlias], InitOptions}.
 
-      {node, NodeAlias, Node}.
+      {multiply_timetraps, N}.
+      {scale_timetraps, Bool}.
  
       {cover, CoverSpecFile}.
       {cover, NodeRef, CoverSpecFile}.
@@ -405,11 +420,13 @@

Types:

-      InitOptions   = term()
       NodeAlias     = atom()
+      InitOptions   = term()
       Node          = node()
       NodeRef       = NodeAlias | Node | master
       NodeRefs      = all_nodes | [NodeRef] | NodeRef
+      N             = integer()
+      Bool          = true | false
       CoverSpecFile = string()
       IncludeDirs   = string() | [string()]
       ConfigFiles   = string() | [string()]
diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml
index 212e3d85be..e2106469b7 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -157,6 +157,15 @@
       {skipped,Reason} (where Reason is a user specific term).
     

 
+    
The end_per_testcase/2 function is called even after a
+      test case terminates due to a call to ct:abort_current_testcase/1,
+      or after a timetrap timeout. However, end_per_testcase
+      will then execute on a different process than the test case
+      function, and in this situation, end_per_testcase will
+      not be able to change the reason for test case termination by
+      returning {fail,Reason}, nor will it be able to save data with
+      {save_config,Data}.

+
     
If init_per_testcase crashes, the test case itself is skipped 
     automatically (so called auto skipped). If init_per_testcase
     returns a skip tuple, also then will the test case be skipped (so
@@ -682,12 +691,33 @@
       end_per_suite execute, like test cases, on dedicated Erlang
       processes.
     

+
+
+ Timetrap timeouts +

The default time limit for a test case is 30 minutes, unless a - timetrap is specified either by the test case info function - or the suite/0 function. -

- + timetrap is specified either by the suite info function + or a test case info function. The timetrap timeout value defined + in suite/0 is the value that will be used for each test case + in the suite (as well as for the configuration functions + init_per_suite/1 and end_per_suite). A timetrap timeout + value set with the test case info function will override the value set + by suite/0, but only for that particular test case.

+

It is also possible to set/reset a timetrap during test case (or + configuration function) execution. This is done by calling + ct:timetrap/1. This function will cancel the current timetrap + and start a new one.

+

Timetrap values can be extended with a multiplier value specified at + startup with the multiply_timetraps option. It is also possible + to let Test Server decide to scale up timetrap timeout values + automatically, e.g. if tools such as cover or trace are running during + the test. This feature is disabled by default and can be enabled with + the scale_timetraps start option.

+

If a test case needs to suspend itself for a time that also gets + multipled by multiply_timetraps, and possibly scaled up if + scale_timetraps is enabled, the function ct:sleep/1 + may be called.

-- cgit v1.2.3