aboutsummaryrefslogtreecommitdiffstats
path: root/lib/common_test/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/common_test/doc')
-rw-r--r--lib/common_test/doc/src/Makefile15
-rw-r--r--lib/common_test/doc/src/common_test_app.xml34
-rw-r--r--lib/common_test/doc/src/config_file_chapter.xml6
-rw-r--r--lib/common_test/doc/src/ct_hooks.xml10
-rw-r--r--lib/common_test/doc/src/ct_hooks_chapter.xml51
-rw-r--r--lib/common_test/doc/src/ct_run.xml7
-rw-r--r--[-rwxr-xr-x]lib/common_test/doc/src/filestruct.gifbin2960 -> 2960 bytes
-rw-r--r--lib/common_test/doc/src/make.dep27
-rw-r--r--lib/common_test/doc/src/notes.xml223
-rw-r--r--lib/common_test/doc/src/run_test_chapter.xml52
-rw-r--r--lib/common_test/doc/src/write_test_chapter.xml14
11 files changed, 369 insertions, 70 deletions
diff --git a/lib/common_test/doc/src/Makefile b/lib/common_test/doc/src/Makefile
index 3ea6ae65d5..964f7c76c1 100644
--- a/lib/common_test/doc/src/Makefile
+++ b/lib/common_test/doc/src/Makefile
@@ -138,12 +138,6 @@ man: $(MAN6_FILES) $(MAN3_FILES) $(MAN1_FILES)
debug opt:
-#
-# checkout make.dep before generating new dependecies
-#
-#make_doc_depend: xml
-# docdepend > make.dep
-
clean clean_docs:
rm -f $(CT_XML_FILES)
rm -rf $(HTMLDIR)/*
@@ -176,12 +170,3 @@ release_docs_spec: docs
release_spec:
release_tests_spec:
-
-# ----------------------------------------------------
-# Include dependency
-# ----------------------------------------------------
-
-include make.dep
-# DO NOT DELETE
-
-
diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml
index c92566de37..f58b2ab0a9 100644
--- a/lib/common_test/doc/src/common_test_app.xml
+++ b/lib/common_test/doc/src/common_test_app.xml
@@ -133,9 +133,15 @@
{require,Name,Required} | {userdata,UserData} |
{silent_connections,Conns} | {stylesheet,CSSFile} |
{ct_hooks, CTHs}</v>
- <v> Time = MilliSec | {seconds,integer()} | {minutes,integer()}
- | {hours,integer()}</v>
+ <v> Time = TimeVal | TimeFunc</v>
+ <v> TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} |
+ {hours,integer()}</v>
+ <v> TimeFunc = {Mod,Func,Args} | Fun</v>
<v> MilliSec = integer()</v>
+ <v> Mod = atom()</v>
+ <v> Func = atom()</v>
+ <v> Args = list()</v>
+ <v> Fun = fun()</v>
<v> Required = Key | {Key,SubKeys}</v>
<v> Key = atom()</v>
<v> SubKeys = SubKey | [SubKey]</v>
@@ -144,7 +150,7 @@
<v> UserData = term()</v>
<v> Conns = [atom()]</v>
<v> CSSFile = string()</v>
- <v> CTHs = [CTHModule | {CTHModule, CTHInitArgs}]</v>
+ <v> CTHs = [CTHModule | {CTHModule, CTHInitArgs} | {CTHModule, CTHInitArgs, CTHPriority}]</v>
<v> CTHModule = atom()</v>
<v> CTHInitArgs = term()</v>
</type>
@@ -161,7 +167,9 @@
test case is allowed to take (including <c>init_per_testcase/2</c>
and <c>end_per_testcase/2</c>). If the timetrap time is
exceeded, the test case fails with reason
- <c>timetrap_timeout</c>.</p>
+ <c>timetrap_timeout</c>. If a <c>TimeFunc</c> function is specified,
+ it will be called initially and must return a value on
+ <c>TimeVal</c> format.</p>
<p>The <c>require</c> tag specifies configuration variables
that are required by test cases in the suite. If the required
@@ -248,7 +256,7 @@
</type>
<desc>
- <p> MANDATORY (only if one or more groups are defined) </p>
+ <p> OPTIONAL </p>
<p>This function is called before execution of a test case group.
It typically contains initialization which is common for
@@ -279,7 +287,7 @@
</type>
<desc>
- <p> MANDATORY (only if one or more groups are defined) </p>
+ <p> OPTIONAL </p>
<p>This function is called after the execution of a test case group is finished.
It is meant to be used for cleaning up after <c>init_per_group/2</c>.
@@ -353,9 +361,15 @@
<v> Info = {timetrap,Time} | {require,Required} |
{require,Name,Required} | {userdata,UserData} |
{silent_connections,Conns}</v>
- <v> Time = MilliSec | {seconds,integer()} | {minutes,integer()}
- | {hours,integer()}</v>
+ <v> Time = TimeVal | TimeFunc</v>
+ <v> TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} |
+ {hours,integer()}</v>
+ <v> TimeFunc = {Mod,Func,Args} | Fun</v>
<v> MilliSec = integer()</v>
+ <v> Mod = atom()</v>
+ <v> Func = atom()</v>
+ <v> Args = list()</v>
+ <v> Fun = fun()</v>
<v> Required = Key | {Key,SubKeys}</v>
<v> Key = atom()</v>
<v> SubKeys = SubKey | [SubKey]</v>
@@ -378,7 +392,9 @@
exceeded, the test case fails with reason
<c>timetrap_timeout</c>. <c>init_per_testcase/2</c>
and <c>end_per_testcase/2</c> are included in the
- timetrap time.</p>
+ timetrap time. If a <c>TimeFunc</c> function is specified,
+ it will be called before the test case (or <c>init_per_testcase/2</c>)
+ and must return a value on <c>TimeVal</c> format.</p>
<p>The <c>require</c> tag specifies configuration variables
that are required by the test case. If the required
diff --git a/lib/common_test/doc/src/config_file_chapter.xml b/lib/common_test/doc/src/config_file_chapter.xml
index 59151a73ec..6fc6638bf7 100644
--- a/lib/common_test/doc/src/config_file_chapter.xml
+++ b/lib/common_test/doc/src/config_file_chapter.xml
@@ -285,7 +285,7 @@
<c>{ok, Config}</c> - if the configuration variables are read successfully,
</item>
<item>
- <c>{error, Error, ErrorDetails}</c> - if the callback module fails to
+ <c>{error, {Error, ErrorDetails}}</c> - if the callback module fails to
proceed with the given configuration parameters.
</item>
</list>
@@ -422,14 +422,14 @@ stop()->
call(Client, Request)->
case whereis(?REGISTERED_NAME) of
undefined->
- {error, not_started, Request};
+ {error, {not_started, Request}};
Pid->
Pid ! {Client, Request},
receive
Reply->
{ok, Reply}
after 4000->
- {error, timeout, Request}
+ {error, {timeout, Request}}
end
end.
diff --git a/lib/common_test/doc/src/ct_hooks.xml b/lib/common_test/doc/src/ct_hooks.xml
index 7aaa29d60c..b98c04a850 100644
--- a/lib/common_test/doc/src/ct_hooks.xml
+++ b/lib/common_test/doc/src/ct_hooks.xml
@@ -75,12 +75,14 @@
<funcs>
<func>
- <name>Module:init(Id, Opts) -&gt; State</name>
+ <name>Module:init(Id, Opts) -&gt; {ok, State} |
+ {ok, State, Priority}</name>
<fsummary>Initiates the Common Test Hook</fsummary>
<type>
<v>Id = reference() | term()</v>
<v>Opts = term()</v>
<v>State = term()</v>
+ <v>Priority = integer()</v>
</type>
<desc>
@@ -97,6 +99,10 @@
if <seealso marker="#Module:id-1">id/1</seealso> is not implemented.
</p>
+ <p><c>Priority</c> is the relative priority of this hook. Hooks with a
+ lower priority will be executed first. If no priority is given,
+ it will be set to 0. </p>
+
<p>For details about when init is called see
<seealso marker="ct_hooks_chapter#scope">scope</seealso>
in the User's Guide.</p>
@@ -290,7 +296,7 @@
<p>Note that it is not possible to add CTH's here right now,
that feature might be added later,
- but it would right now break backwards compatability.</p>
+ but it would right now break backwards compatibility.</p>
</desc>
</func>
diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml
index aec452e135..bac0c4eaa8 100644
--- a/lib/common_test/doc/src/ct_hooks_chapter.xml
+++ b/lib/common_test/doc/src/ct_hooks_chapter.xml
@@ -89,9 +89,11 @@
<seealso marker="common_test#Module:init_per_group-2">
init_per_group/2</seealso>. <c>CTH</c> in this case can be either
only the module name of the CTH or a tuple with the module name and the
- initial arguments to the CTH. Eg:
+ initial arguments and optionally the hook priority of the CTH. Eg:
<c>{ct_hooks,[my_cth_module]}</c> or
- <c>{ct_hooks,[{my_cth_module,[{debug,true}]}]}</c></p>
+ <c>{ct_hooks,[{my_cth_module,[{debug,true}]}]}</c> or
+ <c>{ct_hooks,[{my_cth_module,[{debug,true}],500}]}</c>
+ </p>
<section>
<title>Overriding CTHs</title>
@@ -104,7 +106,16 @@
<c>id</c> in both places, Common Test knows that this CTH
has already been installed and will not try to install it again.</p>
</section>
-
+
+ <section>
+ <title>CTH Priority</title>
+ <p>By default each CTH installed will be executed in the order which
+ they are installed. This is not always wanted so common_test allows
+ the user to specify a priority for each hook. The priority can either
+ be specified in the CTH <seealso marker="ct_hooks#Module:init-2">init/2
+ </seealso> function or when installing the hook. The priority given at
+ installation will override the priority returned by the CTH. </p>
+ </section>
</section>
<marker id="scope"/>
@@ -326,7 +337,7 @@ id(Opts) ->
%% any common state.
init(Id, Opts) ->
{ok,D} = file:open(Id,[write]),
- #state{ file_handle = D, total = 0, data = [] }.
+ {ok, #state{ file_handle = D, total = 0, data = [] }}.
%% @doc Called before init_per_suite is called.
pre_init_per_suite(Suite,Config,State) ->
@@ -389,6 +400,38 @@ terminate(State) ->
ok.</code>
</section>
+ <marker id="builtin_cths"/>
+ <section>
+ <title>Built-in CTHs</title>
+ <p>Common Test is delivered with a couple of general purpose CTHs that
+ can be enabled by the user to provide some generic testing functionality.
+ Some of these are enabled by default when starting running common_test,
+ they can be disabled by setting <c>enable_builtin_hooks</c> to
+ <c>false</c> on the command line or in the test specification. In the
+ table below there is a list of all current CTHs which are delivered with
+ Common Test.</p>
+
+ <table>
+ <row>
+ <cell><em>CTH Name</em></cell>
+ <cell><em>Is Built-in</em></cell>
+ <cell><em>Description</em></cell>
+ </row>
+ <row>
+ <cell>cth_log_redirect</cell>
+ <cell>yes</cell>
+ <cell>Captures all error_logger and SASL logging events and prints them
+ to the current test case log. If an event can not be associated with a
+ testcase it will be printed in the common test framework log. This will
+ happen for testcases which are run in parallel and events which occur
+ inbetween testcases. You can configure the level of
+ <seealso marker="sasl:sasl_app">SASL</seealso> events report
+ using the normal SASL mechanisms. </cell>
+ </row>
+ </table>
+
+ </section>
+
</chapter>
diff --git a/lib/common_test/doc/src/ct_run.xml b/lib/common_test/doc/src/ct_run.xml
index 1ab563d74f..9045646733 100644
--- a/lib/common_test/doc/src/ct_run.xml
+++ b/lib/common_test/doc/src/ct_run.xml
@@ -83,7 +83,7 @@
<title>Run tests from command line</title>
<pre>
ct_run [-dir TestDir1 TestDir2 .. TestDirN] |
- [-suite Suite1 Suite2 .. SuiteN
+ [[-dir TestDir] -suite Suite1 Suite2 .. SuiteN
[[-group Group1 Group2 .. GroupN] [-case Case1 Case2 .. CaseN]]]
[-step [config | keep_inactive]]
[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
@@ -92,6 +92,7 @@
[-decrypt_key Key] | [-decrypt_file KeyFile]
[-label Label]
[-logdir LogDir]
+ [-logopts LogOpts]
[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
[-stylesheet CSSFile]
[-cover CoverCfgFile]
@@ -117,6 +118,7 @@
[-decrypt_key Key] | [-decrypt_file KeyFile]
[-label Label]
[-logdir LogDir]
+ [-logopts LogOpts]
[-allow_user_terms]
[-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
[-stylesheet CSSFile]
@@ -138,10 +140,11 @@
<pre>
ct_run -vts [-browser Browser]
[-dir TestDir1 TestDir2 .. TestDirN] |
- [-suite Suite [[-group Group] [-case Case]]]
+ [[dir TestDir] -suite Suite [[-group Group] [-case Case]]]
[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
ConfigString2 and .. and CallbackModuleN ConfigStringN]
+ [-logopts LogOpts]
[-decrypt_key Key] | [-decrypt_file KeyFile]
[-include InclDir1 InclDir2 .. InclDirN]
[-no_auto_compile]
diff --git a/lib/common_test/doc/src/filestruct.gif b/lib/common_test/doc/src/filestruct.gif
index 2b06833d0b..2b06833d0b 100755..100644
--- a/lib/common_test/doc/src/filestruct.gif
+++ b/lib/common_test/doc/src/filestruct.gif
Binary files differ
diff --git a/lib/common_test/doc/src/make.dep b/lib/common_test/doc/src/make.dep
deleted file mode 100644
index e34075888d..0000000000
--- a/lib/common_test/doc/src/make.dep
+++ /dev/null
@@ -1,27 +0,0 @@
-# ----------------------------------------------------
-# >>>> Do not edit this file <<<<
-# This file was automaticly generated by
-# /home/otp/bin/docdepend
-# ----------------------------------------------------
-
-
-# ----------------------------------------------------
-# TeX files that the DVI file depend on
-# ----------------------------------------------------
-
-book.dvi: basics_chapter.tex book.tex common_test_app.tex \
- config_file_chapter.tex cover_chapter.tex \
- ct.tex ct_cover.tex ct_ftp.tex ct_master.tex \
- ct_master_chapter.tex ct_rpc.tex ct_snmp.tex \
- ct_ssh.tex ct_telnet.tex dependencies_chapter.tex \
- event_handler_chapter.tex example_chapter.tex \
- install_chapter.tex part.tex ref_man.tex run_test.tex \
- run_test_chapter.tex test_structure_chapter.tex \
- unix_telnet.tex why_test_chapter.tex write_test_chapter.tex
-
-# ----------------------------------------------------
-# Source inlined when transforming from source to LaTeX
-# ----------------------------------------------------
-
-book.tex: ref_man.xml
-
diff --git a/lib/common_test/doc/src/notes.xml b/lib/common_test/doc/src/notes.xml
index 826b3c598d..af96ef621f 100644
--- a/lib/common_test/doc/src/notes.xml
+++ b/lib/common_test/doc/src/notes.xml
@@ -32,6 +32,229 @@
<file>notes.xml</file>
</header>
+<section><title>Common_Test 1.5.5</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ An error in how comments are colored in the test suite
+ overview html log file has been corrected. As result, a
+ new framework callback function, format_comment/1, has
+ been introduced.</p>
+ <p>
+ Own Id: OTP-9237</p>
+ </item>
+ <item>
+ <p>
+ Automatically generated init- and end-configuration
+ functions for test case groups caused incorrect execution
+ order of test cases. This has been corrected.</p>
+ <p>
+ Own Id: OTP-9369</p>
+ </item>
+ <item>
+ <p>
+ If multiple directories were specified with the 'logdir'
+ flag/option, Common Test would crash. This has been fixed
+ so that an error is properly reported instead.</p>
+ <p>
+ Own Id: OTP-9370</p>
+ </item>
+ <item>
+ <p>
+ If ct:log/2 was called with bad arguments, this could
+ cause the Common Test IO handling process to crash. This
+ fault has been corrected.</p>
+ <p>
+ Own Id: OTP-9371 Aux Id: OTP-8933 </p>
+ </item>
+ <item>
+ <p>
+ A bug has been fixed that made Test Server call the
+ end_tc/3 framework function with an incorrect module name
+ as first argument.</p>
+ <p>
+ Own Id: OTP-9379 Aux Id: seq11863 </p>
+ </item>
+ <item>
+ <p>
+ If a timetrap timeout occured during execution of of a
+ function in a lib module (i.e. a function called directly
+ or indirectly from a test case), the Suite argument in
+ the end_tc/3 framework callback function would not
+ correctly contain the name of the test suite, but the lib
+ module. (This would only happen if the lib module was
+ compiled with ct.hrl included). This error has been
+ solved.</p>
+ <p>
+ Own Id: OTP-9398</p>
+ </item>
+ <item>
+ <p>
+ Corrections of the vts mode. It will now report errors
+ (about e.g. incorrect config files) instead of crashing
+ or hanging. Furthermore, the requirement that the test
+ directory name must have a "_test" suffix has been
+ removed. Also, a workaround has been implemented for the
+ limitation that the file browser (in many web browsers)
+ will only return the basic file name, not the full
+ directory path (which made it impossible to have config
+ files in other directories than the main test directory).</p>
+ <p>
+ Own Id: OTP-9429</p>
+ </item>
+ <item>
+ <p>
+ Add a proplist() type</p>
+ <p>
+ Recently I was adding specs to an API and found that
+ there is no canonical proplist() type defined. (Thanks to
+ Ryan Zezeski)</p>
+ <p>
+ Own Id: OTP-9499</p>
+ </item>
+ <item>
+ <p>
+ It is now possible to use the 'step' flag/option to run
+ the debugger for test suites that contain test case
+ groups. This previously caused Common Test to crash. If
+ 'step config' is specified, breakpoints are now also
+ automatically set on init_per_group and end_per_group.
+ Note that breakpoints are always set automatically on
+ test case functions and this is true also for grouped
+ cases.</p>
+ <p>
+ Own Id: OTP-9518 Aux Id: OTP-8933 </p>
+ </item>
+ <item>
+ <p>
+ The test index page was not refreshed at the start of
+ each test suite which made it impossible to follow test
+ execution by means of refreshing the browser window (no
+ links to follow). This has been fixed.</p>
+ <p>
+ Own Id: OTP-9520 Aux Id: OTP-8933 </p>
+ </item>
+ <item>
+ <p>
+ If a test suite would start with a test case group
+ defined without the init_per_group/2 and end_per_group/2
+ function, init_per_suite/1 would not execute initially
+ and logging of the test run would fail. This error has
+ been fixed.</p>
+ <p>
+ Own Id: OTP-9584</p>
+ </item>
+ <item>
+ <p>
+ The "Missing Suites" link from the top level index page
+ was incorrect and has been fixed.</p>
+ <p>
+ Own Id: OTP-9592</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Various corrections and updates to improve the handling
+ and reporting of errors.</p>
+ <p>
+ Own Id: OTP-8933</p>
+ </item>
+ <item>
+ <p>
+ The dir and suite start option can now be used in
+ combination. E.g. executing my_SUITE in directory
+ my_tests can either be specified as "ct_run -suite
+ my_tests/my_SUITE" or as "ct_run -dir my_tests -suite
+ my_SUITE". Furthermore, the specification:
+ ct:run_test([{suite,["./my_SUITE"]},{testcase,t1}]) is
+ now interpreted as
+ ct:run_test([{suite,"./my_SUITE"},{testcase,t1}]), i.e.
+ only testcase t1 in test suite my_SUITE - not all cases -
+ will be executed.</p>
+ <p>
+ Own Id: OTP-9155</p>
+ </item>
+ <item>
+ <p>
+ A new option, 'logopts', has been introduced, to make it
+ possible to modify some aspects of the logging behaviour
+ in Common Test (or Test Server). For example, whenever an
+ io printout is made, test_server adds newline (\n) to the
+ end of the output string. This may not always be a
+ preferred action and can therefore be disabled by means
+ of "ct_run ... -logopts no_nl" (or ct:run_test([...,
+ {logopts,[no_nl]}])). A new framework callback function,
+ get_logopts/0, has been introduced (see the ct_framework
+ module for details).</p>
+ <p>
+ Own Id: OTP-9372 Aux Id: OTP-9396 </p>
+ </item>
+ <item>
+ <p>
+ A new option, 'logopts', has been introduced, to make it
+ possible to modify some aspects of the logging behaviour
+ in Common Test (or Test Server). For example, if the html
+ version of the test suite source code should not be
+ generated during the test run (and consequently be
+ unavailable in the log file system), the feature may be
+ disabled by means of "ct_run ... -logopts no_src" (or
+ ct:run_test([..., {logopts,[no_src]}])). A new framework
+ callback function, get_logopts/0, has been introduced
+ (see the ct_framework module for details).</p>
+ <p>
+ Own Id: OTP-9396 Aux Id: seq11869, OTP-9372 </p>
+ </item>
+ <item>
+ <p>
+ CT Hooks can now be assigned a priority. The priority of
+ a CTH determines when it should execute in relation to
+ other CTHs. The CTH with the lowest priority will be
+ executed first, CTHs with equal priority will be executed
+ in the order which they were installed.</p>
+ <p>
+ Own Id: OTP-9445</p>
+ </item>
+ <item>
+ <p>
+ It is now possible to use a tuple {M,F,A}, or a fun, as
+ timetrap specification in the suite info function or test
+ case info functions. The function must return a valid
+ timeout value, as documented in the common_test man page
+ and in the User's Guide.</p>
+ <p>
+ Own Id: OTP-9501 Aux Id: seq11894 </p>
+ </item>
+ <item>
+ <p>
+ A new built-in common test hook has been added which
+ captures error_logger and SASL event and prints them in
+ the testcase log. To disable this (and any other built-in
+ hooks) pass 'enable_builtin_hooks false' to common test.</p>
+ <p>
+ Own Id: OTP-9543</p>
+ </item>
+ <item>
+ <p>
+ Common Test now has the possibility to have built-in
+ hooks which are started by default when any test is run.
+ To disable built-in hooks pass 'enable_builtin_hooks
+ false' to common test. See the common test hooks
+ documentation for more details.</p>
+ <p>
+ Own Id: OTP-9564</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>Common_Test 1.5.4</title>
<section><title>Fixed Bugs and Malfunctions</title>
diff --git a/lib/common_test/doc/src/run_test_chapter.xml b/lib/common_test/doc/src/run_test_chapter.xml
index e6fb85634f..57059f0ba2 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -128,6 +128,15 @@
<p><c>$ ct_run -suite $SYS1_TEST/setup_SUITE -case start stop</c></p>
<p><c>$ ct_run -suite $SYS1_TEST/setup_SUITE -group installation -case start stop</c></p>
+ <p>It is also possible to combine the <c>dir</c>, <c>suite</c> and <c>group/case</c> flags. E.g, to run
+ <c>x_SUITE</c> and <c>y_SUITE</c> in directory <c>testdir</c>:</p>
+
+ <p><c>$ ct_run -dir ./testdir -suite x_SUITE y_SUITE</c></p>
+
+ <p>This has the same effect as calling:</p>
+
+ <p><c>$ ct_run -suite ./testdir/x_SUITE ./testdir/y_SUITE</c></p>
+
<p>Other flags that may be used with <c>ct_run</c>:</p>
<list>
<item><c><![CDATA[-logdir <dir>]]></c>, specifies where the HTML log files are to be written.</item>
@@ -150,6 +159,8 @@
<seealso marker="event_handler_chapter#event_handling">event handlers</seealso> including start arguments.</item>
<item><c><![CDATA[-ct_hooks <ct_hooks>]]></c>, to install
<seealso marker="ct_hooks_chapter#installing">Common Test Hooks</seealso> including start arguments.</item>
+ <item><c><![CDATA[-enable_builtin_hooks <bool>]]></c>, to enable/disable
+ <seealso marker="ct_hooks_chapter#builtin_cths">Built-in Common Test Hooks</seealso>. Default is <c>true</c>.</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
@@ -165,6 +176,8 @@
<item><c><![CDATA[-decrypt_file <key_file>]]></c>, points out a file containing a decryption key for
<seealso marker="config_file_chapter#encrypted_config_files">encrypted configuration files</seealso>.</item>
<item><c><![CDATA[-basic_html]]></c>, switches off html enhancements that might not be compatible with older browsers.</item>
+ <item><c><![CDATA[-logopts <opts>]]></c>, makes it possible to modify aspects of the logging behaviour, see
+ <seealso marker="run_test_chapter#logopts">Log options</seealso> below.</item>
</list>
<note><p>Directories passed to Common Test may have either relative or absolute paths.</p></note>
@@ -322,8 +335,9 @@
are to be executed by Common Test, and those functions only. If
the step option <c>config</c> is specified, breakpoints will
also be initially set on the configuration functions in the suite, i.e.
- <c>init_per_suite/1</c>, <c>end_per_suite/1</c>, <c>init_per_testcase/2</c>
- and <c>end_per_testcase/2</c>.</p>
+ <c>init_per_suite/1</c>, <c>end_per_suite/1</c>,
+ <c>init_per_group/2</c>, <c>end_per_group/2</c>,
+ <c>init_per_testcase/2</c> and <c>end_per_testcase/2</c>.</p>
<p>Common Test enables the Debugger auto attach feature, which means
that for every new interpreted test case function that starts to execute,
a new trace window will automatically pop up. (This is because each test
@@ -450,6 +464,8 @@
{ct_hooks, CTHModules}.
{ct_hooks, NodeRefs, CTHModules}.
+
+ {enable_builtin_hooks, Bool}.
</pre>
<p>Test terms:</p>
<pre>
@@ -488,7 +504,7 @@
LogDir = string()
EventHandlers = atom() | [atom()]
InitArgs = [term()]
- CTHModules = [CTHModule | {CTHModule, CTHInitArgs}]
+ CTHModules = [CTHModule | {CTHModule, CTHInitArgs} | {CTHModule, CTHInitArgs, CTHPriority}]
CTHModule = atom()
CTHInitArgs = term()
DirRef = DirAlias | Dir
@@ -631,7 +647,11 @@
<p>The minor log file contain full details of every single test
case, each one in a separate file. This way the files should
be easy to compare with previous test runs, even if the set of
- test cases change.</p>
+ test cases change. If SASL is running those logs will also be
+ printed there by the
+ <seealso marker="common_test:ct_hooks_chapter#builtin_cths">
+ cth_log_redirect built-in hook</seealso>.
+ </p>
<p>Which information goes where is user configurable via the
test server controller. Three threshold values determine what
@@ -644,6 +664,30 @@
to follow test progress simply by refreshing pages in the HTML browser.
Statistics totals are not presented until a test is complete however.</p>
+ <section>
+ <marker id="logopts"></marker>
+ <title>Log options</title>
+ <p>With the <c>logopts</c> start flag, it's possible to specify
+ options that modify some aspects of the logging behaviour.
+ Currently, the following options are available:</p>
+ <list>
+ <item><c>no_src</c></item>
+ <item><c>no_nl</c></item>
+ </list>
+ <p>With <c>no_src</c>, the html version of the test suite source
+ code will not be generated during the test run (and consequently
+ not be available in the log file system).</p>
+ <p>With <c>no_nl</c>, Common Test will not add a newline character
+ (\n) to the end of an output string that it receives from a call to e.g.
+ <c>io:format/2</c>, and which it prints to the test case log.</p>
+ <p>For example, if a test is started with:</p>
+ <p><c>$ ct_run -suite my_SUITE -logopts no_src</c></p>
+ <p>then printouts during the test made by successive calls to <c>io:format("x")</c>,
+ will appear in the test case log as:</p>
+ <p><c>xxx</c></p>
+ <p>instead of each <c>x</c> printed on a new line, which is the default behaviour.</p>
+ </section>
+
</section>
<section>
diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml
index 3f9fdb7121..e35888e68f 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -280,6 +280,8 @@
the timetrap time is exceeded, the test case fails with
reason <c>timetrap_timeout</c>. Note that <c>init_per_testcase</c>
and <c>end_per_testcase</c> are included in the timetrap time.
+ Please see the <seealso marker="write_test_chapter#timetraps">Timetrap</seealso>
+ section for more details.
</p>
</item>
<tag><em><c>userdata</c></em></tag>
@@ -699,8 +701,8 @@
</section>
<section>
- <title>Timetrap timeouts</title>
<marker id="timetraps"></marker>
+ <title>Timetrap timeouts</title>
<p>The default time limit for a test case is 30 minutes, unless a
<c>timetrap</c> is specified either by the suite info function
or a test case info function. The timetrap timeout value defined
@@ -723,6 +725,13 @@
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>
+ <p>A function (<c>fun</c> or <c>MFA</c>) may be specified as timetrap value
+ in the suite- and test case info function, e.g:</p>
+ <p><c>{timetrap,{test_utils,get_timetrap_value,[?MODULE,system_start]}}</c></p>
+ <p>The function will be called initially by Common Test (before execution
+ of the suite or the test case) and must return a time value such as an
+ integer (millisec), or a <c>{SecMinOrHourTag,Time}</c> tuple. More
+ information can be found in the <c>common_test</c> reference manual.</p>
</section>
<section>
@@ -818,6 +827,3 @@
</list>
</section>
</chapter>
-
-
-