From 2d7ba88ebbb59a473dbcefd0f9dee1f1b816935e Mon Sep 17 00:00:00 2001
From: Peter Andersson <peppe@erlang.org>
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 @@
</func>
<func>
- <name>Module:testcase() -> [Info] </name>
+ <name>Module:Testcase() -> [Info] </name>
<fsummary>Test case info function. </fsummary>
<type>
<v> Info = {timetrap,Time} | {require,Required} |
@@ -396,7 +396,7 @@
<func>
- <name>Module:testcase(Config) -> void() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit() </name>
+ <name>Module:Testcase(Config) -> void() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit() </name>
<fsummary>A test case</fsummary>
<type>
<v> Config = SaveConfig = [{Key,Value}]</v>
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:</p>
<p><c>$ run_test -suite test/my_SUITE -event_handler handlers/my_evh1
handlers/my_evh2 -pa $PWD/handlers</c></p>
+ <p>Use the <c><![CDATA[run_test -event_handler_init]]></c> option instead of
+ <c><![CDATA[-event_handler]]></c> to pass start arguments to the event handler
+ init function.</p>
<p>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).</p>
- <p>It is not possible to specify start arguments to the event handlers when
- using the <c>run_test</c> program. You may however pass along start arguments
- if you use the <c>ct:run_test/1</c> function. An event_handler tuple in the argument
- <c>Opts</c> has the following definition (see also <c>ct:run_test/1</c> in the
- reference manual):</p>
+ <p>An event_handler tuple in the argument <c>Opts</c> has the following
+ definition (see also <c>ct:run_test/1</c> in the reference manual):</p>
<pre>
{event_handler,EventHandlers}
EventHandlers = EH | [EH]
EH = atom() | {atom(),InitArgs} | {[atom()],InitArgs}
- InitArgs = [term()]
- </pre>
+ InitArgs = [term()]</pre>
<p>Example:</p>
<pre>
- 1> ct:run_test([{suite,"test/my_SUITE"},{event_handler,[my_evh1,{my_evh2,[node()]}]}]).
- </pre>
+ 1> ct:run_test([{suite,"test/my_SUITE"},{event_handler,[my_evh1,{my_evh2,[node()]}]}]).</pre>
<p>This will install two event handlers for the <c>my_SUITE</c> test. Event handler
<c>my_evh1</c> is started with <c>[]</c> as argument to the init function. Event handler
<c>my_evh2</c> is started with the name of the current node in the init argument list.</p>
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 <c><![CDATA[{auto_compile,false}]]></c> option with
<c><![CDATA[ct:run_test/1]]></c>. 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.</p>
+ (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.</p>
</section>
<section>
@@ -139,8 +143,14 @@
<seealso marker="cover_chapter#cover">Code Coverage Analysis</seealso>).</item>
<item><c><![CDATA[-event_handler <event_handlers>]]></c>, to install
<seealso marker="event_handler_chapter#event_handling">event handlers</seealso>.</item>
+ <item><c><![CDATA[-event_handler_init <event_handlers>]]></c>, to install
+ <seealso marker="event_handler_chapter#event_handling">event handlers</seealso> including start arguments.</item>
<item><c><![CDATA[-include]]></c>, specifies include directories (see above).</item>
<item><c><![CDATA[-no_auto_compile]]></c>, disables the automatic test suite compilation feature (see above).</item>
+ <item><c><![CDATA[-multiply_timetraps <n>]]></c>, extends <seealso marker="write_test_chapter#timetraps">timetrap
+ timeout</seealso> values.</item>
+ <item><c><![CDATA[-scale_timetraps <bool>]]></c>, enables automatic <seealso marker="write_test_chapter#timetraps">timetrap
+ timeout</seealso> scaling.</item>
<item><c><![CDATA[-repeat <n>]]></c>, tells Common Test to repeat the tests n times (see below).</item>
<item><c><![CDATA[-duration <time>]]></c>, tells Common Test to repeat the tests for duration of time (see below).</item>
<item><c><![CDATA[-until <stop_time>]]></c>, tells Common Test to repeat the tests until stop_time (see below).</item>
@@ -243,11 +253,12 @@
call <c>ct:start_interactive/0</c> to start Common Test. If you use
the <c>run_test</c> program, you may start the Erlang shell and Common Test
in the same go by using the <c>-shell</c> and, optionally, the <c>-config</c>
- flag:
+ and/or <c>-userconfig</c> flag. Examples:
</p>
<list>
<item><c>run_test -shell</c></item>
- <item><c><![CDATA[run_test -shell -config <configfilename>]]></c></item>
+ <item><c><![CDATA[run_test -shell -config cfg/db.cfg]]></c></item>
+ <item><c><![CDATA[run_test -shell -userconfig db_login testuser x523qZ]]></c></item>
</list>
<p>If no config file is given with the <c>run_test</c> 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 ...",...]}</pre>
+ {ok,["ls .","file1 ...",...]}
+ </pre>
<p>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.</p>
<p>Config terms:</p>
<pre>
+ {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 @@
</pre>
<p>Types:</p>
<pre>
- 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 @@
<c>{skipped,Reason}</c> (where Reason is a user specific term).
</p>
+ <p>The <c>end_per_testcase/2</c> function is called even after a
+ test case terminates due to a call to <c>ct:abort_current_testcase/1</c>,
+ or after a timetrap timeout. However, <c>end_per_testcase</c>
+ will then execute on a different process than the test case
+ function, and in this situation, <c>end_per_testcase</c> will
+ not be able to change the reason for test case termination by
+ returning <c>{fail,Reason}</c>, nor will it be able to save data with
+ <c>{save_config,Data}</c>.</p>
+
<p>If <c>init_per_testcase</c> crashes, the test case itself is skipped
automatically (so called <em>auto skipped</em>). If <c>init_per_testcase</c>
returns a <c>skip</c> tuple, also then will the test case be skipped (so
@@ -682,12 +691,33 @@
<c>end_per_suite</c> execute, like test cases, on dedicated Erlang
processes.
</p>
+ </section>
+ <section>
+ <title>Timetrap timeouts</title>
+ <marker id="timetraps"></marker>
<p>The default time limit for a test case is 30 minutes, unless a
- <c>timetrap</c> is specified either by the test case info function
- or the <c>suite/0</c> function.
- </p>
-
+ <c>timetrap</c> is specified either by the suite info function
+ or a test case info function. The timetrap timeout value defined
+ in <c>suite/0</c> is the value that will be used for each test case
+ in the suite (as well as for the configuration functions
+ <c>init_per_suite/1</c> and <c>end_per_suite</c>). A timetrap timeout
+ value set with the test case info function will override the value set
+ by <c>suite/0</c>, but only for that particular test case.</p>
+ <p>It is also possible to set/reset a timetrap during test case (or
+ configuration function) execution. This is done by calling
+ <c>ct:timetrap/1</c>. This function will cancel the current timetrap
+ and start a new one.</p>
+ <p>Timetrap values can be extended with a multiplier value specified at
+ startup with the <c>multiply_timetraps</c> 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 <c>scale_timetraps</c> start option.</p>
+ <p>If a test case needs to suspend itself for a time that also gets
+ multipled by <c>multiply_timetraps</c>, and possibly scaled up if
+ <c>scale_timetraps</c> is enabled, the function <c>ct:sleep/1</c>
+ may be called.</p>
</section>
<section>
--
cgit v1.2.3