aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authortmanevik <[email protected]>2015-12-18 12:21:32 +0100
committerPeter Andersson <[email protected]>2016-03-09 11:15:11 +0100
commit68d7535fe0cccd50622884f704edeb9d8bb47430 (patch)
treec4ca009a89b642ed67b1e461244332a437db1d56
parent7a06301d4eee08d98976ab592ff1b778b3d3a0e7 (diff)
downloadotp-68d7535fe0cccd50622884f704edeb9d8bb47430.tar.gz
otp-68d7535fe0cccd50622884f704edeb9d8bb47430.tar.bz2
otp-68d7535fe0cccd50622884f704edeb9d8bb47430.zip
Common Test: Editorial changes 3
Reference Manual files from Pär Wennstad added
-rw-r--r--lib/common_test/doc/src/common_test_app.xml776
-rw-r--r--lib/common_test/doc/src/ct.xml1386
-rw-r--r--lib/common_test/doc/src/ct_cover.xml106
-rw-r--r--lib/common_test/doc/src/ct_ftp.xml277
-rw-r--r--lib/common_test/doc/src/ct_hooks.xml805
-rw-r--r--lib/common_test/doc/src/ct_master.xml220
-rw-r--r--lib/common_test/doc/src/ct_netconfc.xml1037
-rw-r--r--lib/common_test/doc/src/ct_property_test.xml116
-rw-r--r--lib/common_test/doc/src/ct_rpc.xml220
-rw-r--r--lib/common_test/doc/src/ct_run.xml299
-rw-r--r--lib/common_test/doc/src/ct_slave.xml221
-rw-r--r--lib/common_test/doc/src/ct_snmp.xml524
-rw-r--r--lib/common_test/doc/src/ct_ssh.xml1150
-rw-r--r--lib/common_test/doc/src/ct_telnet.xml601
-rw-r--r--lib/common_test/doc/src/ref_man.xml38
-rw-r--r--lib/common_test/doc/src/unix_telnet.xml134
16 files changed, 6929 insertions, 981 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>
-
diff --git a/lib/common_test/doc/src/ct.xml b/lib/common_test/doc/src/ct.xml
new file mode 100644
index 0000000000..ed3d76061a
--- /dev/null
+++ b/lib/common_test/doc/src/ct.xml
@@ -0,0 +1,1386 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct.xml</file>
+ </header>
+ <module>ct</module>
+ <modulesummary>Main user interface for the Common Test framework.</modulesummary>
+
+ <description>
+
+ <p>Main user interface for the <c>Common Test</c> framework.</p>
+
+ <p>This module implements the command-line interface for running
+ tests and basic functions for <c>Common Test</c> case issues, such as
+ configuration and logging.</p>
+
+ <p><em>Test Suite Support Macros</em></p>
+
+ <p>The <c>config</c> macro is defined in <c>ct.hrl</c>. This macro is
+ to be used to retrieve information from the <c>Config</c> variable sent
+ to all test cases. It is used with two arguments; the first is the name
+ of the configuration variable to retrieve, the second is the
+ <c>Config</c> variable supplied to the test case.</p>
+
+ <p>Possible configuration variables include:</p>
+
+ <list type="bulleted">
+ <item><p><c>data_dir</c> - Data file directory</p></item>
+ <item><p><c>priv_dir</c> - Scratch file directory</p></item>
+ <item><p>Whatever added by
+ <seealso marker="#Module:init_per_suite-1"><c>init_per_suite/1</c></seealso>
+ or
+ <seealso marker="#Module:init_per_testcase-2"><c>init_per_testcase/2</c></seealso>
+ in the test suite.</p></item>
+ </list>
+
+ </description>
+
+ <section>
+ <title>Data Types</title>
+ <marker id="types"/>
+ <taglist>
+
+ <tag><c>handle() = pid()</c></tag>
+ <item><marker id="type-handle"/>
+ <p>The identity (handle) of a connection.</p></item>
+
+ <tag><c>target_name() = atom()</c></tag>
+ <item><marker id="type-target_name"/>
+ <p>A name and association to configuration data introduced
+ through a require statement, or a call to
+ <seealso marker="#require-2"><c>ct:require/2</c></seealso>,
+ for example,
+ <c>ct:require(mynodename,{node,[telnet]})</c>.</p></item>
+
+ </taglist>
+ </section>
+
+ <funcs>
+ <func>
+ <name>abort_current_testcase(Reason) -&gt; ok | {error, ErrorReason}</name>
+ <fsummary>Aborts the currently executing test case.</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ <v>ErrorReason = no_testcase_running | parallel_group</v>
+ </type>
+ <desc><marker id="abort_current_testcase-1"/>
+ <p>Aborts the currently executing test case. The user must know with
+ certainty which test case is currently executing. The function is
+ therefore only safe to call from a function that has been called
+ (or synchronously invoked) by the test case.</p>
+
+ <p><c>Reason</c>, the reason for aborting the test case, is printed
+ in the test case log.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>add_config(Callback, Config) -&gt; ok | {error, Reason}</name>
+ <fsummary>Loads configuration variables using the specified callback
+ module and configuration string.</fsummary>
+ <type>
+ <v>Callback = atom()</v>
+ <v>Config = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="add_config-2"/>
+ <p>Loads configuration variables using the specified callback module and
+ configuration string. The callback module is to be either loaded or
+ present in the code part. Loaded configuration variables can later
+ be removed using function
+ <seealso marker="#remove_config-2"><c>ct:remove_config/2</c></seealso>.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>break(Comment) -&gt; ok | {error, Reason}</name>
+ <fsummary>Cancels any active timetrap and pause the execution of the
+ current test case until the user calls function continue/0.</fsummary>
+ <type>
+ <v>Comment = string()</v>
+ <v>Reason = {multiple_cases_running, TestCases} | 'enable break with release_shell option'</v>
+ <v>TestCases = [atom()]</v>
+ </type>
+ <desc><marker id="break-1"/>
+ <p>Cancels any active timetrap and pauses the execution of the
+ current test case until the user calls function <c>continue/0</c>.
+ The user can then interact with the Erlang node running the tests,
+ for example, for debugging purposes or for manually executing a
+ part of the test case. If a parallel group is executing,
+ <seealso marker="#break-2"><c>ct:break/2</c></seealso> is to be
+ called instead.</p>
+ <p>A cancelled timetrap is not automatically reactivated after the
+ break, but must be started exlicitly with
+ <seealso marker="#timetrap-1"><c>ct:timetrap/1</c></seealso>.</p>
+ <p>In order for the break/continue functionality to work, <c>Common
+ Test</c> must release the shell process controlling <c>stdin</c>.
+ This is done by setting start option <c>release_shell</c>
+ to <c>true</c>. For details, see section
+ <seealso marker="run_test_chapter#erlang_shell_or_program">Running
+ Tests from the Erlang Shell or from an Erlang Program</seealso>
+ in the User's Guide.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>break(TestCase, Comment) -&gt; ok | {error, Reason}</name>
+ <fsummary>Works the same way as break/1, only argument TestCase makes it
+ possible to pause a test case executing in a parallel group.</fsummary>
+ <type>
+ <v>TestCase = atom()</v>
+ <v>Comment = string()</v>
+ <v>Reason = 'test case not running' | 'enable break with release_shell option'</v>
+ </type>
+ <desc><marker id="break-2"/>
+ <p>Works the same way as
+ <seealso marker="#break-1"><c>ct:break/1</c></seealso>, only
+ argument <c>TestCase</c> makes it possible to pause a test case
+ executing in a parallel group. Function
+ <seealso marker="#continue-1"><c>ct:continue/1</c></seealso> is to
+ be used to resume execution of <c>TestCase</c>.</p>
+
+ <p>For details, see
+ <seealso marker="#break/1"><c>ct:break/1</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>capture_get() -&gt; ListOfStrings</name>
+ <fsummary>Equivalent to capture_get([default]).</fsummary>
+ <type>
+ <v>ListOfStrings = [string()]</v>
+ </type>
+ <desc><marker id="capture_get-0"/>
+ <p>Equivalent to
+ <seealso marker="#capture_get-1">ct:capture_get([default])</seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>capture_get(ExclCategories) -&gt; ListOfStrings</name>
+ <fsummary>Returns and purges the list of text strings buffered during
+ the latest session of capturing printouts to stdout.</fsummary>
+ <type>
+ <v>ExclCategories = [atom()]</v>
+ <v>ListOfStrings = [string()]</v>
+ </type>
+ <desc><marker id="capture_get-1"/>
+ <p>Returns and purges the list of text strings buffered during the
+ latest session of capturing printouts to <c>stdout</c>. Log
+ categories that are to be ignored in <c>ListOfStrings</c> can be
+ specified with <c>ExclCategories</c>.
+ If <c>ExclCategories = []</c>, no filtering takes place.</p>
+
+ <p>See also
+ <seealso marker="#capture_start-0"><c>ct:capture_start/0</c></seealso>,
+ <seealso marker="#capture_stop-0"><c>ct:capture_stop/0</c></seealso>,
+ <seealso marker="#log-3"><c>ct:log/3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>capture_start() -&gt; ok</name>
+ <fsummary>Starts capturing all text strings printed to stdout
+ during execution of the test case.</fsummary>
+ <desc><marker id="capture_start-0"/>
+ <p>Starts capturing all text strings printed to <c>stdout</c>
+ during execution of the test case.</p>
+
+ <p>See also
+ <seealso marker="#capture_get-1"><c>ct:capture_get/1</c></seealso>,
+ <seealso marker="#capture_stop-0"><c>ct:capture_stop/0</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>capture_stop() -&gt; ok</name>
+ <fsummary>Stops capturing text strings (a session started with
+ capture_start/0).</fsummary>
+ <desc><marker id="capture_stop-0"/>
+ <p>Stops capturing text strings (a session started with
+ <c>capture_start/0</c>).</p>
+
+ <p>See also
+ <seealso marker="#capture_get-1"><c>ct:capture_get/1</c></seealso>,
+ <seealso marker="#capture_start-0"><c>ct:capture_start/0</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>comment(Comment) -&gt; ok</name>
+ <fsummary>Prints the specified Comment in the comment field in the
+ table on the test suite result page.</fsummary>
+ <type>
+ <v>Comment = term()</v>
+ </type>
+ <desc><marker id="comment-1"/>
+ <p>Prints the specified <c>Comment</c> in the comment field in the
+ table on the test suite result page.</p>
+
+ <p>If called several times, only the last comment is printed. The
+ test case return value <c>{comment,Comment}</c> overwrites the
+ string set by this function.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>comment(Format, Args) -&gt; ok</name>
+ <fsummary>Prints the formatted string in the comment field in the
+ table on the test suite result page.</fsummary>
+ <type>
+ <v>Format = string()</v>
+ <v>Args = list()</v>
+ </type>
+ <desc><marker id="comment-2"/>
+ <p>Prints the formatted string in the comment field in the table
+ on the test suite result page.</p>
+
+ <p>Arguments <c>Format</c> and <c>Args</c> are used in a call to
+ <c>io_lib:format/2</c> to create the comment string. The behavior
+ of <c>comment/2</c> is otherwise the same as function
+ <seealso marker="#comment-1"><c>ct:comment/1</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>continue() -&gt; ok</name>
+ <fsummary>This function must be called to continue after a test
+ case (not executing in a parallel group) has called break/1.</fsummary>
+ <desc><marker id="continue-0"/>
+ <p>This function must be called to continue after a test case
+ (not executing in a parallel group) has called function
+ <seealso marker="#break-1"><c>ct:break/1</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>continue(TestCase) -&gt; ok</name>
+ <fsummary>This function must be called to continue after a test case
+ has called break/2.</fsummary>
+ <type>
+ <v>TestCase = atom()</v>
+ </type>
+ <desc><marker id="continue-1"/>
+ <p>This function must be called to continue after a test case has
+ called <seealso marker="#break-2"><c>ct:break/2</c></seealso>.
+ If the paused test case, <c>TestCase</c>, executes in a parallel
+ group, this function, rather than <c>continue/0</c>, must be used
+ to let the test case proceed.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>decrypt_config_file(EncryptFileName, TargetFileName) -&gt; ok | {error, Reason}</name>
+ <fsummary>Decrypts EncryptFileName, previously generated with
+ encrypt_config_file/2,3.</fsummary>
+ <type>
+ <v>EncryptFileName = string()</v>
+ <v>TargetFileName = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="decrypt_config_file-2"/>
+ <p>Decrypts <c>EncryptFileName</c>, previously generated with
+ <seealso marker="#encrypt_config_file-2"><c>ct:encrypt_config_file/2,3</c></seealso>.
+ The original file contents is saved in the target file. The
+ encryption key, a string, must be available in a text file named
+ <c>.ct_config.crypt</c>, either in the current directory, or the
+ home directory of the user (it is searched for in that order).</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -&gt; ok | {error, Reason}</name>
+ <fsummary>Decrypts EncryptFileName, previously generated with
+ encrypt_config_file/2,3.</fsummary>
+ <type>
+ <v>EncryptFileName = string()</v>
+ <v>TargetFileName = string()</v>
+ <v>KeyOrFile = {key, string()} | {file, string()}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="decrypt_config_file-3"/>
+ <p>Decrypts <c>EncryptFileName</c>, previously generated with
+ <seealso marker="#encrypt_config_file-2"><c>ct:encrypt_config_file/2,3</c></seealso>.
+ The original file contents is saved in the target file. The key
+ must have the same value as that used for encryption.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>encrypt_config_file(SrcFileName, EncryptFileName) -&gt; ok | {error, Reason}</name>
+ <fsummary>Encrypts the source configuration file with DES3 and saves the
+ result in file EncryptFileName.</fsummary>
+ <type>
+ <v>SrcFileName = string()</v>
+ <v>EncryptFileName = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="encrypt_config_file-2"/>
+ <p>Encrypts the source configuration file with DES3 and saves the result
+ in file <c>EncryptFileName</c>. The key, a string, must be
+ available in a text file named <c>.ct_config.crypt</c>, either
+ in the current directory, or the home directory of the user (it
+ is searched for in that order).</p>
+
+ <p>For information about using encrypted configuration files when
+ running tests, see section
+ <seealso marker="config_file_chapter#encrypted_config_files">Encrypted
+ Configuration Files</seealso> in the User's Guide.</p>
+
+ <p>For details on DES3 encryption/decryption, see application
+ <seealso marker="crypto"><c>Crypto</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -&gt; ok | {error, Reason}</name>
+ <fsummary>Encrypts the source configuration file with DES3 and saves the
+ result in the target file EncryptFileName.</fsummary>
+ <type>
+ <v>SrcFileName = string()</v>
+ <v>EncryptFileName = string()</v>
+ <v>KeyOrFile = {key, string()} | {file, string()}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="encrypt_config_file-3"/>
+ <p>Encrypts the source configuration file with DES3 and saves the result
+ in the target file <c>EncryptFileName</c>. The encryption key
+ to use is either the value in <c>{key,Key}</c> or the value
+ stored in the file specified by <c>{file,File}</c>.</p>
+
+ <p>For information about using encrypted configuration files when
+ running tests, see section
+ <seealso marker="config_file_chapter#encrypted_config_files">Encrypted
+ Configuration Files</seealso> in the User's Guide.</p>
+
+ <p>For details on DES3 encryption/decryption, see application
+ <seealso marker="crypto"><c>Crypto</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>fail(Reason) -&gt; ok</name>
+ <fsummary>Terminates a test case with the specified error
+ Reason.</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="fail-1"/>
+ <p>Terminates a test case with the specified error <c>Reason</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>fail(Format, Args) -&gt; ok</name>
+ <fsummary>Terminates a test case with an error message specified by
+ a format string and a list of values (used as arguments to
+ io_lib:format/2).</fsummary>
+ <type>
+ <v>Format = string()</v>
+ <v>Args = list()</v>
+ </type>
+ <desc><marker id="fail-2"/>
+ <p>Terminates a test case with an error message specified by a
+ format string and a list of values (used as arguments to
+ <c>io_lib:format/2</c>).</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_config(Required) -&gt; Value</name>
+ <fsummary>Equivalent to get_config(Required, undefined, []).</fsummary>
+ <desc><marker id="get_config-1"/>
+ <p>Equivalent to <seealso marker="#get_config-3"><c>ct:get_config(Required,
+ undefined, [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_config(Required, Default) -&gt; Value</name>
+ <fsummary>Equivalent to get_config(Required, Default, []).</fsummary>
+ <desc><marker id="get_config-2"/>
+ <p>Equivalent to <seealso marker="#get_config-3"><c>ct:get_config(Required,
+ Default, [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_config(Required, Default, Opts) -&gt; ValueOrElement</name>
+ <fsummary>Reads configuration data values.</fsummary>
+ <type>
+ <v>Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}</v>
+ <v>KeyOrName = atom()</v>
+ <v>SubKey = atom()</v>
+ <v>Default = term()</v>
+ <v>Opts = [Opt] | []</v>
+ <v>Opt = element | all</v>
+ <v>ValueOrElement = term() | Default</v>
+ </type>
+ <desc><marker id="get_config-3"/>
+ <p>Reads configuration data values.</p>
+
+ <p>Returns the matching values or configuration elements, given a
+ configuration variable key or its associated name (if one has been
+ specified with
+ <seealso marker="#require-2"><c>ct:require/2</c></seealso>
+ or a <c>require</c> statement).</p>
+
+ <p><em>Example:</em></p>
+
+ <p>Given the following configuration file:</p>
+
+ <pre>
+ {unix,[{telnet,IpAddr},
+ {user,[{username,Username},
+ {password,Password}]}]}.</pre>
+
+ <p>Then:</p>
+
+ <pre>
+ ct:get_config(unix,Default) -&gt; [{telnet,IpAddr},
+ {user, [{username,Username}, {password,Password}]}]
+ ct:get_config({unix,telnet},Default) -&gt; IpAddr
+ ct:get_config({unix,user,username},Default) -&gt; Username
+ ct:get_config({unix,ftp},Default) -&gt; Default
+ ct:get_config(unknownkey,Default) -&gt; Default</pre>
+
+ <p>If a configuration variable key has been associated with a name (by
+ <seealso marker="#require-2"><c>ct:require/2</c></seealso>
+ or a <c>require</c> statement), the name can be used instead
+ of the key to read the value:</p>
+
+ <pre>
+ ct:require(myuser,{unix,user}) -&gt; ok.
+ ct:get_config(myuser,Default) -&gt; [{username,Username}, {password,Password}]</pre>
+
+ <p>If a configuration variable is defined in multiple files, use option
+ <c>all</c> to access all possible values. The values are returned
+ in a list. The order of the elements corresponds to the order
+ that the configuration files were specified at startup.</p>
+
+ <p>If configuration elements (key-value tuples) are to be returned as
+ result instead of values, use option <c>element</c>. The
+ returned elements are then on the form <c>{Required,Value}</c>.</p>
+
+ <p>See also
+ <seealso marker="#get_config-1"><c>ct:get_config/1</c></seealso>,
+ <seealso marker="#get_config-2"><c>ct:get_config/2</c></seealso>,
+ <seealso marker="#require-1"><c>ct:require/1</c></seealso>,
+ <seealso marker="#require-2"><c>ct:require/2</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_event_mgr_ref() -&gt; EvMgrRef</name>
+ <fsummary>Gets a reference to the <c>Common Test</c> event manager.</fsummary>
+ <type>
+ <v>EvMgrRef = atom()</v>
+ </type>
+ <desc><marker id="get_event_mgr_ref-0"/>
+ <p>Gets a reference to the <c>Common Test</c> event manager.
+ The reference can be used to, for example, add a user-specific
+ event handler while tests are running.</p>
+
+ <p><em>Example:</em></p>
+
+ <pre>
+ gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])</pre>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_status() -&gt; TestStatus | {error, Reason} | no_tests_running</name>
+ <fsummary>Returns status of ongoing test.</fsummary>
+ <type>
+ <v>TestStatus = [StatusElem]</v>
+ <v>StatusElem = {current, TestCaseInfo} | {successful, Successful} | {failed, Failed} | {skipped, Skipped} | {total, Total}</v>
+ <v>TestCaseInfo = {Suite, TestCase} | [{Suite, TestCase}]</v>
+ <v>Suite = atom()</v>
+ <v>TestCase = atom()</v>
+ <v>Successful = integer()</v>
+ <v>Failed = integer()</v>
+ <v>Skipped = {UserSkipped, AutoSkipped}</v>
+ <v>UserSkipped = integer()</v>
+ <v>AutoSkipped = integer()</v>
+ <v>Total = integer()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="get_status-0"/>
+ <p>Returns status of ongoing test. The returned list contains
+ information about which test case is executing (a list of cases
+ when a parallel test case group is executing), as well as
+ counters for successful, failed, skipped, and total test cases
+ so far.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_target_name(Handle) -&gt; {ok, TargetName} | {error, Reason}</name>
+ <fsummary>Returns the name of the target that the specified connection
+ belongs to.</fsummary>
+ <type>
+ <v>Handle = handle()</v>
+ <v>TargetName = target_name()</v>
+ </type>
+ <desc><marker id="get_target_name-1"/>
+ <p>Returns the name of the target that the specified connection
+ belongs to.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_testspec_terms() -&gt; TestSpecTerms | undefined</name>
+ <fsummary>Gets a list of all test specification terms used to
+ configure and run this test.</fsummary>
+ <type>
+ <v>TestSpecTerms = [{Tag, Value}]</v>
+ <v>Value = [term()]</v>
+ </type>
+ <desc><marker id="get_testspec_terms-0"/>
+ <p>Gets a list of all test specification terms used to configure
+ and run this test.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_testspec_terms(Tags) -&gt; TestSpecTerms | undefined</name>
+ <fsummary>Reads one or more terms from the test specification used to
+ configure and run this test.</fsummary>
+ <type>
+ <v>Tags = [Tag] | Tag</v>
+ <v>Tag = atom()</v>
+ <v>TestSpecTerms = [{Tag, Value}] | {Tag, Value}</v>
+ <v>Value = [{Node, term()}] | [term()]</v>
+ <v>Node = atom()</v>
+ </type>
+ <desc><marker id="get_testspec_terms-1"/>
+ <p>Reads one or more terms from the test specification used to
+ configure and run this test. <c>Tag</c> is any valid test
+ specification tag, for example, <c>label</c>, <c>config</c>, or
+ <c>logdir</c>. User-specific terms are also available to read if
+ option <c>allow_user_terms</c> is set.</p>
+ <p>All value tuples returned, except user terms, have the node
+ name as first element.</p>
+ <p>To read test terms, use <c>Tag = tests</c> (rather than
+ <c>suites</c>, <c>groups</c>, or <c>cases</c>). <c>Value</c> is
+ then the list of <em>all</em> tests on the form
+ <c>[{Node,Dir,[{TestSpec,GroupsAndCases1},...]},...]</c>, where
+ <c>GroupsAndCases = [{Group,[Case]}] | [Case]</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_timetrap_info() -&gt; {Time, Scale}</name>
+ <fsummary>Reads information about the timetrap set for the current
+ test case.</fsummary>
+ <type>
+ <v>Time = integer() | infinity</v>
+ <v>Scale = true | false</v>
+ </type>
+ <desc><marker id="get_timetrap_info-0"/>
+ <p>Reads information about the timetrap set for the current test
+ case. <c>Scale</c> indicates if <c>Common Test</c> will attempt
+ to compensate timetraps automatically for runtime delays
+ introduced by, for example, tools like cover.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>install(Opts) -&gt; ok | {error, Reason}</name>
+ <fsummary>Installs configuration files and event handlers.</fsummary>
+ <type>
+ <v>Opts = [Opt]</v>
+ <v>Opt = {config, ConfigFiles} | {event_handler, Modules} | {decrypt, KeyOrFile}</v>
+ <v>ConfigFiles = [ConfigFile]</v>
+ <v>ConfigFile = string()</v>
+ <v>Modules = [atom()]</v>
+ <v>KeyOrFile = {key, Key} | {file, KeyFile}</v>
+ <v>Key = string()</v>
+ <v>KeyFile = string()</v>
+ </type>
+ <desc><marker id="install-1"/>
+ <p>Installs configuration files and event handlers.</p>
+
+ <p>Run this function once before the first test.</p>
+
+ <p><em>Example:</em></p>
+
+ <pre>
+ install([{config,["config_node.ctc","config_user.ctc"]}])</pre>
+
+ <p>This function is automatically run by program <c>ct_run</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>listenv(Telnet) -&gt; [Env]</name>
+ <fsummary>Performs command listenv on the specified Telnet connection
+ and returns the result as a list of key-value pairs.</fsummary>
+ <type>
+ <v>Telnet = term()</v>
+ <v>Env = {Key, Value}</v>
+ <v>Key = string()</v>
+ <v>Value = string()</v>
+ </type>
+ <desc><marker id="listenv-1"/>
+ <p>Performs command <c>listenv</c> on the specified Telnet connection
+ and returns the result as a list of key-value pairs.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>log(Format) -&gt; ok</name>
+ <fsummary>Equivalent to log(default, 50, Format, []).</fsummary>
+ <desc><marker id="log-1"/>
+ <p>Equivalent to
+ <seealso marker="#log-4"><c>ct:log(default, 50, Format, [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>log(X1, X2) -&gt; ok</name>
+ <fsummary>Equivalent to log(Category, Importance, Format,
+ Args).</fsummary>
+ <type>
+ <v>X1 = Category | Importance | Format</v>
+ <v>X2 = Format | Args</v>
+ </type>
+ <desc><marker id="log-2"/>
+ <p>Equivalent to <seealso marker="#log-4"><c>ct:log(Category,
+ Importance, Format, Args)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>log(X1, X2, X3) -&gt; ok</name>
+ <fsummary>Equivalent to log(Category, Importance, Format,
+ Args).</fsummary>
+ <type>
+ <v>X1 = Category | Importance</v>
+ <v>X2 = Importance | Format</v>
+ <v>X3 = Format | Args</v>
+ </type>
+ <desc><marker id="log-3"/>
+ <p>Equivalent to <seealso marker="#log-4"><c>ct:log(Category,
+ Importance, Format, Args)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>log(Category, Importance, Format, Args) -&gt; ok</name>
+ <fsummary>Prints from a test case to the log file.</fsummary>
+ <type>
+ <v>Category = atom()</v>
+ <v>Importance = integer()</v>
+ <v>Format = string()</v>
+ <v>Args = list()</v>
+ </type>
+ <desc><marker id="log-4"/>
+ <p>Prints from a test case to the log file.</p>
+
+ <p>This function is meant for printing a string directly from a
+ test case to the test case log file.</p>
+
+ <p>Default <c>Category</c> is <c>default</c>,
+ default <c>Importance</c> is <c>?STD_IMPORTANCE</c>,
+ and default value for <c>Args</c> is <c>[]</c>.</p>
+
+ <p>For details on <c>Category</c> and <c>Importance</c>, see section
+ <seealso marker="write_test_chapter#logging">Logging - Categories
+ and Verbosity Levels</seealso> in the User's Guide.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>make_priv_dir() -&gt; ok | {error, Reason}</name>
+ <fsummary>If the test has been started with option create_priv_dir
+ set to manual_per_tc, in order for the test case to use the private
+ directory, it must first create it by calling this function.</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="make_priv_dir-0"/>
+ <p>If the test is started with option <c>create_priv_dir</c>
+ set to <c>manual_per_tc</c>, in order for the test case to use
+ the private directory, it must first create it by calling this
+ function.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>notify(Name, Data) -&gt; ok</name>
+ <fsummary>Sends an asynchronous notification of type Name with Data
+ to the <c>Common Test</c> event manager.</fsummary>
+ <type>
+ <v>Name = atom()</v>
+ <v>Data = term()</v>
+ </type>
+ <desc><marker id="notify-2"/>
+ <p>Sends an asynchronous notification of type <c>Name</c> with
+ <c>Data</c>to the Common Test event manager. This can later be
+ caught by any installed event manager.</p>
+
+ <p>See also
+ <seealso marker="stdlib:gen_event"><c>stdlib:gen_event(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pal(Format) -&gt; ok</name>
+ <fsummary>Equivalent to pal(default, 50, Format, []).</fsummary>
+ <desc><marker id="pal-1"/>
+ <p>Equivalent to
+ <seealso marker="#pal-4"><c>ct:pal(default, 50, Format,
+ [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pal(X1, X2) -&gt; ok</name>
+ <fsummary>Equivalent to pal(Category, Importance, Format,
+ Args).</fsummary>
+ <type>
+ <v>X1 = Category | Importance | Format</v>
+ <v>X2 = Format | Args</v>
+ </type>
+ <desc><marker id="pal-2"/>
+ <p>Equivalent to <seealso marker="#pal-4"><c>ct:pal(Category,
+ Importance, Format, Args)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pal(X1, X2, X3) -&gt; ok</name>
+ <fsummary>Equivalent to pal(Category, Importance, Format,
+ Args).</fsummary>
+ <type>
+ <v>X1 = Category | Importance</v>
+ <v>X2 = Importance | Format</v>
+ <v>X3 = Format | Args</v>
+ </type>
+ <desc><marker id="pal-3"/>
+ <p>Equivalent to <seealso marker="#pal-4"><c>ct:pal(Category,
+ Importance, Format, Args)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pal(Category, Importance, Format, Args) -&gt; ok</name>
+ <fsummary>Prints and logs from a test case.</fsummary>
+ <type>
+ <v>Category = atom()</v>
+ <v>Importance = integer()</v>
+ <v>Format = string()</v>
+ <v>Args = list()</v>
+ </type>
+ <desc><marker id="pal-4"/>
+ <p>Prints and logs from a test case.</p>
+
+ <p>This function is meant for printing a string from a test case,
+ both to the test case log file and to the console.</p>
+
+ <p>Default <c>Category</c> is <c>default</c>,
+ default <c>Importance</c> is <c>?STD_IMPORTANCE</c>,
+ and default value for <c>Args</c> is <c>[]</c>.</p>
+
+ <p>For details on <c>Category</c> and <c>Importance</c>, see section
+ <seealso marker="write_test_chapter#logging">Logging - Categories
+ and Verbosity Levels</seealso> in the User's Guide.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>parse_table(Data) -&gt; {Heading, Table}</name>
+ <fsummary>Parses the printout from an SQL table and returns a list of
+ tuples.</fsummary>
+ <type>
+ <v>Data = [string()]</v>
+ <v>Heading = tuple()</v>
+ <v>Table = [tuple()]</v>
+ </type>
+ <desc><marker id="parse_table-1"/>
+ <p>Parses the printout from an SQL table and returns a list of
+ tuples.</p>
+
+ <p>The printout to parse is typically the result of a <c>select</c>
+ command in SQL. The returned <c>Table</c> is a list of tuples,
+ where each tuple is a row in the table.</p>
+
+ <p><c>Heading</c> is a tuple of strings representing the headings
+ of each column in the table.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>print(Format) -&gt; ok</name>
+ <fsummary>Equivalent to print(default, 50, Format, []).</fsummary>
+ <desc><marker id="print-1"/>
+ <p>Equivalent to <seealso marker="#print-4"><c>ct:print(default,
+ 50, Format, [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>print(X1, X2) -&gt; ok</name>
+ <fsummary>Equivalent to print(Category, Importance, Format,
+ Args).</fsummary>
+ <type>
+ <v>X1 = Category | Importance | Format</v>
+ <v>X2 = Format | Args</v>
+ </type>
+ <desc><marker id="print-2"/>
+ <p>Equivalent to <seealso marker="#print-4"><c>ct:print(Category,
+ Importance, Format, Args)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>print(X1, X2, X3) -&gt; ok</name>
+ <fsummary>Equivalent to print(Category, Importance, Format,
+ Args).</fsummary>
+ <type>
+ <v>X1 = Category | Importance</v>
+ <v>X2 = Importance | Format</v>
+ <v>X3 = Format | Args</v>
+ </type>
+ <desc><marker id="print-3"/>
+ <p>Equivalent to <seealso marker="#print-4"><c>ct:print(Category,
+ Importance, Format, Args)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>print(Category, Importance, Format, Args) -&gt; ok</name>
+ <fsummary>Prints from a test case to the console.</fsummary>
+ <type>
+ <v>Category = atom()</v>
+ <v>Importance = integer()</v>
+ <v>Format = string()</v>
+ <v>Args = list()</v>
+ </type>
+ <desc><marker id="print-4"/>
+ <p>Prints from a test case to the console.</p>
+
+ <p>This function is meant for printing a string from a test case to
+ the console.</p>
+
+ <p>Default <c>Category</c> is <c>default</c>,
+ default <c>Importance</c> is <c>?STD_IMPORTANCE</c>,
+ and default value for <c>Args</c> is <c>[]</c>.</p>
+
+ <p>For details on <c>Category</c> and <c>Importance</c>, see section
+ <seealso marker="write_test_chapter#logging">Logging - Categories
+ and Verbosity Levels</seealso> in the User's Guide.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>reload_config(Required) -&gt; ValueOrElement</name>
+ <fsummary>Reloads configuration file containing specified configuration
+ key.</fsummary>
+ <type>
+ <v>Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}</v>
+ <v>KeyOrName = atom()</v>
+ <v>SubKey = atom()</v>
+ <v>ValueOrElement = term()</v>
+ </type>
+ <desc><marker id="reload_config-1"/>
+ <p>Reloads configuration file containing specified configuration key.</p>
+
+ <p>This function updates the configuration data from which the
+ specified configuration variable was read, and returns the (possibly)
+ new value of this variable.</p>
+
+ <p>If some variables were present in the configuration, but are
+ not loaded using this function, they are removed from the
+ configuration table together with their aliases.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>remove_config(Callback, Config) -&gt; ok</name>
+ <fsummary>Removes configuration variables (together with
+ their aliases) that were loaded with specified callback module and
+ configuration string.</fsummary>
+ <type>
+ <v>Callback = atom()</v>
+ <v>Config = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="remove_config-2"/>
+ <p>Removes configuration variables (together wih their aliases)
+ that were loaded with specified callback module and configuration
+ string.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>require(Required) -&gt; ok | {error, Reason}</name>
+ <fsummary>Checks if the required configuration is available.</fsummary>
+ <type>
+ <v>Required = Key | {Key, SubKeys} | {Key, SubKey, SubKeys}</v>
+ <v>Key = atom()</v>
+ <v>SubKeys = SubKey | [SubKey]</v>
+ <v>SubKey = atom()</v>
+ </type>
+ <desc><marker id="require-1"/>
+ <p>Checks if the required configuration is available. Arbitrarily
+ deep tuples can be specified as <c>Required</c>. Only the last
+ element of the tuple can be a list of <c>SubKey</c>s.</p>
+
+ <p><em>Example 1.</em> Require the variable <c>myvar</c>:</p>
+
+ <pre>
+ ok = ct:require(myvar).</pre>
+
+ <p>In this case the configuration file must at least contain:</p>
+
+ <pre>
+ {myvar,Value}.</pre>
+
+ <p><em>Example 2.</em> Require key <c>myvar</c> with subkeys
+ <c>sub1</c> and <c>sub2</c>:</p>
+
+ <pre>
+ ok = ct:require({myvar,[sub1,sub2]}).</pre>
+
+ <p>In this case the configuration file must at least contain:</p>
+
+ <pre>
+ {myvar,[{sub1,Value},{sub2,Value}]}.</pre>
+
+ <p><em>Example 3.</em> Require key <c>myvar</c> with subkey
+ <c>sub1</c> with <c>subsub1</c>:</p>
+
+ <pre>
+ ok = ct:require({myvar,sub1,sub2}).</pre>
+
+ <p>In this case the configuration file must at least contain:</p>
+
+ <pre>
+ {myvar,[{sub1,[{sub2,Value}]}]}.</pre>
+
+ <p>See also
+ <seealso marker="#get_config-1"><c>ct:get_config/1</c></seealso>,
+ <seealso marker="#get_config-2"><c>ct:get_config/2</c></seealso>,
+ <seealso marker="#get_config-3"><c>ct:get_config/3</c></seealso>,
+ <seealso marker="#require-2"><c>ct:require/2</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>require(Name, Required) -&gt; ok | {error, Reason}</name>
+ <fsummary>Checks if the required configuration is available and gives
+ it a name.</fsummary>
+ <type>
+ <v>Name = atom()</v>
+ <v>Required = Key | {Key, SubKey} | {Key, SubKey, SubKey}</v>
+ <v>SubKey = Key</v>
+ <v>Key = atom()</v>
+ </type>
+ <desc><marker id="require-2"/>
+ <p>Checks if the required configuration is available and gives it a
+ name. The semantics for <c>Required</c> is the same as in
+ <seealso marker="#require-1"><c>ct:require/1</c></seealso> except
+ that a list of <c>SubKey</c>s cannot be specified.</p>
+
+ <p>If the requested data is available, the subentry is associated
+ with <c>Name</c> so that the value of the element can be read with
+ <seealso marker="#get_config-1"><c>ct:get_config/1,2</c></seealso>
+ provided <c>Name</c> is used instead of the whole <c>Required</c>
+ term.</p>
+
+ <p><em>Example:</em></p>
+
+ <p>Require one node with a Telnet connection and an FTP connection.
+ Name the node <c>a</c>:</p>
+
+ <pre>
+ ok = ct:require(a,{machine,node}).</pre>
+
+ <p>All references to this node can then use the node name. For
+ example, a file over FTP is fetched like follows:</p>
+
+ <pre>
+ ok = ct:ftp_get(a,RemoteFile,LocalFile).</pre>
+
+ <p>For this to work, the configuration file must at least contain:</p>
+
+ <pre>
+ {machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.</pre>
+
+ <note><p>The behavior of this function changed radically in
+ <c>Common Test</c> 1.6.2. To keep some backwards compatability,
+ it is still possible to do:<br/>
+ <c>ct:require(a,{node,[telnet,ftp]}).</c><br/>
+ This associates the name <c>a</c> with the top-level <c>node</c>
+ entry. For this to work, the configuration file must at least
+ contain:<br/>
+ <c>{node,[{telnet,IpAddr},{ftp,IpAddr}]}.</c></p>
+ </note>
+
+ <p>See also
+ <seealso marker="#get_config-1"><c>ct:get_config/1</c></seealso>,
+ <seealso marker="#get_config-2"><c>ct:get_config/2</c></seealso>,
+ <seealso marker="#get_config-3"><c>ct:get_config/3</c></seealso>,
+ <seealso marker="#require-1"><c>ct:require/1</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run(TestDirs) -&gt; Result</name>
+ <fsummary>Runs all test cases in all suites in the specified
+ directories.</fsummary>
+ <type>
+ <v>TestDirs = TestDir | [TestDir]</v>
+ </type>
+ <desc><marker id="run-1"/>
+ <p>Runs all test cases in all suites in the specified directories.</p>
+
+ <p>See also <seealso marker="#run-3"><c>ct:run/3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run(TestDir, Suite) -&gt; Result</name>
+ <fsummary>Runs all test cases in the specified suite.</fsummary>
+ <desc><marker id="run-2"/>
+ <p>Runs all test cases in the specified suite.</p>
+
+ <p>See also <seealso marker="#run-3"><c>ct:run/3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run(TestDir, Suite, Cases) -&gt; Result</name>
+ <fsummary>Runs the specified test cases.</fsummary>
+ <type>
+ <v>TestDir = string()</v>
+ <v>Suite = atom()</v>
+ <v>Cases = atom() | [atom()]</v>
+ <v>Result = [TestResult] | {error, Reason}</v>
+ </type>
+ <desc><marker id="run-3"/>
+ <p>Runs the specified test cases.</p>
+
+ <p>Requires that
+ <seealso marker="#install-1"><c>ct:install/1</c></seealso> has been
+ run first.</p>
+
+ <p>Suites (<c>*_SUITE.erl</c>) files must be stored in <c>TestDir</c>
+ or <c>TestDir/test</c>. All suites are compiled when the test is
+ run.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run_test(Opts) -&gt; Result</name>
+ <fsummary>Runs tests as specified by the combination of options in
+ Opts.</fsummary>
+ <type>
+ <v>Opts = [OptTuples]</v>
+ <v>OptTuples = {dir, TestDirs} | {suite, Suites} | {group, Groups} | {testcase, Cases} | {spec, TestSpecs} | {join_specs, Bool} | {label, Label} | {config, CfgFiles} | {userconfig, UserConfig} | {allow_user_terms, Bool} | {logdir, LogDir} | {silent_connections, Conns} | {stylesheet, CSSFile} | {cover, CoverSpecFile} | {cover_stop, Bool} | {step, StepOpts} | {event_handler, EventHandlers} | {include, InclDirs} | {auto_compile, Bool} | {abort_if_missing_suites, Bool} | {create_priv_dir, CreatePrivDir} | {multiply_timetraps, M} | {scale_timetraps, Bool} | {repeat, N} | {duration, DurTime} | {until, StopTime} | {force_stop, ForceStop} | {decrypt, DecryptKeyOrFile} | {refresh_logs, LogDir} | {logopts, LogOpts} | {verbosity, VLevels} | {basic_html, Bool} | {ct_hooks, CTHs} | {enable_builtin_hooks, Bool} | {release_shell, Bool}</v>
+ <v>TestDirs = [string()] | string()</v>
+ <v>Suites = [string()] | [atom()] | string() | atom()</v>
+ <v>Cases = [atom()] | atom()</v>
+ <v>Groups = GroupNameOrPath | [GroupNameOrPath]</v>
+ <v>GroupNameOrPath = [atom()] | atom() | all</v>
+ <v>TestSpecs = [string()] | string()</v>
+ <v>Label = string() | atom()</v>
+ <v>CfgFiles = [string()] | string()</v>
+ <v>UserConfig = [{CallbackMod, CfgStrings}] | {CallbackMod, CfgStrings}</v>
+ <v>CallbackMod = atom()</v>
+ <v>CfgStrings = [string()] | string()</v>
+ <v>LogDir = string()</v>
+ <v>Conns = all | [atom()]</v>
+ <v>CSSFile = string()</v>
+ <v>CoverSpecFile = string()</v>
+ <v>StepOpts = [StepOpt] | []</v>
+ <v>StepOpt = config | keep_inactive</v>
+ <v>EventHandlers = EH | [EH]</v>
+ <v>EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}</v>
+ <v>InitArgs = [term()]</v>
+ <v>InclDirs = [string()] | string()</v>
+ <v>CreatePrivDir = auto_per_run | auto_per_tc | manual_per_tc</v>
+ <v>M = integer()</v>
+ <v>N = integer()</v>
+ <v>DurTime = string(HHMMSS)</v>
+ <v>StopTime = string(YYMoMoDDHHMMSS) | string(HHMMSS)</v>
+ <v>ForceStop = skip_rest | Bool</v>
+ <v>DecryptKeyOrFile = {key, DecryptKey} | {file, DecryptFile}</v>
+ <v>DecryptKey = string()</v>
+ <v>DecryptFile = string()</v>
+ <v>LogOpts = [LogOpt]</v>
+ <v>LogOpt = no_nl | no_src</v>
+ <v>VLevels = VLevel | [{Category, VLevel}]</v>
+ <v>VLevel = integer()</v>
+ <v>Category = atom()</v>
+ <v>CTHs = [CTHModule | {CTHModule, CTHInitArgs}]</v>
+ <v>CTHModule = atom()</v>
+ <v>CTHInitArgs = term()</v>
+ <v>Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | TestRunnerPid | {error, Reason}</v>
+ <v>Ok = integer()</v>
+ <v>Failed = integer()</v>
+ <v>UserSkipped = integer()</v>
+ <v>AutoSkipped = integer()</v>
+ <v>TestRunnerPid = pid()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="run_test-1"/>
+ <p>Runs tests as specified by the combination of options in
+ <c>Opts</c>. The options are the same as those used with program
+ <c>ct_run</c>, see <seealso marker="ct_run#ct_run">Run Tests from
+ Command Line</seealso> in the <c>ct_run</c> manual page.</p>
+ <p>Here a <c>TestDir</c> can be used to point out the path to a
+ <c>Suite</c>. Option <c>testcase</c> corresponds to option
+ <c>-case</c> in program <c>ct_run</c>. Configuration files
+ specified in <c>Opts</c> are installed automatically at startup.</p>
+
+ <p><c>TestRunnerPid</c> is returned if <c>release_shell == true</c>.
+ For details, see
+ <seealso marker="#break-1"><c>ct:break/1</c></seealso>.</p>
+
+ <p><c>Reason</c> indicates the type of error encountered.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run_testspec(TestSpec) -&gt; Result</name>
+ <fsummary>Runs a test specified by TestSpec.</fsummary>
+ <type>
+ <v>TestSpec = [term()]</v>
+ <v>Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | {error, Reason}</v>
+ <v>Ok = integer()</v>
+ <v>Failed = integer()</v>
+ <v>UserSkipped = integer()</v>
+ <v>AutoSkipped = integer()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="run_testspec-1"/>
+ <p>Runs a test specified by <c>TestSpec</c>. The same terms are used
+ as in test specification files.</p>
+
+ <p><c>Reason</c> indicates the type of error encountered.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>sleep(Time) -&gt; ok</name>
+ <fsummary>This function, similar to timer:sleep/1, suspends the
+ test case for a specified time.</fsummary>
+ <type>
+ <v>Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity</v>
+ <v>Hours = integer()</v>
+ <v>Mins = integer()</v>
+ <v>Secs = integer()</v>
+ <v>Millisecs = integer() | float()</v>
+ </type>
+ <desc><marker id="sleep-1"/>
+ <p>This function, similar to <c>timer:sleep/1</c> in <c>STDLIB</c>,
+ suspends the test case for a specified time.
+ However, this function also multiplies <c>Time</c> with the
+ <c>multiply_timetraps</c> value (if set) and under certain
+ circumstances also scales up the time automatically if
+ <c>scale_timetraps</c> is set to <c>true</c> (default is
+ <c>false</c>).</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>start_interactive() -&gt; ok</name>
+ <fsummary>Starts <c>Common Test</c> in interactive mode.</fsummary>
+ <desc><marker id="start_interactive-0"/>
+ <p>Starts <c>Common Test</c> in interactive mode.</p>
+
+ <p>From this mode, all test case support functions can be executed
+ directly from the Erlang shell. The interactive mode can also be
+ started from the OS command line with <c>ct_run -shell
+ [-config File...]</c>.</p>
+
+ <p>If any functions (for example, Telnet or FTP) using
+ "required configuration data" are to be called from the Erlang shell,
+ configuration data must first be required with
+ <seealso marker="#require-2"><c>ct:require/2</c></seealso>.</p>
+
+ <p><em>Example:</em></p>
+
+ <pre>
+ &gt; ct:require(unix_telnet, unix).
+ ok
+ &gt; ct_telnet:open(unix_telnet).
+ {ok,&lt;0.105.0&gt;}
+ &gt; ct_telnet:cmd(unix_telnet, "ls .").
+ {ok,["ls","file1 ...",...]}</pre>
+ </desc>
+ </func>
+
+ <func>
+ <name>step(TestDir, Suite, Case) -&gt; Result</name>
+ <fsummary>Steps through a test case with the debugger.</fsummary>
+ <type>
+ <v>Case = atom()</v>
+ </type>
+ <desc><marker id="step-3"/>
+ <p>Steps through a test case with the debugger.</p>
+
+ <p>See also <seealso marker="#run-3"><c>ct:run/3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>step(TestDir, Suite, Case, Opts) -&gt; Result</name>
+ <fsummary>Steps through a test case with the debugger.</fsummary>
+ <type>
+ <v>Case = atom()</v>
+ <v>Opts = [Opt] | []</v>
+ <v>Opt = config | keep_inactive</v>
+ </type>
+ <desc><marker id="step-4"/>
+ <p>Steps through a test case with the debugger. If option
+ <c>config</c> has been specifed, breakpoints are also set on
+ the configuration functions in <c>Suite</c>.</p>
+
+ <p>See also <seealso marker="#run-3"><c>ct:run/3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>stop_interactive() -&gt; ok</name>
+ <fsummary>Exits the interactive mode.</fsummary>
+ <desc><marker id="stop_interactive-0"/>
+ <p>Exits the interactive mode.</p>
+
+ <p>See also
+ <seealso marker="#start_interactive-0"><c>ct:start_interactive/0</c></seealso>.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>sync_notify(Name, Data) -&gt; ok</name>
+ <fsummary>Sends a synchronous notification of type Name with Data to
+ the <c>Common Test</c> event manager.</fsummary>
+ <type>
+ <v>Name = atom()</v>
+ <v>Data = term()</v>
+ </type>
+ <desc><marker id="sync_notify-2"/>
+ <p>Sends a synchronous notification of type <c>Name</c> with
+ <c>Data</c> to the <c>Common Test</c> event manager. This can later be
+ caught by any installed event manager.</p>
+
+ <p>See also
+ <seealso marker="stdlib:gen_event"><c>stdlib:gen_event(3)</c></seealso>.
+ </p>
+ </desc>
+ </func>
+
+ <func>
+ <name>testcases(TestDir, Suite) -&gt; Testcases | {error, Reason}</name>
+ <fsummary>Returns all test cases in the specified suite.</fsummary>
+ <type>
+ <v>TestDir = string()</v>
+ <v>Suite = atom()</v>
+ <v>Testcases = list()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="testcases-2"/>
+ <p>Returns all test cases in the specified suite.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>timetrap(Time) -&gt; ok</name>
+ <fsummary>Sets a new timetrap for the running test case.</fsummary>
+ <type>
+ <v>Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity | Func</v>
+ <v>Hours = integer()</v>
+ <v>Mins = integer()</v>
+ <v>Secs = integer()</v>
+ <v>Millisecs = integer() | float()</v>
+ <v>Func = {M, F, A} | function()</v>
+ <v>M = atom()</v>
+ <v>F = atom()</v>
+ <v>A = list()</v>
+ </type>
+ <desc><marker id="timetrap-1"/>
+ <p>Sets a new timetrap for the running test case.</p>
+
+ <p>If the argument is <c>Func</c>, the timetrap is triggered when
+ this function returns. <c>Func</c> can also return a new
+ <c>Time</c> value, which in that case is the value for the new
+ timetrap.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>userdata(TestDir, Suite) -&gt; SuiteUserData | {error, Reason}</name>
+ <fsummary>Returns any data specified with tag userdata in the list of
+ tuples returned from Suite:suite/0.</fsummary>
+ <type>
+ <v>TestDir = string()</v>
+ <v>Suite = atom()</v>
+ <v>SuiteUserData = [term()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="userdata-2"/>
+ <p>Returns any data specified with tag <c>userdata</c> in the list
+ of tuples returned from
+ <seealso marker="#Module:suite-0"><c>suite/0</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>userdata(TestDir, Suite, Case::GroupOrCase) -&gt; TCUserData | {error, Reason}</name>
+ <fsummary>Returns any data specified with tag userdata in the list of
+ tuples returned from Suite:group(GroupName) or Suite:Case().</fsummary>
+ <type>
+ <v>TestDir = string()</v>
+ <v>Suite = atom()</v>
+ <v>GroupOrCase = {group, GroupName} | atom()</v>
+ <v>GroupName = atom()</v>
+ <v>TCUserData = [term()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="userdata-3"/>
+ <p>Returns any data specified with tag <c>userdata</c> in the list
+ of tuples returned from <c>Suite:group(GroupName)</c> or
+ <c>Suite:Case()</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ct_cover.xml b/lib/common_test/doc/src/ct_cover.xml
new file mode 100644
index 0000000000..be09c08a68
--- /dev/null
+++ b/lib/common_test/doc/src/ct_cover.xml
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct_cover</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct_cover.xml</file>
+ </header>
+ <module>ct_cover</module>
+ <modulesummary>Common Test framework code coverage support module.
+ </modulesummary>
+
+<description>
+
+ <p><c>Common Test</c> framework code coverage support module.</p>
+
+ <p>This module exports help functions for performing code coverage
+ analysis.</p>
+
+</description>
+
+ <funcs>
+ <func>
+ <name>add_nodes(Nodes) -&gt; {ok, StartedNodes} | {error, Reason}</name>
+ <fsummary>Adds nodes to current cover test (only works if cover support
+ is active).</fsummary>
+ <type>
+ <v>Nodes = [atom()]</v>
+ <v>StartedNodes = [atom()]</v>
+ <v>Reason = cover_not_running | not_main_node</v>
+ </type>
+ <desc><marker id="add_nodes-1"/>
+ <p>Adds nodes to current cover test. Notice that this only works if
+ cover support is active.</p>
+
+ <p>To have effect, this function is to be called from
+ <c>init_per_suite/1</c> (see
+ <seealso marker="common_test"><c>common_test</c></seealso>)
+ before any tests are performed.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>cross_cover_analyse(Level, Tests) -&gt; ok</name>
+ <fsummary>Accumulates cover results over multiple tests.</fsummary>
+ <type>
+ <v>Level = overview | details</v>
+ <v>Tests = [{Tag, Dir}]</v>
+ <v>Tag = atom()</v>
+ <v>Dir = string()</v>
+ </type>
+ <desc><marker id="cross_cover_analyse-2"/>
+ <p>Accumulates cover results over multiple tests. See section
+ <seealso marker="cover_chapter#cross_cover">Cross Cover
+ Analysis</seealso> in the Users's Guide.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>remove_nodes(Nodes) -&gt; ok | {error, Reason}</name>
+ <fsummary>Removes nodes from the current cover test.</fsummary>
+ <type>
+ <v>Nodes = [atom()]</v>
+ <v>Reason = cover_not_running | not_main_node</v>
+ </type>
+ <desc><marker id="remove_nodes-1"/>
+ <p>Removes nodes from the current cover test.</p>
+
+ <p>Call this function to stop cover test on nodes previously
+ added with
+ <seealso marker="#add_nodes-1"><c>ct_cover:add_nodes/1</c></seealso>.
+ Results on the remote node are transferred to the <c>Common Test</c>
+ node.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ct_ftp.xml b/lib/common_test/doc/src/ct_ftp.xml
new file mode 100644
index 0000000000..0598dcbe3e
--- /dev/null
+++ b/lib/common_test/doc/src/ct_ftp.xml
@@ -0,0 +1,277 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct_ftp</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct_ftp.xml</file>
+ </header>
+ <module>ct_ftp</module>
+ <modulesummary>FTP client module (based on the FTP support of the Inets
+ application).</modulesummary>
+
+ <description>
+
+ <p>FTP client module (based on the FTP support of the <c>Inets</c>
+ application).</p>
+
+ </description>
+
+ <section>
+ <title>Data Types</title>
+ <marker id="types"/>
+ <taglist>
+ <tag><c>connection() = handle() | target_name()</c></tag>
+ <item><marker id="type-connection"/>
+ <p>For <c>target_name</c>, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p></item>
+
+ <tag><c>handle() = handle()</c></tag>
+ <item><marker id="type-handle"/>
+ <p>Handle for a specific FTP connection, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p></item>
+ </taglist>
+ </section>
+
+ <funcs>
+ <func>
+ <name>cd(Connection, Dir) -&gt; ok | {error, Reason}</name>
+ <fsummary>Changes directory on remote host.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>Dir = string()</v>
+ </type>
+ <desc><marker id="cd-2"/>
+ <p>Changes directory on remote host.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>close(Connection) -&gt; ok | {error, Reason}</name>
+ <fsummary>Closes the FTP connection.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ </type>
+ <desc><marker id="close-1"/>
+ <p>Closes the FTP connection.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>delete(Connection, File) -&gt; ok | {error, Reason}</name>
+ <fsummary>Deletes a file on remote host.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>File = string()</v>
+ </type>
+ <desc><marker id="delete-2"/>
+ <p>Deletes a file on remote host.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get(KeyOrName, RemoteFile, LocalFile) -&gt; ok | {error, Reason}</name>
+ <fsummary>Opens an FTP connection and fetches a file from the remote
+ host.</fsummary>
+ <type>
+ <v>KeyOrName = Key | Name</v>
+ <v>Key = atom()</v>
+ <v>Name = target_name()</v>
+ <v>RemoteFile = string()</v>
+ <v>LocalFile = string()</v>
+ </type>
+ <desc><marker id="get-3"/>
+ <p>Opens an FTP connection and fetches a file from the remote
+ host.</p>
+
+ <p><c>RemoteFile</c> and <c>LocalFile</c> must be absolute paths.</p>
+
+ <p>The configuration file must be as for
+ <seealso marker="#put-3"><c>ct_ftp:put/3</c></seealso>.</p>
+
+ <p>For <c>target_name</c>, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p>
+
+ <p>See also
+ <seealso marker="ct#require-2"><c>ct:require/2</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>ls(Connection, Dir) -&gt; {ok, Listing} | {error, Reason}</name>
+ <fsummary>Lists directory Dir.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>Dir = string()</v>
+ <v>Listing = string()</v>
+ </type>
+ <desc><marker id="ls-2"/>
+ <p>Lists directory <c>Dir</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>open(KeyOrName) -&gt; {ok, Handle} | {error, Reason}</name>
+ <fsummary>Opens an FTP connection to the specified node.</fsummary>
+ <type>
+ <v>KeyOrName = Key | Name</v>
+ <v>Key = atom()</v>
+ <v>Name = target_name()</v>
+ <v>Handle = handle()</v>
+ </type>
+ <desc><marker id="open-1"/>
+ <p>Opens an FTP connection to the specified node.</p>
+
+ <p>You can open a connection for a particular <c>Name</c> and use the
+ same name as reference for all following subsequent operations.
+ If you want
+ the connection to be associated with <c>Handle</c> instead (if you,
+ for example, need to open multiple connections to a host), use
+ <c>Key</c>, the configuration variable name, to specify the target.
+ A connection without an associated target name can only be closed
+ with the handle value.</p>
+
+ <p>For information on how to create a new <c>Name</c>, see
+ <seealso marker="ct#require-2"><c>ct:require/2</c></seealso>.</p>
+
+ <p>For <c>target_name</c>, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>put(KeyOrName, LocalFile, RemoteFile) -&gt; ok | {error, Reason}</name>
+ <fsummary>Opens an FTP connection and sends a file to the remote
+ host.</fsummary>
+ <type>
+ <v>KeyOrName = Key | Name</v>
+ <v>Key = atom()</v>
+ <v>Name = target_name()</v>
+ <v>LocalFile = string()</v>
+ <v>RemoteFile = string()</v>
+ </type>
+ <desc><marker id="put-3"/>
+ <p>Opens an FTP connection and sends a file to the remote host.</p>
+
+ <p><c>LocalFile</c> and <c>RemoteFile</c> must be absolute paths.</p>
+
+ <p>For <c>target_name</c>, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p>
+
+ <p>If the target host is a "special" node, the FTP address must be
+ specified in the configuration file as follows:</p>
+
+ <pre>
+ {node,[{ftp,IpAddr}]}.</pre>
+
+ <p>If the target host is something else, for example, a UNIX host,
+ the configuration file must also include the username and password
+ (both strings):</p>
+
+ <pre>
+ {unix,[{ftp,IpAddr},
+ {username,Username},
+ {password,Password}]}.</pre>
+
+ <p>See also
+ <seealso marker="ct#require-2"><c>ct:require/2</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>recv(Connection, RemoteFile) -&gt; ok | {error, Reason}</name>
+ <fsummary>Fetches a file over FTP.</fsummary>
+ <desc><marker id="recv-2"/>
+ <p>Fetches a file over FTP.</p>
+
+ <p>The file gets the same name on the local host.</p>
+
+ <p>See also <seealso marker="#recv-3"><c>ct_ftp:recv/3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>recv(Connection, RemoteFile, LocalFile) -&gt; ok | {error, Reason}</name>
+ <fsummary>Fetches a file over FTP.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>RemoteFile = string()</v>
+ <v>LocalFile = string()</v>
+ </type>
+ <desc><marker id="recv-3"/>
+ <p>Fetches a file over FTP.</p>
+
+ <p>The file is named <c>LocalFile</c> on the local host.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(Connection, LocalFile) -&gt; ok | {error, Reason}</name>
+ <fsummary>Sends a file over FTP.</fsummary>
+ <desc><marker id="send-2"/>
+ <p>Sends a file over FTP.</p>
+
+ <p>The file gets the same name on the remote host.</p>
+
+ <p>See also
+ <seealso marker="#send-3"><c>ct_ftp:send/3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(Connection, LocalFile, RemoteFile) -&gt; ok | {error, Reason}</name>
+ <fsummary>Sends a file over FTP.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>LocalFile = string()</v>
+ <v>RemoteFile = string()</v>
+ </type>
+ <desc><marker id="send-3"/>
+ <p>Sends a file over FTP.</p>
+
+ <p>The file is named <c>RemoteFile</c> on the remote host.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>type(Connection, Type) -&gt; ok | {error, Reason}</name>
+ <fsummary>Changes the file transfer type.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>Type = ascii | binary</v>
+ </type>
+ <desc><marker id="type-2"/>
+ <p>Changes the file transfer type.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ct_hooks.xml b/lib/common_test/doc/src/ct_hooks.xml
index a9f9450dd7..9c959945d2 100644
--- a/lib/common_test/doc/src/ct_hooks.xml
+++ b/lib/common_test/doc/src/ct_hooks.xml
@@ -1,5 +1,4 @@
<?xml version="1.0" encoding="UTF-8" ?>
-
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
@@ -12,7 +11,7 @@
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
-
+
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
@@ -34,539 +33,515 @@
<file>ct_hooks.sgml</file>
</header>
<module>ct_hooks</module>
- <modulesummary>A callback interface on top of Common Test</modulesummary>
+ <modulesummary>A callback interface on top of Common Test.</modulesummary>
<description>
- <p>The <em>Common Test Hook</em> (henceforth called CTH) framework allows
- extensions of the default behaviour of Common Test by means of callbacks
- before and after all test suite calls. It is meant for advanced users of
- Common Test which want to abstract out behaviour which is common to
- multiple test suites. </p>
+ <p>The <em>Common Test Hook (CTH)</em> framework allows extensions of the
+ default behavior of <c>Common Test</c> by callbacks before and after all
+ test suite calls. It is intended for advanced users of <c>Common Test</c>
+ who want to abstract out behavior that is common to multiple test suites.
+ </p>
- <p>In brief, Common Test Hooks allows you to:</p>
+ <p>In brief, CTH allows you to:</p>
- <list>
- <item>Manipulate the runtime config before each suite
- configuration call</item>
- <item>Manipulate the return of all suite configuration calls and in
- extension the result of the test themselves.</item>
+ <list type="bulleted">
+ <item><p>Manipulate the runtime configuration before each suite
+ configuration call.</p></item>
+ <item><p>Manipulate the return of all suite configuration calls and by
+ extension the result of the test themselves.</p></item>
</list>
<p>The following sections describe the mandatory and optional CTH
- functions Common Test will call during test execution. For more details
- see <seealso marker="ct_hooks_chapter">Common Test Hooks</seealso> in
- the User's Guide.</p>
+ functions that <c>Common Test</c> calls during test execution.
+ For more details, see section
+ <seealso marker="ct_hooks_chapter">Common Test Hooks</seealso> in the
+ User's Guide.</p>
- <p>For information about how to add a CTH to your suite see
- <seealso marker="ct_hooks_chapter#installing">Installing a CTH
- </seealso> in the User's Guide.</p>
+ <p>For information about how to add a CTH to your suite, see section
+ <seealso marker="ct_hooks_chapter#installing">Installing a CTH</seealso>
+ in the User's Guide.</p>
+
+ <note><p>For a minimal example of a CTH, see section
+ <seealso marker="ct_hooks_chapter#example">Example CTH</seealso>
+ in the User's Guide.</p></note>
- <note><p>See the
- <seealso marker="ct_hooks_chapter#example">Example CTH</seealso>
- in the User's Guide for a minimal example of a CTH. </p></note>
-
</description>
<section>
- <title>CALLBACK FUNCTIONS</title>
- <p>The following functions define the callback interface
- for a Common Test Hook.</p>
+ <title>Callback Functions</title>
+ <p>The following functions define the callback interface for a CTH.</p>
</section>
<funcs>
<func>
- <name>Module:init(Id, Opts) -&gt; {ok, State} |
- {ok, State, Priority}</name>
- <fsummary>Initiates the Common Test Hook</fsummary>
+ <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>
+ <v>Id = reference() | term()</v>
+ <v>Opts = term()</v>
+ <v>State = term()</v>
+ <v>Priority = integer()</v>
</type>
-
<desc>
- <p> MANDATORY </p>
-
- <p>Always called before any other callback function.
- Use this to initiate any common state.
- It should return a state for this CTH.</p>
-
- <p><c>Id</c> is the return value of
- <seealso marker="#Module:id-1">id/1</seealso>, or a <c>reference</c>
- (created using
- <seealso marker="erts:erlang#make_ref-0">make_ref/0</seealso>)
- 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>
-
+ <p>MANDATORY</p>
+
+ <p>This function is always called before any other callback function.
+ Use it to initiate any common state. It is to return a state for
+ this CTH.</p>
+
+ <p><c>Id</c> is either the return value of
+ <seealso marker="#Module:id-1"><c>ct_hooks:id/1</c></seealso>,
+ or a <c>reference</c> (created using
+ <seealso marker="erts:erlang#make_ref-0">erlang:make_ref/0</seealso>
+ in <c>ERTS</c>) if
+ <seealso marker="#Module:id-1"><c>ct_hooks:id/1</c></seealso>
+ is not implemented.</p>
+
+ <p><c>Priority</c> is the relative priority of this hook. Hooks with a
+ lower priority are executed first. If no priority is specified, it
+ is set to <c>0</c>.</p>
+
+ <p>For details about when <c>init</c> is called, see section
+ <seealso marker="ct_hooks_chapter#scope">CTH Scope</seealso>
+ in the User's Guide.</p>
</desc>
</func>
<func>
- <name>Module:pre_init_per_suite(SuiteName, InitData, CTHState) -&gt;
- Result</name>
- <fsummary>Called before init_per_suite</fsummary>
+ <name>Module:pre_init_per_suite(SuiteName, InitData, CTHState) -&gt; Result</name>
+ <fsummary>Called before init_per_suite.</fsummary>
<type>
- <v>SuiteName = atom()</v>
- <v>InitData = Config | SkipOrFail</v>
- <v>Config = NewConfig = [{Key,Value}]</v>
- <v>CTHState = NewCTHState = term()</v>
- <v>Result = {Return, NewCTHState}</v>
- <v>Return = NewConfig | SkipOrFail</v>
- <v>SkipOrFail = {fail, Reason} | {skip, Reason}</v>
- <v>Key = atom()</v>
- <v>Value = term()</v>
- <v>Reason = term()</v>
+ <v>SuiteName = atom()</v>
+ <v>InitData = Config | SkipOrFail</v>
+ <v>Config = NewConfig = [{Key,Value}]</v>
+ <v>CTHState = NewCTHState = term()</v>
+ <v>Result = {Return, NewCTHState}</v>
+ <v>Return = NewConfig | SkipOrFail</v>
+ <v>SkipOrFail = {fail, Reason} | {skip, Reason}</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called before
- <seealso marker="common_test#Module:init_per_suite-1">
- init_per_suite</seealso> if it exists.
- It typically contains initialization/logging which needs to be done
- before init_per_suite is called.
- If <c>{skip,Reason}</c> or <c>{fail,Reason}</c> is returned,
- init_per_suite and all test cases of the suite will be skipped and
- Reason printed in the overview log of the suite.</p>
-
- <p><c>SuiteName</c> is the name of the suite to be run.</p>
-
- <p><c>InitData</c> is the original config list of the test suite, or
- a <c>SkipOrFail</c> tuple if a previous CTH has returned this.</p>
-
- <p><c>CTHState</c> is the current internal state of the CTH.</p>
-
- <p><c>Return</c> is the result of the init_per_suite function.
- If it is <c>{skip,Reason}</c> or <c>{fail,Reason}</c>
- <seealso marker="common_test#Module:init_per_suite-1">init_per_suite
- </seealso> will never be called, instead the initiation is considered
- to be skipped/failed respectively. If a <c>NewConfig</c> list
- is returned, <seealso marker="common_test#Module:init_per_suite-1">
- init_per_suite</seealso> will be called with that <c>NewConfig</c> list.
- See <seealso marker="ct_hooks_chapter#pre">
- Pre Hooks</seealso> in the User's Guide for more details.</p>
-
-
- <p>Note that this function is only called if the CTH has been added
- before init_per_suite is run, see
- <seealso marker="ct_hooks_chapter#scope">CTH Scoping</seealso>
- in the User's Guide for details.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called before
+ <seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso>
+ if it exists. It typically contains initialization/logging that must
+ be done before <c>init_per_suite</c> is called. If
+ <c>{skip,Reason}</c> or <c>{fail,Reason}</c> is returned,
+ <c>init_per_suite</c> and all test cases of the suite are skipped
+ and <c>Reason</c> printed in the overview log of the suite.</p>
+
+ <p><c>SuiteName</c> is the name of the suite to be run.</p>
+
+ <p><c>InitData</c> is the original configuration list of the test
+ suite, or a <c>SkipOrFail</c> tuple if a previous CTH has returned
+ this.</p>
+
+ <p><c>CTHState</c> is the current internal state of the CTH.</p>
+
+ <p><c>Return</c> is the result of the <c>init_per_suite</c> function.
+ If it is <c>{skip,Reason}</c> or <c>{fail,Reason}</c>,
+ <seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso>
+ is never called, instead the initiation is considered to be
+ skipped or failed, respectively. If a <c>NewConfig</c> list is
+ returned,
+ <seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso>
+ is called with that <c>NewConfig</c> list. For more details, see
+ section <seealso marker="ct_hooks_chapter#pre">Pre Hooks</seealso>
+ in the User's Guide.</p>
+
+ <p>This function is called only if the CTH is added before
+ <c>init_per_suite is run</c>. For details, see section
+ <seealso marker="ct_hooks_chapter#scope">CTH Scope</seealso>
+ in the User's Guide.</p>
</desc>
</func>
-
+
<func>
- <name>Module:post_init_per_suite(SuiteName, Config, Return, CTHState) -&gt;
- Result</name>
- <fsummary>Called after init_per_suite</fsummary>
+ <name>Module:post_init_per_suite(SuiteName, Config, Return, CTHState) -&gt; Result</name>
+ <fsummary>Called after init_per_suite.</fsummary>
<type>
- <v>SuiteName = atom()</v>
- <v>Config = [{Key,Value}]</v>
- <v>Return = NewReturn = Config | SkipOrFail | term()</v>
- <v>SkipOrFail = {fail, Reason} | {skip, Reason} | term()</v>
- <v>CTHState = NewCTHState = term()</v>
- <v>Result = {NewReturn, NewCTHState}</v>
- <v>Key = atom()</v>
- <v>Value = term()</v>
- <v>Reason = term()</v>
+ <v>SuiteName = atom()</v>
+ <v>Config = [{Key,Value}]</v>
+ <v>Return = NewReturn = Config | SkipOrFail | term()</v>
+ <v>SkipOrFail = {fail, Reason} | {skip, Reason} | term()</v>
+ <v>CTHState = NewCTHState = term()</v>
+ <v>Result = {NewReturn, NewCTHState}</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called after
- <seealso marker="common_test#Module:init_per_suite-1">
- init_per_suite</seealso> if it exists. It typically contains extra
- checks to make sure that all the correct dependencies have
- been started correctly.</p>
-
- <p><c>Return</c> is what
- <seealso marker="common_test#Module:init_per_suite-1">init_per_suite
- </seealso> returned, i.e. {fail,Reason}, {skip,Reason}, a <c>Config</c>
- list or a term describing how
- <seealso marker="common_test#Module:init_per_suite-1">init_per_suite
- </seealso> failed.</p>
-
- <p><c>NewReturn</c> is the possibly modified return value of
- <seealso marker="common_test#Module:init_per_suite-1">init_per_suite
- </seealso>. It is here possible to recover from a failure in
- <seealso marker="common_test#Module:init_per_suite-1">init_per_suite
- </seealso> by returning the <c>ConfigList</c> with the <c>tc_status</c>
- element removed. See <seealso marker="ct_hooks_chapter#post">
- Post Hooks</seealso> in the User's Guide for more details.</p>
-
- <p><c>CTHState</c> is the current internal state of the CTH.</p>
-
- <p>Note that this function is only called if the CTH has been added
- before or in init_per_suite, see
- <seealso marker="ct_hooks_chapter#scope">CTH Scoping</seealso>
- in the User's Guide for details.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called after
+ <seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso>
+ if it exists. It typically contains extra checks to ensure that all
+ the correct dependencies are started correctly.</p>
+
+ <p><c>Return</c> is what
+ <seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso>
+ returned, that is, <c>{fail,Reason}</c>, <c>{skip,Reason}</c>, a
+ <c>Config</c> list, or a term describing how
+ <seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso>
+ failed.</p>
+
+ <p><c>NewReturn</c> is the possibly modified return value of
+ <seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso>.
+ To recover from a failure in
+ <seealso marker="common_test#Module:init_per_suite-1"><c>init_per_suite</c></seealso>,
+ return <c>ConfigList</c> with the <c>tc_status</c> element removed.
+ For more details, see
+ <seealso marker="ct_hooks_chapter#post"> Post Hooks</seealso> in
+ section "Manipulating Tests" in the User's Guide.</p>
+
+ <p><c>CTHState</c> is the current internal state of the CTH.</p>
+
+ <p>This function is called only if the CTH is added before or in
+ <c>init_per_suite</c>. For details, see section
+ <seealso marker="ct_hooks_chapter#scope">CTH Scope</seealso>
+ in the User's Guide.</p>
</desc>
</func>
-
+
<func>
- <name>Module:pre_init_per_group(GroupName, InitData, CTHState) -&gt;
- Result</name>
- <fsummary>Called before init_per_group</fsummary>
+ <name>Module:pre_init_per_group(GroupName, InitData, CTHState) -&gt; Result</name>
+ <fsummary>Called before init_per_group.</fsummary>
<type>
- <v>GroupName = atom()</v>
- <v>InitData = Config | SkipOrFail</v>
- <v>Config = NewConfig = [{Key,Value}]</v>
- <v>CTHState = NewCTHState = term()</v>
- <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
- <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
- <v>Key = atom()</v>
- <v>Value = term()</v>
- <v>Reason = term()</v>
+ <v>GroupName = atom()</v>
+ <v>InitData = Config | SkipOrFail</v>
+ <v>Config = NewConfig = [{Key,Value}]</v>
+ <v>CTHState = NewCTHState = term()</v>
+ <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
+ <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called before
- <seealso marker="common_test#Module:init_per_group-2">
- init_per_group</seealso> if it exists. It behaves the same way as
- <seealso marker="ct_hooks#Module:pre_init_per_suite-3">
- pre_init_per_suite</seealso>, but for the
- <seealso marker="common_test#Module:init_per_group-2">
- init_per_group</seealso> instead.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called before
+ <seealso marker="common_test#Module:init_per_group-2"><c>init_per_group</c></seealso>
+ if it exists. It behaves the same way as
+ <seealso marker="ct_hooks#Module:pre_init_per_suite-3"><c>pre_init_per_suite</c></seealso>,
+ but for function
+ <seealso marker="common_test#Module:init_per_group-2"><c>init_per_group</c></seealso>
+ instead.</p>
</desc>
</func>
-
+
<func>
- <name>Module:post_init_per_group(GroupName, Config, Return, CTHState) -&gt;
- Result</name>
- <fsummary>Called after init_per_group</fsummary>
+ <name>Module:post_init_per_group(GroupName, Config, Return, CTHState) -&gt; Result</name>
+ <fsummary>Called after init_per_group.</fsummary>
<type>
- <v>GroupName = atom()</v>
- <v>Config = [{Key,Value}]</v>
- <v>Return = NewReturn = Config | SkipOrFail | term()</v>
- <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
- <v>CTHState = NewCTHState = term()</v>
- <v>Result = {NewReturn, NewCTHState}</v>
- <v>Key = atom()</v>
- <v>Value = term()</v>
- <v>Reason = term()</v>
+ <v>GroupName = atom()</v>
+ <v>Config = [{Key,Value}]</v>
+ <v>Return = NewReturn = Config | SkipOrFail | term()</v>
+ <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
+ <v>CTHState = NewCTHState = term()</v>
+ <v>Result = {NewReturn, NewCTHState}</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called after
- <seealso marker="common_test#Module:init_per_group-2">
- init_per_group</seealso> if it exists. It behaves the same way as
- <seealso marker="ct_hooks#Module:post_init_per_suite-4">
- post_init_per_suite</seealso>, but for the
- <seealso marker="common_test#Module:init_per_group-2">
- init_per_group</seealso> instead.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called after
+ <seealso marker="common_test#Module:init_per_group-2"><c>init_per_group</c></seealso>
+ if it exists. It behaves the same way as
+ <seealso marker="ct_hooks#Module:post_init_per_suite-4"><c>post_init_per_suite</c></seealso>,
+ but for function
+ <seealso marker="common_test#Module:init_per_group-2"><c>init_per_group</c></seealso>
+ instead.</p>
</desc>
</func>
<func>
- <name>Module:pre_init_per_testcase(TestcaseName, InitData, CTHState) -&gt;
- Result</name>
- <fsummary>Called before init_per_testcase</fsummary>
+ <name>Module:pre_init_per_testcase(TestcaseName, InitData, CTHState) -&gt; Result</name>
+ <fsummary>Called before init_per_testcase.</fsummary>
<type>
- <v>TestcaseName = atom()</v>
- <v>InitData = Config | SkipOrFail</v>
- <v>Config = NewConfig = [{Key,Value}]</v>
- <v>CTHState = NewCTHState = term()</v>
- <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
- <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
- <v>Key = atom()</v>
- <v>Value = term()</v>
- <v>Reason = term()</v>
+ <v>TestcaseName = atom()</v>
+ <v>InitData = Config | SkipOrFail</v>
+ <v>Config = NewConfig = [{Key,Value}]</v>
+ <v>CTHState = NewCTHState = term()</v>
+ <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
+ <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called before
- <seealso marker="common_test#Module:init_per_testcase-2">
- init_per_testcase</seealso> if it exists. It behaves the same way as
- <seealso marker="ct_hooks#Module:pre_init_per_suite-3">
- pre_init_per_suite</seealso>, but for the
- <seealso marker="common_test#Module:init_per_testcase-2">
- init_per_testcase</seealso> function instead.</p>
-
- <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 compatibility.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called before
+ <seealso marker="common_test#Module:init_per_testcase-2"><c>init_per_testcase</c></seealso>
+ if it exists. It behaves the same way as
+ <seealso marker="ct_hooks#Module:pre_init_per_suite-3"><c>pre_init_per_suite</c></seealso>,
+ but for function
+ <seealso marker="common_test#Module:init_per_testcase-2"><c>init_per_testcase</c></seealso>
+ instead.</p>
+
+ <p>CTHs cannot be added here right now. That feature may be added in
+ a later release, but it would right now break backwards
+ compatibility.</p>
</desc>
</func>
<func>
- <name>Module:post_end_per_testcase(TestcaseName, Config, Return, CTHState)
- -&gt; Result</name>
- <fsummary>Called after end_per_testcase</fsummary>
+ <name>Module:post_end_per_testcase(TestcaseName, Config, Return, CTHState) -&gt; Result</name>
+ <fsummary>Called after end_per_testcase.</fsummary>
<type>
- <v>TestcaseName = atom()</v>
- <v>Config = [{Key,Value}]</v>
- <v>Return = NewReturn = Config | SkipOrFail | term()</v>
- <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
- <v>CTHState = NewCTHState = term()</v>
- <v>Result = {NewReturn, NewCTHState}</v>
- <v>Key = atom()</v>
- <v>Value = term()</v>
- <v>Reason = term()</v>
+ <v>TestcaseName = atom()</v>
+ <v>Config = [{Key,Value}]</v>
+ <v>Return = NewReturn = Config | SkipOrFail | term()</v>
+ <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
+ <v>CTHState = NewCTHState = term()</v>
+ <v>Result = {NewReturn, NewCTHState}</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called after
- <seealso marker="common_test#Module:end_per_testcase-2">
- end_per_testcase</seealso> if it exists. It behaves the same way as
- <seealso marker="ct_hooks#Module:post_init_per_suite-4">
- post_init_per_suite</seealso>, but for the
- <seealso marker="common_test#Module:end_per_testcase-2">
- end_per_testcase</seealso> function instead.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called after
+ <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso>
+ if it exists. It behaves the same way as
+ <seealso marker="ct_hooks#Module:post_init_per_suite-4"><c>post_init_per_suite</c></seealso>,
+ but for function
+ <seealso marker="common_test#Module:end_per_testcase-2"><c>end_per_testcase</c></seealso>
+ instead.</p>
</desc>
</func>
<func>
- <name>Module:pre_end_per_group(GroupName, EndData, CTHState) -&gt;
- Result</name>
- <fsummary>Called before end_per_group</fsummary>
+ <name>Module:pre_end_per_group(GroupName, EndData, CTHState) -&gt; Result</name>
+ <fsummary>Called before end_per_group.</fsummary>
<type>
- <v>GroupName = atom()</v>
- <v>EndData = Config | SkipOrFail</v>
- <v>Config = NewConfig = [{Key,Value}]</v>
- <v>CTHState = NewCTHState = term()</v>
- <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
- <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
- <v>Key = atom()</v>
- <v>Value = term()</v>
- <v>Reason = term()</v>
+ <v>GroupName = atom()</v>
+ <v>EndData = Config | SkipOrFail</v>
+ <v>Config = NewConfig = [{Key,Value}]</v>
+ <v>CTHState = NewCTHState = term()</v>
+ <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
+ <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called before
- <seealso marker="common_test#Module:end_per_group-2">
- end_per_group</seealso> if it exists. It behaves the same way as
- <seealso marker="ct_hooks#Module:pre_init_per_suite-3">
- pre_init_per_suite</seealso>, but for the
- <seealso marker="common_test#Module:end_per_group-2">
- end_per_group</seealso> function instead.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called before
+ <seealso marker="common_test#Module:end_per_group-2"><c>end_per_group</c></seealso>
+ if it exists. It behaves the same way as
+ <seealso marker="ct_hooks#Module:pre_init_per_suite-3"><c>pre_init_per_suite</c></seealso>,
+ but for function
+ <seealso marker="common_test#Module:end_per_group-2"><c>end_per_group</c></seealso>
+ instead.</p>
</desc>
</func>
<func>
- <name>Module:post_end_per_group(GroupName, Config, Return, CTHState) -&gt;
- Result</name>
- <fsummary>Called after end_per_group</fsummary>
+ <name>Module:post_end_per_group(GroupName, Config, Return, CTHState) -&gt; Result</name>
+ <fsummary>Called after end_per_group.</fsummary>
<type>
- <v>GroupName = atom()</v>
- <v>Config = [{Key,Value}]</v>
- <v>Return = NewReturn = Config | SkipOrFail | term()</v>
- <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
- <v>CTHState = NewCTHState = term()</v>
- <v>Result = {NewReturn, NewCTHState}</v>
- <v>Key = atom()</v>
- <v>Value = term()</v>
- <v>Reason = term()</v>
+ <v>GroupName = atom()</v>
+ <v>Config = [{Key,Value}]</v>
+ <v>Return = NewReturn = Config | SkipOrFail | term()</v>
+ <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
+ <v>CTHState = NewCTHState = term()</v>
+ <v>Result = {NewReturn, NewCTHState}</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called after
- <seealso marker="common_test#Module:end_per_group-2">
- end_per_group</seealso> if it exists. It behaves the same way as
- <seealso marker="ct_hooks#Module:post_init_per_suite-4">
- post_init_per_suite</seealso>, but for the
- <seealso marker="common_test#Module:end_per_group-2">
- end_per_group</seealso> function instead.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called after
+ <seealso marker="common_test#Module:end_per_group-2"><c>end_per_group</c></seealso>
+ if it exists. It behaves the same way as
+ <seealso marker="ct_hooks#Module:post_init_per_suite-4"><c>post_init_per_suite</c></seealso>,
+ but for function
+ <seealso marker="common_test#Module:end_per_group-2">end_per_group</seealso>
+ instead.</p>
</desc>
</func>
<func>
- <name>Module:pre_end_per_suite(SuiteName, EndData, CTHState) -&gt;
- Result</name>
- <fsummary>Called before end_per_suite</fsummary>
+ <name>Module:pre_end_per_suite(SuiteName, EndData, CTHState) -&gt; Result</name>
+ <fsummary>Called before end_per_suite.</fsummary>
<type>
- <v>SuiteName = atom()</v>
- <v>EndData = Config | SkipOrFail</v>
- <v>Config = NewConfig = [{Key,Value}]</v>
- <v>CTHState = NewCTHState = term()</v>
- <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
- <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
- <v>Key = atom()</v>
- <v>Value = term()</v>
- <v>Reason = term()</v>
+ <v>SuiteName = atom()</v>
+ <v>EndData = Config | SkipOrFail</v>
+ <v>Config = NewConfig = [{Key,Value}]</v>
+ <v>CTHState = NewCTHState = term()</v>
+ <v>Result = {NewConfig | SkipOrFail, NewCTHState}</v>
+ <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called before
- <seealso marker="common_test#Module:end_per_suite-1">
- end_per_suite</seealso> if it exists. It behaves the same way as
- <seealso marker="ct_hooks#Module:pre_init_per_suite-3">
- pre_init_per_suite</seealso>, but for the
- <seealso marker="common_test#Module:end_per_suite-1">
- end_per_suite</seealso> function instead.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called before
+ <seealso marker="common_test#Module:end_per_suite-1"><c>end_per_suite</c></seealso>
+ if it exists. It behaves the same way as
+ <seealso marker="ct_hooks#Module:pre_init_per_suite-3"><c>pre_init_per_suite</c></seealso>,
+ but for function
+ <seealso marker="common_test#Module:end_per_suite-1"><c>end_per_suite</c></seealso>
+ instead.</p>
</desc>
</func>
<func>
- <name>Module:post_end_per_suite(SuiteName, Config, Return, CTHState) -&gt;
- Result</name>
- <fsummary>Called after end_per_suite</fsummary>
+ <name>Module:post_end_per_suite(SuiteName, Config, Return, CTHState) -&gt; Result</name>
+ <fsummary>Called after end_per_suite.</fsummary>
<type>
- <v>SuiteName = atom()</v>
- <v>Config = [{Key,Value}]</v>
- <v>Return = NewReturn = Config | SkipOrFail | term()</v>
- <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
- <v>CTHState = NewCTHState = term()</v>
- <v>Result = {NewReturn, NewCTHState}</v>
- <v>Key = atom()</v>
- <v>Value = term()</v>
- <v>Reason = term()</v>
+ <v>SuiteName = atom()</v>
+ <v>Config = [{Key,Value}]</v>
+ <v>Return = NewReturn = Config | SkipOrFail | term()</v>
+ <v>SkipOrFail = {fail,Reason} | {skip, Reason}</v>
+ <v>CTHState = NewCTHState = term()</v>
+ <v>Result = {NewReturn, NewCTHState}</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>Reason = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called after
- <seealso marker="common_test#Module:end_per_suite-1">
- end_per_suite</seealso> if it exists. It behaves the same way as
- <seealso marker="ct_hooks#Module:post_init_per_suite-4">
- post_init_per_suite</seealso>, but for the
- <seealso marker="common_test#Module:end_per_suite-1">
- end_per_suite</seealso> function instead.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called after
+ <seealso marker="common_test#Module:end_per_suite-1"><c>end_per_suite</c></seealso>
+ if it exists. It behaves the same way as
+ <seealso marker="ct_hooks#Module:post_init_per_suite-4"><c>post_init_per_suite</c></seealso>,
+ but for function
+ <seealso marker="common_test#Module:end_per_suite-1"><c>end_per_suite</c></seealso>
+ instead.</p>
</desc>
</func>
<func>
- <name>Module:on_tc_fail(TestName, Reason, CTHState) -&gt;
- NewCTHState</name>
- <fsummary>Called after the CTH scope ends</fsummary>
+ <name>Module:on_tc_fail(TestName, Reason, CTHState) -&gt; NewCTHState</name>
+ <fsummary>Called after the CTH scope ends.</fsummary>
<type>
- <v>TestName = init_per_suite | end_per_suite |
- {init_per_group,GroupName} | {end_per_group,GroupName} |
- {FuncName,GroupName} | FuncName</v>
- <v>FuncName = atom()</v>
- <v>GroupName = atom()</v>
- <v>Reason = term()</v>
- <v>CTHState = NewCTHState = term()</v>
+ <v>TestName = init_per_suite | end_per_suite | {init_per_group,GroupName} | {end_per_group,GroupName} | {FuncName,GroupName} | FuncName</v>
+ <v>FuncName = atom()</v>
+ <v>GroupName = atom()</v>
+ <v>Reason = term()</v>
+ <v>CTHState = NewCTHState = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called whenever a test case (or config function)
- fails. It is called after the post function has been called for
- the failed test case. I.e. if init_per_suite fails, this function
- is called after
- <seealso marker="#Module:post_init_per_suite-4">
- post_init_per_suite</seealso>, and if a test case fails, it is called
- after <seealso marker="#Module:post_end_per_testcase-4">
- post_end_per_testcase</seealso>. If the failed test case belongs
- to a test case group, the first argument is a tuple
- <c>{FuncName,GroupName}</c>, otherwise simply the function name.</p>
-
- <p>The data which comes with the Reason follows the same format as the
- <seealso marker="event_handler_chapter#failreason">FailReason
- </seealso> in the <seealso marker="event_handler_chapter#tc_done">tc_done</seealso> event.
- See <seealso marker="event_handler_chapter#events">Event Handling
- </seealso> in the User's Guide for details.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called whenever a test case (or configuration
+ function) fails. It is called after the post function is called
+ for the failed test case, that is:</p>
+
+ <list type="bulleted">
+ <item><p>If <c>init_per_suite</c> fails, this function is called after
+ <seealso marker="#Module:post_init_per_suite-4"><c>post_init_per_suite</c></seealso>.</p></item>
+ <item><p>If a test case fails, this funcion is called after
+ <seealso marker="#Module:post_end_per_testcase-4"><c>post_end_per_testcase</c></seealso>.</p></item>
+ </list>
+
+ <p>If the failed test case belongs to a test case group, the first
+ argument is a tuple <c>{FuncName,GroupName}</c>, otherwise only
+ the function name.</p>
+
+ <p>The data that comes with <c>Reason</c> follows the same format as
+ <seealso marker="event_handler_chapter#failreason"><c>FailReason</c></seealso>
+ in event
+ <seealso marker="event_handler_chapter#tc_done"><c>tc_done</c></seealso>.
+ For details, see section
+ <seealso marker="event_handler_chapter#events">Event Handling</seealso>
+ in the User's Guide.</p>
</desc>
</func>
<func>
- <name>Module:on_tc_skip(TestName, Reason, CTHState) -&gt;
- NewCTHState</name>
- <fsummary>Called after the CTH scope ends</fsummary>
+ <name>Module:on_tc_skip(TestName, Reason, CTHState) -&gt; NewCTHState</name>
+ <fsummary>Called after the CTH scope ends.</fsummary>
<type>
- <v>TestName = init_per_suite | end_per_suite |
- {init_per_group,GroupName} | {end_per_group,GroupName} |
- {FuncName,GroupName} | FuncName</v>
- <v>FuncName = atom()</v>
- <v>GroupName = atom()</v>
- <v>Reason = {tc_auto_skip | tc_user_skip, term()}</v>
- <v>CTHState = NewCTHState = term()</v>
+ <v>TestName = init_per_suite | end_per_suite | {init_per_group,GroupName} | {end_per_group,GroupName} | {FuncName,GroupName} | FuncName</v>
+ <v>FuncName = atom()</v>
+ <v>GroupName = atom()</v>
+ <v>Reason = {tc_auto_skip | tc_user_skip, term()}</v>
+ <v>CTHState = NewCTHState = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>This function is called whenever a test case (or config function)
- is skipped. It is called after the post function has been called
- for the skipped test case. I.e. if init_per_group is skipped, this
- function is called after
- <seealso marker="#Module:post_init_per_group-4">
- post_init_per_group</seealso>, and if a test case is skipped,
- it is called after
- <seealso marker="#Module:post_end_per_testcase-4">
- post_end_per_testcase</seealso>. If the skipped test case belongs to a
- test case group, the first argument is a tuple <c>{FuncName,GroupName}</c>,
- otherwise simply the function name.</p>
-
- <p>The data which comes with the Reason follows the same format as
- <seealso marker="event_handler_chapter#tc_auto_skip">tc_auto_skip
- </seealso> and <seealso marker="event_handler_chapter#tc_user_skip">
- tc_user_skip</seealso> events.
- See <seealso marker="event_handler_chapter#events">Event Handling
- </seealso> in the User's Guide for details.</p>
+ <p>OPTIONAL</p>
+
+ <p>This function is called whenever a test case (or configuration
+ function) is skipped. It is called after the post function is called
+ for the skipped test case, that is:</p>
+
+ <list type="bulleted">
+ <item><p>If <c>init_per_group</c> is skipped, this function is
+ called after
+ <seealso marker="#Module:post_init_per_group-4"><c>post_init_per_group</c></seealso>.</p></item>
+ <item><p>If a test case is skipped, this function is called after
+ <seealso marker="#Module:post_end_per_testcase-4"><c>post_end_per_testcase</c></seealso>.</p></item>
+ </list>
+
+ <p>If the skipped test case belongs to a test case group, the first
+ argument is a tuple <c>{FuncName,GroupName}</c>, otherwise only
+ the function name.</p>
+
+ <p>The data that comes with <c>Reason</c> follows the same format as
+ events
+ <seealso marker="event_handler_chapter#tc_auto_skip"><c>tc_auto_skip</c></seealso>
+ and
+ <seealso marker="event_handler_chapter#tc_user_skip"><c>tc_user_skip</c></seealso>
+ For details, see section
+ <seealso marker="event_handler_chapter#events">Event Handling</seealso>
+ in the User's Guide.</p>
</desc>
</func>
<func>
<name>Module:terminate(CTHState)</name>
- <fsummary>Called after the CTH scope ends</fsummary>
+ <fsummary>Called after the CTH scope ends.</fsummary>
<type>
- <v>CTHState = term()</v>
+ <v>CTHState = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
+ <p>OPTIONAL</p>
- <p>This function is called at the end of a CTH's
- <seealso marker="ct_hooks_chapter#scope">scope</seealso>.
- </p>
+ <p>This function is called at the end of a CTH
+ <seealso marker="ct_hooks_chapter#scope">scope</seealso>.</p>
</desc>
</func>
<func>
<name>Module:id(Opts) -&gt; Id</name>
- <fsummary>Called before the init function of a CTH</fsummary>
+ <fsummary>Called before the init function of a CTH.</fsummary>
<type>
- <v>Opts = term()</v>
- <v>Id = term()</v>
+ <v>Opts = term()</v>
+ <v>Id = term()</v>
</type>
-
<desc>
- <p> OPTIONAL </p>
-
- <p>The <c>Id</c> is used to uniquely identify a CTH instance,
- if two CTH's return the same <c>Id</c> the second CTH is ignored
- and subsequent calls to the CTH will only be made to the first
- instance. For more information see
- <seealso marker="ct_hooks_chapter#installing">Installing a CTH
- </seealso> in the User's Guide.
- </p>
-
- <p>This function should NOT have any side effects as it might
- be called multiple times by Common Test.</p>
+ <p>OPTIONAL</p>
- <p>If not implemented the CTH will act as if this function returned a
- call to <c>make_ref/0</c>.</p>
- </desc>
+ <p>The <c>Id</c> identifies a CTH instance uniquely. If two CTHs return
+ the same <c>Id</c>, the second CTH is ignored and subsequent calls to
+ the CTH are only made to the first instance. For details, see section
+ <seealso marker="ct_hooks_chapter#installing">Installing a CTH</seealso>
+ in the User's Guide.</p>
+
+ <p>This function is <em>not</em> to have any side effects, as it can
+ be called multiple times by <c>Common Test</c>.</p>
+
+ <p>If not implemented, the CTH acts as if this function returned a call
+ to <c>make_ref/0</c>.</p>
+ </desc>
</func>
-
</funcs>
</erlref>
diff --git a/lib/common_test/doc/src/ct_master.xml b/lib/common_test/doc/src/ct_master.xml
new file mode 100644
index 0000000000..06f9b04f1b
--- /dev/null
+++ b/lib/common_test/doc/src/ct_master.xml
@@ -0,0 +1,220 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct_master</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct_master.xml</file>
+ </header>
+ <module>ct_master</module>
+ <modulesummary>Distributed test execution control for Common Test.</modulesummary>
+
+<description>
+
+ <p>Distributed test execution control for <c>Common Test</c>.</p>
+
+ <p>This module exports functions for running <c>Common Test</c> nodes on
+ multiple hosts in parallel.</p>
+
+</description>
+
+ <funcs>
+ <func>
+ <name>abort() -&gt; ok</name>
+ <fsummary>Stops all running tests.</fsummary>
+ <desc><marker id="abort-0"/>
+ <p>Stops all running tests.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>abort(Nodes) -&gt; ok</name>
+ <fsummary>Stops tests on specified nodes.</fsummary>
+ <type>
+ <v>Nodes = atom() | [atom()]</v>
+ </type>
+ <desc><marker id="abort-1"/>
+ <p>Stops tests on specified nodes.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>basic_html(Bool) -&gt; ok</name>
+ <fsummary>If set to true, the ct_master logs are written on a primitive
+ HTML format, not using the <c>Common Test</c> CSS style sheet.</fsummary>
+ <type>
+ <v>Bool = true | false</v>
+ </type>
+ <desc><marker id="basic_html-1"/>
+ <p>If set to <c>true</c>, the <c>ct_master logs</c> are written on a
+ primitive HTML format, not using the <c>Common Test</c> CSS style
+ sheet.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_event_mgr_ref() -&gt; MasterEvMgrRef</name>
+ <fsummary>Gets a reference to the <c>Common Test</c> master event
+ manager.</fsummary>
+ <type>
+ <v>MasterEvMgrRef = atom()</v>
+ </type>
+ <desc><marker id="get_event_mgr_ref-0"/>
+ <p>Gets a reference to the <c>Common Test</c> master event manager.
+ The reference can be used to, for example, add a user-specific
+ event handler while tests are running.</p>
+
+ <p><em>Example:</em></p>
+
+ <pre>
+ gen_event:add_handler(ct_master:get_event_mgr_ref(), my_ev_h, [])</pre>
+ </desc>
+ </func>
+
+ <func>
+ <name>progress() -&gt; [{Node, Status}]</name>
+ <fsummary>Returns test progress.</fsummary>
+ <type>
+ <v>Node = atom()</v>
+ <v>Status = finished_ok | ongoing | aborted | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="progress-0"/>
+ <p>Returns test progress. If <c>Status</c> is <c>ongoing</c>, tests
+ are running on the node and are not yet finished.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run(TestSpecs) -&gt; ok</name>
+ <fsummary>Equivalent to run(TestSpecs, false, [], []).</fsummary>
+ <type>
+ <v>TestSpecs = string() | [SeparateOrMerged]</v>
+ </type>
+ <desc><marker id="run-1"/>
+ <p>Equivalent to <seealso marker="#run-4"><c>ct_master:run(TestSpecs,
+ false, [], [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run(TestSpecs, InclNodes, ExclNodes) -&gt; ok</name>
+ <fsummary>Equivalent to run(TestSpecs, false, InclNodes, ExclNodes).
+ </fsummary>
+ <type>
+ <v>TestSpecs = string() | [SeparateOrMerged]</v>
+ <v>SeparateOrMerged = string() | [string()]</v>
+ <v>InclNodes = [atom()]</v>
+ <v>ExclNodes = [atom()]</v>
+ </type>
+ <desc><marker id="run-3"/>
+ <p>Equivalent to <seealso marker="#run-4"><c>ct_master:run(TestSpecs,
+ false, InclNodes, ExclNodes)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run(TestSpecs, AllowUserTerms, InclNodes, ExclNodes) -&gt; ok</name>
+ <fsummary>Tests are spawned on the nodes as specified in TestSpecs.
+ </fsummary>
+ <type>
+ <v>TestSpecs = string() | [SeparateOrMerged]</v>
+ <v>SeparateOrMerged = string() | [string()]</v>
+ <v>AllowUserTerms = bool()</v>
+ <v>InclNodes = [atom()]</v>
+ <v>ExclNodes = [atom()]</v>
+ </type>
+ <desc><marker id="run-4"/>
+ <p>Tests are spawned on the nodes as specified in <c>TestSpecs</c>.
+ Each specification in <c>TestSpec</c> is handled separately.
+ However, it is also possible to specify a list of specifications to
+ be merged into one specification before the tests are executed. Any
+ test without a particular node specification is also executed on
+ the nodes in <c>InclNodes</c>. Nodes in the <c>ExclNodes</c> list
+ are excluded from the test.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run_on_node(TestSpecs, Node) -&gt; ok</name>
+ <fsummary>Equivalent to run_on_node(TestSpecs, false, Node).</fsummary>
+ <type>
+ <v>TestSpecs = string() | [SeparateOrMerged]</v>
+ <v>SeparateOrMerged = string() | [string()]</v>
+ <v>Node = atom()</v>
+ </type>
+ <desc><marker id="run_on_node-2"/>
+ <p>Equivalent to
+ <seealso marker="#run_on_node-3"><c>ct_master:run_on_node(TestSpecs,
+ false, Node)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run_on_node(TestSpecs, AllowUserTerms, Node) -&gt; ok</name>
+ <fsummary>Tests are spawned on Node according to TestSpecs.</fsummary>
+ <type>
+ <v>TestSpecs = string() | [SeparateOrMerged]</v>
+ <v>SeparateOrMerged = string() | [string()]</v>
+ <v>AllowUserTerms = bool()</v>
+ <v>Node = atom()</v>
+ </type>
+ <desc><marker id="run_on_node-3"/>
+ <p>Tests are spawned on <c>Node</c> according to <c>TestSpecs</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>run_test(Node, Opts) -&gt; ok</name>
+ <fsummary>Tests are spawned on Node using ct:run_test/1.</fsummary>
+ <type>
+ <v>Node = atom()</v>
+ <v>Opts = [OptTuples]</v>
+ <v>OptTuples = {config, CfgFiles} | {dir, TestDirs} | {suite, Suites} | {testcase, Cases} | {spec, TestSpecs} | {allow_user_terms, Bool} | {logdir, LogDir} | {event_handler, EventHandlers} | {silent_connections, Conns} | {cover, CoverSpecFile} | {cover_stop, Bool} | {userconfig, UserCfgFiles}</v>
+ <v>CfgFiles = string() | [string()]</v>
+ <v>TestDirs = string() | [string()]</v>
+ <v>Suites = atom() | [atom()]</v>
+ <v>Cases = atom() | [atom()]</v>
+ <v>TestSpecs = string() | [string()]</v>
+ <v>LogDir = string()</v>
+ <v>EventHandlers = EH | [EH]</v>
+ <v>EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}</v>
+ <v>InitArgs = [term()]</v>
+ <v>Conns = all | [atom()]</v>
+ </type>
+ <desc><marker id="run_test-2"/>
+ <p>Tests are spawned on <c>Node</c> using
+ <seealso marker="ct:run_test-1"><c>ct:run_test/1</c></seealso></p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ct_netconfc.xml b/lib/common_test/doc/src/ct_netconfc.xml
new file mode 100644
index 0000000000..8139d8afdb
--- /dev/null
+++ b/lib/common_test/doc/src/ct_netconfc.xml
@@ -0,0 +1,1037 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct_netconfc</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct_netconfc.xml</file>
+ </header>
+ <module>ct_netconfc</module>
+ <modulesummary>NETCONF client module.</modulesummary>
+
+<description>
+
+ <p>NETCONF client module.</p>
+
+ <p>The NETCONF client is compliant with RFC 4741 NETCONF Configuration
+ Protocol and RFC 4742 Using the NETCONF Configuration Protocol over
+ Secure SHell (SSH)..</p>
+
+ <p>For each server to test against, the following entry can be added to a
+ configuration file:</p>
+
+ <pre>
+ {server_id(),options()}.</pre>
+
+ <p>The <c>server_id()</c> or an associated <c>target_name()</c> (see
+ module <seealso marker="ct"><c>ct</c></seealso>) must then be used
+ in calls to
+ <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>.</p>
+
+ <p>If no configuration exists for a server, a session can still be
+ opened by calling
+ <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso> with
+ all necessary options specified in the call. The first argument to
+ <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso> can
+ then be any atom.</p>
+
+ </description>
+
+ <section>
+ <marker id="Logging"/>
+ <title>Logging</title>
+ <p>The NETCONF server uses <c>error_logger</c> for logging of NETCONF
+ traffic. A special purpose error handler is implemented in
+ <c>ct_conn_log_h</c>. To use this error handler, add the
+ <c>cth_conn_log</c> hook in the test suite, for example:</p>
+
+ <pre>
+ suite() -&gt;
+ [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].</pre>
+
+ <p><c>conn_mod()</c> is the name of the <c>Common Test</c> module
+ implementing the connection protocol, for example, <c>ct_netconfc</c>.</p>
+
+ <p>Hook option <c>log_type</c> specifies the type of logging:</p>
+
+ <taglist>
+ <tag><c>raw</c></tag>
+ <item><p>The sent and received NETCONF data is logged to a separate
+ text file "as is" without any formatting. A link to the file is
+ added to the test case HTML log.</p>.</item>
+
+ <tag><c>pretty</c></tag>
+ <item><p>The sent and received NETCONF data is logged to a separate
+ text file with XML data nicely indented. A link to the file is
+ added to the test case HTML log.</p></item>
+
+ <tag><c>html (default)</c></tag>
+ <item><p>The sent and received NETCONF traffic is pretty printed
+ directly in the test case HTML log.</p></item>
+
+ <tag><c>silent</c></tag>
+ <item><p>NETCONF traffic is not logged.</p></item>
+ </taglist>
+
+ <p>By default, all NETCONF traffic is logged in one single log file.
+ However, different connections can be logged in separate files.
+ To do this, use hook option <c>hosts</c> and list the names of the
+ servers/connections to be used in the suite. The connections
+ must be named for this to work, that is, they must be opened with
+ <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>.</p>
+
+ <p>Option <c>hosts</c> has no effect if <c>log_type</c> is set to
+ <c>html</c> or <c>silent</c>.</p>
+
+ <p>The hook options can also be specified in a configuration file with
+ configuration variable <c>ct_conn_log</c>:</p>
+
+ <pre>
+ {ct_conn_log,[{conn_mod(),hook_options()}]}.</pre>
+
+ <p>For example:</p>
+
+ <pre>
+ {ct_conn_log,[{ct_netconfc,[{log_type,pretty},
+ {hosts,[key_or_name()]}]}]}</pre>
+
+ <note>
+ <p>Hook options specified in a configuration file overwrite the
+ hard-coded hook options in the test suite.</p>
+ </note>
+
+ <p><em>Logging Example 1:</em></p>
+ <marker id="Logging_example_1"/>
+
+ <p>The following <c>ct_hooks</c> statement causes pretty printing of
+ NETCONF traffic to separate logs for the connections named
+ <c>nc_server1</c> and <c>nc_server2</c>. Any other connections are
+ logged to default NETCONF log.</p>
+
+ <pre>
+ suite() -&gt;
+ [{ct_hooks, [{cth_conn_log, [{ct_netconfc,[{log_type,pretty}},
+ {hosts,[nc_server1,nc_server2]}]}
+ ]}]}].</pre>
+
+ <p>Connections must be opened as follows:</p>
+
+ <pre>
+ open(nc_server1,[...]),
+ open(nc_server2,[...]).</pre>
+
+ <p><em>Logging Example 2:</em></p>
+ <marker id="Logging_example_2"/>
+
+ <p>The following configuration file causes raw logging of all NETCONF
+ traffic in to one single text file:</p>
+
+ <pre>
+ {ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.</pre>
+
+ <p>The <c>ct_hooks</c> statement must look as follows:</p>
+
+ <pre>
+ suite() -&gt;
+ [{ct_hooks, [{cth_conn_log, []}]}].</pre>
+
+ <p>The same <c>ct_hooks</c> statement without the configuration file
+ would cause HTML logging of all NETCONF connections in to the test
+ case HTML log.</p>
+ </section>
+
+ <section>
+ <marker id="Notifications"/>
+ <title>Notifications</title>
+
+ <p>The NETCONF client is also compliant with RFC 5277 NETCONF Event
+ Notifications, which defines a mechanism for an asynchronous message
+ notification delivery service for the NETCONF protocol.</p>
+
+ <p>Specific functions to support this are
+ <seealso marker="#create_subscription-6"><c>ct_netconfc:create_subscription/6</c></seealso>
+ and
+ <seealso marker="#get_event_streams-3"><c>ct_netconfc:get_event_streams/3</c></seealso>.
+ (The functions also exist with other arities.)</p>
+ </section>
+
+ <section>
+ <title>Data Types</title>
+ <marker id="types"/>
+ <taglist>
+ <tag><c>client() = handle() | key_or_name()</c></tag>
+ <item><marker id="type-client"/>
+ <p>For <c>handle()</c>, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p></item>
+
+ <tag><c>error_reason() = term()</c></tag>
+ <item><marker id="type-error_reason"/> </item>
+ <tag><c>event_time() = {eventTime, xml_attributes(), [xs_datetime()]}</c></tag>
+ <item><marker id="type-event_time"/> </item>
+
+ <tag><c>handle() = term()</c></tag>
+ <item><marker id="type-handle"/>
+ <p>Opaque reference for a connection (NETCONF session). For more
+ information, see module <seealso marker="ct"><c>ct</c></seealso>.</p>
+ </item>
+
+ <tag><c>host() = hostname() | ip_address()</c></tag>
+ <item><marker id="type-host"/>
+ <p>For <c>hostname()</c> and <c>ip_address()</c>, see module
+ <seealso marker="kernel:inet"><c>kernel:inet</c></seealso></p></item>
+
+ <tag><c>key_or_name() = server_id() | target_name()</c></tag>
+ <item><marker id="type-key_or_name"/>
+ <p>For <c>target_name</c>, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p></item>
+
+ <tag><c>netconf_db() = running | startup | candidate</c></tag>
+ <item><marker id="type-netconf_db"/> </item>
+
+ <tag><c>notification() = {notification, xml_attributes(), notification_content()}</c></tag>
+ <item><marker id="type-notification"/> </item>
+
+ <tag><c>notification_content() = [event_time() | simple_xml()]</c></tag>
+ <item><marker id="type-notification_content"/> </item>
+
+ <tag><c>option() = {ssh, host()} | {port, port_number()} | {user, string()} | {password, string()} | {user_dir, string()} | {timeout, timeout()}</c></tag>
+ <item><marker id="type-option"/>
+ <p>For <c>port_number()</c>, see module
+ <seealso marker="kernel:inet"><c>kernel:inet</c></seealso></p></item>
+
+ <tag><c>options() = [option()]</c></tag>
+ <item><marker id="type-options"/>
+ <p>Options used for setting up an SSH connection to a NETCONF
+ server.</p></item>
+
+ <tag><c>server_id() = atom()</c></tag>
+ <item><marker id="type-server_id"/>
+ <p>The identity of a server, specified in a configuration
+ file.</p></item>
+
+ <tag><c>simple_xml() = {xml_tag(), xml_attributes(), xml_content()} | {xml_tag(), xml_content()} | xml_tag()</c></tag>
+ <item><marker id="type-simple_xml"/>
+ <p>This type is further described in application
+ <seealso marker="xmerl"><c>xmerl</c></seealso>.</p></item>
+
+ <tag><c>stream_data() = {description, string()} | {replaySupport, string()} | {replayLogCreationTime, string()} | {replayLogAgedTime, string()}</c></tag>
+ <item><marker id="type-stream_data"/>
+ <p>For details about the data format for the string values, see
+ "XML Schema for Event Notifications" in RFC 5277.</p></item>
+
+ <tag><c>stream_name() = string()</c></tag>
+ <item><marker id="type-stream_name"/> </item>
+
+ <tag><c>streams() = [{stream_name(), [stream_data()]}]</c></tag>
+ <item><marker id="type-streams"/> </item>
+
+ <tag><c>xml_attribute_tag() = atom()</c></tag>
+ <item><marker id="type-xml_attribute_tag"/> </item>
+
+ <tag><c>xml_attribute_value() = string()</c></tag>
+ <item><marker id="type-xml_attribute_value"/> </item>
+
+ <tag><c>xml_attributes() = [{xml_attribute_tag(), xml_attribute_value()}]</c></tag>
+ <item><marker id="type-xml_attributes"/> </item>
+
+ <tag><c>xml_content() = [simple_xml() | iolist()]</c></tag>
+ <item><marker id="type-xml_content"/> </item>
+
+ <tag><c>xml_tag() = atom()</c></tag>
+ <item><marker id="type-xml_tag"/> </item>
+
+ <tag><c>xpath() = {xpath, string()}</c></tag>
+ <item><marker id="type-xpath"/> </item>
+
+ <tag><c>xs_datetime() = string()</c></tag>
+ <item><marker id="type-xs_datetime"/>
+ <p>This date and time identifier has the same format as the XML type
+ <c>dateTime</c> and is compliant with RFC 3339 Date and Time on
+ the Internet Timestamps. The format is as follows:</p>
+ <pre>
+ [-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]</pre>
+ </item>
+ </taglist>
+ </section>
+
+ <funcs>
+ <func>
+ <name>action(Client, Action) -&gt; Result</name>
+ <fsummary>Equivalent to action(Client, Action, infinity).</fsummary>
+ <desc><marker id="action-2"/>
+ <p>Equivalent to
+ <seealso marker="#action-3"><c>ct_netconfc:action(Client, Action,
+ infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>action(Client, Action, Timeout) -&gt; Result</name>
+ <fsummary>Executes an action.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Action = simple_xml()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = ok | {ok, [simple_xml()]} | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="action-3"/>
+ <p>Executes an action. If the return type is void, <c>ok</c> is
+ returned instead of <c>{ok,[simple_xml()]}</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>close_session(Client) -&gt; Result</name>
+ <fsummary>Equivalent to close_session(Client, infinity).</fsummary>
+ <desc><marker id="close_session-1"/>
+ <p>Equivalent to
+ <seealso marker="#close_session-2"><c>ct_netconfc:close_session(Client,
+ infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>close_session(Client, Timeout) -&gt; Result</name>
+ <fsummary>Requests graceful termination of the session associated with
+ the client.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = ok | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="close_session-2"/>
+ <p>Requests graceful termination of the session associated with the
+ client.</p>
+
+ <p>When a NETCONF server receives a <c>close-session</c> request, it
+ gracefully closes the session. The server releases any locks and
+ resources associated with the session and gracefully closes any
+ associated connections. Any NETCONF requests received after a
+ <c>close-session</c> request are ignored.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>copy_config(Client, Source, Target) -&gt; Result</name>
+ <fsummary>Equivalent to copy_config(Client, Source, Target,
+ infinity).</fsummary>
+ <desc><marker id="copy_config-3"/>
+ <p>Equivalent to
+ <seealso marker="#copy_config-4"><c>ct_netconfc:copy_config(Client,
+ Source, Target, infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>copy_config(Client, Target, Source, Timeout) -&gt; Result</name>
+ <fsummary>Copies configuration data.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Target = netconf_db()</v>
+ <v>Source = netconf_db()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = ok | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="copy_config-4"/>
+ <p>Copies configuration data.</p>
+
+ <p>Which source and target options that can be issued depends on the
+ capabilities supported by the server. That is, <c>:candidate</c>
+ and/or <c>:startup</c> are required.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>create_subscription(Client) -&gt; term()</name>
+ <fsummary>Creates a subscription for event notifications.</fsummary>
+ <desc><marker id="create_subscription-1"/></desc>
+ </func>
+
+ <func>
+ <name>create_subscription(Client, Timeout) -&gt; term()</name>
+ <fsummary>Creates a subscription for event notifications.</fsummary>
+ <desc><marker id="create_subscription-2"/></desc>
+ </func>
+
+ <func>
+ <name>create_subscription(Client, Stream, Timeout) -&gt; term()</name>
+ <fsummary>Creates a subscription for event notifications.</fsummary>
+ <desc><marker id="create_subscription-3"/></desc>
+ </func>
+
+ <func>
+ <name>create_subscription(Client, StartTime, StopTime, Timeout) -&gt; term()</name>
+ <fsummary>Creates a subscription for event notifications.</fsummary>
+ <desc><marker id="create_subscription-4"/></desc>
+ </func>
+
+ <func>
+ <name>create_subscription(Client, Stream, StartTime, StopTime, Timeout) -&gt; term()</name>
+ <fsummary>Creates a subscription for event notifications.</fsummary>
+ <desc><marker id="create_subscription-5"/></desc>
+ </func>
+
+ <func>
+ <name>create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout) -&gt; Result</name>
+ <fsummary>Creates a subscription for event notifications.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Stream = stream_name()</v>
+ <v>Filter = simple_xml() | [simple_xml()]</v>
+ <v>StartTime = xs_datetime()</v>
+ <v>StopTime = xs_datetime()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = ok | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="create_subscription-6"/>
+ <p>Creates a subscription for event notifications.</p>
+
+ <p>This function sets up a subscription for NETCONF event
+ notifications of the specified stream type, matching the specified
+ filter. The calling process receives notifications as messages of
+ type <c>notification()</c>.</p>
+
+ <taglist>
+ <tag><c>Stream</c></tag>
+ <item><p>Optional parameter that indicates which stream of event
+ is of interest. If not present, events in the default NETCONF
+ stream are sent.</p></item>
+ <tag><c>Filter</c></tag>
+ <item><p>Optional parameter that indicates which subset of all
+ possible events is of interest. The parameter format is the
+ same as that of the filter parameter in the NETCONF protocol
+ operations. If not present, all events not precluded by other
+ parameters are sent.</p></item>
+ <tag><c>StartTime</c></tag>
+ <item><p>Optional parameter used to trigger the replay feature and
+ indicate that the replay is to start at the time specified.
+ If <c>StartTime</c> is not present, this is not a replay
+ subscription.</p>
+ <p>It is not valid to specify start times that are later than
+ the current time. If <c>StartTime</c> is specified earlier
+ than the log can support, the replay begins with the earliest
+ available notification.</p>
+ <p>This parameter is of type <c>dateTime</c> and compliant to
+ RFC 3339. Implementations must support time zones.</p></item>
+ <tag><c>StopTime</c></tag>
+ <item><p>Optional parameter used with the optional replay feature
+ to indicate the newest notifications of interest. If
+ <c>StopTime</c> is not present, the notifications continues
+ until the subscription is terminated.</p>
+ <p>Must be used with and be later than <c>StartTime</c>. Values
+ of <c>StopTime</c> in the future are valid. This parameter is
+ of type <c>dateTime</c> and compliant to RFC 3339.
+ Implementations must support time zones.</p></item>
+ </taglist>
+
+ <p>For more details about the event notification mechanism, see
+ RFC 5277.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>delete_config(Client, Target) -&gt; Result</name>
+ <fsummary>Equivalent to delete_config(Client, Target,
+ infinity).</fsummary>
+ <desc><marker id="delete_config-2"/>
+ <p>Equivalent to
+ <seealso marker="#delete_config-3"><c>ct_netconfc:delete_config(Client, Target, infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>delete_config(Client, Target, Timeout) -&gt; Result</name>
+ <fsummary>Deletes configuration data.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Target = startup | candidate</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = ok | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="delete_config-3"/>
+ <p>Deletes configuration data.</p>
+
+ <p>The running configuration cannot be deleted and <c>:candidate</c>
+ or <c>:startup</c> must be advertised by the server.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>edit_config(Client, Target, Config) -&gt; Result</name>
+ <fsummary>Equivalent to edit_config(Client, Target, Config, [],
+ infinity).</fsummary>
+ <desc><marker id="edit_config-3"/>
+ <p>Equivalent to
+ <seealso marker="#edit_config-5"><c>ct_netconfc:edit_config(Client,
+ Target, Config, [], infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>edit_config(Client, Target, Config, OptParamsOrTimeout) -&gt; Result</name>
+ <fsummary>If OptParamsOrTimeout is a time-out value, this function is
+ equivalent to ct_netconfc:edit_config(Client, Target, Config, [],
+ Timeout).</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Target = netconf_db()</v>
+ <v>Config = simple_xml()</v>
+ <v>OptParamsOrTimeout = [simple_xml()] | timeout()</v>
+ <v>Result = ok | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="edit_config-4"/>
+ <p>If <c>OptParamsOrTimeout</c> is a time-out value, this function is
+ equivalent to
+ <seealso marker="#edit_config-5"><c>ct_netconfc:edit_config(Client,
+ Target, Config, [], Timeout)</c></seealso>.</p>
+
+ <p>If <c>OptParamsOrTimeout</c> is a list of simple XML, this
+ function is equivalent to
+ <seealso marker="#edit_config-5"><c>ct_netconfc:edit_config(Client,
+ Target, Config, OptParams, infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>edit_config(Client, Target, Config, OptParams, Timeout) -&gt; Result</name>
+ <fsummary>Edits configuration data.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Target = netconf_db()</v>
+ <v>Config = simple_xml()</v>
+ <v>OptParams = [simple_xml()]</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = ok | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="edit_config-5"/>
+ <p>Edits configuration data.</p>
+
+ <p>By default only the running target is available, unless the server
+ includes <c>:candidate</c> or <c>:startup</c> in its list of
+ capabilities.</p>
+
+ <p><c>OptParams</c> can be used for specifying optional parameters
+ (<c>default-operation</c>, <c>test-option</c>, or
+ <c>error-option</c>) to be added to the <c>edit-config</c>
+ request. The value must be a list containing valid simple XML,
+ for example:</p>
+
+ <pre>
+ [{'default-operation', ["none"]},
+ {'error-option', ["rollback-on-error"]}]</pre>
+ </desc>
+ </func>
+
+ <func>
+ <name>get(Client, Filter) -&gt; Result</name>
+ <fsummary>Equivalent to get(Client, Filter, infinity).</fsummary>
+ <desc><marker id="get-2"/>
+ <p>Equivalent to
+ <seealso marker="#get-3"><c>ct_netconfc:get(Client, Filter,
+ infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get(Client, Filter, Timeout) -&gt; Result</name>
+ <fsummary>Gets data.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Filter = simple_xml() | xpath()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = {ok, [simple_xml()]} | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="get-3"/>
+ <p>Gets data.</p>
+
+ <p>This operation returns both configuration and state data from the
+ server.</p>
+
+ <p>Filter type <c>xpath</c> can be used only if the server supports
+ <c>:xpath</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_capabilities(Client) -&gt; Result</name>
+ <fsummary>Equivalent to get_capabilities(Client, infinity).</fsummary>
+ <desc><marker id="get_capabilities-1"/>
+ <p>Equivalent to
+ <seealso marker="#get_capabilities-2"><c>ct_netconfc:get_capabilities(Client,
+ infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_capabilities(Client, Timeout) -&gt; Result</name>
+ <fsummary>Returns the server side capabilities.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = [string()] | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="get_capabilities-2"/>
+ <p>Returns the server side capabilities.</p>
+
+ <p>The following capability identifiers, defined in RFC 4741 NETCONF
+ Configuration Protocol, can be returned:</p>
+
+ <list>
+ <item><p><c>"urn:ietf:params:netconf:base:1.0"</c></p></item>
+ <item><p><c>"urn:ietf:params:netconf:capability:writable-running:1.0"</c></p></item>
+ <item><p><c>"urn:ietf:params:netconf:capability:candidate:1.0"</c></p></item>
+ <item><p><c>"urn:ietf:params:netconf:capability:confirmed-commit:1.0"</c></p></item>
+ <item><p><c>"urn:ietf:params:netconf:capability:rollback-on-error:1.0"</c></p></item>
+ <item><p><c>"urn:ietf:params:netconf:capability:startup:1.0"</c></p></item>
+ <item><p><c>"urn:ietf:params:netconf:capability:url:1.0"</c></p></item>
+ <item><p><c>"urn:ietf:params:netconf:capability:xpath:1.0"</c></p></item>
+ </list>
+
+ <p>More identifiers can exist, for example, server-side namespace.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_config(Client, Source, Filter) -&gt; Result</name>
+ <fsummary>Equivalent to get_config(Client, Source, Filter,
+ infinity).</fsummary>
+ <desc><marker id="get_config-3"/>
+ <p>Equivalent to
+ <seealso marker="#get_config-4"><c>ct_netconfc:get_config(Client, Source, Filter, infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_config(Client, Source, Filter, Timeout) -&gt; Result</name>
+ <fsummary>Gets configuration data.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Source = netconf_db()</v>
+ <v>Filter = simple_xml() | xpath()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = {ok, [simple_xml()]} | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="get_config-4"/>
+ <p>Gets configuration data.</p>
+
+ <p>To be able to access another source than <c>running</c>, the
+ server must advertise <c>:candidate</c> and/or <c>:startup</c>.</p>
+
+ <p>Filter type <c>xpath</c> can be used only if the server supports
+ <c>:xpath</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_event_streams(Client, Timeout) -&gt; Result</name>
+ <fsummary>Equivalent to get_event_streams(Client, [], Timeout).</fsummary>
+ <desc><marker id="get_event_streams-2"/>
+ <p>Equivalent to
+ <seealso marker="#get_event_streams-3"><c>ct_netconfc:get_event_streams(Client,
+ [], Timeout)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_event_streams(Client, Streams, Timeout) -&gt; Result</name>
+ <fsummary>Sends a request to get the specified event streams.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Streams = [stream_name()]</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = {ok, streams()} | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="get_event_streams-3"/>
+ <p>Sends a request to get the specified event streams.</p>
+
+ <p><c>Streams</c> is a list of stream names. The following filter is
+ sent to the NETCONF server in a <c>get</c> request:</p>
+
+ <pre>
+ &lt;netconf xmlns="urn:ietf:params:xml:ns:netmod:notification"&gt;
+ &lt;streams&gt;
+ &lt;stream&gt;
+ &lt;name&gt;StreamName1&lt;/name&gt;
+ &lt;/stream&gt;
+ &lt;stream&gt;
+ &lt;name&gt;StreamName2&lt;/name&gt;
+ &lt;/stream&gt;
+ ...
+ &lt;/streams&gt;
+ &lt;/netconf&gt;</pre>
+
+ <p>If <c>Streams</c> is an empty list, <em>all</em> streams are
+ requested by sending the following filter:</p>
+
+ <pre>
+ &lt;netconf xmlns="urn:ietf:params:xml:ns:netmod:notification"&gt;
+ &lt;streams/&gt;
+ &lt;/netconf&gt;</pre>
+
+ <p>If more complex filtering is needed, use
+ <seealso marker="#get-2"><c>ct_netconfc:get/2</c></seealso> or
+ <seealso marker="#get-3"><c>ct_netconfc:get/3</c></seealso> and
+ specify the exact filter according to "XML Schema for Event
+ Notifications" in RFC 5277.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_session_id(Client) -&gt; Result</name>
+ <fsummary>Equivalent to get_session_id(Client, infinity).</fsummary>
+ <desc><marker id="get_session_id-1"/>
+ <p>Equivalent to
+ <seealso marker="#get_session_id-2"><c>ct_netconfc:get_session_id(Client,
+ infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_session_id(Client, Timeout) -&gt; Result</name>
+ <fsummary>Returns the session Id associated with the specified
+ client.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = pos_integer() | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="get_session_id-2"/>
+ <p>Returns the session Id associated with the specified client.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>hello(Client) -&gt; Result</name>
+ <fsummary>Equivalent to hello(Client, [], infinity).</fsummary>
+ <desc><marker id="hello-1"/>
+ <p>Equivalent to
+ <seealso marker="#hello-3"><c>ct_netconfc:hello(Client, [],
+ infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>hello(Client, Timeout) -&gt; Result</name>
+ <fsummary>Equivalent to hello(Client, [], Timeout).</fsummary>
+ <desc><marker id="hello-2"/>
+ <p>Equivalent to
+ <seealso marker="#hello-3"><c>ct_netconfc:hello(Client, [],
+ Timeout)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>hello(Client, Options, Timeout) -&gt; Result</name>
+ <fsummary>Exchanges hello messages with the server.</fsummary>
+ <type>
+ <v>Client = handle()</v>
+ <v>Options = [{capability, [string()]}]</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = ok | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="hello-3"/>
+ <p>Exchanges <c>hello</c> messages with the server.</p>
+
+ <p>Adds optional capabilities and sends a <c>hello</c> message to the
+ server and waits for the return.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>kill_session(Client, SessionId) -&gt; Result</name>
+ <fsummary>Equivalent to kill_session(Client, SessionId,
+ infinity).</fsummary>
+ <desc><marker id="kill_session-2"/>
+ <p>Equivalent to
+ <seealso marker="#kill_session-3"><c>ct_netconfc:kill_session(Client,
+SessionId, infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>kill_session(Client, SessionId, Timeout) -&gt; Result</name>
+ <fsummary>Forces termination of the session associated with the supplied
+ session Id.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>SessionId = pos_integer()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = ok | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="kill_session-3"/>
+ <p>Forces termination of the session associated with the supplied
+ session Id.</p>
+
+ <p>The server side must abort any ongoing operations, release any
+ locks and resources associated with the session, and close any
+ associated connections.</p>
+
+ <p>Only if the server is in the confirmed commit phase, the
+ configuration is restored to its state before entering the confirmed
+ commit phase. Otherwise, no configuration rollback is performed.</p>
+
+ <p>If the specified <c>SessionId</c> is equal to the current session
+ Id, an error is returned.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>lock(Client, Target) -&gt; Result</name>
+ <fsummary>Equivalent to lock(Client, Target, infinity).</fsummary>
+ <desc><marker id="lock-2"/>
+ <p>Equivalent to
+ <seealso marker="#lock-3"><c>ct_netconfc:lock(Client, Target,
+ infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>lock(Client, Target, Timeout) -&gt; Result</name>
+ <fsummary>Unlocks the configuration target.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Target = netconf_db()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = ok | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="lock-3"/>
+ <p>Unlocks the configuration target.</p>
+
+ <p>Which target parameters that can be used depends on if
+ <c>:candidate</c> and/or <c>:startup</c> are supported by the
+ server. If successfull, the configuration system of the device is
+ unavailable to other clients (NETCONF, CORBA, SNMP, and so on).
+ Locks are intended to be short-lived.</p>
+
+ <p>Operation
+ <seealso marker="#kill_session-2"><c>ct_netconfc:kill_session/2</c></seealso>
+ or
+ <seealso marker="#kill_session-3"><c>ct_netconfc:kill_session/3</c></seealso>
+ can be used to force the release of a lock owned by another NETCONF
+ session. How this is achieved by the server side is
+ implementation-specific.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>only_open(Options) -&gt; Result</name>
+ <fsummary>Opens a NETCONF session, but does not send hello.</fsummary>
+ <type>
+ <v>Options = options()</v>
+ <v>Result = {ok, handle()} | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="only_open-1"/>
+ <p>Opens a NETCONF session, but does not send <c>hello</c>.</p>
+
+ <p>As <seealso marker="#open-1"><c>ct_netconfc:open/1</c></seealso>,
+ but does not send a <c>hello</c> message.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>only_open(KeyOrName, ExtraOptions) -&gt; Result</name>
+ <fsummary>Opens a name NETCONF session, but does not send
+ hello.</fsummary>
+ <type>
+ <v>KeyOrName = key_or_name()</v>
+ <v>ExtraOptions = options()</v>
+ <v>Result = {ok, handle()} | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="only_open-2"/>
+ <p>Opens a name NETCONF session, but does not send <c>hello</c>.</p>
+
+ <p>As <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>,
+ but does not send a <c>hello</c> message.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>open(Options) -&gt; Result</name>
+ <fsummary>Opens a NETCONF session and exchanges hello messages.</fsummary>
+ <type>
+ <v>Options = options()</v>
+ <v>Result = {ok, handle()} | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="open-1"/>
+ <p>Opens a NETCONF session and exchanges <c>hello</c> messages.</p>
+
+ <p>If the server options are specified in a configuration file,
+ or if a named client is needed for logging purposes (see section
+ <seealso marker="#Logging">Logging</seealso> in this module), use
+ <seealso marker="#open-2"><c>ct_netconfc:open/2</c></seealso>
+ instead.</p>
+
+ <p>The opaque <c>handler()</c> reference returned from this
+ function is required as client identifier when calling any other
+ function in this module.</p>
+
+ <p>Option <c>timeout</c> (milliseconds) is used when setting up the
+ SSH connection and when waiting for the <c>hello</c> message from
+ the server. It is not used for any other purposes during the
+ lifetime of the connection.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>open(KeyOrName, ExtraOptions) -&gt; Result</name>
+ <fsummary>Opens a named NETCONF session and exchanges hello
+ messages.</fsummary>
+ <type>
+ <v>KeyOrName = key_or_name()</v>
+ <v>ExtraOptions = options()</v>
+ <v>Result = {ok, handle()} | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="open-2"/>
+ <p>Opens a named NETCONF session and exchanges <c>hello</c>
+ messages.</p>
+
+ <p>If <c>KeyOrName</c> is a configured <c>server_id()</c> or a
+ <c>target_name()</c> associated with such an Id, then the options
+ for this server are fetched from the configuration file.</p>
+
+ <p>Argument <c>ExtraOptions</c> is added to the options found in the
+ configuration file. If the same options are specified, the values
+ from the configuration file overwrite <c>ExtraOptions</c>.</p>
+
+ <p>If the server is not specified in a configuration file, use
+ <seealso marker="#open-1"><c>ct_netconfc:open/1</c></seealso>
+ instead.</p>
+
+ <p>The opaque <c>handle()</c> reference returned from this
+ function can be used as client identifier when calling any other
+ function in this module. However, if <c>KeyOrName</c> is a
+ <c>target_name()</c>, that is, if the server is named through a
+ call to <seealso marker="ct#require-2"><c>ct:require/2</c></seealso>
+ or a <c>require</c> statement in the test suite, then this name can
+ be used instead of <c>handle()</c>.</p>
+
+ <p>Option <c>timeout</c> (milliseconds) is used when setting up the
+ SSH connection and when waiting for the <c>hello</c> message from
+ the server. It is not used for any other purposes during the
+ lifetime of the connection.</p>
+
+ <p>See also
+ <seealso marker="ct#require-2"><c>ct:require/2</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(Client, SimpleXml) -&gt; Result</name>
+ <fsummary>Equivalent to send(Client, SimpleXml, infinity).</fsummary>
+ <desc><marker id="send-2"/>
+ <p>Equivalent to
+ <seealso marker="#send-3"><c>ct_netconfc:send(Client, SimpleXml,
+ infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(Client, SimpleXml, Timeout) -&gt; Result</name>
+ <fsummary>Sends an XML document to the server.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>SimpleXml = simple_xml()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = simple_xml() | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="send-3"/>
+ <p>Sends an XML document to the server.</p>
+
+ <p>The specified XML document is sent "as is" to the server. This
+ function can be used for sending XML documents that cannot be
+ expressed by other interface functions in this module.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_rpc(Client, SimpleXml) -&gt; Result</name>
+ <fsummary>Equivalent to send_rpc(Client, SimpleXml, infinity).</fsummary>
+ <desc><marker id="send_rpc-2"/>
+ <p>Equivalent to
+ <seealso marker="#send_rpc-3"><c>ct_netconfc:send_rpc(Client,
+ SimpleXml, infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_rpc(Client, SimpleXml, Timeout) -&gt; Result</name>
+ <fsummary>Sends a NETCONF rpc request to the server.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>SimpleXml = simple_xml()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = [simple_xml()] | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="send_rpc-3"/>
+ <p>Sends a NETCONF <c>rpc</c> request to the server.</p>
+
+ <p>The specified XML document is wrapped in a valid NETCONF <c>rpc</c>
+ request and sent to the server. The <c>message-id</c> and namespace
+ attributes are added to element <c>rpc</c>.</p>
+
+ <p>This function can be used for sending <c>rpc</c> requests that
+ cannot be expressed by other interface functions in this module.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>unlock(Client, Target) -&gt; Result</name>
+ <fsummary>Equivalent to unlock(Client, Target, infinity).</fsummary>
+ <desc><marker id="unlock-2"/>
+ <p>Equivalent to
+ <seealso marker="#unlock-3"><c>ct_netconfc:unlock(Client, Target,
+ infinity)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>unlock(Client, Target, Timeout) -&gt; Result</name>
+ <fsummary>Unlocks the configuration target.</fsummary>
+ <type>
+ <v>Client = client()</v>
+ <v>Target = netconf_db()</v>
+ <v>Timeout = timeout()</v>
+ <v>Result = ok | {error, error_reason()}</v>
+ </type>
+ <desc><marker id="unlock-3"/>
+ <p>Unlocks the configuration target.</p>
+
+ <p>If the client earlier has acquired a lock through
+ <seealso marker="#lock-2"><c>ct_netconfc:lock/2</c></seealso> or
+ <seealso marker="#lock-3"><c>ct_netconfc:lock/3</c></seealso>, this
+ operation releases the associated lock. To access another target
+ than <c>running</c>, the server must support <c>:candidate</c>
+ and/or <c>:startup</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ct_property_test.xml b/lib/common_test/doc/src/ct_property_test.xml
new file mode 100644
index 0000000000..2e9bd1969c
--- /dev/null
+++ b/lib/common_test/doc/src/ct_property_test.xml
@@ -0,0 +1,116 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct_property_test</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct_property_test.xml</file>
+ </header>
+ <module>ct_property_test</module>
+ <modulesummary>EXPERIMENTAL support in Common Test for calling
+ property-based tests.</modulesummary>
+
+ <description>
+
+ <p>EXPERIMENTAL support in <c>Common Test</c> for calling property-based
+ tests.</p>
+
+ <p>This module is a first step to run property-based tests in the
+ <c>Common Test</c> framework. A property testing tool like QuickCheck
+ or PropEr is assumed to be installed.</p>
+
+ <p>The idea is to have a <c>Common Test</c> test suite calling a property
+ testing tool with special property test suites as defined by that tool.
+ The usual Erlang application directory structure is assumed. The tests
+ are collected in the <c>test</c> directory of the application. The
+ <c>test</c> directory has a subdirectory <c>property_test</c>, where
+ everything needed for the property tests is collected.</p>
+
+ <p>A typical <c>Common Test</c> test suite using <c>ct_property_test</c>
+ is organized as follows:</p>
+
+ <pre>
+ -include_lib("common_test/include/ct.hrl").
+
+ all() -&gt; [prop_ftp_case].
+
+ init_per_suite(Config) -&gt;
+ ct_property_test:init_per_suite(Config).
+
+ %%%---- test case
+ prop_ftp_case(Config) -&gt;
+ ct_property_test:quickcheck(
+ ftp_simple_client_server:prop_ftp(Config),
+ Config
+ ).</pre>
+
+ <warning>
+ <p>This is experimental code that can be changed or removed anytime
+ without any warning.</p>
+ </warning>
+
+ </description>
+
+ <funcs>
+ <func>
+ <name>init_per_suite(Config) -&gt; Config | {skip, Reason}</name>
+ <fsummary>Initializes Config for property testing.</fsummary>
+ <desc><marker id="init_per_suite-1"/>
+ <p>Initializes <c>Config</c> for property testing.</p>
+
+ <p>This function investigates if support is available for either
+ Quickcheck, PropEr, or Triq. The options
+ <c>{property_dir,AbsPath}</c> and <c>{property_test_tool,Tool}</c>
+ are set in the <c>Config</c> returned.</p>
+
+ <p>The function is intended to be called in function
+ <c>init_per_suite</c> in the test suite.</p>
+
+ <p>The property tests are assumed to be in subdirectory
+ <c>property_test</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>quickcheck(Property, Config) -&gt; true | {fail, Reason}</name>
+ <fsummary>Calls quickcheck and returns the result in a form suitable for
+ Common Test.</fsummary>
+ <desc><marker id="quickcheck-2"/>
+ <p>Calls quickcheck and returns the result in a form suitable for
+ <c>Common Test</c>.</p>
+
+ <p>This function is intended to be called in the test cases in the
+ test suite.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ct_rpc.xml b/lib/common_test/doc/src/ct_rpc.xml
new file mode 100644
index 0000000000..132d04545d
--- /dev/null
+++ b/lib/common_test/doc/src/ct_rpc.xml
@@ -0,0 +1,220 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct_rpc</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct_rpc.xml</file>
+ </header>
+ <module>ct_rpc</module>
+ <modulesummary>Common Test specific layer on Erlang/OTP rpc.</modulesummary>
+
+ <description>
+
+ <p><c>Common Test</c> specific layer on Erlang/OTP <c>rpc</c>.</p>
+
+ </description>
+
+ <funcs>
+ <func>
+ <name>app_node(App, Candidates) -&gt; NodeName</name>
+ <fsummary>From a set of candidate nodes determines which of them is
+ running the application App.</fsummary>
+ <type>
+ <v>App = atom()</v>
+ <v>Candidates = [NodeName]</v>
+ <v>NodeName = atom()</v>
+ </type>
+ <desc><marker id="app_node-2"/>
+ <p>From a set of candidate nodes determines which of them is running
+ the application <c>App</c>. If none of the candidate nodes is
+ running <c>App</c>, the function makes the test case calling
+ this function to fail. This function is the same as calling
+ <c>app_node(App, Candidates, true)</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>app_node(App, Candidates, FailOnBadRPC) -&gt; NodeName</name>
+ <fsummary>Same as app_node/2, except that argument FailOnBadRPC
+ determines if the search for a candidate node is to stop if
+ badrpc is received at some point.</fsummary>
+ <type>
+ <v>App = atom()</v>
+ <v>Candidates = [NodeName]</v>
+ <v>NodeName = atom()</v>
+ <v>FailOnBadRPC = true | false</v>
+ </type>
+ <desc><marker id="app_node-3"/>
+ <p>Same as
+ <seealso marker="app_node-2"><c>ct_rpc:app_node/2</c></seealso>,
+ except that argument <c>FailOnBadRPC</c> determines if the search
+ for a candidate node is to stop if <c>badrpc</c> is received at
+ some point.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>app_node(App, Candidates, FailOnBadRPC, Cookie) -&gt; NodeName</name>
+ <fsummary>Same as app_node/2, except that argument FailOnBadRPC
+ determines if the search for a candidate node is to stop if badrpc is
+ received at some point.</fsummary>
+ <type>
+ <v>App = atom()</v>
+ <v>Candidates = [NodeName]</v>
+ <v>NodeName = atom()</v>
+ <v>FailOnBadRPC = true | false</v>
+ <v>Cookie = atom()</v>
+ </type>
+ <desc><marker id="app_node-4"/>
+ <p>Same as
+ <seealso marker="app_node-2"><c>ct_rpc:app_node/2</c></seealso>,
+ except that argument <c>FailOnBadRPC</c> determines if the search
+ for a candidate node is to stop if <c>badrpc</c> is received at
+ some point.</p>
+
+ <p>The cookie on the client node is set to <c>Cookie</c> for this
+ <c>rpc</c> operation (used to match the server node cookie).</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>call(Node, Module, Function, Args) -&gt; term() | {badrpc, Reason}</name>
+ <fsummary>Same as call(Node, Module, Function, Args, infinity).</fsummary>
+ <desc><marker id="call-4"/>
+ <p>Same as <c>call(Node, Module, Function, Args, infinity)</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>call(Node, Module, Function, Args, TimeOut) -&gt; term() | {badrpc, Reason}</name>
+ <fsummary>Evaluates apply(Module, Function, Args) on the node
+ Node.</fsummary>
+ <type>
+ <v>Node = NodeName | {Fun, FunArgs}</v>
+ <v>Fun = function()</v>
+ <v>FunArgs = term()</v>
+ <v>NodeName = atom()</v>
+ <v>Module = atom()</v>
+ <v>Function = atom()</v>
+ <v>Args = [term()]</v>
+ <v>Reason = timeout | term()</v>
+ </type>
+ <desc><marker id="call-5"/>
+ <p>Evaluates <c>apply(Module, Function, Args)</c> on the node
+ <c>Node</c>. Returns either whatever <c>Function</c> returns, or
+ <c>{badrpc, Reason}</c> if the remote procedure call fails. If
+ <c>Node</c> is <c>{Fun, FunArgs}</c>, applying <c>Fun</c> to
+ <c>FunArgs</c> is to return a node name.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>call(Node, Module, Function, Args, TimeOut, Cookie) -&gt; term() | {badrpc, Reason}</name>
+ <fsummary>Evaluates apply(Module, Function, Args) on the node
+ Node.</fsummary>
+ <type>
+ <v>Node = NodeName | {Fun, FunArgs}</v>
+ <v>Fun = function()</v>
+ <v>FunArgs = term()</v>
+ <v>NodeName = atom()</v>
+ <v>Module = atom()</v>
+ <v>Function = atom()</v>
+ <v>Args = [term()]</v>
+ <v>Reason = timeout | term()</v>
+ <v>Cookie = atom()</v>
+ </type>
+ <desc><marker id="call-6"/>
+ <p>Evaluates <c>apply(Module, Function, Args)</c> on the node
+ <c>Node</c>. Returns either whatever <c>Function</c> returns, or
+ <c>{badrpc, Reason}</c> if the remote procedure call fails. If
+ <c>Node</c> is <c>{Fun, FunArgs}</c>, applying <c>Fun</c> to
+ <c>FunArgs</c> is to return a node name.</p>
+
+ <p>The cookie on the client node is set to <c>Cookie</c> for this
+ <c>rpc</c> operation (used to match the server node cookie).</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>cast(Node, Module, Function, Args) -&gt; ok</name>
+ <fsummary>Evaluates apply(Module, Function, Args) on the node
+ Node.</fsummary>
+ <type>
+ <v>Node = NodeName | {Fun, FunArgs}</v>
+ <v>Fun = function()</v>
+ <v>FunArgs = term()</v>
+ <v>NodeName = atom()</v>
+ <v>Module = atom()</v>
+ <v>Function = atom()</v>
+ <v>Args = [term()]</v>
+ <v>Reason = timeout | term()</v>
+ </type>
+ <desc><marker id="cast-4"/>
+ <p>Evaluates <c>apply(Module, Function, Args)</c> on the node
+ <c>Node</c>. No response is delivered and the process that makes
+ the call is not suspended until the evaluation is completed as in
+ the case of <c>call/3,4</c>. If <c>Node</c> is
+ <c>{Fun, FunArgs}</c>, applying <c>Fun</c> to <c>FunArgs</c> is to
+ return a node name.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>cast(Node, Module, Function, Args, Cookie) -&gt; ok</name>
+ <fsummary>Evaluates apply(Module, Function, Args) on the node
+ Node.</fsummary>
+ <type>
+ <v>Node = NodeName | {Fun, FunArgs}</v>
+ <v>Fun = function()</v>
+ <v>FunArgs = term()</v>
+ <v>NodeName = atom()</v>
+ <v>Module = atom()</v>
+ <v>Function = atom()</v>
+ <v>Args = [term()]</v>
+ <v>Reason = timeout | term()</v>
+ <v>Cookie = atom()</v>
+ </type>
+ <desc><marker id="cast-5"/>
+ <p>Evaluates <c>apply(Module, Function, Args)</c> on the node
+ <c>Node</c>. No response is delivered and the process that makes
+ the call is not suspended until the evaluation is completed as in
+ the case of <c>call/3,4</c>. If <c>Node</c> is
+ <c>{Fun, FunArgs}</c>, applying <c>Fun</c> to <c>FunArgs</c> is to
+ return a node name.</p>
+
+ <p>The cookie on the client node is set to <c>Cookie</c> for this
+ <c>rpc</c> operation (used to match the server node cookie).</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ct_run.xml b/lib/common_test/doc/src/ct_run.xml
index 5518bb039b..a1ad060366 100644
--- a/lib/common_test/doc/src/ct_run.xml
+++ b/lib/common_test/doc/src/ct_run.xml
@@ -33,179 +33,190 @@
<file>ct_run.xml</file>
</header>
<com>ct_run</com>
- <comsummary>Program used for starting Common Test from the
- OS command line.
- </comsummary>
+ <comsummary>Program used for starting <c>Common Test</c> from the
+ OS command line.</comsummary>
<description>
<p>The <c>ct_run</c> program is automatically installed with Erlang/OTP
- and Common Test (please see the Installation chapter in the Common
- Test User's Guide for more information). The program accepts a number
- of different start flags. Some flags trigger <c>ct_run</c>
- to start the Common Test application and pass on data to it. Some
- flags start an Erlang node prepared for running Common Test in a
- particular mode.</p>
-
- <p>There is an interface function that corresponds to this program,
- called <seealso marker="ct#run_test-1"><c>ct:run_test/1</c></seealso>, for starting Common Test from the Erlang
- shell (or an Erlang program). Please see the <c>ct</c> man page for
- details.</p>
+ and the <c>Common Test</c> application (for more information, see
+ section <seealso marker="install_chapter">Installation</seealso>
+ in the User's Guide). The program accepts different start flags.
+ Some flags trigger <c>ct_run</c> to start <c>Common Test</c> and
+ pass on data to it. Some flags start an Erlang node prepared for
+ running <c>Common Test</c> in a particular mode.</p>
+
+ <p>The interface function
+ <seealso marker="ct#run_test-1"><c>ct:run_test/1</c></seealso>,
+ corresponding to the <c>ct_run</c> program, is used for starting
+ <c>Common Test</c> from the Erlang shell (or an Erlang program).
+ For details, see the <seealso marker="ct"><c>ct</c></seealso>
+ manual page.</p>
<p><c>ct_run</c> also accepts Erlang emulator flags. These are used
- when <c>ct_run</c> calls <c>erl</c> to start the Erlang node
- (making it possible to e.g. add directories to the code server path,
- change the cookie on the node, start additional applications, etc).</p>
-
- <p>With the optional flag:</p>
- <pre>-erl_args</pre>
- <p>it's possible to divide the options on the <c>ct_run</c> command line into
- two groups, one that Common Test should process (those preceding <c>-erl_args</c>),
- and one it should completely ignore and pass on directly to the emulator
- (those following <c>-erl_args</c>). Options preceding <c>-erl_args</c> that Common Test
- doesn't recognize, also get passed on to the emulator untouched.
- By means of <c>-erl_args</c> the user may specify flags with the same name, but
+ when <c>ct_run</c> calls <c>erl</c> to start the Erlang node (this
+ makes it possible to add directories to the code server path,
+ change the cookie on the node, start more applications, and so on).</p>
+
+ <p>With the optional flag <c>-erl_args</c>, options on the <c>ct_run</c>
+ command line can be divided into two groups:</p>
+
+ <list type="bulleted">
+ <item>One group that <c>Common Test</c> is to process (those
+ preceding <c>-erl_args</c>).</item>
+ <item>One group that <c>Common Test</c> is to ignore and pass on
+ directly to the emulator (those following <c>-erl_args</c>).</item>
+ </list>
+
+ <p>Options preceding <c>-erl_args</c> that <c>Common Test</c>
+ does not recognize are also passed on to the emulator untouched.
+ By <c>-erl_args</c> the user can specify flags with the same name, but
with different destinations, on the <c>ct_run</c> command line.</p>
- <p>If <c>-pa</c> or <c>-pz</c> flags are specified in the Common Test group of options
- (preceding <c>-erl_args</c>), relative directories will be converted to
- absolute and re-inserted into the code path by Common Test (to avoid
- problems loading user modules when Common Test changes working directory
- during test runs). Common Test will however ignore <c>-pa</c> and <c>-pz</c> flags
- following <c>-erl_args</c> on the command line. These directories are added
- to the code path normally (i.e. on specified form)</p>
-
- <p>Exit status is set before the program ends. Value <c>0</c> indicates a successful
- test result, <c>1</c> indicates one or more failed or auto-skipped test cases, and
- <c>2</c> indicates test execution failure.</p>
-
- <p>If <c>ct_run</c> is called with option:</p>
- <pre>-help</pre>
- <p>it prints all valid start flags to stdout.</p>
- </description>
+ <p>If flags <c>-pa</c> or <c>-pz</c> are specified in the
+ <c>Common Test</c> group of options (preceding <c>-erl_args</c>),
+ relative directories are converted to absolute and reinserted into
+ the code path by <c>Common Test</c>. This is to avoid problems
+ loading user modules when <c>Common Test</c> changes working directory
+ during test runs. However, <c>Common Test</c> ignores flags <c>-pa</c>
+ and <c>-pz</c> following <c>-erl_args</c> on the command line. These
+ directories are added to the code path normally (that is, on specified
+ form).</p>
+
+ <p>Exit status is set before the program ends. Value <c>0</c> indicates
+ a successful test result, <c>1</c> indicates one or more failed or
+ auto-skipped test cases, and <c>2</c> indicates test execution failure.</p>
+
+ <p>If <c>ct_run</c> is called with option <c>-help</c>, it prints all
+ valid start flags to <c>stdout</c>.</p>
+ </description>
<section>
<marker id="ct_run"></marker>
- <title>Run tests from command line</title>
+ <title>Run Tests from Command Line</title>
<pre>
- ct_run -dir TestDir1 TestDir2 .. TestDirN |
- [-dir TestDir] -suite Suite1 Suite2 .. SuiteN
- [-group Groups1 Groups2 .. GroupsN] [-case Case1 Case2 .. CaseN]
- [-step [config | keep_inactive]]
- [-config ConfigFile1 ConfigFile2 .. ConfigFileN]
- [-userconfig CallbackModule1 ConfigString1 and CallbackModule2
- ConfigString2 and .. CallbackModuleN ConfigStringN]
- [-decrypt_key Key] | [-decrypt_file KeyFile]
- [-label Label]
- [-logdir LogDir]
- [-logopts LogOpts]
- [-verbosity GenVLevel | [Category1 VLevel1 and
- Category2 VLevel2 and .. CategoryN VLevelN]]
- [-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
- [-stylesheet CSSFile]
- [-cover CoverCfgFile]
- [-cover_stop Bool]
- [-event_handler EvHandler1 EvHandler2 .. EvHandlerN] |
- [-event_handler_init EvHandler1 InitArg1 and
- EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
- [-include InclDir1 InclDir2 .. InclDirN]
- [-no_auto_compile]
- [-abort_if_missing_suites]
- [-muliply_timetraps Multiplier]
- [-scale_timetraps]
- [-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
- [-repeat N] |
- [-duration HHMMSS [-force_stop [skip_rest]]] |
- [-until [YYMoMoDD]HHMMSS [-force_stop [skip_rest]]]
- [-basic_html]
- [-ct_hooks CTHModule1 CTHOpts1 and CTHModule2 CTHOpts2 and ..
- CTHModuleN CTHOptsN]
- [-exit_status ignore_config]
- [-help]
- </pre>
+ ct_run -dir TestDir1 TestDir2 .. TestDirN |
+ [-dir TestDir] -suite Suite1 Suite2 .. SuiteN
+ [-group Groups1 Groups2 .. GroupsN] [-case Case1 Case2 .. CaseN]
+ [-step [config | keep_inactive]]
+ [-config ConfigFile1 ConfigFile2 .. ConfigFileN]
+ [-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+ ConfigString2 and .. CallbackModuleN ConfigStringN]
+ [-decrypt_key Key] | [-decrypt_file KeyFile]
+ [-label Label]
+ [-logdir LogDir]
+ [-logopts LogOpts]
+ [-verbosity GenVLevel | [Category1 VLevel1 and
+ Category2 VLevel2 and .. CategoryN VLevelN]]
+ [-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
+ [-stylesheet CSSFile]
+ [-cover CoverCfgFile]
+ [-cover_stop Bool]
+ [-event_handler EvHandler1 EvHandler2 .. EvHandlerN] |
+ [-event_handler_init EvHandler1 InitArg1 and
+ EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
+ [-include InclDir1 InclDir2 .. InclDirN]
+ [-no_auto_compile]
+ [-abort_if_missing_suites]
+ [-muliply_timetraps Multiplier]
+ [-scale_timetraps]
+ [-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
+ [-repeat N] |
+ [-duration HHMMSS [-force_stop [skip_rest]]] |
+ [-until [YYMoMoDD]HHMMSS [-force_stop [skip_rest]]]
+ [-basic_html]
+ [-ct_hooks CTHModule1 CTHOpts1 and CTHModule2 CTHOpts2 and ..
+ CTHModuleN CTHOptsN]
+ [-exit_status ignore_config]
+ [-help]</pre>
</section>
+
<section>
- <title>Run tests using test specification</title>
+ <title>Run Tests using Test Specification</title>
<pre>
- ct_run -spec TestSpec1 TestSpec2 .. TestSpecN
- [-join_specs]
- [-config ConfigFile1 ConfigFile2 .. ConfigFileN]
- [-userconfig CallbackModule1 ConfigString1 and CallbackModule2
- ConfigString2 and .. and CallbackModuleN ConfigStringN]
- [-decrypt_key Key] | [-decrypt_file KeyFile]
- [-label Label]
- [-logdir LogDir]
- [-logopts LogOpts]
- [-verbosity GenVLevel | [Category1 VLevel1 and
- Category2 VLevel2 and .. CategoryN VLevelN]]
- [-allow_user_terms]
- [-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
- [-stylesheet CSSFile]
- [-cover CoverCfgFile]
- [-cover_stop Bool]
- [-event_handler EvHandler1 EvHandler2 .. EvHandlerN] |
- [-event_handler_init EvHandler1 InitArg1 and
- EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
- [-include InclDir1 InclDir2 .. InclDirN]
- [-no_auto_compile]
- [-abort_if_missing_suites]
- [-muliply_timetraps Multiplier]
- [-scale_timetraps]
- [-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
- [-repeat N] |
- [-duration HHMMSS [-force_stop [skip_rest]]] |
- [-until [YYMoMoDD]HHMMSS [-force_stop [skip_rest]]]
- [-basic_html]
- [-ct_hooks CTHModule1 CTHOpts1 and CTHModule2 CTHOpts2 and ..
- CTHModuleN CTHOptsN]
- [-exit_status ignore_config]
- </pre>
+ ct_run -spec TestSpec1 TestSpec2 .. TestSpecN
+ [-join_specs]
+ [-config ConfigFile1 ConfigFile2 .. ConfigFileN]
+ [-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+ ConfigString2 and .. and CallbackModuleN ConfigStringN]
+ [-decrypt_key Key] | [-decrypt_file KeyFile]
+ [-label Label]
+ [-logdir LogDir]
+ [-logopts LogOpts]
+ [-verbosity GenVLevel | [Category1 VLevel1 and
+ Category2 VLevel2 and .. CategoryN VLevelN]]
+ [-allow_user_terms]
+ [-silent_connections [ConnType1 ConnType2 .. ConnTypeN]]
+ [-stylesheet CSSFile]
+ [-cover CoverCfgFile]
+ [-cover_stop Bool]
+ [-event_handler EvHandler1 EvHandler2 .. EvHandlerN] |
+ [-event_handler_init EvHandler1 InitArg1 and
+ EvHandler2 InitArg2 and .. EvHandlerN InitArgN]
+ [-include InclDir1 InclDir2 .. InclDirN]
+ [-no_auto_compile]
+ [-abort_if_missing_suites]
+ [-muliply_timetraps Multiplier]
+ [-scale_timetraps]
+ [-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
+ [-repeat N] |
+ [-duration HHMMSS [-force_stop [skip_rest]]] |
+ [-until [YYMoMoDD]HHMMSS [-force_stop [skip_rest]]]
+ [-basic_html]
+ [-ct_hooks CTHModule1 CTHOpts1 and CTHModule2 CTHOpts2 and ..
+ CTHModuleN CTHOptsN]
+ [-exit_status ignore_config]</pre>
</section>
+
<section>
- <title>Run tests in web based GUI</title>
+ <title>Run Tests in Web-Based GUI</title>
<pre>
- ct_run -vts [-browser Browser]
- [-dir TestDir1 TestDir2 .. TestDirN] |
- [[dir TestDir] -suite Suite [[-group Group] [-case Case]]]
- [-config ConfigFile1 ConfigFile2 .. ConfigFileN]
- [-userconfig CallbackModule1 ConfigString1 and CallbackModule2
- ConfigString2 and .. and CallbackModuleN ConfigStringN]
- [-logopts LogOpts]
- [-verbosity GenVLevel | [Category1 VLevel1 and
- Category2 VLevel2 and .. CategoryN VLevelN]]
- [-decrypt_key Key] | [-decrypt_file KeyFile]
- [-include InclDir1 InclDir2 .. InclDirN]
- [-no_auto_compile]
- [-abort_if_missing_suites]
- [-muliply_timetraps Multiplier]
- [-scale_timetraps]
- [-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
- [-basic_html]</pre>
+ ct_run -vts [-browser Browser]
+ [-dir TestDir1 TestDir2 .. TestDirN] |
+ [[dir TestDir] -suite Suite [[-group Group] [-case Case]]]
+ [-config ConfigFile1 ConfigFile2 .. ConfigFileN]
+ [-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+ ConfigString2 and .. and CallbackModuleN ConfigStringN]
+ [-logopts LogOpts]
+ [-verbosity GenVLevel | [Category1 VLevel1 and
+ Category2 VLevel2 and .. CategoryN VLevelN]]
+ [-decrypt_key Key] | [-decrypt_file KeyFile]
+ [-include InclDir1 InclDir2 .. InclDirN]
+ [-no_auto_compile]
+ [-abort_if_missing_suites]
+ [-muliply_timetraps Multiplier]
+ [-scale_timetraps]
+ [-create_priv_dir auto_per_run | auto_per_tc | manual_per_tc]
+ [-basic_html]</pre>
</section>
+
<section>
- <title>Refresh the HTML index files</title>
+ <title>Refresh HTML Index Files</title>
<pre>
- ct_run -refresh_logs [-logdir LogDir] [-basic_html]</pre>
+ ct_run -refresh_logs [-logdir LogDir] [-basic_html]</pre>
</section>
+
<section>
- <title>Run CT in interactive mode</title>
+ <title>Run Common Test in Interactive Mode</title>
<pre>
- ct_run -shell
- [-config ConfigFile1 ConfigFile2 ... ConfigFileN]
- [-userconfig CallbackModule1 ConfigString1 and CallbackModule2
- ConfigString2 and .. and CallbackModuleN ConfigStringN]
- [-decrypt_key Key] | [-decrypt_file KeyFile]</pre>
+ ct_run -shell
+ [-config ConfigFile1 ConfigFile2 ... ConfigFileN]
+ [-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+ ConfigString2 and .. and CallbackModuleN ConfigStringN]
+ [-decrypt_key Key] | [-decrypt_file KeyFile]</pre>
</section>
+
<section>
- <title>Start a Common Test Master node</title>
+ <title>Start a Common Test Master Node</title>
<pre>
- ct_run -ctmaster</pre>
+ ct_run -ctmaster</pre>
</section>
<section>
- <title>See also</title>
- <p>Please read the <seealso marker="run_test_chapter">Running Test Suites</seealso>
- chapter in the Common Test User's Guide for information about the meaning of the
- different start flags.</p>
+ <title>See Also</title>
+ <p>For information about the start flags, see section
+ <seealso marker="run_test_chapter">Running Tests and Analyzing
+ Results</seealso> in the User's Guide.</p>
</section>
</comref>
+
diff --git a/lib/common_test/doc/src/ct_slave.xml b/lib/common_test/doc/src/ct_slave.xml
new file mode 100644
index 0000000000..44a7b7873f
--- /dev/null
+++ b/lib/common_test/doc/src/ct_slave.xml
@@ -0,0 +1,221 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct_slave</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct_slave.xml</file>
+ </header>
+ <module>ct_slave</module>
+ <modulesummary>Common Test framework functions for starting and stopping
+ nodes for Large-Scale Testing.</modulesummary>
+
+ <description>
+
+ <p><c>Common Test</c> framework functions for starting and stopping nodes
+ for Large-Scale Testing.</p>
+
+ <p>This module exports functions used by the <c>Common Test</c>
+ Master to start and stop "slave" nodes. It is the default callback
+ module for the <c>{init, node_start}</c> term in the Test
+ Specification.</p>
+
+ </description>
+
+ <funcs>
+ <func>
+ <name>start(Node) -&gt; Result</name>
+ <fsummary>Starts an Erlang node with name Node on the local
+ host.</fsummary>
+ <type>
+ <v>Node = atom()</v>
+ <v>Result = {ok, NodeName} | {error, Reason, NodeName}</v>
+ <v>Reason = already_started | started_not_connected | boot_timeout | init_timeout | startup_timeout | not_alive</v>
+ <v>NodeName = atom()</v>
+ </type>
+ <desc><marker id="start-1"/>
+ <p>Starts an Erlang node with name <c>Node</c> on the local host.</p>
+
+ <p>See also
+ <seealso marker="#start-3"><c>ct_slave:start/3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>start(HostOrNode, NodeOrOpts) -&gt; Result</name>
+ <fsummary>Starts an Erlang node with default options on a specified
+ host, or on the local host with specified options.</fsummary>
+ <type>
+ <v>HostOrNode = atom()</v>
+ <v>NodeOrOpts = atom() | list()</v>
+ <v>Result = {ok, NodeName} | {error, Reason, NodeName}</v>
+ <v>Reason = already_started | started_not_connected | boot_timeout | init_timeout | startup_timeout | not_alive</v>
+ <v>NodeName = atom()</v>
+ </type>
+ <desc><marker id="start-2"/>
+ <p>Starts an Erlang node with default options on a specified host, or
+ on the local host with specified options. That is, the call is
+ interpreted as <c>start(Host, Node)</c> when the second argument is
+ atom-valued and <c>start(Node, Opts)</c> when it is list-valued.</p>
+
+ <p>See also
+ <seealso marker="#start-3"><c>ct_slave:start/3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>start(Host, Node, Opts) -&gt; Result</name>
+ <fsummary>Starts an Erlang node with name Node on host Host as
+ specified by the combination of options in Opts.</fsummary>
+ <type>
+ <v>Node = atom()</v>
+ <v>Host = atom()</v>
+ <v>Opts = [OptTuples]</v>
+ <v>OptTuples = {username, Username} | {password, Password} | {boot_timeout, BootTimeout} | {init_timeout, InitTimeout} | {startup_timeout, StartupTimeout} | {startup_functions, StartupFunctions} | {monitor_master, Monitor} | {kill_if_fail, KillIfFail} | {erl_flags, ErlangFlags} | {env, [{EnvVar, Value}]}</v>
+ <v>Username = string()</v>
+ <v>Password = string()</v>
+ <v>BootTimeout = integer()</v>
+ <v>InitTimeout = integer()</v>
+ <v>StartupTimeout = integer()</v>
+ <v>StartupFunctions = [StartupFunctionSpec]</v>
+ <v>StartupFunctionSpec = {Module, Function, Arguments}</v>
+ <v>Module = atom()</v>
+ <v>Function = atom()</v>
+ <v>Arguments = [term]</v>
+ <v>Monitor = bool()</v>
+ <v>KillIfFail = bool()</v>
+ <v>ErlangFlags = string()</v>
+ <v>EnvVar = string()</v>
+ <v>Value = string()</v>
+ <v>Result = {ok, NodeName} | {error, Reason, NodeName}</v>
+ <v>Reason = already_started | started_not_connected | boot_timeout | init_timeout | startup_timeout | not_alive</v>
+ <v>NodeName = atom()</v>
+ </type>
+ <desc><marker id="start-3"/>
+ <p>Starts an Erlang node with name <c>Node</c> on host <c>Host</c> as
+ specified by the combination of options in <c>Opts</c>.</p>
+
+ <p>Options <c>Username</c> and <c>Password</c> are used to log on to the
+ remote host <c>Host</c>. <c>Username</c>, if omitted, defaults to
+ the current username. <c>Password</c> is empty by default.</p>
+
+ <p>A list of functions specified in option <c>Startup</c> are
+ executed after startup of the node. Notice that all used modules
+ are to be present in the code path on <c>Host</c>.</p>
+
+ <p>The time-outs are applied as follows:</p>
+
+ <taglist>
+ <tag><c>BootTimeout</c></tag>
+ <item><p>The time to start the Erlang node, in seconds. Defaults to
+ 3 seconds. If the node is not pingable within this time, the result
+ <c>{error, boot_timeout, NodeName}</c> is returned.</p></item>
+ <tag><c>InitTimeout</c></tag>
+ <item><p>The time to wait for the node until it calls the internal
+ callback function informing master about a successful startup.
+ Defaults to 1 second. In case of a timed out message, the result
+ <c>{error, init_timeout, NodeName}</c> is returned.</p></item>
+ <tag><c>StartupTimeout</c></tag>
+ <item><p>The time to wait until the node stops to run
+ <c>StartupFunctions</c>. Defaults to 1 second. If this time-out
+ occurs, the result <c>{error, startup_timeout, NodeName}</c> is
+ returned.</p></item>
+ </taglist>
+
+ <p><em>Options:</em></p>
+
+ <taglist>
+ <tag><c>monitor_master</c></tag>
+ <item><p>Specifies if the slave node is to be stopped if the
+ master node stops. Defaults to <c>false</c>.</p></item>
+ <tag><c>kill_if_fail</c></tag>
+ <item><p>Specifies if the slave node is to be killed if a time-out
+ occurs during initialization or startup. Defaults to <c>true</c>.
+ Notice that the node can also be still alive it the boot time-out
+ occurred, but it is not killed in this case.</p></item>
+ <tag><c>erlang_flags</c></tag>
+ <item><p>Specifies which flags are added to the parameters of the
+ executable <c>erl</c>.</p></item>
+ <tag><c>env</c></tag>
+ <item><p>Specifies a list of environment variables that will extend
+ the environment.</p></item>
+ </taglist>
+
+ <p><em>Special return values:</em></p>
+
+ <list type="bulleted">
+ <item><p><c>{error, already_started, NodeName}</c> if the node
+ with the specified name is already started on a specified
+ host.</p></item>
+ <item><p><c>{error, started_not_connected, NodeName}</c> if the
+ node is started, but not connected to the master node.</p></item>
+ <item><p><c>{error, not_alive, NodeName}</c> if the node on which
+ <seealso marker="#start-3"><c>ct_slave:start/3</c></seealso> is
+ called, is not alive. Notice that <c>NodeName</c> is the name of
+ the current node in this case.</p></item>
+ </list>
+ </desc>
+ </func>
+
+ <func>
+ <name>stop(Node) -&gt; Result</name>
+ <fsummary>Stops the running Erlang node with name Node on the local
+ host.</fsummary>
+ <type>
+ <v>Node = atom()</v>
+ <v>Result = {ok, NodeName} | {error, Reason, NodeName}</v>
+ <v>Reason = not_started | not_connected | stop_timeout</v>
+ </type>
+ <desc><marker id="stop-1"/>
+ <p>Stops the running Erlang node with name <c>Node</c> on the local
+ host.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>stop(Host, Node) -&gt; Result</name>
+ <fsummary>Stops the running Erlang node with name Node on host
+ Host.</fsummary>
+ <type>
+ <v>Host = atom()</v>
+ <v>Node = atom()</v>
+ <v>Result = {ok, NodeName} | {error, Reason, NodeName}</v>
+ <v>Reason = not_started | not_connected | stop_timeout</v>
+ <v>NodeName = atom()</v>
+ </type>
+ <desc><marker id="stop-2"/>
+ <p>Stops the running Erlang node with name <c>Node</c> on host
+ <c>Host</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ct_snmp.xml b/lib/common_test/doc/src/ct_snmp.xml
new file mode 100644
index 0000000000..60f1d600e0
--- /dev/null
+++ b/lib/common_test/doc/src/ct_snmp.xml
@@ -0,0 +1,524 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct_snmp</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct_snmp.xml</file>
+ </header>
+ <module>ct_snmp</module>
+ <modulesummary>Common Test user interface module for the SNMP application.</modulesummary>
+
+ <description>
+
+ <p><c>Common Test</c> user interface module for the <c>SNMP</c>
+ application.</p>
+
+ <p>The purpose of this module is to simplify SNMP configuration for the
+ test case writer. Many test cases can use default values for common
+ operations and then no SNMP configuration files need to be supplied.
+ When it is necessary to change particular configuration parameters, a
+ subset of the relevant SNMP configuration files can be passed to
+ <c>ct_snmp</c> by <c>Common Test</c> configuration files. For more
+ specialized configuration parameters, a simple SNMP configuration file
+ can be placed in the test suite data directory. To simplify the test
+ suite, <c>Common Test</c> keeps track of some of the SNMP manager
+ information. This way the test suite does not have to handle as many
+ input parameters as if it had to interface wthe OTP SNMP manager
+ directly.</p>
+
+ <p><em>Configurable SNMP Manager and Agent Parameters:</em></p>
+
+ <p>Manager configuration:</p>
+
+ <taglist>
+ <tag><c>[{start_manager, boolean()}</c></tag>
+ <item><p>Optional. Default is <c>true</c>.</p></item>
+ <tag><c>{users, [{user_name(), [call_back_module(), user_data()]}]}</c></tag>
+ <item><p>Optional.</p></item>
+ <tag><c>{usm_users, [{usm_user_name(), [usm_config()]}]}</c></tag>
+ <item><p>Optional. SNMPv3 only.</p></item>
+ <tag><c>{managed_agents,[{agent_name(), [user_name(), agent_ip(), agent_port(), [agent_config()]]}]}</c></tag>
+ <item><p><c>managed_agents</c> is optional.</p></item>
+ <tag><c>{max_msg_size, integer()}</c></tag>
+ <item><p>Optional. Default is <c>484</c>.</p></item>
+ <tag><c>{mgr_port, integer()}</c></tag>
+ <item><p>Optional. Default is <c>5000</c>.</p></item>
+ <tag><c>{engine _id, string()}</c></tag>
+ <item><p>Optional. Default is <c>"mgrEngine"</c>.</p></item>
+ </taglist>
+
+ <p>Agent configuration:</p>
+
+ <taglist>
+ <tag><c>{start_agent, boolean()}</c></tag>
+ <item><p>Optional. Default is <c>false</c>.</p></item>
+ <tag><c>{agent_sysname, string()}</c></tag>
+ <item><p>Optional. Default is <c>"ct_test"</c>.</p></item>
+ <tag><c>{agent_manager_ip, manager_ip()}</c></tag>
+ <item><p>Optional. Default is <c>localhost</c>.</p></item>
+ <tag><c>{agent_vsns, list()}</c></tag>
+ <item><p>Optional. Default is <c>[v2]</c>.</p></item>
+ <tag><c>{agent_trap_udp, integer()}</c></tag>
+ <item><p>Optional. Default is <c>5000</c>.</p></item>
+ <tag><c>{agent_udp, integer()}</c></tag>
+ <item><p>Optional. Default is <c>4000</c>.</p></item>
+ <tag><c>{agent_notify_type, atom()}</c></tag>
+ <item><p>Optional. Default is <c>trap</c>.</p></item>
+ <tag><c>{agent_sec_type, sec_type()}</c></tag>
+ <item><p>Optional. Default is <c>none</c>.</p></item>
+ <tag><c>{agent_passwd, string()}</c></tag>
+ <item><p>Optional. Default is <c>""</c>.</p></item>
+ <tag><c>{agent_engine_id, string()}</c></tag>
+ <item><p>Optional. Default is <c>"agentEngine"</c>.</p></item>
+ <tag><c>{agent_max_msg_size, string()}</c></tag>
+ <item><p>Optional. Default is <c>484</c>.</p></item>
+ </taglist>
+
+ <p>The following parameters represents the SNMP configuration files
+ <c>context.conf</c>, <c>standard.conf</c>, <c>community.conf</c>,
+ <c>vacm.conf</c>, <c>usm.conf</c>, <c>notify.conf</c>,
+ <c>target_addr.conf</c>, and <c>target_params.conf</c>. Notice that
+ all values in <c>agent.conf</c> can be modified by the parameters
+ listed above. All these configuration files have default values set by
+ the <c>SNMP</c> application. These values can be overridden by suppling
+ a list of valid configuration values or a file located in the test
+ suites data directory, which can produce a list of valid configuration
+ values if you apply function <c>file:consult/1</c> to the file.</p>
+
+ <taglist>
+ <tag><c>{agent_contexts, [term()] | {data_dir_file, rel_path()}}</c></tag>
+ <item><p>Optional.</p></item>
+ <tag><c>{agent_community, [term()] | {data_dir_file, rel_path()}}</c></tag>
+ <item><p>Optional.</p></item>
+ <tag><c>{agent_sysinfo, [term()] | {data_dir_file, rel_path()}}</c></tag>
+ <item><p>Optional.</p></item>
+ <tag><c>{agent_vacm, [term()] | {data_dir_file, rel_path()}}</c></tag>
+ <item><p>Optional.</p></item>
+ <tag><c>{agent_usm, [term()] | {data_dir_file, rel_path()}}</c></tag>
+ <item><p>Optional.</p></item>
+ <tag><c>{agent_notify_def, [term()] | {data_dir_file, rel_path()}}</c></tag>
+ <item><p>Optional.</p></item>
+ <tag><c>{agent_target_address_def, [term()] | {data_dir_file, rel_path()}}</c></tag>
+ <item><p>Optional.</p></item>
+ <tag><c>{agent_target_param_def, [term()] | {data_dir_file, rel_path()}}</c></tag>
+ <item><p>Optional.</p></item>
+ </taglist>
+
+ <p>Parameter <c>MgrAgentConfName</c> in the functions is to be a name
+ you allocate in your test suite using a <c>require</c> statement.
+ Example (where <c>MgrAgentConfName = snmp_mgr_agent</c>):</p>
+
+ <pre>
+ suite() -&gt; [{require, snmp_mgr_agent, snmp}].</pre>
+
+ <p>or</p>
+
+ <pre>
+ ct:require(snmp_mgr_agent, snmp).</pre>
+
+ <p>Notice that USM users are needed for SNMPv3 configuration and are
+ not to be confused with users.</p>
+
+ <p>SNMP traps, inform, and report messages are handled by the user
+ callback module. For details, see the
+ <seealso marker="snmp"><c>SNMP</c></seealso> application.</p>
+
+ <p>It is recommended to use the <c>.hrl</c> files created by the
+ Erlang/OTP MIB compiler to define the Object Identifiers (OIDs).
+ For example, to get the Erlang node name from <c>erlNodeTable</c>
+ in the OTP-MIB:</p>
+
+ <pre>
+ Oid = ?erlNodeEntry ++ [?erlNodeName, 1]</pre>
+
+ <p>Furthermore, values can be set for <c>SNMP</c> application configuration
+ parameters, <c>config</c>, <c>server</c>, <c>net_if</c>, and so on (for
+ a list of valid parameters and types, see the User's Guide for
+ the <seealso marker="snmp"><c>SNMP</c></seealso> application). This is
+ done by defining a configuration data variable on the following form:</p>
+
+ <pre>
+ {snmp_app, [{manager, [snmp_app_manager_params()]},
+ {agent, [snmp_app_agent_params()]}]}.</pre>
+
+ <p>A name for the data must be allocated in the suite using
+ <c>require</c> (see the example above). Pass this name as argument
+ <c>SnmpAppConfName</c> to
+ <seealso marker="#start-3"><c>ct_snmp:start/3</c></seealso>.
+ <c>ct_snmp</c> specifies default values for some <c>SNMP</c> application
+ configuration parameters (such as <c>{verbosity,trace}</c> for parameter
+ <c>config</c>). This set of defaults is merged with the parameters
+ specified by the user. The user values override <c>ct_snmp</c>
+ defaults.</p>
+
+ </description>
+
+ <section>
+ <title>Data Types</title>
+ <marker id="types"/>
+ <taglist>
+ <tag><c>agent_config() = {Item, Value}</c></tag>
+ <item><marker id="type-agent_config"/> </item>
+ <tag><c>agent_ip() = ip()</c></tag>
+ <item><marker id="type-agent_ip"/> </item>
+ <tag><c>agent_name() = atom()</c></tag>
+ <item><marker id="type-agent_name"/> </item>
+ <tag><c>agent_port() = integer()</c></tag>
+ <item><marker id="type-agent_port"/> </item>
+ <tag><c>call_back_module() = atom()</c></tag>
+ <item><marker id="type-call_back_module"/> </item>
+ <tag><c>error_index() = integer()</c></tag>
+ <item><marker id="type-error_index"/> </item>
+ <tag><c>error_status() = noError | atom()</c></tag>
+ <item><marker id="type-error_status"/> </item>
+ <tag><c>ip() = string() | {integer(), integer(), integer(), integer()}</c></tag>
+ <item><marker id="type-ip"/> </item>
+ <tag><c>manager_ip() = ip()</c></tag>
+ <item><marker id="type-manager_ip"/> </item>
+ <tag><c>oid() = [byte()]</c></tag>
+ <item><marker id="type-oid"/> </item>
+ <tag><c>oids() = [oid()]</c></tag>
+ <item><marker id="type-oids"/> </item>
+ <tag><c>rel_path() = string()</c></tag>
+ <item><marker id="type-rel_path"/> </item>
+ <tag><c>sec_type() = none | minimum | semi</c></tag>
+ <item><marker id="type-sec_type"/> </item>
+ <tag><c>snmp_app_agent_params() = term()</c></tag>
+ <item><marker id="type-snmp_app_agent_params"/> </item>
+ <tag><c>snmp_app_manager_params() = term()</c></tag>
+ <item><marker id="type-snmp_app_manager_params"/> </item>
+ <tag><c>snmpreply() = {error_status(), error_index(), varbinds()}</c></tag>
+ <item><marker id="type-snmpreply"/> </item>
+ <tag><c>user_data() = term()</c></tag>
+ <item><marker id="type-user_data"/> </item>
+ <tag><c>user_name() = atom()</c></tag>
+ <item><marker id="type-user_name"/> </item>
+ <tag><c>usm_config() = {Item, Value}</c></tag>
+ <item><marker id="type-usm_config"/> </item>
+ <tag><c>usm_user_name() = string()</c></tag>
+ <item><marker id="type-usm_user_name"/> </item>
+ <tag><c>value_type() = o('OBJECT IDENTIFIER') | i('INTEGER') | u('Unsigned32') | g('Unsigned32') | s('OCTET STRING')</c></tag>
+ <item><marker id="type-value_type"/> </item>
+ <tag><c>var_and_val() = {oid(), value_type(), value()}</c></tag>
+ <item><marker id="type-var_and_val"/> </item>
+ <tag><c>varbind() = term()</c></tag>
+ <item><marker id="type-varbind"/> </item>
+ <tag><c>varbinds() = [varbind()]</c></tag>
+ <item><marker id="type-varbinds"/> </item>
+ <tag><c>varsandvals() = [var_and_val()]</c></tag>
+ <item><marker id="type-varsandvals"/> </item>
+ </taglist>
+ <p>These data types are described in the documentation for
+ the <seealso marker="snmp"><c>SNMP</c></seealso> application.</p>
+ </section>
+
+ <funcs>
+ <func>
+ <name>get_next_values(Agent, Oids, MgrAgentConfName) -&gt; SnmpReply</name>
+ <fsummary>Issues a synchronous SNMP get next request.</fsummary>
+ <type>
+ <v>Agent = agent_name()</v>
+ <v>Oids = oids()</v>
+ <v>MgrAgentConfName = atom()</v>
+ <v>SnmpReply = snmpreply()</v>
+ </type>
+ <desc><marker id="get_next_values-3"/>
+ <p>Issues a synchronous SNMP <c>get next</c> request.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_values(Agent, Oids, MgrAgentConfName) -&gt; SnmpReply</name>
+ <fsummary>Issues a synchronous SNMP get request.</fsummary>
+ <type>
+ <v>Agent = agent_name()</v>
+ <v>Oids = oids()</v>
+ <v>MgrAgentConfName = atom()</v>
+ <v>SnmpReply = snmpreply()</v>
+ </type>
+ <desc><marker id="get_values-3"/>
+ <p>Issues a synchronous SNMP <c>get</c> request.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>load_mibs(Mibs) -&gt; ok | {error, Reason}</name>
+ <fsummary>Loads the MIBs into agent snmp_master_agent.</fsummary>
+ <type>
+ <v>Mibs = [MibName]</v>
+ <v>MibName = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="load_mibs-1"/>
+ <p>Loads the MIBs into agent <c>snmp_master_agent</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>register_agents(MgrAgentConfName, ManagedAgents) -&gt; ok | {error, Reason}</name>
+ <fsummary>Explicitly instructs the manager to handle this
+ agent.</fsummary>
+ <type>
+ <v>MgrAgentConfName = atom()</v>
+ <v>ManagedAgents = [agent()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="register_agents-2"/>
+ <p>Explicitly instructs the manager to handle this agent. Corresponds
+ to making an entry in <c>agents.conf</c>.</p>
+
+ <p>This function tries to register the specified managed agents, without
+ checking if any of them exist. To change a registered managed agent,
+ the agent must first be unregistered.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>register_users(MgrAgentConfName, Users) -&gt; ok | {error, Reason}</name>
+ <fsummary>Registers the manager entity (=user) responsible for specific
+ agent(s).</fsummary>
+ <type>
+ <v>MgrAgentConfName = atom()</v>
+ <v>Users = [user()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="register_users-2"/>
+ <p>Registers the manager entity (=user) responsible for specific
+ agent(s). Corresponds to making an entry in <c>users.conf</c>.</p>
+
+ <p>This function tries to register the specified users, without checking
+ if any of them exist. To change a registered user, the user must
+ first be unregistered.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>register_usm_users(MgrAgentConfName, UsmUsers) -&gt; ok | {error, Reason}</name>
+ <fsummary>Explicitly instructs the manager to handle this USM user.</fsummary>
+ <type>
+ <v>MgrAgentConfName = atom()</v>
+ <v>UsmUsers = [usm_user()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="register_usm_users-2"/>
+ <p>Explicitly instructs the manager to handle this USM user.
+ Corresponds to making an entry in <c>usm.conf</c>.</p>
+
+ <p>This function tries to register the specified users, without checking
+ if any of them exist. To change a registered user, the user must
+ first be unregistered.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>set_info(Config) -&gt; [{Agent, OldVarsAndVals, NewVarsAndVals}]</name>
+ <fsummary>Returns a list of all successful set requests performed in the
+ test case in reverse order.</fsummary>
+ <type>
+ <v>Config = [{Key, Value}]</v>
+ <v>Agent = agent_name()</v>
+ <v>OldVarsAndVals = varsandvals()</v>
+ <v>NewVarsAndVals = varsandvals()</v>
+ </type>
+ <desc><marker id="set_info-1"/>
+ <p>Returns a list of all successful <c>set</c> requests performed in
+ the test case in reverse order. The list contains the involved user
+ and agent, the value before <c>set</c>, and the new value. This is
+ intended to simplify the cleanup in function <c>end_per_testcase</c>,
+ that is, the undoing of the <c>set</c> requests and their possible
+ side-effects.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>set_values(Agent, VarsAndVals, MgrAgentConfName, Config) -&gt; SnmpReply</name>
+ <fsummary>Issues a synchronous SNMP set request.</fsummary>
+ <type>
+ <v>Agent = agent_name()</v>
+ <v>Oids = oids()</v>
+ <v>MgrAgentConfName = atom()</v>
+ <v>Config = [{Key, Value}]</v>
+ <v>SnmpReply = snmpreply()</v>
+ </type>
+ <desc><marker id="set_values-4"/>
+ <p>Issues a synchronous SNMP <c>set</c> request.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>start(Config, MgrAgentConfName) -&gt; ok</name>
+ <fsummary>Equivalent to start(Config, MgrAgentConfName,
+ undefined).</fsummary>
+ <desc><marker id="start-2"/>
+ <p>Equivalent to
+ <seealso marker="#start-3"><c>ct_snmp:start(Config, MgrAgentConfName,
+ undefined)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>start(Config, MgrAgentConfName, SnmpAppConfName) -&gt; ok</name>
+ <fsummary>Starts an SNMP manager and/or agent.</fsummary>
+ <type>
+ <v>Config = [{Key, Value}]</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ <v>MgrAgentConfName = atom()</v>
+ <v>SnmpConfName = atom()</v>
+ </type>
+ <desc><marker id="start-3"/>
+ <p>Starts an SNMP manager and/or agent. In the manager case,
+ registrations of users and agents, as specified by the configuration
+ <c>MgrAgentConfName</c>, are performed. When using SNMPv3, called
+ USM users are also registered. Users, <c>usm_users</c>, and
+ managed agents can also be registered later using
+ <seealso marker="#register_users-2"><c>ct_snmp:register_users/2</c></seealso>,
+ <seealso marker="#register_agents-2"><c>ct_snmp:register_agents/2</c></seealso>,
+ and
+ <seealso marker="#register_usm_users-2"><c>ct_snmp:register_usm_users/2</c></seealso>.</p>
+
+ <p>The agent started is called <c>snmp_master_agent</c>. Use
+ <seealso marker="#load_mibs-1"><c>ct_snmp:load_mibs/1</c></seealso>
+ to load MIBs into the agent.</p>
+
+ <p>With <c>SnmpAppConfName</c> SNMP applications can be configured
+ with parameters <c>config</c>, <c>mibs</c>, <c>net_if</c>, and so on.
+ The values are merged with (and possibly override) default values
+ set by <c>ct_snmp</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>stop(Config) -&gt; ok</name>
+ <fsummary>Stops the SNMP manager and/or agent, and removes all files
+ created.</fsummary>
+ <type>
+ <v>Config = [{Key, Value}]</v>
+ <v>Key = atom()</v>
+ <v>Value = term()</v>
+ </type>
+ <desc><marker id="stop-1"/>
+ <p>Stops the SNMP manager and/or agent, and removes all files
+ created.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>unload_mibs(Mibs) -&gt; ok | {error, Reason}</name>
+ <fsummary>Unloads the MIBs from agent snmp_master_agent.</fsummary>
+ <type>
+ <v>Mibs = [MibName]</v>
+ <v>MibName = string()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="unload_mibs-1"/>
+ <p>Unloads the MIBs from agent <c>snmp_master_agent</c>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>unregister_agents(MgrAgentConfName) -&gt; ok</name>
+ <fsummary>Unregisters all managed agents.</fsummary>
+ <type>
+ <v>MgrAgentConfName = atom()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="unregister_agents-1"/>
+ <p>Unregisters all managed agents.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>unregister_agents(MgrAgentConfName, ManagedAgents) -&gt; ok</name>
+ <fsummary>Unregisters the specified managed agents.</fsummary>
+ <type>
+ <v>MgrAgentConfName = atom()</v>
+ <v>ManagedAgents = [agent_name()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="unregister_agents-2"/>
+ <p>Unregisters the specified managed agents.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>unregister_users(MgrAgentConfName) -&gt; ok</name>
+ <fsummary>Unregisters all users.</fsummary>
+ <type>
+ <v>MgrAgentConfName = atom()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="unregister_users-1"/>
+ <p>Unregisters all users.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>unregister_users(MgrAgentConfName, Users) -&gt; ok</name>
+ <fsummary>Unregisters the specified users.</fsummary>
+ <type>
+ <v>MgrAgentConfName = atom()</v>
+ <v>Users = [user_name()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="unregister_users-2"/>
+ <p>Unregisters the specified users.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>unregister_usm_users(MgrAgentConfName) -&gt; ok</name>
+ <fsummary>Unregisters all USM users.</fsummary>
+ <type>
+ <v>MgrAgentConfName = atom()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="unregister_usm_users-1"/>
+ <p>Unregisters all USM users.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>unregister_usm_users(MgrAgentConfName, UsmUsers) -&gt; ok</name>
+ <fsummary>Unregisters the specified USM users.</fsummary>
+ <type>
+ <v>MgrAgentConfName = atom()</v>
+ <v>UsmUsers = [usm_user_name()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="unregister_usm_users-2"/>
+ <p>Unregisters the specified USM users.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ct_ssh.xml b/lib/common_test/doc/src/ct_ssh.xml
new file mode 100644
index 0000000000..897fd509d3
--- /dev/null
+++ b/lib/common_test/doc/src/ct_ssh.xml
@@ -0,0 +1,1150 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct_ssh</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct_ssh.xml</file>
+ </header>
+ <module>ct_ssh</module>
+ <modulesummary>SSH/SFTP client module.</modulesummary>
+
+<description>
+
+ <p>SSH/SFTP client module.</p>
+
+ <p>This module uses application <c>SSH</c>, which provides detailed
+ information about, for example, functions, types, and options.</p>
+
+ <p>Argument <c>Server</c> in the SFTP functions is only to be used for
+ SFTP sessions that have been started on existing SSH connections
+ (that is, when the original connection type is <c>ssh</c>). Whenever
+ the connection type is <c>sftp</c>, use the SSH connection reference
+ only.</p>
+
+ <p>The following options are valid for specifying an SSH/SFTP
+ connection (that is, can be used as configuration elements):</p>
+
+ <pre>
+ [{ConnType, Addr},
+ {port, Port},
+ {user, UserName}
+ {password, Pwd}
+ {user_dir, String}
+ {public_key_alg, PubKeyAlg}
+ {connect_timeout, Timeout}
+ {key_cb, KeyCallbackMod}]</pre>
+
+ <p><c>ConnType = ssh | sftp</c>.</p>
+
+ <p>For other types, see
+ <seealso marker="ssh:ssh"><c>ssh:ssh(3)</c></seealso>.</p>
+
+ <p>All time-out parameters in <c>ct_ssh</c> functions are values in
+ milliseconds.</p>
+
+ </description>
+
+ <section>
+ <title>Data Types</title>
+ <marker id="types"/>
+ <taglist>
+ <tag><c>connection() = handle() | target_name()</c></tag>
+ <item><marker id="type-connection"/>
+ <p>For <c>target_name</c>, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p></item>
+
+ <tag><c>handle() = handle()</c></tag>
+ <item><marker id="type-handle"/>
+ <p>Handle for a specific SSH/SFTP connection, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p></item>
+
+ <tag><c>ssh_sftp_return() = term()</c></tag>
+ <item><marker id="type-ssh_sftp_return"/>
+ <p>Return value from an
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp</c></seealso>
+ function.</p></item>
+ </taglist>
+ </section>
+
+ <funcs>
+ <func>
+ <name>apread(SSH, Handle, Position, Length) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="apread-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>apread(SSH, Server, Handle, Position, Length) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="apread-5"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>apwrite(SSH, Handle, Position, Data) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="apwrite-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>apwrite(SSH, Server, Handle, Position, Data) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="apwrite-5"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>aread(SSH, Handle, Len) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="aread-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>aread(SSH, Server, Handle, Len) -&gt; Result</name>
+ <fsummary>For inforamtion and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="aread-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>awrite(SSH, Handle, Data) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="awrite-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>awrite(SSH, Server, Handle, Data) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="awrite-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>close(SSH, Handle) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="close-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>close(SSH, Server, Handle) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="close-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>connect(KeyOrName) -&gt; {ok, Handle} | {error, Reason}</name>
+ <fsummary>Equivalent to connect(KeyOrName, host, []).</fsummary>
+ <desc><marker id="connect-1"/>
+ <p>Equivalent to
+ <seealso marker="#connect-3"><c>ct_ssh:connect(KeyOrName, host,
+ [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>connect(KeyOrName, ConnType) -&gt; {ok, Handle} | {error, Reason}</name>
+ <fsummary>Equivalent to connect(KeyOrName, ConnType, []).</fsummary>
+ <desc><marker id="connect-2"/>
+ <p>Equivalent to
+ <seealso marker="#connect-3"><c>ct_ssh:connect(KeyOrName, ConnType,
+ [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>connect(KeyOrName, ConnType, ExtraOpts) -&gt; {ok, Handle} | {error, Reason}</name>
+ <fsummary>Opens an SSH or SFTP connection using the information
+ associated with KeyOrName.</fsummary>
+ <type>
+ <v>KeyOrName = Key | Name</v>
+ <v>Key = atom()</v>
+ <v>Name = target_name()</v>
+ <v>ConnType = ssh | sftp | host</v>
+ <v>ExtraOpts = ssh_connect_options()</v>
+ <v>Handle = handle()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="connect-3"/>
+ <p>Opens an SSH or SFTP connection using the information associated
+ with <c>KeyOrName</c>.</p>
+
+ <p>If <c>Name</c> (an alias name for <c>Key</c>) is used to identify
+ the connection, this name can be used as connection reference for
+ subsequent calls. Only one open connection at a time associated
+ with <c>Name</c> is possible. If <c>Key</c> is used, the returned
+ handle must be used for subsequent calls (multiple connections can
+ be opened using the configuration data specified by <c>Key</c>).</p>
+
+ <p>For information on how to create a new <c>Name</c>, see
+ <seealso marker="ct#require-2"><c>ct:require/2</c></seealso>.</p>
+
+ <p>For <c>target_name</c>, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p>
+
+ <p><c>ConnType</c> always overrides the type specified in the
+ address tuple in the configuration data (and in <c>ExtraOpts</c>).
+ So it is possible to, for example, open an SFTP connection
+ directly using data originally specifying an SSH connection. Value
+ <c>host</c> means that the connection type specified by the host
+ option (either in the configuration data or in <c>ExtraOpts</c>)
+ is used.</p>
+
+ <p><c>ExtraOpts</c> (optional) are extra SSH options to be added to
+ the configuration data for <c>KeyOrName</c>. The extra options
+ override any existing options with the same key in the
+ configuration data. For details on valid SSH options, see
+ application <seealso marker="ssh"><c>SSH</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>del_dir(SSH, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="del_dir-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>del_dir(SSH, Server, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="del_dir-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>delete(SSH, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="delete-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>delete(SSH, Server, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="delete-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>disconnect(SSH) -&gt; ok | {error, Reason}</name>
+ <fsummary>Closes an SSH/SFTP connection.</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="disconnect-1"/>
+ <p>Closes an SSH/SFTP connection.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>exec(SSH, Command) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Equivalent to exec(SSH, Command, DefaultTimeout).</fsummary>
+ <desc><marker id="exec-2"/>
+ <p>Equivalent to
+ <seealso marker="#exec-3"><c>ct_ssh:exec(SSH, Command,
+ DefaultTimeout)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>exec(SSH, Command, Timeout) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Requests server to perform Command.</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Command = string()</v>
+ <v>Timeout = integer()</v>
+ <v>Data = list()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="exec-3"/>
+ <p>Requests server to perform <c>Command</c>. A session channel is
+ opened automatically for the request. <c>Data</c> is received from
+ the server as a result of the command.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>exec(SSH, ChannelId, Command, Timeout) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Requests server to perform Command.</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>ChannelId = integer()</v>
+ <v>Command = string()</v>
+ <v>Timeout = integer()</v>
+ <v>Data = list()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="exec-4"/>
+ <p>Requests server to perform <c>Command</c>. A previously opened
+ session channel is used for the request. <c>Data</c> is received
+ from the server as a result of the command.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_file_info(SSH, Handle) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="get_file_info-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_file_info(SSH, Server, Handle) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="get_file_info-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>list_dir(SSH, Path) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="list_dir-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>list_dir(SSH, Server, Path) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="list_dir-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>make_dir(SSH, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="make_dir-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>make_dir(SSH, Server, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="make_dir-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>make_symlink(SSH, Name, Target) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="make_symlink-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>make_symlink(SSH, Server, Name, Target) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="make_symlink-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>open(SSH, File, Mode) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="open-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>open(SSH, Server, File, Mode) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="open-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>opendir(SSH, Path) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="opendir-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>opendir(SSH, Server, Path) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="opendir-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>position(SSH, Handle, Location) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="position-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>position(SSH, Server, Handle, Location) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="position-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pread(SSH, Handle, Position, Length) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="pread-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pread(SSH, Server, Handle, Position, Length) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="pread-5"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pwrite(SSH, Handle, Position, Data) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="pwrite-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>pwrite(SSH, Server, Handle, Position, Data) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="pwrite-5"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read(SSH, Handle, Len) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="read-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read(SSH, Server, Handle, Len) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="read-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read_file(SSH, File) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="read_file-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read_file(SSH, Server, File) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="read_file-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read_file_info(SSH, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="read_file_info-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read_file_info(SSH, Server, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="read_file_info-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read_link(SSH, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="read_link-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read_link(SSH, Server, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="read_link-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read_link_info(SSH, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="read_link_info-2"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>read_link_info(SSH, Server, Name) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="read_link_info-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>receive_response(SSH, ChannelId) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Equivalent to receive_response(SSH, ChannelId,
+ close).</fsummary>
+ <desc><marker id="receive_response-2"/>
+ <p>Equivalent to
+ <seealso marker="#receive_response-3"><c>ct_ssh:receive_response(SSH,
+ChannelId, close)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>receive_response(SSH, ChannelId, End) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Equivalent to receive_response(SSH, ChannelId, End,
+ DefaultTimeout).</fsummary>
+ <desc><marker id="receive_response-3"/>
+ <p>Equivalent to
+ <seealso marker="#receive_response-4"><c>ct_ssh:receive_response(SSH,
+ChannelId, End, DefaultTimeout)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>receive_response(SSH, ChannelId, End, Timeout) -&gt; {ok, Data} | {timeout, Data} | {error, Reason}</name>
+ <fsummary>Receives expected data from server on the specified session
+ channel.</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>ChannelId = integer()</v>
+ <v>End = Fun | close | timeout</v>
+ <v>Timeout = integer()</v>
+ <v>Data = list()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="receive_response-4"/>
+ <p>Receives expected data from server on the specified session
+ channel.</p>
+
+ <p>If <c>End == close</c>, data is returned to the caller when the
+ channel is closed by the server. If a time-out occurs before this
+ happens, the function returns <c>{timeout,Data}</c> (where
+ <c>Data</c> is the data received so far).</p>
+ <p>If <c>End == timeout</c>, a time-out is expected and
+ <c>{ok,Data}</c> is returned both in the case of a time-out and
+ when the channel is closed.</p>
+
+ <p>If <c>End</c> is a fun, this fun is called with one argument, the
+ data value in a received <c>ssh_cm</c> message (see
+ <seealso marker="ssh:ssh_connection"><c>ssh:ssh_connection(3)</c></seealso>.
+ The fun is to return either <c>true</c> to end the receiving
+ operation (and have the so far collected data returned) or
+ <c>false</c> to wait for more data from the server. Even if a fun
+ is supplied, the function returns immediately if the server closes
+ the channel).</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>rename(SSH, OldName, NewName) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="rename-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>rename(SSH, Server, OldName, NewName) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="rename-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(SSH, ChannelId, Data) -&gt; ok | {error, Reason}</name>
+ <fsummary>Equivalent to send(SSH, ChannelId, 0, Data,
+ DefaultTimeout).</fsummary>
+ <desc><marker id="send-3"/>
+ <p>Equivalent to <seealso marker="#send-5"><c>ct_ssh:send(SSH,
+ ChannelId, 0, Data, DefaultTimeout)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(SSH, ChannelId, Data, Timeout) -&gt; ok | {error, Reason}</name>
+ <fsummary>Equivalent to send(SSH, ChannelId, 0, Data, Timeout).</fsummary>
+ <desc><marker id="send-4"/>
+ <p>Equivalent to <seealso marker="#send-5"><c>ct_ssh:send(SSH,
+ ChannelId, 0, Data, Timeout)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(SSH, ChannelId, Type, Data, Timeout) -&gt; ok | {error, Reason}</name>
+ <fsummary>Sends data to server on specified session channel.</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>ChannelId = integer()</v>
+ <v>Type = integer()</v>
+ <v>Data = list()</v>
+ <v>Timeout = integer()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="send-5"/>
+ <p>Sends data to server on specified session channel.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_and_receive(SSH, ChannelId, Data) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Equivalent to send_and_receive(SSH, ChannelId, Data,
+ close).</fsummary>
+ <desc><marker id="send_and_receive-3"/>
+ <p>Equivalent to
+ <seealso marker="#send_and_receive-4"><c>ct_ssh:send_and_receive(SSH,
+ ChannelId, Data, close)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_and_receive(SSH, ChannelId, Data, End) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Equivalent to send_and_receive(SSH, ChannelId, 0, Data, End,
+ DefaultTimeout).</fsummary>
+ <desc><marker id="send_and_receive-4"/>
+ <p>Equivalent to
+ <seealso marker="#send_and_receive-6"><c>ct_ssh;send_and_receive(SSH,
+ChannelId, 0, Data, End, DefaultTimeout)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_and_receive(SSH, ChannelId, Data, End, Timeout) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Equivalent to send_and_receive(SSH, ChannelId, 0, Data, End,
+ Timeout).</fsummary>
+ <desc><marker id="send_and_receive-5"/>
+ <p>Equivalent to
+ <seealso marker="#send_and_receive-6"><c>ct_ssh:send_and_receive(SSH,
+ChannelId, 0, Data, End, Timeout)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send_and_receive(SSH, ChannelId, Type, Data, End, Timeout) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Sends data to server on specified session channel and waits
+ to receive the server response.</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>ChannelId = integer()</v>
+ <v>Type = integer()</v>
+ <v>Data = list()</v>
+ <v>End = Fun | close | timeout</v>
+ <v>Timeout = integer()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="send_and_receive-6"/>
+ <p>Sends data to server on specified session channel and waits to
+ receive the server response.</p>
+
+ <p>For details on argument <c>End</c>, see
+ <seealso marker="receive_response-4"><c>ct_ssh:receive_response/4</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>session_close(SSH, ChannelId) -&gt; ok | {error, Reason}</name>
+ <fsummary>Closes an SSH session channel.</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>ChannelId = integer()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="session_close-2"/>
+ <p>Closes an SSH session channel.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>session_open(SSH) -&gt; {ok, ChannelId} | {error, Reason}</name>
+ <fsummary>Equivalent to session_open(SSH, DefaultTimeout).</fsummary>
+ <desc><marker id="session_open-1"/>
+ <p>Equivalent to
+ <seealso marker="#session_open-2"><c>ct_ssh:session_open(SSH,
+ DefaultTimeout)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>session_open(SSH, Timeout) -&gt; {ok, ChannelId} | {error, Reason}</name>
+ <fsummary>Opens a channel for an SSH session.</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Timeout = integer()</v>
+ <v>ChannelId = integer()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="session_open-2"/>
+ <p>Opens a channel for an SSH session.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>sftp_connect(SSH) -&gt; {ok, Server} | {error, Reason}</name>
+ <fsummary>Starts an SFTP session on an already existing SSH
+ connection.</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Server = pid()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="sftp_connect-1"/>
+ <p>Starts an SFTP session on an already existing SSH connection.
+ <c>Server</c> identifies the new session and must be specified
+ whenever SFTP requests are to be sent.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>subsystem(SSH, ChannelId, Subsystem) -&gt; Status | {error, Reason}</name>
+ <fsummary>Equivalent to subsystem(SSH, ChannelId, Subsystem,
+ DefaultTimeout).</fsummary>
+ <desc><marker id="subsystem-3"/>
+ <p>Equivalent to
+ <seealso marker="#subsystem-4"><c>ct_ssh:subsystem(SSH, ChannelId,
+ Subsystem, DefaultTimeout)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>subsystem(SSH, ChannelId, Subsystem, Timeout) -&gt; Status | {error, Reason}</name>
+ <fsummary>Sends a request to execute a predefined subsystem.</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>ChannelId = integer()</v>
+ <v>Subsystem = string()</v>
+ <v>Timeout = integer()</v>
+ <v>Status = success | failure</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="subsystem-4"/>
+ <p>Sends a request to execute a predefined subsystem.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>write(SSH, Handle, Data) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="write-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>write(SSH, Server, Handle, Data) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="write-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>write_file(SSH, File, Iolist) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="write_file-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>write_file(SSH, Server, File, Iolist) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="write_file-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>write_file_info(SSH, Name, Info) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="write_file_info-3"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>write_file_info(SSH, Server, Name, Info) -&gt; Result</name>
+ <fsummary>For information and other types, see ssh_sftp(3).</fsummary>
+ <type>
+ <v>SSH = connection()</v>
+ <v>Result = ssh_sftp_return() | {error, Reason}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="write_file_info-4"/>
+ <p>For information and other types, see
+ <seealso marker="ssh:ssh_sftp"><c>ssh:ssh_sftp(3)</c></seealso>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ct_telnet.xml b/lib/common_test/doc/src/ct_telnet.xml
new file mode 100644
index 0000000000..6f7fc13055
--- /dev/null
+++ b/lib/common_test/doc/src/ct_telnet.xml
@@ -0,0 +1,601 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>ct_telnet</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>ct_telnet.xml</file>
+ </header>
+ <module>ct_telnet</module>
+ <modulesummary>Common Test specific layer on top of Telnet client ct_telnet_client.erl</modulesummary>
+
+ <description>
+
+ <p><c>Common Test</c> specific layer on top of Telnet client
+ <c>ct_telnet_client.erl</c>.</p>
+
+ <p>Use this module to set up Telnet connections, send commands, and
+ perform string matching on the result. For information about how to use
+ <c>ct_telnet</c> and configure connections, specifically for UNIX hosts,
+ see the
+ <seealso marker="unix_telnet"><c>unix_telnet</c></seealso> manual page.
+ </p>
+
+ <p>Default values defined in <c>ct_telnet</c>:</p>
+ <marker id="Default_values"/>
+
+ <list type="bulleted">
+ <item><p>Connection timeout (time to wait for connection) = 10
+ seconds</p></item>
+ <item><p>Command timeout (time to wait for a command to return) =
+ 10 seconds</p></item>
+ <item><p>Max number of reconnection attempts = 3</p></item>
+ <item><p>Reconnection interval (time to wait in between
+ reconnection attempts) = 5 seconds</p></item>
+ <item><p>Keep alive (sends NOP to the server every 8 sec if
+ connection is idle) = <c>true</c></p></item>
+ <item><p>Polling limit (max number of times to poll to get a
+ remaining string terminated) = 0</p></item>
+ <item><p>Polling interval (sleep time between polls) = 1 second</p>
+ </item>
+ </list>
+
+ <p>These parameters can be modified by the user with the following
+ configuration term:</p>
+
+ <pre>
+ {telnet_settings, [{connect_timeout,Millisec},
+ {command_timeout,Millisec},
+ {reconnection_attempts,N},
+ {reconnection_interval,Millisec},
+ {keep_alive,Bool},
+ {poll_limit,N},
+ {poll_interval,Millisec}]}.</pre>
+
+ <p><c>Millisec = integer(), N = integer()</c></p>
+
+ <p>Enter the <c>telnet_settings</c> term in a configuration file included
+ in the test and <c>ct_telnet</c> retrieves the information
+ automatically.</p>
+
+ <p><c>keep_alive</c> can be specified per connection, if necessary. For
+ details, see
+ <seealso marker="unix_telnet"><c>unix_telnet</c></seealso>.</p>
+
+ </description>
+
+ <section>
+ <title>Logging</title>
+ <marker id="Logging"/>
+
+ <p>The default logging behavior of <c>ct_telnet</c> is to print information
+ about performed operations, commands, and their corresponding results to
+ the test case HTML log. The following is not printed to the HTML
+ log: text strings sent from the Telnet server that are not explicitly
+ received by a <c>ct_telnet</c> function, such as <c>expect/3</c>.
+ However, <c>ct_telnet</c> can be configured to use a special purpose
+ event handler, implemented in <c>ct_conn_log_h</c>, for logging
+ <em>all</em> Telnet traffic. To use this handler, install a <c>Common
+ Test</c> hook named <c>cth_conn_log</c>. Example (using the test suite
+ information function):</p>
+
+ <pre>
+ suite() -&gt;
+ [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].</pre>
+
+ <p><c>conn_mod()</c> is the name of the <c>Common Test</c> module
+ implementing the connection protocol, that is, <c>ct_telnet</c>.</p>
+
+ <p>The <c>cth_conn_log</c> hook performs unformatted logging of Telnet
+ data to a separate text file. All Telnet communication is captured and
+ printed, including any data sent from the server. The link to
+ this text file is located at the top of the test case HTML log.</p>
+
+ <p>By default, data for all Telnet connections is logged in one common
+ file (named <c>default</c>), which can get messy, for example, if
+ multiple Telnet sessions are running in parallel. Therefore a separate
+ log file can be created for each connection. To configure this, use hook
+ option <c>hosts</c> and list the names of the servers/connections
+ to be used in the suite. The connections must be named for this to
+ work (see
+ <seealso marker="#open-1"><c>ct_telnet:open/1,2,3,4</c></seealso>.</p>
+
+ <p>Hook option <c>log_type</c> can be used to change the
+ <c>cth_conn_log</c> behavior. The default value of this option is
+ <c>raw</c>, which results in the behavior described above. If the value
+ is set to <c>html</c>, all Telnet communication is printed to the test
+ case HTML log instead.</p>
+
+ <p>All <c>cth_conn_log</c> hook options described can also be
+ specified in a configuration file with configuration variable
+ <c>ct_conn_log</c>.</p>
+
+ <p><em>Example:</em></p>
+
+ <pre>
+ {ct_conn_log, [{ct_telnet,[{log_type,raw},
+ {hosts,[key_or_name()]}]}]}</pre>
+
+ <note>
+ <p>Hook options specified in a configuration file overwrite any
+ hard-coded hook options in the test suite.</p>
+ </note>
+
+ <marker id="Logging_example"/>
+ <p><em>Logging Example:</em></p>
+
+ <p>The following <c>ct_hooks</c> statement causes printing of Telnet
+ traffic to separate logs for the connections <c>server1</c> and
+ <c>server2</c>. Traffic for any other connections is logged in the
+ default Telnet log.</p>
+
+ <pre>
+ suite() -&gt;
+ [{ct_hooks,
+ [{cth_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}]}].</pre>
+
+ <p>As previously explained, this specification can also be provided by an
+ entry like the following in a configuration file:</p>
+
+ <pre>
+ {ct_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}.</pre>
+
+ <p>In this case the <c>ct_hooks</c> statement in the test suite can look
+ as follows:</p>
+
+ <pre>
+ suite() -&gt;
+ [{ct_hooks, [{cth_conn_log, []}]}].</pre>
+ </section>
+
+ <section>
+ <title>Data Types</title>
+ <marker id="types"/>
+ <taglist>
+ <tag><c>connection() = handle() | {target_name(), connection_type()} | target_name()</c></tag>
+ <item><marker id="type-connection"/>
+ <p>For <c>target_name()</c>, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p></item>
+
+ <tag><c>connection_type() = telnet | ts1 | ts2</c></tag>
+ <item><marker id="type-connection_type"/> </item>
+
+ <tag><c>handle() = handle()</c></tag>
+ <item><marker id="type-handle"/>
+ <p>Handle for a specific Telnet connection, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p></item>
+
+ <tag><c>prompt_regexp() = string()</c></tag>
+ <item><marker id="type-prompt_regexp"/>
+ <p>Regular expression matching all possible prompts for a specific
+ target type. <c>regexp</c> must not have any groups, that is, when
+ matching, <c>re:run/3</c> (in <c>STDLIB</c>) must return a list with
+ one single element.</p></item>
+ </taglist>
+ </section>
+
+ <funcs>
+ <func>
+ <name>close(Connection) -&gt; ok | {error, Reason}</name>
+ <fsummary>Closes the Telnet connection and stops the process managing
+ it.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="close-1"/>
+ <p>Closes the Telnet connection and stops the process managing it.</p>
+
+ <p>A connection can be associated with a target name and/or a handle.
+ If <c>Connection</c> has no associated target name, it can only
+ be closed with the handle value (see
+ <seealso marker="#open-4"><c>ct_telnet:open/4</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>cmd(Connection, Cmd) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Equivalent to cmd(Connection, Cmd, []).</fsummary>
+ <desc><marker id="cmd-2"/>
+ <p>Equivalent to
+ <seealso marker="#cmd-3"><c>ct_telnet:cmd(Connection, Cmd,
+ [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>cmd(Connection, Cmd, Opts) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Sends a command through Telnet and waits for prompt.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>Cmd = string()</v>
+ <v>Opts = [Opt]</v>
+ <v>Opt = {timeout, timeout()} | {newline, boolean()}</v>
+ <v>Data = [string()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="cmd-3"/>
+ <p>Sends a command through Telnet and waits for prompt.</p>
+
+ <p>By default, this function adds a new line to the end of the
+ specified command. If this is not desired, use option
+ <c>{newline,false}</c>. This is necessary, for example, when
+ sending Telnet command sequences prefixed with character
+ Interprete As Command (IAC).</p>
+
+ <p>Option <c>timeout</c> specifies how long the client must wait
+ for prompt. If the time expires, the function returns
+ <c>{error,timeout}</c>. For information about the default value
+ for the command timeout, see the
+ <seealso marker="#Default_values">list of default values</seealso>
+ in the beginning of this module.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>cmdf(Connection, CmdFormat, Args) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Equivalent to cmdf(Connection, CmdFormat, Args, []).</fsummary>
+ <desc><marker id="cmdf-3"/>
+ <p>Equivalent to
+ <seealso marker="#cmdf-4"><c>ct_telnet:cmdf(Connection, CmdFormat,
+ Args, [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>cmdf(Connection, CmdFormat, Args, Opts) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Sends a Telnet command and waits for prompt (uses a format
+ string and a list of arguments to build the command).</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>CmdFormat = string()</v>
+ <v>Args = list()</v>
+ <v>Opts = [Opt]</v>
+ <v>Opt = {timeout, timeout()} | {newline, boolean()}</v>
+ <v>Data = [string()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="cmdf-4"/>
+ <p>Sends a Telnet command and waits for prompt (uses a format string
+ and a list of arguments to build the command).</p>
+
+ <p>For details, see
+ <seealso marker="#cmd-3"><c>ct_telnet:cmd/3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>expect(Connection, Patterns) -&gt; term()</name>
+ <fsummary>Equivalent to expect(Connections, Patterns, []).</fsummary>
+ <desc><marker id="expect-2"/>
+ <p>Equivalent to
+ <seealso marker="#expect-3"><c>ct_telnet:expect(Connections,
+ Patterns, [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>expect(Connection, Patterns, Opts) -&gt; {ok, Match} | {ok, MatchList, HaltReason} | {error, Reason}</name>
+ <fsummary>Gets data from Telnet and waits for the expected
+ pattern.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>Patterns = Pattern | [Pattern]</v>
+ <v>Pattern = string() | {Tag, string()} | prompt | {prompt, Prompt}</v>
+ <v>Prompt = string()</v>
+ <v>Tag = term()</v>
+ <v>Opts = [Opt]</v>
+ <v>Opt = {idle_timeout, IdleTimeout} | {total_timeout, TotalTimeout} | repeat | {repeat, N} | sequence | {halt, HaltPatterns} | ignore_prompt | no_prompt_check | wait_for_prompt | {wait_for_prompt, Prompt}</v>
+ <v>IdleTimeout = infinity | integer()</v>
+ <v>TotalTimeout = infinity | integer()</v>
+ <v>N = integer()</v>
+ <v>HaltPatterns = Patterns</v>
+ <v>MatchList = [Match]</v>
+ <v>Match = RxMatch | {Tag, RxMatch} | {prompt, Prompt}</v>
+ <v>RxMatch = [string()]</v>
+ <v>HaltReason = done | Match</v>
+ <v>Reason = timeout | {prompt, Prompt}</v>
+ </type>
+ <desc><marker id="expect-3"/>
+ <p>Gets data from Telnet and waits for the expected pattern.</p>
+
+ <p><c>Pattern</c> can be a POSIX regular expression. The function
+ returns when a pattern is successfully matched (at least one, in
+ the case of multiple patterns).</p>
+
+ <p><c>RxMatch</c> is a list of matched strings. It looks as
+ follows <c>[FullMatch, SubMatch1, SubMatch2, ...]</c>, where
+ <c>FullMatch</c> is the string matched by the whole regular
+ expression, and <c>SubMatchN</c> is the string that matched
+ subexpression number <c>N</c>. Subexpressions are denoted with
+ <c>(' ')</c> in the regular expression.</p>
+
+ <p>If a <c>Tag</c> is speciifed, the returned <c>Match</c> also
+ includes the matched <c>Tag</c>. Otherwise, only <c>RxMatch</c>
+ is returned.</p>
+
+ <p><em>Options:</em></p>
+
+ <taglist>
+ <tag><c>idle_timeout</c></tag>
+ <item><p>Indicates that the function must return if the Telnet
+ client is idle (that is, if no data is received) for more than
+ <c>IdleTimeout</c> milliseconds. Default time-out is 10
+ seconds.</p></item>
+ <tag><c>total_timeout</c></tag>
+ <item><p>Sets a time limit for the complete <c>expect</c> operation.
+ After <c>TotalTimeout</c> milliseconds, <c>{error,timeout}</c>
+ is returned. Default is <c>infinity</c> (that is, no time
+ limit).</p></item>
+ <tag><c>ignore_prompt | no_prompt_check</c></tag>
+ <item><p>>The function returns when a prompt is received, even if
+ no pattern has yet been matched, and
+ <c>{error,{prompt,Prompt}}</c> is returned. However, this
+ behavior can be modified with option <c>ignore_prompt</c> or
+ option <c>no_prompt_check</c>, which tells <c>expect</c> to
+ return only when a match is found or after a time-out.</p></item>
+ <tag><c>ignore_prompt</c></tag>
+ <item><p><c>ct_telnet</c> ignores any prompt found. This option is
+ useful if data sent by the server can include a pattern
+ matching prompt <c>regexp</c> (as returned by
+ <c>TargedMod:get_prompt_regexp/0</c>), but is not to not cause
+ the function to return.</p></item>
+ <tag><c>no_prompt_check</c></tag>
+ <item><p><c>ct_telnet</c> does not search for a prompt at all. This
+ is useful if, for example, <c>Pattern</c> itself matches the
+ prompt.</p></item>
+ <tag><c>wait_for_prompt</c></tag>
+ <item><p>Forces <c>ct_telnet</c> to wait until the prompt string
+ is received before returning (even if a pattern has already been
+ matched). This is equal to calling
+ <c>expect(Conn, Patterns++[{prompt,Prompt}], [sequence|Opts])</c>.
+ Notice that option <c>idle_timeout</c> and <c>total_timeout</c>
+ can abort the operation of waiting for prompt.</p></item>
+ <tag><c>repeat | repeat, N</c></tag>
+ <item><p>The pattern(s) must be matched multiple times. If <c>N</c>
+ is speciified, the pattern(s) are matched <c>N</c> times, and
+ the function returns <c>HaltReason = done</c>. This option can be
+ interrupted by one or more <c>HaltPatterns</c>. <c>MatchList</c>
+ is always returned, that is, a list of <c>Match</c> instead of
+ only one <c>Match</c>. Also <c>HaltReason</c> is returned.</p>
+ </item>
+ <tag><c>sequence</c></tag>
+ <item><p>All patterns must be matched in a sequence. A match is not
+ concluded until all patterns are matched. This option can be
+ interrupted by one or more <c>HaltPatterns</c>. <c>MatchList</c>
+ is always returned, that is, a list of <c>Match</c> instead of
+ only one <c>Match</c>. Also <c>HaltReason</c> is returned.</p>
+ </item>
+ </taglist>
+
+ <p><em>Example 1:</em></p>
+
+ <pre>
+ expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[sequence,{halt,[{nnn,"NNN"}]}])</pre>
+
+ <p>First this tries to match <c>"ABC"</c>, and then <c>"XYZ"</c>, but
+ if <c>"NNN"</c> appears, the function returns
+ <c>{error,{nnn,["NNN"]}}</c>. If both <c>"ABC"</c> and <c>"XYZ"</c>
+ are matched, the function returns <c>{ok,[AbcMatch,XyzMatch]}</c>.</p>
+
+ <p><em>Example 2:</em></p>
+
+ <pre>
+ expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[{repeat,2},{halt,[{nnn,"NNN"}]}])</pre>
+
+ <p>This tries to match <c>"ABC"</c> or <c>"XYZ"</c> twice. If
+ <c>"NNN"</c> appears, the function returns
+ <c>HaltReason = {nnn,["NNN"]}</c>.</p>
+
+ <p>Options <c>repeat</c> and <c>sequence</c> can be combined to
+ match a sequence multiple times.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_data(Connection) -&gt; {ok, Data} | {error, Reason}</name>
+ <fsummary>Gets all data received by the Telnet client since the last
+ command was sent.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>Data = [string()]</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="get_data-1"/>
+ <p>Gets all data received by the Telnet client since the last
+ command was sent. Only newline-terminated strings are returned.
+ If the last received string has not yet been terminated, the
+ connection can be polled automatically until the string is
+ complete.</p>
+
+ <p>The polling feature is controlled by the configuration values
+ <c>poll_limit</c> and <c>poll_interval</c> and is by default
+ disabled. This means that the function immediately returns all
+ complete strings received and saves a remaining non-terminated
+ string for a later <c>get_data</c> call.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>open(Name) -&gt; {ok, Handle} | {error, Reason}</name>
+ <fsummary>Equivalent to open(Name, telnet).</fsummary>
+ <desc><marker id="open-1"/>
+ <p>Equivalent to
+ <seealso marker="#open-2"><c>ct_telnet:open(Name,
+ telnet)</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>open(Name, ConnType) -&gt; {ok, Handle} | {error, Reason}</name>
+ <fsummary>Opens a Telnet connection to the specified target
+ host.</fsummary>
+ <type>
+ <v>Name = target_name()</v>
+ <v>ConnType = connection_type()</v>
+ <v>Handle = handle()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="open-2"/>
+ <p>Opens a Telnet connection to the specified target host.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>open(KeyOrName, ConnType, TargetMod) -&gt; {ok, Handle} | {error, Reason}</name>
+ <fsummary>Equivalent to open(KeyOrName, ConnType, TargetMod, []).</fsummary>
+ <desc><marker id="open-3"/>
+ <p>Equivalent to
+ <seealso marker="#open-4"><c>ct_telnet:ct_telnet:open(KeyOrName,
+ ConnType, TargetMod, [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>open(KeyOrName, ConnType, TargetMod, Extra) -&gt; {ok, Handle} | {error, Reason}</name>
+ <fsummary>Opens a Telnet connection to the specified target
+ host.</fsummary>
+ <type>
+ <v>KeyOrName = Key | Name</v>
+ <v>Key = atom()</v>
+ <v>Name = target_name()</v>
+ <v>ConnType = connection_type()</v>
+ <v>TargetMod = atom()</v>
+ <v>Extra = term()</v>
+ <v>Handle = handle()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="open-4"/>
+ <p>Opens a Telnet connection to the specified target host.</p>
+
+ <p>The target data must exist in a configuration file. The connection
+ can be associated with <c>Name</c> and/or the returned <c>Handle</c>.
+ To allocate a name for the target, use one of the following
+ alternatives:</p>
+
+ <list type="bulleted">
+ <item><p><seealso marker="ct#require-2"><c>ct:require/2</c></seealso>
+ in a test case</p></item>
+ <item><p>A <c>require</c> statement in the suite information
+ function (<c>suite/0</c>)</p></item>
+ <item><p>A <c>require</c> statement in a test case information
+ function</p></item>
+ </list>
+
+ <p>If you want the connection to be associated with <c>Handle</c> only
+ (if you, for example, need to open multiple connections to a host),
+ use <c>Key</c>, the configuration variable name, to specify the
+ target. Notice that a connection without an associated target name
+ can only be closed with the <c>Handle</c> value.</p>
+
+ <p><c>TargetMod</c> is a module that exports the functions
+ <c>connect(Ip, Port, KeepAlive, Extra)</c> and
+ <c>get_prompt_regexp()</c> for the specified <c>TargetType</c>
+ (for example, <c>unix_telnet</c>).</p>
+
+ <p>For <c>target_name()</c>, see module
+ <seealso marker="ct"><c>ct</c></seealso>.</p>
+
+ <p>See also
+ <seealso marker="ct#require-2"><c>ct:require/2</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(Connection, Cmd) -&gt; ok | {error, Reason}</name>
+ <fsummary>Equivalent to send(Connection, Cmd, []).</fsummary>
+ <desc><marker id="send-2"/>
+ <p>Equivalent to
+ <seealso marker="#send-3"><c>ct_telnet:send(Connection, Cmd,
+ [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>send(Connection, Cmd, Opts) -&gt; ok | {error, Reason}</name>
+ <fsummary>Sends a Telnet command and returns immediately.</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>Cmd = string()</v>
+ <v>Opts = [Opt]</v>
+ <v>Opt = {newline, boolean()}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="send-3"/>
+ <p>Sends a Telnet command and returns immediately.</p>
+
+ <p>By default, this function adds a newline to the end of the
+ specified command. If this is not desired, option
+ <c>{newline,false}</c> can be used. This is necessary, for example,
+ when sending Telnet command sequences prefixed with character
+ Interprete As Command (IAC).</p>
+
+ <p>The resulting output from the command can be read with
+ <seealso marker="#get_data-1"><c>ct_telnet:get_data/2</c></seealso> or
+ <seealso marker="#expect-2"><c>ct_telnet:expect/2,3</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>sendf(Connection, CmdFormat, Args) -&gt; ok | {error, Reason}</name>
+ <fsummary>Equivalent to sendf(Connection, CmdFormat, Args, []).</fsummary>
+ <desc><marker id="sendf-3"/>
+ <p>Equivalent to
+ <seealso marker="#sendf-4"><c>ct_telnet:sendf(Connection, CmdFormat,
+ Args, [])</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>sendf(Connection, CmdFormat, Args, Opts) -&gt; ok | {error, Reason}</name>
+ <fsummary>Sends a Telnet command and returns immediately (uses a format
+ string and a list of arguments to build the command).</fsummary>
+ <type>
+ <v>Connection = connection()</v>
+ <v>CmdFormat = string()</v>
+ <v>Args = list()</v>
+ <v>Opts = [Opt]</v>
+ <v>Opt = {newline, boolean()}</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="sendf-4"/>
+ <p>Sends a Telnet command and returns immediately (uses a format
+ string and a list of arguments to build the command).</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>See Also</title>
+ <p><seealso marker="unix_telnet"><c>unix_telnet</c></seealso></p>
+ </section>
+
+</erlref>
+
+
diff --git a/lib/common_test/doc/src/ref_man.xml b/lib/common_test/doc/src/ref_man.xml
index f98e2475a9..19960bfea7 100644
--- a/lib/common_test/doc/src/ref_man.xml
+++ b/lib/common_test/doc/src/ref_man.xml
@@ -30,43 +30,10 @@
<file>ref_man.xml</file>
</header>
<description>
- <p><em>Common Test</em> is a portable application for automated
- testing. It is suitable for black-box testing of target
- systems of any type (i.e. not necessarily implemented in Erlang),
- as well as for white-box testing of Erlang/OTP programs.
- Black-box testing is performed via standard O&amp;M
- interfaces (such as SNMP, HTTP, Corba, Telnet, etc) and,
- if required, via user specific interfaces (often called test
- ports). White-box testing of Erlang/OTP programs is easily
- accomplished by calling the target API functions directly
- from the test case functions. Common Test also integrates
- usage of the OTP cover tool for code coverage analysis of
- Erlang/OTP programs.</p>
-
- <p>Common Test executes test suite programs automatically,
- without operator interaction. Test progress and results is
- printed to logs on HTML format, easily browsed with a standard
- web browser. Common Test also sends notifications about progress
- and results via an OTP event manager to event handlers plugged
- in to the system. This way users can integrate their own
- programs for e.g. logging, database storing or supervision with
- Common Test.</p>
-
- <p>Common Test provides libraries that contain useful support
- functions to fill various testing needs and requirements.
- There is for example support for flexible test declarations
- by means of so called test specifications. There is also support
- for central configuration and control of multiple
- independent test sessions (towards different target systems)
- running in parallel.</p>
-
- <p>Common Test is implemented as a framework based on the OTP Test
- Server application.</p>
</description>
+
<xi:include href="common_test_app.xml"/>
<xi:include href="ct_run.xml"/>
- <!-- If you make modifications in the module list below,
- you also need to update CT_MODULES in Makefile. -->
<xi:include href="ct.xml"/>
<xi:include href="ct_master.xml"/>
<xi:include href="ct_cover.xml"/>
@@ -83,6 +50,3 @@
</application>
-
-
-
diff --git a/lib/common_test/doc/src/unix_telnet.xml b/lib/common_test/doc/src/unix_telnet.xml
new file mode 100644
index 0000000000..189379c39a
--- /dev/null
+++ b/lib/common_test/doc/src/unix_telnet.xml
@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2010</year><year>2012</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+ </legalnotice>
+
+ <title>unix_telnet</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev>A</rev>
+ <file>unix_telnet.xml</file>
+ </header>
+ <module>unix_telnet</module>
+ <modulesummary>Callback module for ct_telnet, for connecting to a Telnet
+ server on a UNIX host.</modulesummary>
+
+ <description>
+
+ <p>Callback module for
+ <seealso marker="ct_telnet"><c>ct_telnet</c></seealso>,
+ for connecting to a Telnet server on a UNIX host.</p>
+
+ <p>It requires the following entry in the configuration file:</p>
+
+ <pre>
+ {unix,[{telnet,HostNameOrIpAddress},
+ {port,PortNum}, % optional
+ {username,UserName},
+ {password,Password},
+ {keep_alive,Bool}]}. % optional</pre>
+
+ <p>To communicate through Telnet to the host specified by
+ <c>HostNameOrIpAddress</c>, use the interface functions in
+ <seealso marker="ct_telnet"><c>ct_telnet</c></seealso>, for example,
+ <c>open(Name)</c> and <c>cmd(Name,Cmd)</c>.</p>
+
+ <p><c>Name</c> is the name you allocated to the Unix host in your
+ <c>require</c> statement, for example:</p>
+
+ <pre>
+ suite() -&gt; [{require,Name,{unix,[telnet]}}].</pre>
+
+ <p>or</p>
+
+ <pre>
+ ct:require(Name,{unix,[telnet]}).</pre>
+
+ <p>The "keep alive" activity (that is, that <c>Common Test</c> sends NOP
+ to the server every 10 seconds if the connection is idle) can be
+ enabled or disabled for one particular connection as described here.
+ It can be disabled for all connections using <c>telnet_settings</c>
+ (see <seealso marker="ct_telnet"><c>ct_telnet</c></seealso>).</p>
+
+ <p>The <c>{port,PortNum}</c> tuple is optional and if omitted, default
+ Telnet port 23 is used. Also the <c>keep_alive</c> tuple is optional,
+ and the value defauls to <c>true</c> (enabled).</p>
+ </description>
+
+ <funcs>
+ <func>
+ <name>connect(ConnName, Ip, Port, Timeout, KeepAlive, Extra) -&gt; {ok, Handle} | {error, Reason}</name>
+ <fsummary>Callback for ct_telnet.erl.</fsummary>
+ <type>
+ <v>ConnName = target_name()</v>
+ <v>Ip = string() | {integer(), integer(), integer(), integer()}</v>
+ <v>Port = integer()</v>
+ <v>Timeout = integer()</v>
+ <v>KeepAlive = bool()</v>
+ <v>Extra = target_name() | {Username, Password}</v>
+ <v>Username = string()</v>
+ <v>Password = string()</v>
+ <v>Handle = handle()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc><marker id="connect-6"/>
+ <p>Callback for <c>ct_telnet.erl</c>.</p>
+
+ <p>Setup Telnet connection to a Unix host.</p>
+
+ <p>For <c>target_name()</c>, see
+ <seealso marker="ct"><c>ct</c></seealso>. For <c>handle()</c>, see
+ <seealso marker="ct_telnet"><c>ct_telnet</c></seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>get_prompt_regexp() -&gt; PromptRegexp</name>
+ <fsummary>Callback for ct_telnet.erl.</fsummary>
+ <type>
+ <v>PromptRegexp = prompt_regexp()</v>
+ </type>
+ <desc><marker id="get_prompt_regexp-0"/>
+ <p>Callback for <c>ct_telnet.erl</c>.</p>
+
+ <p>Returns a suitable <c>regexp</c> string matching common prompts
+ for users on Unix hosts.</p>
+
+ <p>For <c>prompt_regexp()</c>, see
+ <seealso marker="ct_telnet"><c>ct_telnet</c></seealso>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>See Also</title>
+ <p><seealso marker="ct"><c>ct</c></seealso>,
+ <seealso marker="ct_telnet"><c>ct_telnet</c></seealso></p>
+ </section>
+
+</erlref>
+
+