aboutsummaryrefslogtreecommitdiffstats
path: root/lib/common_test/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'lib/common_test/doc/src')
-rw-r--r--lib/common_test/doc/src/common_test_app.xml11
-rw-r--r--lib/common_test/doc/src/ct_hooks_chapter.xml43
-rw-r--r--lib/common_test/doc/src/ct_run.xml2
-rw-r--r--lib/common_test/doc/src/notes.xml144
-rw-r--r--lib/common_test/doc/src/run_test_chapter.xml202
-rw-r--r--lib/common_test/doc/src/write_test_chapter.xml52
6 files changed, 390 insertions, 64 deletions
diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml
index b6d4a633cb..151159ad69 100644
--- a/lib/common_test/doc/src/common_test_app.xml
+++ b/lib/common_test/doc/src/common_test_app.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>2003</year><year>2012</year>
+ <year>2003</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -170,7 +170,9 @@
<v> UserData = term()</v>
<v> Conns = [atom()]</v>
<v> CSSFile = string()</v>
- <v> CTHs = [CTHModule | {CTHModule, CTHInitArgs} | {CTHModule, CTHInitArgs, CTHPriority}]</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>
@@ -297,8 +299,9 @@
<v> UserData = term()</v>
<v> Conns = [atom()]</v>
<v> CSSFile = string()</v>
- <v> CTHs = [CTHModule | {CTHModule, CTHInitArgs} |
- {CTHModule, CTHInitArgs, CTHPriority}]</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>
diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml
index 86237f5fc1..fe871eb516 100644
--- a/lib/common_test/doc/src/ct_hooks_chapter.xml
+++ b/lib/common_test/doc/src/ct_hooks_chapter.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2011</year><year>2012</year>
+ <year>2011</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -439,14 +439,14 @@ terminate(State) ->
<table>
<row>
- <cell><em>CTH Name</em></cell>
- <cell><em>Is Built-in</em></cell>
- <cell><em>Description</em></cell>
+ <cell align="left"><em>CTH Name</em></cell>
+ <cell align="left"><em>Is Built-in</em></cell>
+ <cell align="left"><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
+ <cell align="left">cth_log_redirect</cell>
+ <cell align="left">yes</cell>
+ <cell align="left">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
@@ -455,14 +455,29 @@ terminate(State) ->
using the normal SASL mechanisms. </cell>
</row>
<row>
- <cell>cth_surefire</cell>
- <cell>no</cell>
- <cell>Captures all test results and outputs them as surefire XML into
- a file. The file which is created is by default called junit_report.xml.
- The name can be by setting the path option for this hook. e.g.
+ <cell align="left">cth_surefire</cell>
+ <cell align="left">no</cell>
+ <cell align="left"><p>Captures all test results and outputs them as surefire
+ XML into a file. The file which is created is by default
+ called junit_report.xml. The file name can be changed by
+ setting the <c>path</c> option for this hook, e.g.</p>
+
<code>-ct_hooks cth_surefire [{path,"/tmp/report.xml"}]</code>
- Surefire XML can forinstance be used by Jenkins to display test
- results.</cell>
+
+ <p>If the <c>url_base</c> option is set, an additional
+ attribute named <c>url</c> will be added to each
+ <c>testsuite</c> and <c>testcase</c> XML element. The value will
+ be constructed from the <c>url_base</c> and a relative path
+ to the test suite or test case log respectively, e.g.</p>
+
+ <code>-ct_hooks cth_surefire [{url_base, "http://myserver.com/"}]</code>
+ <p>will give a url attribute value similar to</p>
+
+ <code>"http://myserver.com/[email protected]_11.19.39/
+x86_64-unknown-linux-gnu.my_test.logs/run.2012-12-12_11.19.39/suite.log.html"</code>
+
+ <p>Surefire XML can for instance be used by Jenkins to display test
+ results.</p></cell>
</row>
</table>
diff --git a/lib/common_test/doc/src/ct_run.xml b/lib/common_test/doc/src/ct_run.xml
index da18640df7..0750f560b3 100644
--- a/lib/common_test/doc/src/ct_run.xml
+++ b/lib/common_test/doc/src/ct_run.xml
@@ -90,7 +90,7 @@
<pre>
ct_run [-dir TestDir1 TestDir2 .. TestDirN] |
[[-dir TestDir] -suite Suite1 Suite2 .. SuiteN
- [[-group Group1 Group2 .. GroupN] [-case Case1 Case2 .. CaseN]]]
+ [[-group Groups1 Groups2 .. GroupsN] [-case Case1 Case2 .. CaseN]]]
[-step [config | keep_inactive]]
[-config ConfigFile1 ConfigFile2 .. ConfigFileN]
[-userconfig CallbackModule1 ConfigString1 and CallbackModule2
diff --git a/lib/common_test/doc/src/notes.xml b/lib/common_test/doc/src/notes.xml
index abe8cb2041..8c3b13951d 100644
--- a/lib/common_test/doc/src/notes.xml
+++ b/lib/common_test/doc/src/notes.xml
@@ -32,6 +32,150 @@
<file>notes.xml</file>
</header>
+<section><title>Common_Test 1.6.3.1</title>
+
+ <section><title>Known Bugs and Problems</title>
+ <list>
+ <item>
+ <p>
+ The following corrections/changes are done in the
+ cth_surefire hook:</p>
+ <p>
+ <list> <item> Earlier there would always be a
+ 'properties' element under the 'testsuites' element. This
+ would exist even if there were no 'property' element
+ inside it. This has been changed so if there are no
+ 'property' elements to display, then there will not be a
+ 'properties' element either. </item> <item> The XML file
+ will now (unless other is specified) be stored in the top
+ log directory. Earlier, the default directory would be
+ the current working directory for the erlang node, which
+ would mostly, but not always, be the top log directory.
+ </item> <item> The 'hostname' attribute in the
+ 'testsuite' element would earlier never have the correct
+ value. This has been corrected. </item> <item> The
+ 'errors' attribute in the 'testsuite' element would
+ earlier display the number of failed testcases. This has
+ been changed and will now always have the value 0, while
+ the 'failures' attribute will show the number of failed
+ testcases. </item> <item> A new attribute 'skipped' is
+ added to the 'testsuite' element. This will display the
+ number of skipped testcases. These would earlier be
+ included in the number of failed test cases. </item>
+ <item> The total number of tests displayed by the 'tests'
+ attribute in the 'testsuite' element would earlier
+ include init/end_per_suite and init/end_per_group. This
+ is no longer the case. The 'tests' attribute will now
+ only count "real" test cases. </item> <item> Earlier,
+ auto skipped test cases would have no value in the 'log'
+ attribute. This is now corrected. </item> <item> A new
+ attributes 'log' is added to the 'testsuite' element.
+ </item> <item> A new option named 'url_base' is added for
+ this hook. If this option is used, a new attribute named
+ 'url' will be added to the 'testcase' and 'testsuite'
+ elements. </item> </list></p>
+ <p>
+ Own Id: OTP-10589</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>Common_Test 1.6.3</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ The ct:run_test/1 option 'config' only worked with a
+ single config file, not a list of files. This has been
+ fixed.</p>
+ <p>
+ Own Id: OTP-10495</p>
+ </item>
+ <item>
+ <p>
+ ct_netconfc:close_session sometimes returned
+ {error,closed} because the ssh connection was closed
+ (from the server side) before the rpc-reply was received
+ by the client. This is normal and can not be helped. It
+ has been corrected so the return will be 'ok' in this
+ case. Other error situations will still give
+ {error,Reason}.</p>
+ <p>
+ Own Id: OTP-10510 Aux Id: kunagi-320 [231] </p>
+ </item>
+ <item>
+ <p>
+ ct_netconfc:close_session sometimes returned
+ {error,closed} or (if the connection was named)
+ {error,{process_down,Pid,normal}} because the ssh
+ connection was closed (from the server side) before the
+ rpc-reply was received by the client. This is normal and
+ can not be helped. It has been corrected so the return
+ will be 'ok' in this situation.</p>
+ <p>
+ Own Id: OTP-10570</p>
+ </item>
+ <item>
+ <p>
+ Fix bug where ct:require of same name with same config
+ would return name_in_use.</p>
+ <p>
+ Own Id: OTP-10572</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ A new test case group search functionality has been
+ implemented that makes Common Test search automatically
+ through the group definitions tree (the return value of
+ groups/0) and create tests for all paths of nested groups
+ that match the specification. It also allows for
+ specifying unique paths to sub groups in order to avoid
+ execution of unwanted tests. This new feature can be used
+ whenever starting a test run by means of the ct_run
+ program, the ct:run_test/1 API function, or a Test
+ Specification. Details can be found in the Test Case
+ Group Execution section in the Running Tests chapter.</p>
+ <p>
+ Own Id: OTP-10466 Aux Id: kunagi-276 [187] </p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Known Bugs and Problems</title>
+ <list>
+ <item>
+ <p>
+ Restore Config data if lost when test case fails.</p>
+ <p>
+ Own Id: OTP-10070 Aux Id: kunagi-175 [86] </p>
+ </item>
+ <item>
+ <p>
+ IO server error in test_server.</p>
+ <p>
+ Own Id: OTP-10125 Aux Id: OTP-10101, kunagi-177 [88] </p>
+ </item>
+ <item>
+ <p>
+ Faulty connection handling in common_test.</p>
+ <p>
+ Own Id: OTP-10126 Aux Id: kunagi-178 [89] </p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>Common_Test 1.6.2.1</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 b5b914d506..d5f5d89e05 100644
--- a/lib/common_test/doc/src/run_test_chapter.xml
+++ b/lib/common_test/doc/src/run_test_chapter.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2012</year>
+ <year>2003</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -119,7 +119,7 @@
<item><c><![CDATA[ct_run -userconfig <callbackmodulename> <configfilenames> -suite <suiteswithfullpath>]]></c>
</item>
<item><c><![CDATA[ct_run -config <configfilenames> -suite <suitewithfullpath>
- -group <groupnames> -case <casenames>]]></c></item>
+ -group <groups> -case <casenames>]]></c></item>
</list>
<p>Examples:</p>
<p><c>$ ct_run -config $CFGS/sys1.cfg $CFGS/sys2.cfg -dir $SYS1_TEST $SYS2_TEST</c></p>
@@ -137,6 +137,8 @@
<p><c>$ ct_run -suite ./testdir/x_SUITE ./testdir/y_SUITE</c></p>
+ <p>For more details on <seealso marker="run_test_chapter#group_execution">test case group execution</seealso>, please see below.</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>
@@ -269,6 +271,163 @@
<c><seealso marker="ct#run_test-1">ct</seealso></c> manual page.</p>
</section>
+ <marker id="group_execution"></marker>
+ <section>
+ <title>Test case group execution</title>
+
+ <p>With the <c>ct_run</c> flag, or <c>ct:run_test/1</c> option <c>group</c>,
+ one or more test case groups can be specified, optionally in combination
+ with specific test cases. The syntax for specifying groups is as follows
+ (on the command line):</p>
+
+ <pre>
+ <![CDATA[$ ct_run -group <group_names_or_paths> [-case <cases>]]]></pre>
+ <p>or (in the Erlang shell):</p>
+ <pre>
+ <![CDATA[1> ct:run_test([{group,GroupsNamesOrPaths}, {case,Cases}]).]]></pre>
+
+ <p>The <c>group_names_or_paths</c> parameter specifies either one
+ or more group names and/or one or more group paths. At start up,
+ Common Test will search for matching groups in the group definitions
+ tree (i.e. the list returned from <c>Suite:groups/0</c>, please see the
+ <seealso marker="write_test_chapter#test_case_groups">Test case groups</seealso>
+ chapter for details).
+ Given a group name, say <c>g</c>, Common Test will search for all paths
+ that lead to <c>g</c>. By path here we mean a sequence of nested groups,
+ all of which have to be followed in order to get from the top level
+ group to <c>g</c>. Actually, what Common Test needs to do in order to
+ execute the test cases in group <c>g</c>, is to call the
+ <c>init_per_group/2</c> function for each group in the path to
+ <c>g</c>, as well as all corresponding <c>end_per_group/2</c>
+ functions afterwards. The obvious reason for this is that the configuration
+ of a test case in <c>g</c> (and its <c>Config</c> input data) depends on
+ <c>init_per_testcase(TestCase, Config)</c> and its return value, which
+ in turn depends on <c>init_per_group(g, Config)</c> and its return value,
+ which in turn depends on <c>init_per_group/2</c> of the group above
+ <c>g</c>, etc, all the way up to the top level group.</p>
+
+ <p>As you may have already realized, this means that if there is more than
+ one way to locate a group (and its test cases) in a path, the result of the
+ group search operation is a number of tests, all of which will be performed.
+ Common Test actually interprets a group specification that consists of a
+ single name this way:</p>
+
+ <p>"Search and find all paths in the group definitions tree that lead
+ to the specified group and, for each path, create a test which (1) executes
+ all configuration functions in the path to the specified group, then (2)
+ executes all - or all matching - test cases in this group, as well as (3)
+ all - or all matching - test cases in all sub groups of the group".
+ </p>
+
+ <p>It is also possible for the user to specify a specific group path with
+ the <c>group_names_or_paths</c> parameter. With this type of specification it's
+ possible to avoid execution of unwanted groups (in otherwise matching paths),
+ and/or the execution of sub groups. The syntax of the group path is a list of
+ group names in the path, e.g. on the command line:
+ </p>
+ <p><c>$ ct_run -suite "./x_SUITE" -group [g1,g3,g4] -case tc1 tc5</c></p>
+ <p>or similarly in the Erlang shell (requires a list within the groups list):</p>
+ <p><c>1> ct:run_test([{suite,"./x_SUITE"}, {group,[[g1,g3,g4]]}, {testcase,[tc1,tc5]}]).</c></p>
+
+ <p>The last group in the specified path will be the terminating group in
+ the test, i.e. no sub groups following this group will be executed. In the
+ example above, <c>g4</c> is the terminating group, hence Common Test will
+ execute a test that calls all init configuration functions in the path to
+ <c>g4</c>, i.e. <c>g1..g3..g4</c>. It will then call test cases <c>tc1</c>
+ and <c>tc5</c> in <c>g4</c> and finally all end configuration functions in order
+ <c>g4..g3..g1</c>.</p>
+
+ <p>Note that the group path specification doesn't necessarily
+ have to include <em>all</em> groups in the path to the terminating group.
+ Common Test will search for all matching paths if given an incomplete group
+ path.</p>
+
+ <p>Note also that it's possible to combine group names and group paths with the
+ <c>group_names_or_paths</c> parameter. Each element is treated as
+ an individual specification in combination with the <c>cases</c> parameter.
+ See examples below.</p>
+
+ <p>Examples:</p>
+ <pre>
+ -module(x_SUITE).
+ ...
+ %% The group definitions:
+ groups() ->
+ [{top1,[],[tc11,tc12,
+ {sub11,[],[tc12,tc13]},
+ {sub12,[],[tc14,tc15,
+ {sub121,[],[tc12,tc16]}]}]},
+
+ {top2,[],[{group,sub21},{group,sub22}]},
+ {sub21,[],[tc21,{group,sub2X2}]},
+ {sub22,[],[{group,sub221},tc21,tc22,{group,sub2X2}]},
+ {sub221,[],[tc21,tc23]},
+ {sub2X2,[],[tc21,tc24]}].
+ </pre>
+ <br></br>
+ <p><c>$ ct_run -suite "x_SUITE" -group all</c></p>
+ <p><c>1> ct:run_test([{suite,"x_SUITE"}, {group,all}]).</c></p>
+ <p>Two tests will be executed, one for all cases and all sub groups under <c>top1</c>,
+ and one for all under <c>top2</c>. (We would get the same result with
+ <c>-group top1 top2</c>, or <c>{group,[top1,top2]}</c>.</p>
+ <br></br>
+ <p><c>$ ct_run -suite "x_SUITE" -group top1</c></p>
+ <p><c>1> ct:run_test([{suite,"x_SUITE"}, {group,[top1]}]).</c></p>
+ <p>This will execute one test for all cases and sub groups under <c>top1</c>.</p>
+ <br></br>
+ <p><c>$ ct_run -suite "x_SUITE" -group top1 -case tc12</c></p>
+ <p><c>1> ct:run_test([{suite,"x_SUITE"}, {group,[top1]}, {testcase,[tc12]}]).</c></p>
+ <p>This will run a test that executes <c>tc12</c> in <c>top1</c> and any sub group
+ under <c>top1</c> where it can be found (<c>sub11</c> and <c>sub121</c>).</p>
+ <br></br>
+ <p><c>$ ct_run -suite "x_SUITE" -group [top1] -case tc12</c></p>
+ <p><c>1> ct:run_test([{suite,"x_SUITE"}, {group,[[top1]]}, {testcase,[tc12]}]).</c></p>
+ <p>This will execute <c>tc12</c> <em>only</em> in group <c>top1</c>.</p>
+ <br></br>
+ <p><c>$ ct_run -suite "x_SUITE" -group top1 -case tc16</c></p>
+ <p><c>1> ct:run_test([{suite,"x_SUITE"}, {group,[top1]}, {testcase,[tc16]}]).</c></p>
+ <p>This will search <c>top1</c> and all its sub groups for <c>tc16</c> and the result
+ will be that this test case executes in group <c>sub121</c>. (The specific path:
+ <c>-group [sub121]</c> or <c>{group,[[sub121]]}</c>, would have given
+ us the same result in this example).</p>
+ <br></br>
+ <p><c>$ ct_run -suite "x_SUITE" -group sub12 [sub12]</c></p>
+ <p><c>1> ct:run_test([{suite,"x_SUITE"}, {group,[sub12,[sub12]]}]).</c></p>
+ <p>This will execute two tests, one that includes all cases and sub groups under
+ <c>sub12</c>, and one with <em>only</em> the test cases in <c>sub12</c>.</p>
+ <br></br>
+ <p><c>$ ct_run -suite "x_SUITE" -group sub2X2</c></p>
+ <p><c>1> ct:run_test([{suite,"x_SUITE"}, {group,[sub2X2]}]).</c></p>
+ <p>In this example, Common Test will find and execute two tests, one for the path from
+ <c>top2</c> to <c>sub2X2</c> via <c>sub21</c>, and one from <c>top2</c> to <c>sub2X2</c>
+ via <c>sub22</c>.</p>
+ <br></br>
+ <p><c>$ ct_run -suite "x_SUITE" -group [sub21,sub2X2]</c></p>
+ <p><c>1> ct:run_test([{suite,"x_SUITE"}, {group,[[sub21,sub2X2]]}]).</c></p>
+ <p>Here, by specifying the unique path: <c>top2 -> sub21 -> sub2X2</c>, only one test
+ is executed. The second possible path from <c>top2</c> to <c>sub2X2</c> (above)
+ will be discarded.</p>
+ <br></br>
+ <p><c>$ ct_run -suite "x_SUITE" -group [sub22] -case tc22 tc21</c></p>
+ <p><c>1> ct:run_test([{suite,"x_SUITE"}, {group,[[sub22]]}, {testcase,[tc22,tc21]}]).</c></p>
+ <p>In this example only the test cases for <c>sub22</c> will be executed, and in
+ reverse order compared to the group definition.</p>
+ <br></br>
+
+ <p>If a test case that belongs to a group (according to the group definition), is executed
+ without a group specification, i.e. simply by means of (command line):</p>
+ <p><c>$ ct_run -suite "my_SUITE" -case my_tc</c></p>
+ <p>or (Erlang shell):</p>
+ <p><c>1> ct:run_test([{suite,"my_SUITE"}, {testcase,my_tc}]).</c></p>
+ <p>then Common Test ignores the group definition and executes the test case in the scope of the
+ test suite only (no group configuration functions are called).</p>
+
+ <p>The group specification feature, exactly as it has been presented in this section, can also
+ be used in <seealso marker="run_test_chapter#test_specifications">Test
+ Specifications</seealso> (with some extra features added). Please see below.</p>
+ </section>
+
+
<section>
<title>Running the interactive shell mode</title>
@@ -400,8 +559,8 @@
terms (e.g. log directory, label, style sheet, auto compilation).</p>
<p>With test specification terms it is possible to state exactly
which tests should run and in which order. A test term specifies
- either one or more suites, one or more test case groups, or one
- or more test cases in a group or suite.</p>
+ either one or more suites, one or more test case groups (possibly nested),
+ or one or more test cases in a group (or in multiple groups) or in a suite.</p>
<p>An arbitrary number of test terms may be declared in sequence.
Common Test will by default compile the terms into one or more tests
to be performed in one resulting test run. Note that a term that
@@ -420,28 +579,32 @@
are not executed and show up in the HTML log files as
SKIPPED.</p>
<p>When a test case group is specified, the resulting test
- executes the
- <c>init_per_group</c> function, followed by all test cases and
- sub groups (including their configuration functions), and
+ executes the <c>init_per_group</c> function, followed by all test
+ cases and sub groups (including their configuration functions), and
finally the <c>end_per_group</c> function. Also if particular
test cases in a group are specified, <c>init_per_group</c>
and <c>end_per_group</c> for the group in question are
called. If a group which is defined (in <c>Suite:group/0</c>) to
- be a sub group of another group, is specified (or particular test
+ be a sub group of another group, is specified (or if particular test
cases of a sub group are), Common Test will call the configuration
functions for the top level groups as well as for the sub group
in question (making it possible to pass configuration data all
the way from <c>init_per_suite</c> down to the test cases in the
sub group).</p>
-
- <p>With the <c>GroupSpec</c> element (below) it's possible to specify
- group execution properties that will override those specified in the
+ <p>The test specification utilizes the same mechanism for specifying
+ test case groups by means of names and paths, as explained in the
+ <seealso marker="run_test_chapter#group_execution">Group Execution</seealso>
+ section above, with the addition of the <c>GroupSpec</c> element
+ described next.</p>
+ <p>The <c>GroupSpec</c> element makes it possible to specify
+ group execution properties that will override those in the
group definition (i.e. in <c>groups/0</c>). Execution properties for
sub-groups may be overridden as well. This feature makes it possible to
change properties of groups at the time of execution,
- without even having to edit the test suite. More detailed documentation,
- and examples, can be found in the
- <seealso marker="write_test_chapter#test_case_groups">
+ without even having to edit the test suite. The very same
+ feature is available for <c>group</c> elements in the <c>Suite:all/0</c>
+ list. Therefore, more detailed documentation, and examples, can be
+ found in the <seealso marker="write_test_chapter#test_case_groups">
Test case groups</seealso> chapter.</p>
<p>Below is the test specification syntax. Test specifications can
@@ -546,8 +709,8 @@
{groups, Dir, Suite, Groups}.
{groups, NodeRefs, Dir, Suite, Groups}.
- {groups, Dir, Suite, GroupSpec, {cases,Cases}}.
- {groups, NodeRefs, Dir, Suite, GroupSpec, {cases,Cases}}.
+ {groups, Dir, Suite, Groups, {cases,Cases}}.
+ {groups, NodeRefs, Dir, Suite, Groups, {cases,Cases}}.
{cases, Dir, Suite, Cases}.
{cases, NodeRefs, Dir, Suite, Cases}.
@@ -589,13 +752,16 @@
PrivDirOption = auto_per_run | auto_per_tc | manual_per_tc
EventHandlers = atom() | [atom()]
InitArgs = [term()]
- CTHModules = [CTHModule | {CTHModule, CTHInitArgs} | {CTHModule, CTHInitArgs, CTHPriority}]
+ CTHModules = [CTHModule |
+ {CTHModule, CTHInitArgs} |
+ {CTHModule, CTHInitArgs, CTHPriority}]
CTHModule = atom()
CTHInitArgs = term()
Dir = string()
Suites = atom() | [atom()] | all
Suite = atom()
- Groups = GroupSpec | [GroupSpec] | all
+ Groups = GroupPath | [GroupPath] | GroupSpec | [GroupSpec] | all
+ GroupPath = [GroupName]
GroupSpec = GroupName | {GroupName,Properties} | {GroupName,Properties,GroupSpec}
GroupName = atom()
GroupNames = GroupName | [GroupName]
diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml
index 248d7de8b6..cc8d913994 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2012</year>
+ <year>2003</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -982,38 +982,36 @@
<p>Example:</p>
<pre>
+ Some printouts during test case execution:
- Some printouts during test case execution:
+ io:format("1. Standard IO, importance = ~w~n", [?STD_IMPORTANCE]),
+ ct:log("2. Uncategorized, importance = ~w", [?STD_IMPORTANCE]),
+ ct:log(info, "3. Categorized info, importance = ~w", [?STD_IMPORTANCE]]),
+ ct:log(info, ?LOW_IMPORTANCE, "4. Categorized info, importance = ~w", [?LOW_IMPORTANCE]),
+ ct:log(error, "5. Categorized error, importance = ~w", [?HI_IMPORTANCE]),
+ ct:log(error, ?HI_IMPORTANCE, "6. Categorized error, importance = ~w", [?MAX_IMPORTANCE]),
- io:format("1. Standard IO, importance = ~w~n", [?STD_IMPORTANCE]),
- ct:log("2. Uncategorized, importance = ~w", [?STD_IMPORTANCE]),
- ct:log(info, "3. Categorized info, importance = ~w", [?STD_IMPORTANCE]]),
- ct:log(info, ?LOW_IMPORTANCE, "4. Categorized info, importance = ~w", [?LOW_IMPORTANCE]),
- ct:log(error, "5. Categorized error, importance = ~w", [?HI_IMPORTANCE]),
- ct:log(error, ?HI_IMPORTANCE, "6. Categorized error, importance = ~w", [?MAX_IMPORTANCE]),
+ If starting the test without specifying any verbosity levels:
- If starting the test without specifying any verbosity levels:
+ $ ct_run ...
- $ ct_run ...
+ the following gets printed:
- the following gets printed:
-
- 1. Standard IO, importance = 50
- 2. Uncategorized, importance = 50
- 3. Categorized info, importance = 50
- 5. Categorized error, importance = 75
- 6. Categorized error, importance = 99
-
- If starting the test with:
-
- $ ct_run -verbosity 1 and info 75
-
- the following gets printed:
+ 1. Standard IO, importance = 50
+ 2. Uncategorized, importance = 50
+ 3. Categorized info, importance = 50
+ 5. Categorized error, importance = 75
+ 6. Categorized error, importance = 99
+
+ If starting the test with:
+
+ $ ct_run -verbosity 1 and info 75
+
+ the following gets printed:
- 3. Categorized info, importance = 50
- 4. Categorized info, importance = 25
- 6. Categorized error, importance = 99
- </pre>
+ 3. Categorized info, importance = 50
+ 4. Categorized info, importance = 25
+ 6. Categorized error, importance = 99</pre>
<p>How categories can be mapped to CSS tags is documented in the
<seealso marker="run_test_chapter#html_stylesheet">Running Tests</seealso>