aboutsummaryrefslogtreecommitdiffstats
path: root/lib/common_test/doc/src/common_test_app.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/common_test/doc/src/common_test_app.xml')
-rw-r--r--lib/common_test/doc/src/common_test_app.xml776
1 files changed, 391 insertions, 385 deletions
diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml
index cc554eb84e..10c93e2ed1 100644
--- a/lib/common_test/doc/src/common_test_app.xml
+++ b/lib/common_test/doc/src/common_test_app.xml
@@ -33,89 +33,84 @@
<file>common_test_app.sgml</file>
</header>
<module>common_test</module>
- <modulesummary>A framework for automated testing of arbitrary target nodes</modulesummary>
+ <modulesummary>A framework for automated testing of any target nodes.</modulesummary>
<description>
- <p>The <em>Common Test</em> framework is an environment for
+ <p>The <c>Common Test</c> framework is an environment for
implementing and performing automatic and semi-automatic execution of
- test cases.
+ test cases.</p>
- Common Test uses the OTP Test Server as engine for test case
- execution and logging.</p>
-
- <p>In brief, Common Test supports:</p>
+ <p>In brief, <c>Common Test</c> supports:</p>
<list>
- <item>Automated execution of test suites (sets of test cases).</item>
- <item>Logging of the events during execution.</item>
- <item>HTML presentation of test suite results.</item>
- <item>HTML presentation of test suite code.</item>
- <item>Support functions for test suite authors.</item>
- <item>Step by step execution of test cases.</item>
+ <item>Automated execution of test suites (sets of test cases)</item>
+ <item>Logging of events during execution</item>
+ <item>HTML presentation of test suite results</item>
+ <item>HTML presentation of test suite code</item>
+ <item>Support functions for test suite authors</item>
+ <item>Step-by-step execution of test cases</item>
</list>
-
- <p>The following sections describe the mandatory and optional test suite
- functions Common Test will call during test execution. For more details
- see <seealso marker="write_test_chapter">Common Test User's
- Guide.</seealso> </p>
-
+
+ <p>The following section describes the mandatory and optional test suite
+ functions that <c>Common Test</c> calls during test execution.
+ For more details, see section
+ <seealso marker="write_test_chapter">Writing Test Suites</seealso>
+ in the User's Guide.</p>
+
</description>
<section>
- <title>TEST CASE CALLBACK FUNCTIONS</title>
+ <title>Test Case Callback Functions</title>
<p>The following functions define the callback interface
for a test suite.</p>
</section>
-
+
<funcs>
<func>
<name>Module:all() -> Tests | {skip,Reason} </name>
<fsummary>Returns the list of all test case groups and test cases
in the module.</fsummary>
<type>
- <v>Tests = [TestCase | {group,GroupName} |
- {group,GroupName,Properties} |
- {group,GroupName,Properties,SubGroups}]</v>
+ <v>Tests = [TestCase | {group,GroupName} | {group,GroupName,Properties} | {group,GroupName,Properties,SubGroups}]</v>
<v>TestCase = atom()</v>
<v>GroupName = atom()</v>
- <v>Properties = [parallel | sequence | Shuffle | {RepeatType,N}] |
- default</v>
- <v>SubGroups = [{GroupName,Properties} |
- {GroupName,Properties,SubGroups}]</v>
+ <v>Properties = [parallel | sequence | Shuffle | {RepeatType,N}] | default</v>
+ <v>SubGroups = [{GroupName,Properties} | {GroupName,Properties,SubGroups}]</v>
<v>Shuffle = shuffle | {shuffle,Seed}</v>
<v>Seed = {integer(),integer(),integer()}</v>
- <v>RepeatType = repeat | repeat_until_all_ok | repeat_until_all_fail |
- repeat_until_any_ok | repeat_until_any_fail</v>
+ <v>RepeatType = repeat | repeat_until_all_ok | repeat_until_all_fail | repeat_until_any_ok | repeat_until_any_fail</v>
<v>N = integer() | forever</v>
<v>Reason = term()</v>
</type>
-
+
<desc>
- <p> MANDATORY </p>
-
- <p>This function must return the list of all test cases and test
- case groups in the test suite module that are to be executed.
- This list also specifies the order the cases and groups will
- be executed by Common Test. A test case is represented by an atom,
+ <p>MANDATORY</p>
+
+ <p>Returns the list of all test cases and test case groups in the
+ test suite module to be executed. This list also specifies the
+ order the cases and groups are executed by <c>Common Test</c>.
+ A test case is represented by an atom,
the name of the test case function. A test case group is
represented by a <c>group</c> tuple, where <c>GroupName</c>,
- an atom, is the name of the group (defined in <seealso marker="#Module:groups-0"><c>groups/0</c></seealso>).
- Execution properties for groups may also be specified, both
- for a top level group and for any of its sub-groups.
- Group execution properties specified here, will override
- properties in the group definition (see <seealso marker="#Module:groups-0"><c>groups/0</c></seealso>).
+ an atom, is the name of the group (defined in
+ <seealso marker="#Module:groups-0"><c>groups/0</c></seealso>).
+ Execution properties for groups can also be specified, both
+ for a top-level group and for any of its subgroups.
+ Group execution properties specified here override
+ properties in the group definition (see
+ <seealso marker="#Module:groups-0"><c>groups/0</c></seealso>).
(With value <c>default</c>, the group definition properties
- will be used).</p>
-
- <p> If <c>{skip,Reason}</c> is returned, all test cases
- in the module will be skipped, and the <c>Reason</c> will
- be printed on the HTML result page.</p>
-
- <p>For details on groups, see
- <seealso marker="write_test_chapter#test_case_groups">Test case
- groups</seealso> in the User's Guide.</p>
-
+ are used).</p>
+
+ <p>If <c>{skip,Reason}</c> is returned, all test cases
+ in the module are skipped and <c>Reason</c>
+ is printed on the HTML result page.</p>
+
+ <p>For details on groups, see section
+ <seealso marker="write_test_chapter#test_case_groups">Test Case
+ Groups</seealso> in the User's Guide.</p>
+
</desc>
</func>
@@ -123,25 +118,24 @@
<name>Module:groups() -> GroupDefs</name>
<fsummary>Returns a list of test case group definitions.</fsummary>
<type>
- <v>GroupDefs = [Group]</v>
- <v>Group = {GroupName,Properties,GroupsAndTestCases}</v>
- <v>GroupName = atom()</v>
- <v>Properties = [parallel | sequence | Shuffle | {RepeatType,N}]</v>
- <v>GroupsAndTestCases = [Group | {group,GroupName} | TestCase]</v>
- <v>TestCase = atom()</v>
- <v>Shuffle = shuffle | {shuffle,Seed}</v>
- <v>Seed = {integer(),integer(),integer()}</v>
- <v>RepeatType = repeat | repeat_until_all_ok | repeat_until_all_fail |
- repeat_until_any_ok | repeat_until_any_fail</v>
- <v>N = integer() | forever</v>
+ <v>GroupDefs = [Group]</v>
+ <v>Group = {GroupName,Properties,GroupsAndTestCases}</v>
+ <v>GroupName = atom()</v>
+ <v>Properties = [parallel | sequence | Shuffle | {RepeatType,N}]</v>
+ <v>GroupsAndTestCases = [Group | {group,GroupName} | TestCase]</v>
+ <v>TestCase = atom()</v>
+ <v>Shuffle = shuffle | {shuffle,Seed}</v>
+ <v>Seed = {integer(),integer(),integer()}</v>
+ <v>RepeatType = repeat | repeat_until_all_ok | repeat_until_all_fail | repeat_until_any_ok | repeat_until_any_fail</v>
+ <v>N = integer() | forever</v>
</type>
-
+
<desc>
- <p> OPTIONAL </p>
-
- <p>Function for defining test case groups. Please see
- <seealso marker="write_test_chapter#test_case_groups">Test case
- groups</seealso> in the User's Guide for details.</p>
+ <p>OPTIONAL</p>
+
+ <p>Defines test case groups. For details, see section
+ <seealso marker="write_test_chapter#test_case_groups">Test Case
+ Groups</seealso> in the User's Guide.</p>
</desc>
</func>
@@ -150,75 +144,71 @@
<fsummary>Test suite info function (providing default data
for the suite).</fsummary>
<type>
- <v> Info = {timetrap,Time} | {require,Required} |
- {require,Name,Required} | {userdata,UserData} |
- {silent_connections,Conns} | {stylesheet,CSSFile} |
- {ct_hooks, CTHs}</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} | {Key,SubKey} | {Key,SubKey,SubKeys}</v>
- <v> Key = atom()</v>
- <v> SubKeys = SubKey | [SubKey]</v>
- <v> SubKey = atom()</v>
- <v> Name = atom()</v>
- <v> UserData = term()</v>
- <v> Conns = [atom()]</v>
- <v> CSSFile = string()</v>
- <v> CTHs = [CTHModule |</v>
- <v>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{CTHModule, CTHInitArgs} |</v>
- <v>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{CTHModule, CTHInitArgs, CTHPriority}]</v>
- <v> CTHModule = atom()</v>
- <v> CTHInitArgs = term()</v>
+ <v>Info = {timetrap,Time} | {require,Required} | {require,Name,Required} | {userdata,UserData} | {silent_connections,Conns} | {stylesheet,CSSFile} | {ct_hooks, CTHs}</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} | {Key,SubKey} | {Key,SubKey,SubKeys}</v>
+ <v>Key = atom()</v>
+ <v>SubKeys = SubKey | [SubKey]</v>
+ <v>SubKey = atom()</v>
+ <v>Name = atom()</v>
+ <v>UserData = term()</v>
+ <v>Conns = [atom()]</v>
+ <v>CSSFile = string()</v>
+ <v>CTHs = [CTHModule |</v>
+ <v>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{CTHModule, CTHInitArgs} |</v>
+ <v>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{CTHModule, CTHInitArgs, CTHPriority}]</v>
+ <v>CTHModule = atom()</v>
+ <v>CTHInitArgs = term()</v>
</type>
<desc>
-
- <p> OPTIONAL </p>
-
- <p>This is the test suite info function. It is supposed to
- return a list of tagged tuples that specify various properties
- related to the execution of this test suite (common for all
- test cases in the suite).</p>
-
- <p>The <c>timetrap</c> tag sets the maximum time each
- test case is allowed to execute (including <seealso marker="#Module:init_per_testcase-2"><c>init_per_testcase/2</c></seealso>
- and <seealso marker="#Module:end_per_testcase-2"><c>end_per_testcase/2</c></seealso>). If the timetrap time is
- exceeded, the test case fails with reason
+
+ <p>OPTIONAL</p>
+
+ <p>The test suite information function. Returns a list of tagged
+ tuples specifying various properties related to the execution of
+ this test suite (common for all test cases in the suite).</p>
+
+ <p>Tag <c>timetrap</c> sets the maximum time that each
+ test case is allowed to execute (including
+ <seealso marker="#Module:init_per_testcase-2"><c>init_per_testcase/2</c></seealso>
+ and
+ <seealso marker="#Module:end_per_testcase-2"><c>end_per_testcase/2</c></seealso>).
+ If the timetrap time is exceeded, the test case fails with reason
<c>timetrap_timeout</c>. A <c>TimeFunc</c> function can be used to
- set a new timetrap by returning a <c>TimeVal</c>. It may also be
- used to trigger a timetrap timeout by, at some point, returning a
- value other than a <c>TimeVal</c>. (See the
- <seealso marker="write_test_chapter#timetraps">User's Guide</seealso>
- for details).
- </p>
-
- <p>The <c>require</c> tag specifies configuration variables
- that are required by test cases (and/or configuration functions)
+ set a new timetrap by returning a <c>TimeVal</c>. It can also be
+ used to trigger a timetrap time-out by, at some point, returning a
+ value other than a <c>TimeVal</c>. For details, see section
+ <seealso marker="write_test_chapter#timetraps">Timetrap Time-Outs</seealso>
+ in the User's Guide.</p>
+
+ <p>Tag <c>require</c> specifies configuration variables
+ required by test cases (or configuration functions)
in the suite. If the required configuration variables are not found
- in any of the configuration files, all test cases are skipped. For more
- information about the 'require' functionality, see the
- reference manual for the function
- <seealso marker="ct#require-1"><c>ct:require/1/2</c></seealso>.</p>
+ in any of the configuration files, all test cases are skipped.
+ For details about the <c>require</c> functionality, see funtion
+ <seealso marker="ct#require-1"><c>ct:require/1,2</c></seealso>.</p>
- <p>With <c>userdata</c>, it is possible for the user to
- specify arbitrary test suite related information which can be
- read by calling <seealso marker="ct#userdata-2"><c>ct:userdata/2</c></seealso>.</p>
+ <p>With <c>userdata</c>, the user can
+ specify any test suite-related information, which can be
+ read by calling
+ <seealso marker="ct#userdata-2"><c>ct:userdata/2</c></seealso>.</p>
- <p>The <c>ct_hooks</c> tag specifies which
+ <p>Tag <c>ct_hooks</c> specifies the
<seealso marker="ct_hooks_chapter">Common Test Hooks</seealso>
- are to be run together with this suite.</p>
-
- <p>Other tuples than the ones defined will simply be ignored.</p>
+ to be run with this suite.</p>
- <p>For more information about the test suite info function,
- see <seealso marker="write_test_chapter#suite">Test
- suite info function</seealso> in the User's Guide.</p>
+ <p>Other tuples than the ones defined are ignored.</p>
+
+ <p>For details about the test suite information function, see section
+ <seealso marker="write_test_chapter#suite">Test
+ Suite Information Function</seealso> in the User's Guide.</p>
</desc>
</func>
@@ -227,129 +217,133 @@
{skip_and_save,Reason,SaveConfig}</name>
<fsummary>Test suite initializations.</fsummary>
<type>
- <v> Config = NewConfig = SaveConfig = [{Key,Value}]</v>
- <v> Key = atom()</v>
- <v> Value = term()</v>
- <v> Reason = term()</v>
+ <v>Config = NewConfig = SaveConfig = [{Key,Value}]</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
<desc>
-
- <p> OPTIONAL </p>
-
+
+ <p>OPTIONAL</p>
+
<p>This configuration function is called as the first function in the
- suite. It typically contains initializations which are common for
- all test cases in the suite, and which shall only be done
- once. The <c>Config</c> parameter is the configuration data
- which can be modified here. Whatever is returned from this
- function is given as <c>Config</c> to all configuration functions
- and test cases in the suite. If <c>{skip,Reason}</c>
- is returned, all test cases in the suite will be skipped
- and <c>Reason</c> printed in the overview log for the suite.</p>
- <p>For information on <c>save_config</c> and <c>skip_and_save</c>,
- please see
- <seealso marker="dependencies_chapter#save_config">Dependencies
- between Test Cases and Suites</seealso> in the User's Guide.</p>
- </desc>
+ suite. It typically contains initializations that are common for
+ all test cases in the suite, and that must only be done
+ once. Parameter <c>Config</c> is the configuration data
+ that can be modified. Whatever is returned from this
+ function is specified as <c>Config</c> to all configuration functions
+ and test cases in the suite.</p>
+
+ <p>If <c>{skip,Reason}</c>
+ is returned, all test cases in the suite are skipped
+ and <c>Reason</c> is printed in the overview log for the suite.</p>
+
+ <p>For information on <c>save_config</c> and <c>skip_and_save</c>,
+ see section
+ <seealso marker="dependencies_chapter#save_config">Saving
+ Configuration Data</seealso> in the User's Guide.</p>
+ </desc>
</func>
-
+
<func>
<name>Module:end_per_suite(Config) -> term() |
{save_config,SaveConfig}</name>
- <fsummary>Test suite finalization. </fsummary>
+ <fsummary>Test suite finalization.</fsummary>
<type>
- <v> Config = SaveConfig = [{Key,Value}]</v>
- <v> Key = atom()</v>
- <v> Value = term()</v>
+ <v>Config = SaveConfig = [{Key,Value}]</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
</type>
-
+
<desc>
- <p> OPTIONAL </p>
+ <p>OPTIONAL</p>
<p>This function is called as the last test case in the
suite. It is meant to be used for cleaning up after
- <seealso marker="#Module:init_per_suite-1"><c>init_per_suite/1</c></seealso>.
- For information on <c>save_config</c>, please see
- <seealso marker="dependencies_chapter#save_config">Dependencies
- between Test Cases and Suites</seealso> in the User's Guide.</p>
+ <seealso marker="#Module:init_per_suite-1"><c>init_per_suite/1</c></seealso>.</p>
+ <p>For information on <c>save_config</c>, see section
+ <seealso marker="dependencies_chapter#save_config">Saving
+ Configuration Data</seealso> in the User's Guide.</p>
</desc>
</func>
<func>
<name>Module:group(GroupName) -> [Info] </name>
- <fsummary>Test case group info function (providing default data
- for a test case group, i.e. its test cases and sub-groups).</fsummary>
+ <fsummary>Test case group information function (providing default data
+ for a test case group, that is, its test cases and
+ subgroups).</fsummary>
<type>
- <v> Info = {timetrap,Time} | {require,Required} |
- {require,Name,Required} | {userdata,UserData} |
- {silent_connections,Conns} | {stylesheet,CSSFile} |
- {ct_hooks, CTHs}</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} | {Key,Subkey} | {Key,Subkey,SubKeys}</v>
- <v> Key = atom()</v>
- <v> SubKeys = SubKey | [SubKey]</v>
- <v> SubKey = atom()</v>
- <v> Name = atom()</v>
- <v> UserData = term()</v>
- <v> Conns = [atom()]</v>
- <v> CSSFile = string()</v>
- <v> CTHs = [CTHModule |</v>
- <v> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{CTHModule, CTHInitArgs} |</v>
- <v> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{CTHModule, CTHInitArgs, CTHPriority}]</v>
- <v> CTHModule = atom()</v>
- <v> CTHInitArgs = term()</v>
- </type>
- <desc>
-
- <p> OPTIONAL </p>
-
- <p>This is the test case group info function. It is supposed to
+ <v>Info = {timetrap,Time} | {require,Required} | {require,Name,Required} | {userdata,UserData} | {silent_connections,Conns} | {stylesheet,CSSFile} | {ct_hooks, CTHs}</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} | {Key,Subkey} | {Key,Subkey,SubKeys}</v>
+ <v>Key = atom()</v>
+ <v>SubKeys = SubKey | [SubKey]</v>
+ <v>SubKey = atom()</v>
+ <v>Name = atom()</v>
+ <v>UserData = term()</v>
+ <v>Conns = [atom()]</v>
+ <v>CSSFile = string()</v>
+ <v>CTHs = [CTHModule |</v>
+ <v>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{CTHModule, CTHInitArgs} |</v>
+ <v>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;{CTHModule, CTHInitArgs, CTHPriority}]</v>
+ <v>CTHModule = atom()</v>
+ <v>CTHInitArgs = term()</v>
+ </type>
+ <desc>
+
+ <p>OPTIONAL</p>
+
+ <p>The test case group information function. It is supposed to
return a list of tagged tuples that specify various properties
- related to the execution of a test case group (i.e. its test cases
- and sub-groups). Properties set by
+ related to the execution of a test case group (that is, its test
+ cases and subgroups). Properties set by
<seealso marker="#Module:group-1"><c>group/1</c></seealso> override
- properties with the same key that have been previously set by
+ properties with the same key that have been set previously by
<seealso marker="#Module:suite-0"><c>suite/0</c></seealso>.</p>
- <p>The <c>timetrap</c> tag sets the maximum time each
- test case is allowed to execute (including <seealso marker="#Module:init_per_testcase-2"><c>init_per_testcase/2</c></seealso>
- and <seealso marker="#Module:end_per_testcase-2"><c>end_per_testcase/2</c></seealso>). If the timetrap time is
+ <p>Tag <c>timetrap</c> sets the maximum time that each
+ test case is allowed to execute (including
+ <seealso marker="#Module:init_per_testcase-2"><c>init_per_testcase/2</c></seealso>
+ and
+ <seealso marker="#Module:end_per_testcase-2"><c>end_per_testcase/2</c></seealso>).
+ If the timetrap time is
exceeded, the test case fails with reason
<c>timetrap_timeout</c>. A <c>TimeFunc</c> function can be used to
- set a new timetrap by returning a <c>TimeVal</c>. It may also be
- used to trigger a timetrap timeout by, at some point, returning a
- value other than a <c>TimeVal</c>. (See the
- <seealso marker="write_test_chapter#timetraps">User's Guide</seealso>
- for details).</p>
+ set a new timetrap by returning a <c>TimeVal</c>. It can also be
+ used to trigger a timetrap time-out by, at some point, returning a
+ value other than a <c>TimeVal</c>. For details, see section
+ <seealso marker="write_test_chapter#timetraps">Timetrap
+ Time-Outs</seealso> in the User's Guide.</p>
- <p>The <c>require</c> tag specifies configuration variables
- that are required by test cases (and/or configuration functions)
+ <p>Tag <c>require</c> specifies configuration variables
+ required by test cases (or configuration functions)
in the suite. If the required configuration variables are not found
- in any of the configuration files, all test cases in this group are skipped.
- For more information about the 'require' functionality, see the
- reference manual for the function
- <seealso marker="ct#require-1"><c>ct:require/1/2</c></seealso>.</p>
+ in any of the configuration files, all test cases in this group are
+ skipped. For details about the <c>require</c> functionality, see
+ function
+ <seealso marker="ct#require-1"><c>ct:require/1,2</c></seealso>.</p>
- <p>With <c>userdata</c>, it is possible for the user to
- specify arbitrary test case group related information which can be
- read by calling <seealso marker="ct#userdata-2"><c>ct:userdata/2</c></seealso>.</p>
+ <p>With <c>userdata</c>, the user can
+ specify any test case group related information that can be
+ read by calling
+ <seealso marker="ct#userdata-2"><c>ct:userdata/2</c></seealso>.</p>
- <p>The <c>ct_hooks</c> tag specifies which
+ <p>Tag <c>ct_hooks</c> specifies the
<seealso marker="ct_hooks_chapter">Common Test Hooks</seealso>
- are to be run together with this suite.</p>
-
- <p>Other tuples than the ones defined will simply be ignored.</p>
+ to be run with this suite.</p>
- <p>For more information about the test case group info function,
- see <seealso marker="write_test_chapter#suite">Test
- case group info function</seealso> in the User's Guide.</p>
+ <p>Other tuples than the ones defined are ignored.</p>
+
+ <p>For details about the test case group information function,
+ see section <seealso marker="write_test_chapter#group_info">Group
+ Information Function</seealso> in the User's Guide.</p>
</desc>
</func>
@@ -358,59 +352,66 @@
{skip,Reason}</name>
<fsummary>Test case group initializations.</fsummary>
<type>
- <v> GroupName = atom()</v>
- <v> Config = NewConfig = [{Key,Value}]</v>
- <v> Key = atom()</v>
- <v> Value = term()</v>
- <v> Reason = term()</v>
+ <v>GroupName = atom()</v>
+ <v>Config = NewConfig = [{Key,Value}]</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
<desc>
-
- <p> OPTIONAL </p>
-
+
+ <p>OPTIONAL</p>
+
<p>This configuration function is called before execution of a
- test case group. It typically contains initializations which are
- common for all test cases and sub-groups in the group, and which
- shall only be performed once. <c>GroupName</c> is the name of the
- group, as specified in the group definition (see <seealso marker="#Module:groups-0"><c>groups/0</c></seealso>). The
- <c>Config</c> parameter is the configuration data which can be modified
- here. The return value of this function is given as <c>Config</c>
- to all test cases and sub-groups in the group. If <c>{skip,Reason}</c>
- is returned, all test cases in the group will be skipped and
- <c>Reason</c> printed in the overview log for the group.</p>
-
- <p>For information about test case groups, please see
- <seealso marker="write_test_chapter#test_case_groups">Test case
- groups</seealso> chapter in the User's Guide.</p>
+ test case group. It typically contains initializations that are
+ common for all test cases and subgroups in the group, and that
+ must only be performed once. <c>GroupName</c> is the name of the
+ group, as specified in the group definition (see
+ <seealso marker="#Module:groups-0"><c>groups/0</c></seealso>).
+ Parameter <c>Config</c> is the configuration data that can be
+ modified.
+ The return value of this function is given as <c>Config</c>
+ to all test cases and subgroups in the group.</p>
+
+ <p>If <c>{skip,Reason}</c>
+ is returned, all test cases in the group are skipped and
+ <c>Reason</c> is printed in the overview log for the group.</p>
+
+ <p>For information about test case groups, see section
+ <seealso marker="write_test_chapter#test_case_groups">Test Case
+ Groups</seealso> in the User's Guide.</p>
</desc>
</func>
-
+
<func>
<name>Module:end_per_group(GroupName, Config) -> term() |
{return_group_result,Status}</name>
<fsummary>Test case group finalization.</fsummary>
<type>
- <v> GroupName = atom()</v>
- <v> Config = [{Key,Value}]</v>
- <v> Key = atom()</v>
- <v> Value = term()</v>
- <v> Status = ok | skipped | failed</v>
+ <v>GroupName = atom()</v>
+ <v>Config = [{Key,Value}]</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Status = ok | skipped | failed</v>
</type>
-
+
<desc>
- <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 <seealso marker="#Module:init_per_group-2"><c>init_per_group/2</c></seealso>.
- By means of <c>{return_group_result,Status}</c>, it is possible to return a
- status value for a nested sub-group. The status can be retrieved in
- <seealso marker="#Module:end_per_group-2"><c>end_per_group/2</c></seealso> for the group on the level above. The status will also
- be used by Common Test for deciding if execution of a group should proceed in
- case the property <c>sequence</c> or <c>repeat_until_*</c> is set.</p>
-
- <p>For more information about test case groups, please see
- <seealso marker="write_test_chapter#test_case_groups">Test case
- groups</seealso> chapter in the User's Guide.</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
+ <seealso marker="#Module:init_per_group-2"><c>init_per_group/2</c></seealso>.
+ A status value for a nested subgroup can be returned with
+ <c>{return_group_result,Status}</c>. The status can be retrieved in
+ <seealso marker="#Module:end_per_group-2"><c>end_per_group/2</c></seealso>
+ for the group on the level above. The status is also used by
+ <c>Common Test</c> for deciding if execution of a group is to
+ proceed if property <c>sequence</c> or <c>repeat_until_*</c>
+ is set.</p>
+
+ <p>For details about test case groups, see section
+ <seealso marker="write_test_chapter#test_case_groups">Test Case
+ Groups</seealso> in the User's Guide.</p>
</desc>
</func>
@@ -424,168 +425,173 @@
<v> Value = term()</v>
<v> Reason = term()</v>
</type>
- <desc>
-
+ <desc>
+
<p>OPTIONAL</p>
-
- <p>This function is called before each test case. The
- <c>TestCase</c> argument is the name of the test case, and
+
+ <p>This function is called before each test case. Argument
+ <c>TestCase</c> is the test case name, and
<c>Config</c> (list of key-value tuples) is the configuration
- data that can be modified here. The <c>NewConfig</c> list returned
+ data that can be modified. The <c>NewConfig</c> list returned
from this function is given as <c>Config</c> to the test case.
If <c>{fail,Reason}</c> is returned, the test case is
- marked as failed without being executed. If <c>{skip,Reason}</c> is
- returned, the test case will be skipped and <c>Reason</c> printed
- in the overview log for the suite.</p>
+ marked as failed without being executed.</p>
+
+ <p>If <c>{skip,Reason}</c> is returned, the test case is skipped
+ and <c>Reason</c> is printed in the overview log for the suite.</p>
</desc>
</func>
-
+
<func>
<name>Module:end_per_testcase(TestCase, Config) -> term() | {fail,Reason} | {save_config,SaveConfig}</name>
<fsummary>Test case finalization.</fsummary>
<type>
- <v> TestCase = atom()</v>
- <v> Config = SaveConfig = [{Key,Value}]</v>
- <v> Key = atom()</v>
- <v> Value = term()</v>
- <v> Reason = term()</v>
+ <v>TestCase = atom()</v>
+ <v>Config = SaveConfig = [{Key,Value}]</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
<desc>
-
- <p> OPTIONAL </p>
-
- <p> This function is called after each test case, and can be used
- to clean up after <seealso marker="#Module:init_per_testcase-2"><c>init_per_testcase/2</c></seealso> and the test case.
- Any return value (besides <c>{fail,Reason}</c> and <c>{save_config,SaveConfig}</c>)
- is ignored. By returning <c>{fail,Reason}</c>, <c>TestCase</c> will be marked as
- failed (even though it was actually successful in the sense that it returned
- a value instead of terminating). For information on <c>save_config</c>, please see
- <seealso marker="dependencies_chapter#save_config">Dependencies between
- Test Cases and Suites</seealso> in the User's Guide</p>
+
+ <p>OPTIONAL</p>
+
+ <p>This function is called after each test case, and can be used
+ to clean up after
+ <seealso marker="#Module:init_per_testcase-2"><c>init_per_testcase/2</c></seealso>
+ and the test case. Any return value (besides <c>{fail,Reason}</c>
+ and <c>{save_config,SaveConfig}</c>) is ignored. By returning
+ <c>{fail,Reason}</c>, <c>TestCase</c> is marked as faulty (even
+ though it was successful in the sense that it returned
+ a value instead of terminating).</p>
+
+ <p>For information on <c>save_config</c>, see section
+ <seealso marker="dependencies_chapter#save_config">Saving
+ Configuration Data</seealso> in the User's Guide.</p>
</desc>
</func>
-
+
<func>
<name>Module:Testcase() -> [Info] </name>
- <fsummary>Test case info function. </fsummary>
+ <fsummary>Test case information function.</fsummary>
<type>
- <v> Info = {timetrap,Time} | {require,Required} |
- {require,Name,Required} | {userdata,UserData} |
- {silent_connections,Conns}</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} | {Key,Subkey} | {Key,Subkey,SubKeys}</v>
- <v> Key = atom()</v>
- <v> SubKeys = SubKey | [SubKey]</v>
- <v> SubKey = atom()</v>
- <v> Name = atom()</v>
- <v> UserData = term()</v>
- <v> Conns = [atom()]</v>
+ <v>Info = {timetrap,Time} | {require,Required} | {require,Name,Required} | {userdata,UserData} | {silent_connections,Conns}</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} | {Key,Subkey} | {Key,Subkey,SubKeys}</v>
+ <v>Key = atom()</v>
+ <v>SubKeys = SubKey | [SubKey]</v>
+ <v>SubKey = atom()</v>
+ <v>Name = atom()</v>
+ <v>UserData = term()</v>
+ <v>Conns = [atom()]</v>
</type>
-
- <desc>
+
+ <desc>
<p>OPTIONAL</p>
-
- <p>This is the test case info function. It is supposed to
+
+ <p>The test case information function. It is supposed to
return a list of tagged tuples that specify various properties
related to the execution of this particular test case.
- Properties set by <seealso marker="#Module:Testcase-0"><c>Testcase/0</c></seealso> override
- properties that have been previously set for the test case
- by <seealso marker="#Module:group-1"><c>group/1</c></seealso> or <seealso marker="#Module:suite-0"><c>suite/0</c></seealso>.</p>
-
- <p>The <c>timetrap</c> tag sets the maximum time the
+ Properties set by
+ <seealso marker="#Module:Testcase-0"><c>Testcase/0</c></seealso>
+ override properties set previously for the test case by
+ <seealso marker="#Module:group-1"><c>group/1</c></seealso> or
+ <seealso marker="#Module:suite-0"><c>suite/0</c></seealso>.</p>
+
+ <p>Tag <c>timetrap</c> sets the maximum time that the
test case is allowed to execute. If the timetrap time is
- exceeded, the test case fails with reason
- <c>timetrap_timeout</c>. <seealso marker="#Module:init_per_testcase-2"><c>init_per_testcase/2</c></seealso>
- and <seealso marker="#Module:end_per_testcase-2"><c>end_per_testcase/2</c></seealso> are included in the
- timetrap time. A <c>TimeFunc</c> function can be used to
- set a new timetrap by returning a <c>TimeVal</c>. It may also be
- used to trigger a timetrap timeout by, at some point, returning a
- value other than a <c>TimeVal</c>. (See the
- <seealso marker="write_test_chapter#timetraps">User's Guide</seealso>
- for details).</p>
+ exceeded, the test case fails with reason <c>timetrap_timeout</c>.
+ <seealso marker="#Module:init_per_testcase-2"><c>init_per_testcase/2</c></seealso>
+ and
+ <seealso marker="#Module:end_per_testcase-2"><c>end_per_testcase/2</c></seealso>
+ are included in the timetrap time.
+ A <c>TimeFunc</c> function can be used to
+ set a new timetrap by returning a <c>TimeVal</c>. It can also be
+ used to trigger a timetrap time-out by, at some point, returning a
+ value other than a <c>TimeVal</c>. For details, see section
+ <seealso marker="write_test_chapter#timetraps">Timetrap
+ Time-Outs</seealso> in the User's Guide.</p>
- <p>The <c>require</c> tag specifies configuration variables
- that are required by the test case (and/or <c>init/end_per_testcase/2</c>).
+ <p>Tag <c>require</c> specifies configuration variables
+ that are required by the test case (or <c>init_per_testcase/2</c>
+ or <c>end_per_testcase/2</c>).
If the required configuration variables are not found in any of the
- configuration files, the test case is skipped. For more
- information about the 'require' functionality, see the
- reference manual for the function
- <seealso marker="ct#require-1"><c>ct:require/1/2</c></seealso>.</p>
-
- <p>If <c>timetrap</c> and/or <c>require</c> is not set, the
- default values specified by <seealso marker="#Module:suite-0"><c>suite/0</c></seealso> (or
- <seealso marker="#Module:group-1"><c>group/1</c></seealso>) will be used.</p>
-
- <p>With <c>userdata</c>, it is possible for the user to
- specify arbitrary test case related information which can be
- read by calling <seealso marker="ct#userdata-3"><c>ct:userdata/3</c></seealso>.</p>
-
- <p>Other tuples than the ones defined will simply be ignored.</p>
+ configuration files, the test case is skipped. For details about
+ the <c>require</c> functionality, see function
+ <seealso marker="ct#require-1"><c>ct:require/1,2</c></seealso>.</p>
+
+ <p>If <c>timetrap</c> or <c>require</c> is not set, the
+ default values specified by
+ <seealso marker="#Module:suite-0"><c>suite/0</c></seealso> (or
+ <seealso marker="#Module:group-1"><c>group/1</c></seealso>) are used.</p>
+
+ <p>With <c>userdata</c>, the user can specify any test case-related
+ information that can be read by calling
+ <seealso marker="ct#userdata-3"><c>ct:userdata/3</c></seealso>.</p>
+
+ <p>Other tuples than the ones defined are ignored.</p>
- <p>For more information about the test case info function,
- see <seealso marker="write_test_chapter#info_function">Test
- case info function</seealso> in the User's Guide.</p>
+ <p>For details about the test case information function, see section
+ <seealso marker="write_test_chapter#info_function">Test
+ Case Information Function</seealso> in the User's Guide.</p>
</desc>
</func>
-
-
+
<func>
<name>Module:Testcase(Config) -> term() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit() </name>
- <fsummary>A test case</fsummary>
+ <fsummary>A test case.</fsummary>
<type>
- <v> Config = SaveConfig = [{Key,Value}]</v>
- <v> Key = atom()</v>
- <v> Value = term()</v>
- <v> Reason = term()</v>
- <v> Comment = string()</v>
+ <v>Config = SaveConfig = [{Key,Value}]</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
+ <v>Comment = string()</v>
</type>
-
+
<desc>
- <p> MANDATORY </p>
-
- <p>This is the implementation of a test case. Here you must
- call the functions you want to test, and do whatever you
- need to check the result. If something fails, make sure the
- function causes a runtime error, or call <seealso marker="ct#fail-1"><c>ct:fail/1/2</c></seealso>
+ <p>MANDATORY</p>
+
+ <p>The implementation of a test case. Call the functions to test and
+ check the result. If something fails, ensure the
+ function causes a runtime error or call
+ <seealso marker="ct#fail-1"><c>ct:fail/1,2</c></seealso>
(which also causes the test case process to terminate).</p>
-
- <p>Elements from the <c>Config</c> list can e.g. be read
- with <c>proplists:get_value/2</c> (or the macro <c>?config</c>
- defined in <c>ct.hrl</c>).</p>
- <p>You can return <c>{skip,Reason}</c> if you decide not to
- run the test case after all. <c>Reason</c> will then be
- printed in 'Comment' field on the HTML result page.</p>
-
- <p>You can return <c>{comment,Comment}</c> if you wish to
- print some information in the 'Comment' field on the HTML
- result page.</p>
-
- <p>If the function returns anything else, the test case is
- considered successful. (The return value always gets printed
- in the test case log file).</p>
+ <p>Elements from the <c>Config</c> list can, for example, be read
+ with <c>proplists:get_value/2</c> in <c>STDLIB</c>
+ (or the macro <c>?config</c> defined in <c>ct.hrl</c>).</p>
+
+ <p>If you decide not to run the test case after all, return
+ <c>{skip,Reason}</c>. <c>Reason</c> is then
+ printed in field <c>Comment</c> on the HTML result page.</p>
+
+ <p>To print some information in field <c>Comment</c> on the HTML
+ result page, return <c>{comment,Comment}</c>.</p>
- <p>For more information about test case implementation, please
- see <seealso marker="write_test_chapter#test_cases">Test
- cases</seealso> in the User's Guide.</p>
+ <p>If the function returns anything else, the test case is
+ considered successful. The return value always gets printed
+ in the test case log file.</p>
- <p>For information on <c>save_config</c> and <c>skip_and_save</c>, please see
- <seealso marker="dependencies_chapter#save_config">Dependencies between
- Test Cases and Suites</seealso> in the User's Guide.</p>
+ <p>For details about test case implementation, see section
+ <seealso marker="write_test_chapter#test_cases">Test Cases</seealso>
+ in the User's Guide.</p>
+
+ <p>For information on <c>save_config</c> and <c>skip_and_save</c>,
+ see section
+ <seealso marker="dependencies_chapter#save_config">Saving
+ Configuration Data</seealso> in the User's Guide.</p>
</desc>
</func>
-
+
</funcs>
</erlref>
-