From 68d7535fe0cccd50622884f704edeb9d8bb47430 Mon Sep 17 00:00:00 2001
From: tmanevik
Date: Fri, 18 Dec 2015 12:21:32 +0100
Subject: Common Test: Editorial changes 3
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Reference Manual files from Pär Wennstad added
---
lib/common_test/doc/src/common_test_app.xml | 776 +++++++-------
lib/common_test/doc/src/ct.xml | 1386 ++++++++++++++++++++++++++
lib/common_test/doc/src/ct_cover.xml | 106 ++
lib/common_test/doc/src/ct_ftp.xml | 277 +++++
lib/common_test/doc/src/ct_hooks.xml | 805 ++++++++-------
lib/common_test/doc/src/ct_master.xml | 220 ++++
lib/common_test/doc/src/ct_netconfc.xml | 1037 +++++++++++++++++++
lib/common_test/doc/src/ct_property_test.xml | 116 +++
lib/common_test/doc/src/ct_rpc.xml | 220 ++++
lib/common_test/doc/src/ct_run.xml | 299 +++---
lib/common_test/doc/src/ct_slave.xml | 221 ++++
lib/common_test/doc/src/ct_snmp.xml | 524 ++++++++++
lib/common_test/doc/src/ct_ssh.xml | 1150 +++++++++++++++++++++
lib/common_test/doc/src/ct_telnet.xml | 601 +++++++++++
lib/common_test/doc/src/ref_man.xml | 38 +-
lib/common_test/doc/src/unix_telnet.xml | 134 +++
16 files changed, 6929 insertions(+), 981 deletions(-)
create mode 100644 lib/common_test/doc/src/ct.xml
create mode 100644 lib/common_test/doc/src/ct_cover.xml
create mode 100644 lib/common_test/doc/src/ct_ftp.xml
create mode 100644 lib/common_test/doc/src/ct_master.xml
create mode 100644 lib/common_test/doc/src/ct_netconfc.xml
create mode 100644 lib/common_test/doc/src/ct_property_test.xml
create mode 100644 lib/common_test/doc/src/ct_rpc.xml
create mode 100644 lib/common_test/doc/src/ct_slave.xml
create mode 100644 lib/common_test/doc/src/ct_snmp.xml
create mode 100644 lib/common_test/doc/src/ct_ssh.xml
create mode 100644 lib/common_test/doc/src/ct_telnet.xml
create mode 100644 lib/common_test/doc/src/unix_telnet.xml
(limited to 'lib/common_test/doc/src')
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 @@
common_test_app.sgml
common_test
- A framework for automated testing of arbitrary target nodes
+ A framework for automated testing of any target nodes.
- The Common Test framework is an environment for
+
The Common Test framework is an environment for
implementing and performing automatic and semi-automatic execution of
- test cases.
+ test cases.
- Common Test uses the OTP Test Server as engine for test case
- execution and logging.
-
- In brief, Common Test supports:
+ In brief, Common Test supports:
- - Automated execution of test suites (sets of test cases).
- - Logging of the events during execution.
- - HTML presentation of test suite results.
- - HTML presentation of test suite code.
- - Support functions for test suite authors.
- - Step by step execution of test cases.
+ - Automated execution of test suites (sets of test cases)
+ - Logging of events during execution
+ - HTML presentation of test suite results
+ - HTML presentation of test suite code
+ - Support functions for test suite authors
+ - Step-by-step execution of test cases
-
- The following sections describe the mandatory and optional test suite
- functions Common Test will call during test execution. For more details
- see Common Test User's
- Guide.
-
+
+ The following section describes the mandatory and optional test suite
+ functions that Common Test calls during test execution.
+ For more details, see section
+ Writing Test Suites
+ in the User's Guide.
+
- TEST CASE CALLBACK FUNCTIONS
+ Test Case Callback Functions
The following functions define the callback interface
for a test suite.
-
+
Module:all() -> Tests | {skip,Reason}
Returns the list of all test case groups and test cases
in the module.
- Tests = [TestCase | {group,GroupName} |
- {group,GroupName,Properties} |
- {group,GroupName,Properties,SubGroups}]
+ Tests = [TestCase | {group,GroupName} | {group,GroupName,Properties} | {group,GroupName,Properties,SubGroups}]
TestCase = atom()
GroupName = atom()
- Properties = [parallel | sequence | Shuffle | {RepeatType,N}] |
- default
- SubGroups = [{GroupName,Properties} |
- {GroupName,Properties,SubGroups}]
+ Properties = [parallel | sequence | Shuffle | {RepeatType,N}] | default
+ SubGroups = [{GroupName,Properties} | {GroupName,Properties,SubGroups}]
Shuffle = shuffle | {shuffle,Seed}
Seed = {integer(),integer(),integer()}
- RepeatType = repeat | repeat_until_all_ok | repeat_until_all_fail |
- repeat_until_any_ok | repeat_until_any_fail
+ RepeatType = repeat | repeat_until_all_ok | repeat_until_all_fail | repeat_until_any_ok | repeat_until_any_fail
N = integer() | forever
Reason = term()
-
+
- MANDATORY
-
- 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,
+
MANDATORY
+
+ 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 Common Test.
+ A test case is represented by an atom,
the name of the test case function. A test case group is
represented by a group tuple, where GroupName,
- an atom, is the name of the group (defined in groups/0).
- 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 groups/0).
+ an atom, is the name of the group (defined in
+ groups/0).
+ 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
+ groups/0).
(With value default, the group definition properties
- will be used).
-
- If {skip,Reason} is returned, all test cases
- in the module will be skipped, and the Reason will
- be printed on the HTML result page.
-
- For details on groups, see
- Test case
- groups in the User's Guide.
-
+ are used).
+
+ If {skip,Reason} is returned, all test cases
+ in the module are skipped and Reason
+ is printed on the HTML result page.
+
+ For details on groups, see section
+ Test Case
+ Groups in the User's Guide.
+
@@ -123,25 +118,24 @@
Module:groups() -> GroupDefs
Returns a list of test case group definitions.
- GroupDefs = [Group]
- Group = {GroupName,Properties,GroupsAndTestCases}
- GroupName = atom()
- Properties = [parallel | sequence | Shuffle | {RepeatType,N}]
- GroupsAndTestCases = [Group | {group,GroupName} | TestCase]
- TestCase = atom()
- Shuffle = shuffle | {shuffle,Seed}
- Seed = {integer(),integer(),integer()}
- RepeatType = repeat | repeat_until_all_ok | repeat_until_all_fail |
- repeat_until_any_ok | repeat_until_any_fail
- N = integer() | forever
+ GroupDefs = [Group]
+ Group = {GroupName,Properties,GroupsAndTestCases}
+ GroupName = atom()
+ Properties = [parallel | sequence | Shuffle | {RepeatType,N}]
+ GroupsAndTestCases = [Group | {group,GroupName} | TestCase]
+ TestCase = atom()
+ Shuffle = shuffle | {shuffle,Seed}
+ Seed = {integer(),integer(),integer()}
+ RepeatType = repeat | repeat_until_all_ok | repeat_until_all_fail | repeat_until_any_ok | repeat_until_any_fail
+ N = integer() | forever
-
+
- OPTIONAL
-
- Function for defining test case groups. Please see
- Test case
- groups in the User's Guide for details.
+ OPTIONAL
+
+ Defines test case groups. For details, see section
+ Test Case
+ Groups in the User's Guide.
@@ -150,75 +144,71 @@
Test suite info function (providing default data
for the suite).
- Info = {timetrap,Time} | {require,Required} |
- {require,Name,Required} | {userdata,UserData} |
- {silent_connections,Conns} | {stylesheet,CSSFile} |
- {ct_hooks, CTHs}
- Time = TimeVal | TimeFunc
- TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} |
- {hours,integer()}
- TimeFunc = {Mod,Func,Args} | Fun
- MilliSec = integer()
- Mod = atom()
- Func = atom()
- Args = list()
- Fun = fun()
- Required = Key | {Key,SubKeys} | {Key,SubKey} | {Key,SubKey,SubKeys}
- Key = atom()
- SubKeys = SubKey | [SubKey]
- SubKey = atom()
- Name = atom()
- UserData = term()
- Conns = [atom()]
- CSSFile = string()
- CTHs = [CTHModule |
- {CTHModule, CTHInitArgs} |
- {CTHModule, CTHInitArgs, CTHPriority}]
- CTHModule = atom()
- CTHInitArgs = term()
+ Info = {timetrap,Time} | {require,Required} | {require,Name,Required} | {userdata,UserData} | {silent_connections,Conns} | {stylesheet,CSSFile} | {ct_hooks, CTHs}
+ Time = TimeVal | TimeFunc
+ TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} | {hours,integer()}
+ TimeFunc = {Mod,Func,Args} | Fun
+ MilliSec = integer()
+ Mod = atom()
+ Func = atom()
+ Args = list()
+ Fun = fun()
+ Required = Key | {Key,SubKeys} | {Key,SubKey} | {Key,SubKey,SubKeys}
+ Key = atom()
+ SubKeys = SubKey | [SubKey]
+ SubKey = atom()
+ Name = atom()
+ UserData = term()
+ Conns = [atom()]
+ CSSFile = string()
+ CTHs = [CTHModule |
+ {CTHModule, CTHInitArgs} |
+ {CTHModule, CTHInitArgs, CTHPriority}]
+ CTHModule = atom()
+ CTHInitArgs = term()
-
- OPTIONAL
-
- 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).
-
- The timetrap tag sets the maximum time each
- test case is allowed to execute (including init_per_testcase/2
- and end_per_testcase/2). If the timetrap time is
- exceeded, the test case fails with reason
+
+
OPTIONAL
+
+ 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).
+
+ Tag timetrap sets the maximum time that each
+ test case is allowed to execute (including
+ init_per_testcase/2
+ and
+ end_per_testcase/2).
+ If the timetrap time is exceeded, the test case fails with reason
timetrap_timeout. A TimeFunc function can be used to
- set a new timetrap by returning a TimeVal. It may also be
- used to trigger a timetrap timeout by, at some point, returning a
- value other than a TimeVal. (See the
- User's Guide
- for details).
-
-
- The require tag specifies configuration variables
- that are required by test cases (and/or configuration functions)
+ set a new timetrap by returning a TimeVal. It can also be
+ used to trigger a timetrap time-out by, at some point, returning a
+ value other than a TimeVal. For details, see section
+ Timetrap Time-Outs
+ in the User's Guide.
+
+ Tag require 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
- ct:require/1/2.
+ in any of the configuration files, all test cases are skipped.
+ For details about the require functionality, see funtion
+ ct:require/1,2.
- With userdata, it is possible for the user to
- specify arbitrary test suite related information which can be
- read by calling ct:userdata/2.
+ With userdata, the user can
+ specify any test suite-related information, which can be
+ read by calling
+ ct:userdata/2.
- The ct_hooks tag specifies which
+
Tag ct_hooks specifies the
Common Test Hooks
- are to be run together with this suite.
-
- Other tuples than the ones defined will simply be ignored.
+ to be run with this suite.
- For more information about the test suite info function,
- see Test
- suite info function in the User's Guide.
+ Other tuples than the ones defined are ignored.
+
+ For details about the test suite information function, see section
+ Test
+ Suite Information Function in the User's Guide.
@@ -227,129 +217,133 @@
{skip_and_save,Reason,SaveConfig}
Test suite initializations.
- Config = NewConfig = SaveConfig = [{Key,Value}]
- Key = atom()
- Value = term()
- Reason = term()
+ Config = NewConfig = SaveConfig = [{Key,Value}]
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
+
+ OPTIONAL
+
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 Config parameter is the configuration data
- which can be modified here. Whatever is returned from this
- function is given as Config to all configuration functions
- and test cases in the suite. If {skip,Reason}
- is returned, all test cases in the suite will be skipped
- and Reason printed in the overview log for the suite.
- For information on save_config and skip_and_save,
- please see
- Dependencies
- between Test Cases and Suites in the User's Guide.
-
+ suite. It typically contains initializations that are common for
+ all test cases in the suite, and that must only be done
+ once. Parameter Config is the configuration data
+ that can be modified. Whatever is returned from this
+ function is specified as Config to all configuration functions
+ and test cases in the suite.
+
+ If {skip,Reason}
+ is returned, all test cases in the suite are skipped
+ and Reason is printed in the overview log for the suite.
+
+ For information on save_config and skip_and_save,
+ see section
+ Saving
+ Configuration Data in the User's Guide.
+
-
+
Module:end_per_suite(Config) -> term() |
{save_config,SaveConfig}
- Test suite finalization.
+ Test suite finalization.
- Config = SaveConfig = [{Key,Value}]
- Key = atom()
- Value = term()
+ Config = SaveConfig = [{Key,Value}]
+ Key = atom()
+ Value = term()
-
+
- OPTIONAL
+ OPTIONAL
This function is called as the last test case in the
suite. It is meant to be used for cleaning up after
- init_per_suite/1.
- For information on save_config, please see
- Dependencies
- between Test Cases and Suites in the User's Guide.
+ init_per_suite/1.
+ For information on save_config, see section
+ Saving
+ Configuration Data in the User's Guide.
Module:group(GroupName) -> [Info]
- Test case group info function (providing default data
- for a test case group, i.e. its test cases and sub-groups).
+ Test case group information function (providing default data
+ for a test case group, that is, its test cases and
+ subgroups).
- Info = {timetrap,Time} | {require,Required} |
- {require,Name,Required} | {userdata,UserData} |
- {silent_connections,Conns} | {stylesheet,CSSFile} |
- {ct_hooks, CTHs}
- Time = TimeVal | TimeFunc
- TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} |
- {hours,integer()}
- TimeFunc = {Mod,Func,Args} | Fun
- MilliSec = integer()
- Mod = atom()
- Func = atom()
- Args = list()
- Fun = fun()
- Required = Key | {Key,SubKeys} | {Key,Subkey} | {Key,Subkey,SubKeys}
- Key = atom()
- SubKeys = SubKey | [SubKey]
- SubKey = atom()
- Name = atom()
- UserData = term()
- Conns = [atom()]
- CSSFile = string()
- CTHs = [CTHModule |
- {CTHModule, CTHInitArgs} |
- {CTHModule, CTHInitArgs, CTHPriority}]
- CTHModule = atom()
- CTHInitArgs = term()
-
-
-
- OPTIONAL
-
- This is the test case group info function. It is supposed to
+ Info = {timetrap,Time} | {require,Required} | {require,Name,Required} | {userdata,UserData} | {silent_connections,Conns} | {stylesheet,CSSFile} | {ct_hooks, CTHs}
+ Time = TimeVal | TimeFunc
+ TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} | {hours,integer()}
+ TimeFunc = {Mod,Func,Args} | Fun
+ MilliSec = integer()
+ Mod = atom()
+ Func = atom()
+ Args = list()
+ Fun = fun()
+ Required = Key | {Key,SubKeys} | {Key,Subkey} | {Key,Subkey,SubKeys}
+ Key = atom()
+ SubKeys = SubKey | [SubKey]
+ SubKey = atom()
+ Name = atom()
+ UserData = term()
+ Conns = [atom()]
+ CSSFile = string()
+ CTHs = [CTHModule |
+ {CTHModule, CTHInitArgs} |
+ {CTHModule, CTHInitArgs, CTHPriority}]
+ CTHModule = atom()
+ CTHInitArgs = term()
+
+
+
+ OPTIONAL
+
+ 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
group/1 override
- properties with the same key that have been previously set by
+ properties with the same key that have been set previously by
suite/0.
- The timetrap tag sets the maximum time each
- test case is allowed to execute (including init_per_testcase/2
- and end_per_testcase/2). If the timetrap time is
+
Tag timetrap sets the maximum time that each
+ test case is allowed to execute (including
+ init_per_testcase/2
+ and
+ end_per_testcase/2).
+ If the timetrap time is
exceeded, the test case fails with reason
timetrap_timeout. A TimeFunc function can be used to
- set a new timetrap by returning a TimeVal. It may also be
- used to trigger a timetrap timeout by, at some point, returning a
- value other than a TimeVal. (See the
- User's Guide
- for details).
+ set a new timetrap by returning a TimeVal. It can also be
+ used to trigger a timetrap time-out by, at some point, returning a
+ value other than a TimeVal. For details, see section
+ Timetrap
+ Time-Outs in the User's Guide.
- The require tag specifies configuration variables
- that are required by test cases (and/or configuration functions)
+
Tag require 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
- ct:require/1/2.
+ in any of the configuration files, all test cases in this group are
+ skipped. For details about the require functionality, see
+ function
+ ct:require/1,2.
- With userdata, it is possible for the user to
- specify arbitrary test case group related information which can be
- read by calling ct:userdata/2.
+ With userdata, the user can
+ specify any test case group related information that can be
+ read by calling
+ ct:userdata/2.
- The ct_hooks tag specifies which
+
Tag ct_hooks specifies the
Common Test Hooks
- are to be run together with this suite.
-
- Other tuples than the ones defined will simply be ignored.
+ to be run with this suite.
- For more information about the test case group info function,
- see Test
- case group info function in the User's Guide.
+ Other tuples than the ones defined are ignored.
+
+ For details about the test case group information function,
+ see section Group
+ Information Function in the User's Guide.
@@ -358,59 +352,66 @@
{skip,Reason}
Test case group initializations.
- GroupName = atom()
- Config = NewConfig = [{Key,Value}]
- Key = atom()
- Value = term()
- Reason = term()
+ GroupName = atom()
+ Config = NewConfig = [{Key,Value}]
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
+
+ OPTIONAL
+
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. GroupName is the name of the
- group, as specified in the group definition (see groups/0). The
- Config parameter is the configuration data which can be modified
- here. The return value of this function is given as Config
- to all test cases and sub-groups in the group. If {skip,Reason}
- is returned, all test cases in the group will be skipped and
- Reason printed in the overview log for the group.
-
- For information about test case groups, please see
- Test case
- groups chapter in the User's Guide.
+ 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. GroupName is the name of the
+ group, as specified in the group definition (see
+ groups/0).
+ Parameter Config is the configuration data that can be
+ modified.
+ The return value of this function is given as Config
+ to all test cases and subgroups in the group.
+
+ If {skip,Reason}
+ is returned, all test cases in the group are skipped and
+ Reason is printed in the overview log for the group.
+
+ For information about test case groups, see section
+ Test Case
+ Groups in the User's Guide.
-
+
Module:end_per_group(GroupName, Config) -> term() |
{return_group_result,Status}
Test case group finalization.
- GroupName = atom()
- Config = [{Key,Value}]
- Key = atom()
- Value = term()
- Status = ok | skipped | failed
+ GroupName = atom()
+ Config = [{Key,Value}]
+ Key = atom()
+ Value = term()
+ Status = ok | skipped | failed
-
+
- OPTIONAL
-
- This function is called after the execution of a test case group is finished.
- It is meant to be used for cleaning up after init_per_group/2.
- By means of {return_group_result,Status}, it is possible to return a
- status value for a nested sub-group. The status can be retrieved in
- end_per_group/2 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 sequence or repeat_until_* is set.
-
- For more information about test case groups, please see
- Test case
- groups chapter in the User's Guide.
+ OPTIONAL
+
+ This function is called after the execution of a test case group
+ is finished. It is meant to be used for cleaning up after
+ init_per_group/2.
+ A status value for a nested subgroup can be returned with
+ {return_group_result,Status}. The status can be retrieved in
+ end_per_group/2
+ for the group on the level above. The status is also used by
+ Common Test for deciding if execution of a group is to
+ proceed if property sequence or repeat_until_*
+ is set.
+
+ For details about test case groups, see section
+ Test Case
+ Groups in the User's Guide.
@@ -424,168 +425,173 @@
Value = term()
Reason = term()
-
-
+
+
OPTIONAL
-
- This function is called before each test case. The
- TestCase argument is the name of the test case, and
+
+
This function is called before each test case. Argument
+ TestCase is the test case name, and
Config (list of key-value tuples) is the configuration
- data that can be modified here. The NewConfig list returned
+ data that can be modified. The NewConfig list returned
from this function is given as Config to the test case.
If {fail,Reason} is returned, the test case is
- marked as failed without being executed. If {skip,Reason} is
- returned, the test case will be skipped and Reason printed
- in the overview log for the suite.
+ marked as failed without being executed.
+
+ If {skip,Reason} is returned, the test case is skipped
+ and Reason is printed in the overview log for the suite.
-
+
Module:end_per_testcase(TestCase, Config) -> term() | {fail,Reason} | {save_config,SaveConfig}
Test case finalization.
- TestCase = atom()
- Config = SaveConfig = [{Key,Value}]
- Key = atom()
- Value = term()
- Reason = term()
+ TestCase = atom()
+ Config = SaveConfig = [{Key,Value}]
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called after each test case, and can be used
- to clean up after init_per_testcase/2 and the test case.
- Any return value (besides {fail,Reason} and {save_config,SaveConfig})
- is ignored. By returning {fail,Reason}, TestCase 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 save_config, please see
- Dependencies between
- Test Cases and Suites in the User's Guide
+
+ OPTIONAL
+
+ This function is called after each test case, and can be used
+ to clean up after
+ init_per_testcase/2
+ and the test case. Any return value (besides {fail,Reason}
+ and {save_config,SaveConfig}) is ignored. By returning
+ {fail,Reason}, TestCase is marked as faulty (even
+ though it was successful in the sense that it returned
+ a value instead of terminating).
+
+ For information on save_config, see section
+ Saving
+ Configuration Data in the User's Guide.
-
+
Module:Testcase() -> [Info]
- Test case info function.
+ Test case information function.
- Info = {timetrap,Time} | {require,Required} |
- {require,Name,Required} | {userdata,UserData} |
- {silent_connections,Conns}
- Time = TimeVal | TimeFunc
- TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} |
- {hours,integer()}
- TimeFunc = {Mod,Func,Args} | Fun
- MilliSec = integer()
- Mod = atom()
- Func = atom()
- Args = list()
- Fun = fun()
- Required = Key | {Key,SubKeys} | {Key,Subkey} | {Key,Subkey,SubKeys}
- Key = atom()
- SubKeys = SubKey | [SubKey]
- SubKey = atom()
- Name = atom()
- UserData = term()
- Conns = [atom()]
+ Info = {timetrap,Time} | {require,Required} | {require,Name,Required} | {userdata,UserData} | {silent_connections,Conns}
+ Time = TimeVal | TimeFunc
+ TimeVal = MilliSec | {seconds,integer()} | {minutes,integer()} | {hours,integer()}
+ TimeFunc = {Mod,Func,Args} | Fun
+ MilliSec = integer()
+ Mod = atom()
+ Func = atom()
+ Args = list()
+ Fun = fun()
+ Required = Key | {Key,SubKeys} | {Key,Subkey} | {Key,Subkey,SubKeys}
+ Key = atom()
+ SubKeys = SubKey | [SubKey]
+ SubKey = atom()
+ Name = atom()
+ UserData = term()
+ Conns = [atom()]
-
-
+
+
OPTIONAL
-
- This is the test case info function. It is supposed to
+
+
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 Testcase/0 override
- properties that have been previously set for the test case
- by group/1 or suite/0.
-
- The timetrap tag sets the maximum time the
+ Properties set by
+ Testcase/0
+ override properties set previously for the test case by
+ group/1 or
+ suite/0.
+
+ Tag timetrap sets the maximum time that the
test case is allowed to execute. If the timetrap time is
- exceeded, the test case fails with reason
- timetrap_timeout. init_per_testcase/2
- and end_per_testcase/2 are included in the
- timetrap time. A TimeFunc function can be used to
- set a new timetrap by returning a TimeVal. It may also be
- used to trigger a timetrap timeout by, at some point, returning a
- value other than a TimeVal. (See the
- User's Guide
- for details).
+ exceeded, the test case fails with reason timetrap_timeout.
+ init_per_testcase/2
+ and
+ end_per_testcase/2
+ are included in the timetrap time.
+ A TimeFunc function can be used to
+ set a new timetrap by returning a TimeVal. It can also be
+ used to trigger a timetrap time-out by, at some point, returning a
+ value other than a TimeVal. For details, see section
+ Timetrap
+ Time-Outs in the User's Guide.
- The require tag specifies configuration variables
- that are required by the test case (and/or init/end_per_testcase/2).
+
Tag require specifies configuration variables
+ that are required by the test case (or init_per_testcase/2
+ or end_per_testcase/2).
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
- ct:require/1/2.
-
- If timetrap and/or require is not set, the
- default values specified by suite/0 (or
- group/1) will be used.
-
- With userdata, it is possible for the user to
- specify arbitrary test case related information which can be
- read by calling ct:userdata/3.
-
- Other tuples than the ones defined will simply be ignored.
+ configuration files, the test case is skipped. For details about
+ the require functionality, see function
+ ct:require/1,2.
+
+ If timetrap or require is not set, the
+ default values specified by
+ suite/0 (or
+ group/1) are used.
+
+ With userdata, the user can specify any test case-related
+ information that can be read by calling
+ ct:userdata/3.
+
+ Other tuples than the ones defined are ignored.
- For more information about the test case info function,
- see Test
- case info function in the User's Guide.
+ For details about the test case information function, see section
+ Test
+ Case Information Function in the User's Guide.
-
-
+
Module:Testcase(Config) -> term() | {skip,Reason} | {comment,Comment} | {save_config,SaveConfig} | {skip_and_save,Reason,SaveConfig} | exit()
- A test case
+ A test case.
- Config = SaveConfig = [{Key,Value}]
- Key = atom()
- Value = term()
- Reason = term()
- Comment = string()
+ Config = SaveConfig = [{Key,Value}]
+ Key = atom()
+ Value = term()
+ Reason = term()
+ Comment = string()
-
+
- MANDATORY
-
- 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 ct:fail/1/2
+
MANDATORY
+
+ 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
+ ct:fail/1,2
(which also causes the test case process to terminate).
-
- Elements from the Config list can e.g. be read
- with proplists:get_value/2 (or the macro ?config
- defined in ct.hrl).
- You can return {skip,Reason} if you decide not to
- run the test case after all. Reason will then be
- printed in 'Comment' field on the HTML result page.
-
- You can return {comment,Comment} if you wish to
- print some information in the 'Comment' field on the HTML
- result page.
-
- If the function returns anything else, the test case is
- considered successful. (The return value always gets printed
- in the test case log file).
+ Elements from the Config list can, for example, be read
+ with proplists:get_value/2 in STDLIB
+ (or the macro ?config defined in ct.hrl).
+
+ If you decide not to run the test case after all, return
+ {skip,Reason}. Reason is then
+ printed in field Comment on the HTML result page.
+
+ To print some information in field Comment on the HTML
+ result page, return {comment,Comment}.
- For more information about test case implementation, please
- see Test
- cases in the User's Guide.
+ If the function returns anything else, the test case is
+ considered successful. The return value always gets printed
+ in the test case log file.
- For information on save_config and skip_and_save, please see
- Dependencies between
- Test Cases and Suites in the User's Guide.
+ For details about test case implementation, see section
+ Test Cases
+ in the User's Guide.
+
+ For information on save_config and skip_and_save,
+ see section
+ Saving
+ Configuration Data in the User's Guide.
-
+
-
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct
+
+
+
+
+
+
+ A
+ ct.xml
+
+ ct
+ Main user interface for the Common Test framework.
+
+
+
+ Main user interface for the Common Test framework.
+
+ This module implements the command-line interface for running
+ tests and basic functions for Common Test case issues, such as
+ configuration and logging.
+
+ Test Suite Support Macros
+
+ The config macro is defined in ct.hrl. This macro is
+ to be used to retrieve information from the Config 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
+ Config variable supplied to the test case.
+
+ Possible configuration variables include:
+
+
+ data_dir - Data file directory
+ priv_dir - Scratch file directory
+ Whatever added by
+ init_per_suite/1
+ or
+ init_per_testcase/2
+ in the test suite.
+
+
+
+
+
+ Data Types
+
+
+
+ handle() = pid()
+ -
+
The identity (handle) of a connection.
+
+ target_name() = atom()
+ -
+
A name and association to configuration data introduced
+ through a require statement, or a call to
+ ct:require/2,
+ for example,
+ ct:require(mynodename,{node,[telnet]}).
+
+
+
+
+
+
+ abort_current_testcase(Reason) -> ok | {error, ErrorReason}
+ Aborts the currently executing test case.
+
+ Reason = term()
+ ErrorReason = no_testcase_running | parallel_group
+
+
+ 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.
+
+ Reason, the reason for aborting the test case, is printed
+ in the test case log.
+
+
+
+
+ add_config(Callback, Config) -> ok | {error, Reason}
+ Loads configuration variables using the specified callback
+ module and configuration string.
+
+ Callback = atom()
+ Config = string()
+ Reason = term()
+
+
+ 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
+ ct:remove_config/2.
+
+
+
+
+
+ break(Comment) -> ok | {error, Reason}
+ Cancels any active timetrap and pause the execution of the
+ current test case until the user calls function continue/0.
+
+ Comment = string()
+ Reason = {multiple_cases_running, TestCases} | 'enable break with release_shell option'
+ TestCases = [atom()]
+
+
+ Cancels any active timetrap and pauses the execution of the
+ current test case until the user calls function continue/0.
+ 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,
+ ct:break/2 is to be
+ called instead.
+ A cancelled timetrap is not automatically reactivated after the
+ break, but must be started exlicitly with
+ ct:timetrap/1.
+ In order for the break/continue functionality to work, Common
+ Test must release the shell process controlling stdin.
+ This is done by setting start option release_shell
+ to true. For details, see section
+ Running
+ Tests from the Erlang Shell or from an Erlang Program
+ in the User's Guide.
+
+
+
+
+ break(TestCase, Comment) -> ok | {error, Reason}
+ Works the same way as break/1, only argument TestCase makes it
+ possible to pause a test case executing in a parallel group.
+
+ TestCase = atom()
+ Comment = string()
+ Reason = 'test case not running' | 'enable break with release_shell option'
+
+
+ Works the same way as
+ ct:break/1, only
+ argument TestCase makes it possible to pause a test case
+ executing in a parallel group. Function
+ ct:continue/1 is to
+ be used to resume execution of TestCase.
+
+ For details, see
+ ct:break/1.
+
+
+
+
+ capture_get() -> ListOfStrings
+ Equivalent to capture_get([default]).
+
+ ListOfStrings = [string()]
+
+
+ Equivalent to
+ ct:capture_get([default]).
+
+
+
+
+ capture_get(ExclCategories) -> ListOfStrings
+ Returns and purges the list of text strings buffered during
+ the latest session of capturing printouts to stdout.
+
+ ExclCategories = [atom()]
+ ListOfStrings = [string()]
+
+
+ Returns and purges the list of text strings buffered during the
+ latest session of capturing printouts to stdout. Log
+ categories that are to be ignored in ListOfStrings can be
+ specified with ExclCategories.
+ If ExclCategories = [], no filtering takes place.
+
+ See also
+ ct:capture_start/0,
+ ct:capture_stop/0,
+ ct:log/3.
+
+
+
+
+ capture_start() -> ok
+ Starts capturing all text strings printed to stdout
+ during execution of the test case.
+
+ Starts capturing all text strings printed to stdout
+ during execution of the test case.
+
+ See also
+ ct:capture_get/1,
+ ct:capture_stop/0.
+
+
+
+
+ capture_stop() -> ok
+ Stops capturing text strings (a session started with
+ capture_start/0).
+
+ Stops capturing text strings (a session started with
+ capture_start/0).
+
+ See also
+ ct:capture_get/1,
+ ct:capture_start/0.
+
+
+
+
+ comment(Comment) -> ok
+ Prints the specified Comment in the comment field in the
+ table on the test suite result page.
+
+ Comment = term()
+
+
+ Prints the specified Comment in the comment field in the
+ table on the test suite result page.
+
+ If called several times, only the last comment is printed. The
+ test case return value {comment,Comment} overwrites the
+ string set by this function.
+
+
+
+
+ comment(Format, Args) -> ok
+ Prints the formatted string in the comment field in the
+ table on the test suite result page.
+
+ Format = string()
+ Args = list()
+
+
+ Prints the formatted string in the comment field in the table
+ on the test suite result page.
+
+ Arguments Format and Args are used in a call to
+ io_lib:format/2 to create the comment string. The behavior
+ of comment/2 is otherwise the same as function
+ ct:comment/1.
+
+
+
+
+ continue() -> ok
+ This function must be called to continue after a test
+ case (not executing in a parallel group) has called break/1.
+
+ This function must be called to continue after a test case
+ (not executing in a parallel group) has called function
+ ct:break/1.
+
+
+
+
+ continue(TestCase) -> ok
+ This function must be called to continue after a test case
+ has called break/2.
+
+ TestCase = atom()
+
+
+ This function must be called to continue after a test case has
+ called ct:break/2.
+ If the paused test case, TestCase, executes in a parallel
+ group, this function, rather than continue/0, must be used
+ to let the test case proceed.
+
+
+
+
+ decrypt_config_file(EncryptFileName, TargetFileName) -> ok | {error, Reason}
+ Decrypts EncryptFileName, previously generated with
+ encrypt_config_file/2,3.
+
+ EncryptFileName = string()
+ TargetFileName = string()
+ Reason = term()
+
+
+ Decrypts EncryptFileName, previously generated with
+ ct:encrypt_config_file/2,3.
+ The original file contents is saved in the target file. The
+ encryption key, a string, must be available in a text file named
+ .ct_config.crypt, either in the current directory, or the
+ home directory of the user (it is searched for in that order).
+
+
+
+
+ decrypt_config_file(EncryptFileName, TargetFileName, KeyOrFile) -> ok | {error, Reason}
+ Decrypts EncryptFileName, previously generated with
+ encrypt_config_file/2,3.
+
+ EncryptFileName = string()
+ TargetFileName = string()
+ KeyOrFile = {key, string()} | {file, string()}
+ Reason = term()
+
+
+ Decrypts EncryptFileName, previously generated with
+ ct:encrypt_config_file/2,3.
+ The original file contents is saved in the target file. The key
+ must have the same value as that used for encryption.
+
+
+
+
+ encrypt_config_file(SrcFileName, EncryptFileName) -> ok | {error, Reason}
+ Encrypts the source configuration file with DES3 and saves the
+ result in file EncryptFileName.
+
+ SrcFileName = string()
+ EncryptFileName = string()
+ Reason = term()
+
+
+ Encrypts the source configuration file with DES3 and saves the result
+ in file EncryptFileName. The key, a string, must be
+ available in a text file named .ct_config.crypt, either
+ in the current directory, or the home directory of the user (it
+ is searched for in that order).
+
+ For information about using encrypted configuration files when
+ running tests, see section
+ Encrypted
+ Configuration Files in the User's Guide.
+
+ For details on DES3 encryption/decryption, see application
+ Crypto.
+
+
+
+
+ encrypt_config_file(SrcFileName, EncryptFileName, KeyOrFile) -> ok | {error, Reason}
+ Encrypts the source configuration file with DES3 and saves the
+ result in the target file EncryptFileName.
+
+ SrcFileName = string()
+ EncryptFileName = string()
+ KeyOrFile = {key, string()} | {file, string()}
+ Reason = term()
+
+
+ Encrypts the source configuration file with DES3 and saves the result
+ in the target file EncryptFileName. The encryption key
+ to use is either the value in {key,Key} or the value
+ stored in the file specified by {file,File}.
+
+ For information about using encrypted configuration files when
+ running tests, see section
+ Encrypted
+ Configuration Files in the User's Guide.
+
+ For details on DES3 encryption/decryption, see application
+ Crypto.
+
+
+
+
+ fail(Reason) -> ok
+ Terminates a test case with the specified error
+ Reason.
+
+ Reason = term()
+
+
+ Terminates a test case with the specified error Reason.
+
+
+
+
+ fail(Format, Args) -> ok
+ 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).
+
+ Format = string()
+ Args = list()
+
+
+ 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).
+
+
+
+
+ get_config(Required) -> Value
+ Equivalent to get_config(Required, undefined, []).
+
+ Equivalent to ct:get_config(Required,
+ undefined, []).
+
+
+
+
+ get_config(Required, Default) -> Value
+ Equivalent to get_config(Required, Default, []).
+
+ Equivalent to ct:get_config(Required,
+ Default, []).
+
+
+
+
+ get_config(Required, Default, Opts) -> ValueOrElement
+ Reads configuration data values.
+
+ Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}
+ KeyOrName = atom()
+ SubKey = atom()
+ Default = term()
+ Opts = [Opt] | []
+ Opt = element | all
+ ValueOrElement = term() | Default
+
+
+ Reads configuration data values.
+
+ Returns the matching values or configuration elements, given a
+ configuration variable key or its associated name (if one has been
+ specified with
+ ct:require/2
+ or a require statement).
+
+ Example:
+
+ Given the following configuration file:
+
+
+ {unix,[{telnet,IpAddr},
+ {user,[{username,Username},
+ {password,Password}]}]}.
+
+ Then:
+
+
+ ct:get_config(unix,Default) -> [{telnet,IpAddr},
+ {user, [{username,Username}, {password,Password}]}]
+ ct:get_config({unix,telnet},Default) -> IpAddr
+ ct:get_config({unix,user,username},Default) -> Username
+ ct:get_config({unix,ftp},Default) -> Default
+ ct:get_config(unknownkey,Default) -> Default
+
+ If a configuration variable key has been associated with a name (by
+ ct:require/2
+ or a require statement), the name can be used instead
+ of the key to read the value:
+
+
+ ct:require(myuser,{unix,user}) -> ok.
+ ct:get_config(myuser,Default) -> [{username,Username}, {password,Password}]
+
+ If a configuration variable is defined in multiple files, use option
+ all 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.
+
+ If configuration elements (key-value tuples) are to be returned as
+ result instead of values, use option element. The
+ returned elements are then on the form {Required,Value}.
+
+ See also
+ ct:get_config/1,
+ ct:get_config/2,
+ ct:require/1,
+ ct:require/2.
+
+
+
+
+ get_event_mgr_ref() -> EvMgrRef
+ Gets a reference to the Common Test event manager.
+
+ EvMgrRef = atom()
+
+
+ Gets a reference to the Common Test event manager.
+ The reference can be used to, for example, add a user-specific
+ event handler while tests are running.
+
+ Example:
+
+
+ gen_event:add_handler(ct:get_event_mgr_ref(), my_ev_h, [])
+
+
+
+
+ get_status() -> TestStatus | {error, Reason} | no_tests_running
+ Returns status of ongoing test.
+
+ TestStatus = [StatusElem]
+ StatusElem = {current, TestCaseInfo} | {successful, Successful} | {failed, Failed} | {skipped, Skipped} | {total, Total}
+ TestCaseInfo = {Suite, TestCase} | [{Suite, TestCase}]
+ Suite = atom()
+ TestCase = atom()
+ Successful = integer()
+ Failed = integer()
+ Skipped = {UserSkipped, AutoSkipped}
+ UserSkipped = integer()
+ AutoSkipped = integer()
+ Total = integer()
+ Reason = term()
+
+
+ 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.
+
+
+
+
+ get_target_name(Handle) -> {ok, TargetName} | {error, Reason}
+ Returns the name of the target that the specified connection
+ belongs to.
+
+ Handle = handle()
+ TargetName = target_name()
+
+
+ Returns the name of the target that the specified connection
+ belongs to.
+
+
+
+
+ get_testspec_terms() -> TestSpecTerms | undefined
+ Gets a list of all test specification terms used to
+ configure and run this test.
+
+ TestSpecTerms = [{Tag, Value}]
+ Value = [term()]
+
+
+ Gets a list of all test specification terms used to configure
+ and run this test.
+
+
+
+
+ get_testspec_terms(Tags) -> TestSpecTerms | undefined
+ Reads one or more terms from the test specification used to
+ configure and run this test.
+
+ Tags = [Tag] | Tag
+ Tag = atom()
+ TestSpecTerms = [{Tag, Value}] | {Tag, Value}
+ Value = [{Node, term()}] | [term()]
+ Node = atom()
+
+
+ Reads one or more terms from the test specification used to
+ configure and run this test. Tag is any valid test
+ specification tag, for example, label, config, or
+ logdir. User-specific terms are also available to read if
+ option allow_user_terms is set.
+ All value tuples returned, except user terms, have the node
+ name as first element.
+ To read test terms, use Tag = tests (rather than
+ suites, groups, or cases). Value is
+ then the list of all tests on the form
+ [{Node,Dir,[{TestSpec,GroupsAndCases1},...]},...], where
+ GroupsAndCases = [{Group,[Case]}] | [Case].
+
+
+
+
+ get_timetrap_info() -> {Time, Scale}
+ Reads information about the timetrap set for the current
+ test case.
+
+ Time = integer() | infinity
+ Scale = true | false
+
+
+ Reads information about the timetrap set for the current test
+ case. Scale indicates if Common Test will attempt
+ to compensate timetraps automatically for runtime delays
+ introduced by, for example, tools like cover.
+
+
+
+
+ install(Opts) -> ok | {error, Reason}
+ Installs configuration files and event handlers.
+
+ Opts = [Opt]
+ Opt = {config, ConfigFiles} | {event_handler, Modules} | {decrypt, KeyOrFile}
+ ConfigFiles = [ConfigFile]
+ ConfigFile = string()
+ Modules = [atom()]
+ KeyOrFile = {key, Key} | {file, KeyFile}
+ Key = string()
+ KeyFile = string()
+
+
+ Installs configuration files and event handlers.
+
+ Run this function once before the first test.
+
+ Example:
+
+
+ install([{config,["config_node.ctc","config_user.ctc"]}])
+
+ This function is automatically run by program ct_run.
+
+
+
+
+ listenv(Telnet) -> [Env]
+ Performs command listenv on the specified Telnet connection
+ and returns the result as a list of key-value pairs.
+
+ Telnet = term()
+ Env = {Key, Value}
+ Key = string()
+ Value = string()
+
+
+ Performs command listenv on the specified Telnet connection
+ and returns the result as a list of key-value pairs.
+
+
+
+
+ log(Format) -> ok
+ Equivalent to log(default, 50, Format, []).
+
+ Equivalent to
+ ct:log(default, 50, Format, []).
+
+
+
+
+ log(X1, X2) -> ok
+ Equivalent to log(Category, Importance, Format,
+ Args).
+
+ X1 = Category | Importance | Format
+ X2 = Format | Args
+
+
+ Equivalent to ct:log(Category,
+ Importance, Format, Args).
+
+
+
+
+ log(X1, X2, X3) -> ok
+ Equivalent to log(Category, Importance, Format,
+ Args).
+
+ X1 = Category | Importance
+ X2 = Importance | Format
+ X3 = Format | Args
+
+
+ Equivalent to ct:log(Category,
+ Importance, Format, Args).
+
+
+
+
+ log(Category, Importance, Format, Args) -> ok
+ Prints from a test case to the log file.
+
+ Category = atom()
+ Importance = integer()
+ Format = string()
+ Args = list()
+
+
+ Prints from a test case to the log file.
+
+ This function is meant for printing a string directly from a
+ test case to the test case log file.
+
+ Default Category is default,
+ default Importance is ?STD_IMPORTANCE,
+ and default value for Args is [].
+
+ For details on Category and Importance, see section
+ Logging - Categories
+ and Verbosity Levels in the User's Guide.
+
+
+
+
+ make_priv_dir() -> ok | {error, Reason}
+ 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.
+
+ Reason = term()
+
+
+ If the test is 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.
+
+
+
+
+ notify(Name, Data) -> ok
+ Sends an asynchronous notification of type Name with Data
+ to the Common Test event manager.
+
+ Name = atom()
+ Data = term()
+
+
+ Sends an asynchronous notification of type Name with
+ Datato the Common Test event manager. This can later be
+ caught by any installed event manager.
+
+ See also
+ stdlib:gen_event(3).
+
+
+
+
+ pal(Format) -> ok
+ Equivalent to pal(default, 50, Format, []).
+
+ Equivalent to
+ ct:pal(default, 50, Format,
+ []).
+
+
+
+
+ pal(X1, X2) -> ok
+ Equivalent to pal(Category, Importance, Format,
+ Args).
+
+ X1 = Category | Importance | Format
+ X2 = Format | Args
+
+
+ Equivalent to ct:pal(Category,
+ Importance, Format, Args).
+
+
+
+
+ pal(X1, X2, X3) -> ok
+ Equivalent to pal(Category, Importance, Format,
+ Args).
+
+ X1 = Category | Importance
+ X2 = Importance | Format
+ X3 = Format | Args
+
+
+ Equivalent to ct:pal(Category,
+ Importance, Format, Args).
+
+
+
+
+ pal(Category, Importance, Format, Args) -> ok
+ Prints and logs from a test case.
+
+ Category = atom()
+ Importance = integer()
+ Format = string()
+ Args = list()
+
+
+ Prints and logs from a test case.
+
+ This function is meant for printing a string from a test case,
+ both to the test case log file and to the console.
+
+ Default Category is default,
+ default Importance is ?STD_IMPORTANCE,
+ and default value for Args is [].
+
+ For details on Category and Importance, see section
+ Logging - Categories
+ and Verbosity Levels in the User's Guide.
+
+
+
+
+ parse_table(Data) -> {Heading, Table}
+ Parses the printout from an SQL table and returns a list of
+ tuples.
+
+ Data = [string()]
+ Heading = tuple()
+ Table = [tuple()]
+
+
+ Parses the printout from an SQL table and returns a list of
+ tuples.
+
+ The printout to parse is typically the result of a select
+ command in SQL. The returned Table is a list of tuples,
+ where each tuple is a row in the table.
+
+ Heading is a tuple of strings representing the headings
+ of each column in the table.
+
+
+
+
+ print(Format) -> ok
+ Equivalent to print(default, 50, Format, []).
+
+ Equivalent to ct:print(default,
+ 50, Format, []).
+
+
+
+
+ print(X1, X2) -> ok
+ Equivalent to print(Category, Importance, Format,
+ Args).
+
+ X1 = Category | Importance | Format
+ X2 = Format | Args
+
+
+ Equivalent to ct:print(Category,
+ Importance, Format, Args).
+
+
+
+
+ print(X1, X2, X3) -> ok
+ Equivalent to print(Category, Importance, Format,
+ Args).
+
+ X1 = Category | Importance
+ X2 = Importance | Format
+ X3 = Format | Args
+
+
+ Equivalent to ct:print(Category,
+ Importance, Format, Args).
+
+
+
+
+ print(Category, Importance, Format, Args) -> ok
+ Prints from a test case to the console.
+
+ Category = atom()
+ Importance = integer()
+ Format = string()
+ Args = list()
+
+
+ Prints from a test case to the console.
+
+ This function is meant for printing a string from a test case to
+ the console.
+
+ Default Category is default,
+ default Importance is ?STD_IMPORTANCE,
+ and default value for Args is [].
+
+ For details on Category and Importance, see section
+ Logging - Categories
+ and Verbosity Levels in the User's Guide.
+
+
+
+
+ reload_config(Required) -> ValueOrElement
+ Reloads configuration file containing specified configuration
+ key.
+
+ Required = KeyOrName | {KeyOrName, SubKey} | {KeyOrName, SubKey, SubKey}
+ KeyOrName = atom()
+ SubKey = atom()
+ ValueOrElement = term()
+
+
+ Reloads configuration file containing specified configuration key.
+
+ This function updates the configuration data from which the
+ specified configuration variable was read, and returns the (possibly)
+ new value of this variable.
+
+ 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.
+
+
+
+
+ remove_config(Callback, Config) -> ok
+ Removes configuration variables (together with
+ their aliases) that were loaded with specified callback module and
+ configuration string.
+
+ Callback = atom()
+ Config = string()
+ Reason = term()
+
+
+ Removes configuration variables (together wih their aliases)
+ that were loaded with specified callback module and configuration
+ string.
+
+
+
+
+ require(Required) -> ok | {error, Reason}
+ Checks if the required configuration is available.
+
+ Required = Key | {Key, SubKeys} | {Key, SubKey, SubKeys}
+ Key = atom()
+ SubKeys = SubKey | [SubKey]
+ SubKey = atom()
+
+
+ Checks if the required configuration is available. Arbitrarily
+ deep tuples can be specified as Required. Only the last
+ element of the tuple can be a list of SubKeys.
+
+ Example 1. Require the variable myvar:
+
+
+ ok = ct:require(myvar).
+
+ In this case the configuration file must at least contain:
+
+
+ {myvar,Value}.
+
+ Example 2. Require key myvar with subkeys
+ sub1 and sub2:
+
+
+ ok = ct:require({myvar,[sub1,sub2]}).
+
+ In this case the configuration file must at least contain:
+
+
+ {myvar,[{sub1,Value},{sub2,Value}]}.
+
+ Example 3. Require key myvar with subkey
+ sub1 with subsub1:
+
+
+ ok = ct:require({myvar,sub1,sub2}).
+
+ In this case the configuration file must at least contain:
+
+
+ {myvar,[{sub1,[{sub2,Value}]}]}.
+
+ See also
+ ct:get_config/1,
+ ct:get_config/2,
+ ct:get_config/3,
+ ct:require/2.
+
+
+
+
+ require(Name, Required) -> ok | {error, Reason}
+ Checks if the required configuration is available and gives
+ it a name.
+
+ Name = atom()
+ Required = Key | {Key, SubKey} | {Key, SubKey, SubKey}
+ SubKey = Key
+ Key = atom()
+
+
+ Checks if the required configuration is available and gives it a
+ name. The semantics for Required is the same as in
+ ct:require/1 except
+ that a list of SubKeys cannot be specified.
+
+ If the requested data is available, the subentry is associated
+ with Name so that the value of the element can be read with
+ ct:get_config/1,2
+ provided Name is used instead of the whole Required
+ term.
+
+ Example:
+
+ Require one node with a Telnet connection and an FTP connection.
+ Name the node a:
+
+
+ ok = ct:require(a,{machine,node}).
+
+ All references to this node can then use the node name. For
+ example, a file over FTP is fetched like follows:
+
+
+ ok = ct:ftp_get(a,RemoteFile,LocalFile).
+
+ For this to work, the configuration file must at least contain:
+
+
+ {machine,[{node,[{telnet,IpAddr},{ftp,IpAddr}]}]}.
+
+ The behavior of this function changed radically in
+ Common Test 1.6.2. To keep some backwards compatability,
+ it is still possible to do:
+ ct:require(a,{node,[telnet,ftp]}).
+ This associates the name a with the top-level node
+ entry. For this to work, the configuration file must at least
+ contain:
+ {node,[{telnet,IpAddr},{ftp,IpAddr}]}.
+
+
+ See also
+ ct:get_config/1,
+ ct:get_config/2,
+ ct:get_config/3,
+ ct:require/1.
+
+
+
+
+ run(TestDirs) -> Result
+ Runs all test cases in all suites in the specified
+ directories.
+
+ TestDirs = TestDir | [TestDir]
+
+
+ Runs all test cases in all suites in the specified directories.
+
+ See also ct:run/3.
+
+
+
+
+ run(TestDir, Suite) -> Result
+ Runs all test cases in the specified suite.
+
+ Runs all test cases in the specified suite.
+
+ See also ct:run/3.
+
+
+
+
+ run(TestDir, Suite, Cases) -> Result
+ Runs the specified test cases.
+
+ TestDir = string()
+ Suite = atom()
+ Cases = atom() | [atom()]
+ Result = [TestResult] | {error, Reason}
+
+
+ Runs the specified test cases.
+
+ Requires that
+ ct:install/1 has been
+ run first.
+
+ Suites (*_SUITE.erl) files must be stored in TestDir
+ or TestDir/test. All suites are compiled when the test is
+ run.
+
+
+
+
+ run_test(Opts) -> Result
+ Runs tests as specified by the combination of options in
+ Opts.
+
+ Opts = [OptTuples]
+ 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}
+ TestDirs = [string()] | string()
+ Suites = [string()] | [atom()] | string() | atom()
+ Cases = [atom()] | atom()
+ Groups = GroupNameOrPath | [GroupNameOrPath]
+ GroupNameOrPath = [atom()] | atom() | all
+ TestSpecs = [string()] | string()
+ Label = string() | atom()
+ CfgFiles = [string()] | string()
+ UserConfig = [{CallbackMod, CfgStrings}] | {CallbackMod, CfgStrings}
+ CallbackMod = atom()
+ CfgStrings = [string()] | string()
+ LogDir = string()
+ Conns = all | [atom()]
+ CSSFile = string()
+ CoverSpecFile = string()
+ StepOpts = [StepOpt] | []
+ StepOpt = config | keep_inactive
+ EventHandlers = EH | [EH]
+ EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}
+ InitArgs = [term()]
+ InclDirs = [string()] | string()
+ CreatePrivDir = auto_per_run | auto_per_tc | manual_per_tc
+ M = integer()
+ N = integer()
+ DurTime = string(HHMMSS)
+ StopTime = string(YYMoMoDDHHMMSS) | string(HHMMSS)
+ ForceStop = skip_rest | Bool
+ DecryptKeyOrFile = {key, DecryptKey} | {file, DecryptFile}
+ DecryptKey = string()
+ DecryptFile = string()
+ LogOpts = [LogOpt]
+ LogOpt = no_nl | no_src
+ VLevels = VLevel | [{Category, VLevel}]
+ VLevel = integer()
+ Category = atom()
+ CTHs = [CTHModule | {CTHModule, CTHInitArgs}]
+ CTHModule = atom()
+ CTHInitArgs = term()
+ Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | TestRunnerPid | {error, Reason}
+ Ok = integer()
+ Failed = integer()
+ UserSkipped = integer()
+ AutoSkipped = integer()
+ TestRunnerPid = pid()
+ Reason = term()
+
+
+ Runs tests as specified by the combination of options in
+ Opts. The options are the same as those used with program
+ ct_run, see Run Tests from
+ Command Line in the ct_run manual page.
+ Here a TestDir can be used to point out the path to a
+ Suite. Option testcase corresponds to option
+ -case in program ct_run. Configuration files
+ specified in Opts are installed automatically at startup.
+
+ TestRunnerPid is returned if release_shell == true.
+ For details, see
+ ct:break/1.
+
+ Reason indicates the type of error encountered.
+
+
+
+
+ run_testspec(TestSpec) -> Result
+ Runs a test specified by TestSpec.
+
+ TestSpec = [term()]
+ Result = {Ok, Failed, {UserSkipped, AutoSkipped}} | {error, Reason}
+ Ok = integer()
+ Failed = integer()
+ UserSkipped = integer()
+ AutoSkipped = integer()
+ Reason = term()
+
+
+ Runs a test specified by TestSpec. The same terms are used
+ as in test specification files.
+
+ Reason indicates the type of error encountered.
+
+
+
+
+ sleep(Time) -> ok
+ This function, similar to timer:sleep/1, suspends the
+ test case for a specified time.
+
+ Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity
+ Hours = integer()
+ Mins = integer()
+ Secs = integer()
+ Millisecs = integer() | float()
+
+
+ This function, similar to timer:sleep/1 in STDLIB,
+ suspends the test case for a specified time.
+ However, this function also multiplies Time with the
+ multiply_timetraps value (if set) and under certain
+ circumstances also scales up the time automatically if
+ scale_timetraps is set to true (default is
+ false).
+
+
+
+
+ start_interactive() -> ok
+ Starts Common Test in interactive mode.
+
+ Starts Common Test in interactive mode.
+
+ 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 ct_run -shell
+ [-config File...].
+
+ 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
+ ct:require/2.
+
+ Example:
+
+
+ > ct:require(unix_telnet, unix).
+ ok
+ > ct_telnet:open(unix_telnet).
+ {ok,<0.105.0>}
+ > ct_telnet:cmd(unix_telnet, "ls .").
+ {ok,["ls","file1 ...",...]}
+
+
+
+
+ step(TestDir, Suite, Case) -> Result
+ Steps through a test case with the debugger.
+
+ Case = atom()
+
+
+ Steps through a test case with the debugger.
+
+ See also ct:run/3.
+
+
+
+
+ step(TestDir, Suite, Case, Opts) -> Result
+ Steps through a test case with the debugger.
+
+ Case = atom()
+ Opts = [Opt] | []
+ Opt = config | keep_inactive
+
+
+ Steps through a test case with the debugger. If option
+ config has been specifed, breakpoints are also set on
+ the configuration functions in Suite.
+
+ See also ct:run/3.
+
+
+
+
+ stop_interactive() -> ok
+ Exits the interactive mode.
+
+ Exits the interactive mode.
+
+ See also
+ ct:start_interactive/0.
+
+
+
+
+
+ sync_notify(Name, Data) -> ok
+ Sends a synchronous notification of type Name with Data to
+ the Common Test event manager.
+
+ Name = atom()
+ Data = term()
+
+
+ Sends a synchronous notification of type Name with
+ Data to the Common Test event manager. This can later be
+ caught by any installed event manager.
+
+ See also
+ stdlib:gen_event(3).
+
+
+
+
+
+ testcases(TestDir, Suite) -> Testcases | {error, Reason}
+ Returns all test cases in the specified suite.
+
+ TestDir = string()
+ Suite = atom()
+ Testcases = list()
+ Reason = term()
+
+
+ Returns all test cases in the specified suite.
+
+
+
+
+ timetrap(Time) -> ok
+ Sets a new timetrap for the running test case.
+
+ Time = {hours, Hours} | {minutes, Mins} | {seconds, Secs} | Millisecs | infinity | Func
+ Hours = integer()
+ Mins = integer()
+ Secs = integer()
+ Millisecs = integer() | float()
+ Func = {M, F, A} | function()
+ M = atom()
+ F = atom()
+ A = list()
+
+
+ Sets a new timetrap for the running test case.
+
+ If the argument is Func, the timetrap is triggered when
+ this function returns. Func can also return a new
+ Time value, which in that case is the value for the new
+ timetrap.
+
+
+
+
+ userdata(TestDir, Suite) -> SuiteUserData | {error, Reason}
+ Returns any data specified with tag userdata in the list of
+ tuples returned from Suite:suite/0.
+
+ TestDir = string()
+ Suite = atom()
+ SuiteUserData = [term()]
+ Reason = term()
+
+
+ Returns any data specified with tag userdata in the list
+ of tuples returned from
+ suite/0.
+
+
+
+
+ userdata(TestDir, Suite, Case::GroupOrCase) -> TCUserData | {error, Reason}
+ Returns any data specified with tag userdata in the list of
+ tuples returned from Suite:group(GroupName) or Suite:Case().
+
+ TestDir = string()
+ Suite = atom()
+ GroupOrCase = {group, GroupName} | atom()
+ GroupName = atom()
+ TCUserData = [term()]
+ Reason = term()
+
+
+ Returns any data specified with tag userdata in the list
+ of tuples returned from Suite:group(GroupName) or
+ Suite:Case().
+
+
+
+
+
+
+
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct_cover
+
+
+
+
+
+
+ A
+ ct_cover.xml
+
+ ct_cover
+ Common Test framework code coverage support module.
+
+
+
+
+ Common Test framework code coverage support module.
+
+ This module exports help functions for performing code coverage
+ analysis.
+
+
+
+
+
+ add_nodes(Nodes) -> {ok, StartedNodes} | {error, Reason}
+ Adds nodes to current cover test (only works if cover support
+ is active).
+
+ Nodes = [atom()]
+ StartedNodes = [atom()]
+ Reason = cover_not_running | not_main_node
+
+
+ Adds nodes to current cover test. Notice that this only works if
+ cover support is active.
+
+ To have effect, this function is to be called from
+ init_per_suite/1 (see
+ common_test)
+ before any tests are performed.
+
+
+
+
+ cross_cover_analyse(Level, Tests) -> ok
+ Accumulates cover results over multiple tests.
+
+ Level = overview | details
+ Tests = [{Tag, Dir}]
+ Tag = atom()
+ Dir = string()
+
+
+ Accumulates cover results over multiple tests. See section
+ Cross Cover
+ Analysis in the Users's Guide.
+
+
+
+
+ remove_nodes(Nodes) -> ok | {error, Reason}
+ Removes nodes from the current cover test.
+
+ Nodes = [atom()]
+ Reason = cover_not_running | not_main_node
+
+
+ Removes nodes from the current cover test.
+
+ Call this function to stop cover test on nodes previously
+ added with
+ ct_cover:add_nodes/1.
+ Results on the remote node are transferred to the Common Test
+ node.
+
+
+
+
+
+
+
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct_ftp
+
+
+
+
+
+
+ A
+ ct_ftp.xml
+
+ ct_ftp
+ FTP client module (based on the FTP support of the Inets
+ application).
+
+
+
+ FTP client module (based on the FTP support of the Inets
+ application).
+
+
+
+
+ Data Types
+
+
+ connection() = handle() | target_name()
+ -
+
For target_name, see module
+ ct.
+
+ handle() = handle()
+ -
+
Handle for a specific FTP connection, see module
+ ct.
+
+
+
+
+
+ cd(Connection, Dir) -> ok | {error, Reason}
+ Changes directory on remote host.
+
+ Connection = connection()
+ Dir = string()
+
+
+ Changes directory on remote host.
+
+
+
+
+ close(Connection) -> ok | {error, Reason}
+ Closes the FTP connection.
+
+ Connection = connection()
+
+
+ Closes the FTP connection.
+
+
+
+
+ delete(Connection, File) -> ok | {error, Reason}
+ Deletes a file on remote host.
+
+ Connection = connection()
+ File = string()
+
+
+ Deletes a file on remote host.
+
+
+
+
+ get(KeyOrName, RemoteFile, LocalFile) -> ok | {error, Reason}
+ Opens an FTP connection and fetches a file from the remote
+ host.
+
+ KeyOrName = Key | Name
+ Key = atom()
+ Name = target_name()
+ RemoteFile = string()
+ LocalFile = string()
+
+
+ Opens an FTP connection and fetches a file from the remote
+ host.
+
+ RemoteFile and LocalFile must be absolute paths.
+
+ The configuration file must be as for
+ ct_ftp:put/3.
+
+ For target_name, see module
+ ct.
+
+ See also
+ ct:require/2.
+
+
+
+
+ ls(Connection, Dir) -> {ok, Listing} | {error, Reason}
+ Lists directory Dir.
+
+ Connection = connection()
+ Dir = string()
+ Listing = string()
+
+
+ Lists directory Dir.
+
+
+
+
+ open(KeyOrName) -> {ok, Handle} | {error, Reason}
+ Opens an FTP connection to the specified node.
+
+ KeyOrName = Key | Name
+ Key = atom()
+ Name = target_name()
+ Handle = handle()
+
+
+ Opens an FTP connection to the specified node.
+
+ You can open a connection for a particular Name and use the
+ same name as reference for all following subsequent operations.
+ If you want
+ the connection to be associated with Handle instead (if you,
+ for example, need to open multiple connections to a host), use
+ Key, the configuration variable name, to specify the target.
+ A connection without an associated target name can only be closed
+ with the handle value.
+
+ For information on how to create a new Name, see
+ ct:require/2.
+
+ For target_name, see module
+ ct.
+
+
+
+
+ put(KeyOrName, LocalFile, RemoteFile) -> ok | {error, Reason}
+ Opens an FTP connection and sends a file to the remote
+ host.
+
+ KeyOrName = Key | Name
+ Key = atom()
+ Name = target_name()
+ LocalFile = string()
+ RemoteFile = string()
+
+
+ Opens an FTP connection and sends a file to the remote host.
+
+ LocalFile and RemoteFile must be absolute paths.
+
+ For target_name, see module
+ ct.
+
+ If the target host is a "special" node, the FTP address must be
+ specified in the configuration file as follows:
+
+
+ {node,[{ftp,IpAddr}]}.
+
+ If the target host is something else, for example, a UNIX host,
+ the configuration file must also include the username and password
+ (both strings):
+
+
+ {unix,[{ftp,IpAddr},
+ {username,Username},
+ {password,Password}]}.
+
+ See also
+ ct:require/2.
+
+
+
+
+ recv(Connection, RemoteFile) -> ok | {error, Reason}
+ Fetches a file over FTP.
+
+ Fetches a file over FTP.
+
+ The file gets the same name on the local host.
+
+ See also ct_ftp:recv/3.
+
+
+
+
+ recv(Connection, RemoteFile, LocalFile) -> ok | {error, Reason}
+ Fetches a file over FTP.
+
+ Connection = connection()
+ RemoteFile = string()
+ LocalFile = string()
+
+
+ Fetches a file over FTP.
+
+ The file is named LocalFile on the local host.
+
+
+
+
+ send(Connection, LocalFile) -> ok | {error, Reason}
+ Sends a file over FTP.
+
+ Sends a file over FTP.
+
+ The file gets the same name on the remote host.
+
+ See also
+ ct_ftp:send/3.
+
+
+
+
+ send(Connection, LocalFile, RemoteFile) -> ok | {error, Reason}
+ Sends a file over FTP.
+
+ Connection = connection()
+ LocalFile = string()
+ RemoteFile = string()
+
+
+ Sends a file over FTP.
+
+ The file is named RemoteFile on the remote host.
+
+
+
+
+ type(Connection, Type) -> ok | {error, Reason}
+ Changes the file transfer type.
+
+ Connection = connection()
+ Type = ascii | binary
+
+
+ Changes the file transfer type.
+
+
+
+
+
+
+
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 @@
-
@@ -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 @@
ct_hooks.sgml
ct_hooks
- A callback interface on top of Common Test
+ A callback interface on top of Common Test.
- The Common Test Hook (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.
+ The Common Test Hook (CTH) framework allows extensions of the
+ default behavior of Common Test by callbacks before and after all
+ test suite calls. It is intended for advanced users of Common Test
+ who want to abstract out behavior that is common to multiple test suites.
+
- In brief, Common Test Hooks allows you to:
+ In brief, CTH allows you to:
-
- - Manipulate the runtime config before each suite
- configuration call
- - Manipulate the return of all suite configuration calls and in
- extension the result of the test themselves.
+
+ Manipulate the runtime configuration before each suite
+ configuration call.
+ Manipulate the return of all suite configuration calls and by
+ extension the result of the test themselves.
The following sections describe the mandatory and optional CTH
- functions Common Test will call during test execution. For more details
- see Common Test Hooks in
- the User's Guide.
+ functions that Common Test calls during test execution.
+ For more details, see section
+ Common Test Hooks in the
+ User's Guide.
- For information about how to add a CTH to your suite see
- Installing a CTH
- in the User's Guide.
+ For information about how to add a CTH to your suite, see section
+ Installing a CTH
+ in the User's Guide.
+
+ For a minimal example of a CTH, see section
+ Example CTH
+ in the User's Guide.
- See the
- Example CTH
- in the User's Guide for a minimal example of a CTH.
-
- CALLBACK FUNCTIONS
- The following functions define the callback interface
- for a Common Test Hook.
+ Callback Functions
+ The following functions define the callback interface for a CTH.
- Module:init(Id, Opts) -> {ok, State} |
- {ok, State, Priority}
- Initiates the Common Test Hook
+ Module:init(Id, Opts) -> {ok, State} | {ok, State, Priority}
+ Initiates the Common Test Hook.
- Id = reference() | term()
- Opts = term()
- State = term()
- Priority = integer()
+ Id = reference() | term()
+ Opts = term()
+ State = term()
+ Priority = integer()
-
- MANDATORY
-
- Always called before any other callback function.
- Use this to initiate any common state.
- It should return a state for this CTH.
-
- Id is the return value of
- id/1, or a reference
- (created using
- make_ref/0)
- if id/1 is not implemented.
-
-
- Priority 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.
-
- For details about when init is called see
- scope
- in the User's Guide.
-
+ MANDATORY
+
+ 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.
+
+ Id is either the return value of
+ ct_hooks:id/1,
+ or a reference (created using
+ erlang:make_ref/0
+ in ERTS) if
+ ct_hooks:id/1
+ is not implemented.
+
+ Priority is the relative priority of this hook. Hooks with a
+ lower priority are executed first. If no priority is specified, it
+ is set to 0.
+
+ For details about when init is called, see section
+ CTH Scope
+ in the User's Guide.
- Module:pre_init_per_suite(SuiteName, InitData, CTHState) ->
- Result
- Called before init_per_suite
+ Module:pre_init_per_suite(SuiteName, InitData, CTHState) -> Result
+ Called before init_per_suite.
- SuiteName = atom()
- InitData = Config | SkipOrFail
- Config = NewConfig = [{Key,Value}]
- CTHState = NewCTHState = term()
- Result = {Return, NewCTHState}
- Return = NewConfig | SkipOrFail
- SkipOrFail = {fail, Reason} | {skip, Reason}
- Key = atom()
- Value = term()
- Reason = term()
+ SuiteName = atom()
+ InitData = Config | SkipOrFail
+ Config = NewConfig = [{Key,Value}]
+ CTHState = NewCTHState = term()
+ Result = {Return, NewCTHState}
+ Return = NewConfig | SkipOrFail
+ SkipOrFail = {fail, Reason} | {skip, Reason}
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called before
-
- init_per_suite if it exists.
- It typically contains initialization/logging which needs to be done
- before init_per_suite is called.
- If {skip,Reason} or {fail,Reason} 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.
-
- SuiteName is the name of the suite to be run.
-
- InitData is the original config list of the test suite, or
- a SkipOrFail tuple if a previous CTH has returned this.
-
- CTHState is the current internal state of the CTH.
-
- Return is the result of the init_per_suite function.
- If it is {skip,Reason} or {fail,Reason}
- init_per_suite
- will never be called, instead the initiation is considered
- to be skipped/failed respectively. If a NewConfig list
- is returned,
- init_per_suite will be called with that NewConfig list.
- See
- Pre Hooks in the User's Guide for more details.
-
-
- Note that this function is only called if the CTH has been added
- before init_per_suite is run, see
- CTH Scoping
- in the User's Guide for details.
+ OPTIONAL
+
+ This function is called before
+ init_per_suite
+ if it exists. It typically contains initialization/logging that must
+ be done before init_per_suite is called. If
+ {skip,Reason} or {fail,Reason} is returned,
+ init_per_suite and all test cases of the suite are skipped
+ and Reason printed in the overview log of the suite.
+
+ SuiteName is the name of the suite to be run.
+
+ InitData is the original configuration list of the test
+ suite, or a SkipOrFail tuple if a previous CTH has returned
+ this.
+
+ CTHState is the current internal state of the CTH.
+
+ Return is the result of the init_per_suite function.
+ If it is {skip,Reason} or {fail,Reason},
+ init_per_suite
+ is never called, instead the initiation is considered to be
+ skipped or failed, respectively. If a NewConfig list is
+ returned,
+ init_per_suite
+ is called with that NewConfig list. For more details, see
+ section Pre Hooks
+ in the User's Guide.
+
+ This function is called only if the CTH is added before
+ init_per_suite is run. For details, see section
+ CTH Scope
+ in the User's Guide.
-
+
- Module:post_init_per_suite(SuiteName, Config, Return, CTHState) ->
- Result
- Called after init_per_suite
+ Module:post_init_per_suite(SuiteName, Config, Return, CTHState) -> Result
+ Called after init_per_suite.
- SuiteName = atom()
- Config = [{Key,Value}]
- Return = NewReturn = Config | SkipOrFail | term()
- SkipOrFail = {fail, Reason} | {skip, Reason} | term()
- CTHState = NewCTHState = term()
- Result = {NewReturn, NewCTHState}
- Key = atom()
- Value = term()
- Reason = term()
+ SuiteName = atom()
+ Config = [{Key,Value}]
+ Return = NewReturn = Config | SkipOrFail | term()
+ SkipOrFail = {fail, Reason} | {skip, Reason} | term()
+ CTHState = NewCTHState = term()
+ Result = {NewReturn, NewCTHState}
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called after
-
- init_per_suite if it exists. It typically contains extra
- checks to make sure that all the correct dependencies have
- been started correctly.
-
- Return is what
- init_per_suite
- returned, i.e. {fail,Reason}, {skip,Reason}, a Config
- list or a term describing how
- init_per_suite
- failed.
-
- NewReturn is the possibly modified return value of
- init_per_suite
- . It is here possible to recover from a failure in
- init_per_suite
- by returning the ConfigList with the tc_status
- element removed. See
- Post Hooks in the User's Guide for more details.
-
- CTHState is the current internal state of the CTH.
-
- Note that this function is only called if the CTH has been added
- before or in init_per_suite, see
- CTH Scoping
- in the User's Guide for details.
+ OPTIONAL
+
+ This function is called after
+ init_per_suite
+ if it exists. It typically contains extra checks to ensure that all
+ the correct dependencies are started correctly.
+
+ Return is what
+ init_per_suite
+ returned, that is, {fail,Reason}, {skip,Reason}, a
+ Config list, or a term describing how
+ init_per_suite
+ failed.
+
+ NewReturn is the possibly modified return value of
+ init_per_suite.
+ To recover from a failure in
+ init_per_suite,
+ return ConfigList with the tc_status element removed.
+ For more details, see
+ Post Hooks in
+ section "Manipulating Tests" in the User's Guide.
+
+ CTHState is the current internal state of the CTH.
+
+ This function is called only if the CTH is added before or in
+ init_per_suite. For details, see section
+ CTH Scope
+ in the User's Guide.
-
+
- Module:pre_init_per_group(GroupName, InitData, CTHState) ->
- Result
- Called before init_per_group
+ Module:pre_init_per_group(GroupName, InitData, CTHState) -> Result
+ Called before init_per_group.
- GroupName = atom()
- InitData = Config | SkipOrFail
- Config = NewConfig = [{Key,Value}]
- CTHState = NewCTHState = term()
- Result = {NewConfig | SkipOrFail, NewCTHState}
- SkipOrFail = {fail,Reason} | {skip, Reason}
- Key = atom()
- Value = term()
- Reason = term()
+ GroupName = atom()
+ InitData = Config | SkipOrFail
+ Config = NewConfig = [{Key,Value}]
+ CTHState = NewCTHState = term()
+ Result = {NewConfig | SkipOrFail, NewCTHState}
+ SkipOrFail = {fail,Reason} | {skip, Reason}
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called before
-
- init_per_group if it exists. It behaves the same way as
-
- pre_init_per_suite, but for the
-
- init_per_group instead.
+ OPTIONAL
+
+ This function is called before
+ init_per_group
+ if it exists. It behaves the same way as
+ pre_init_per_suite,
+ but for function
+ init_per_group
+ instead.
-
+
- Module:post_init_per_group(GroupName, Config, Return, CTHState) ->
- Result
- Called after init_per_group
+ Module:post_init_per_group(GroupName, Config, Return, CTHState) -> Result
+ Called after init_per_group.
- GroupName = atom()
- Config = [{Key,Value}]
- Return = NewReturn = Config | SkipOrFail | term()
- SkipOrFail = {fail,Reason} | {skip, Reason}
- CTHState = NewCTHState = term()
- Result = {NewReturn, NewCTHState}
- Key = atom()
- Value = term()
- Reason = term()
+ GroupName = atom()
+ Config = [{Key,Value}]
+ Return = NewReturn = Config | SkipOrFail | term()
+ SkipOrFail = {fail,Reason} | {skip, Reason}
+ CTHState = NewCTHState = term()
+ Result = {NewReturn, NewCTHState}
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called after
-
- init_per_group if it exists. It behaves the same way as
-
- post_init_per_suite, but for the
-
- init_per_group instead.
+ OPTIONAL
+
+ This function is called after
+ init_per_group
+ if it exists. It behaves the same way as
+ post_init_per_suite,
+ but for function
+ init_per_group
+ instead.
- Module:pre_init_per_testcase(TestcaseName, InitData, CTHState) ->
- Result
- Called before init_per_testcase
+ Module:pre_init_per_testcase(TestcaseName, InitData, CTHState) -> Result
+ Called before init_per_testcase.
- TestcaseName = atom()
- InitData = Config | SkipOrFail
- Config = NewConfig = [{Key,Value}]
- CTHState = NewCTHState = term()
- Result = {NewConfig | SkipOrFail, NewCTHState}
- SkipOrFail = {fail,Reason} | {skip, Reason}
- Key = atom()
- Value = term()
- Reason = term()
+ TestcaseName = atom()
+ InitData = Config | SkipOrFail
+ Config = NewConfig = [{Key,Value}]
+ CTHState = NewCTHState = term()
+ Result = {NewConfig | SkipOrFail, NewCTHState}
+ SkipOrFail = {fail,Reason} | {skip, Reason}
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called before
-
- init_per_testcase if it exists. It behaves the same way as
-
- pre_init_per_suite, but for the
-
- init_per_testcase function instead.
-
- 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.
+ OPTIONAL
+
+ This function is called before
+ init_per_testcase
+ if it exists. It behaves the same way as
+ pre_init_per_suite,
+ but for function
+ init_per_testcase
+ instead.
+
+ CTHs cannot be added here right now. That feature may be added in
+ a later release, but it would right now break backwards
+ compatibility.
- Module:post_end_per_testcase(TestcaseName, Config, Return, CTHState)
- -> Result
- Called after end_per_testcase
+ Module:post_end_per_testcase(TestcaseName, Config, Return, CTHState) -> Result
+ Called after end_per_testcase.
- TestcaseName = atom()
- Config = [{Key,Value}]
- Return = NewReturn = Config | SkipOrFail | term()
- SkipOrFail = {fail,Reason} | {skip, Reason}
- CTHState = NewCTHState = term()
- Result = {NewReturn, NewCTHState}
- Key = atom()
- Value = term()
- Reason = term()
+ TestcaseName = atom()
+ Config = [{Key,Value}]
+ Return = NewReturn = Config | SkipOrFail | term()
+ SkipOrFail = {fail,Reason} | {skip, Reason}
+ CTHState = NewCTHState = term()
+ Result = {NewReturn, NewCTHState}
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called after
-
- end_per_testcase if it exists. It behaves the same way as
-
- post_init_per_suite, but for the
-
- end_per_testcase function instead.
+ OPTIONAL
+
+ This function is called after
+ end_per_testcase
+ if it exists. It behaves the same way as
+ post_init_per_suite,
+ but for function
+ end_per_testcase
+ instead.
- Module:pre_end_per_group(GroupName, EndData, CTHState) ->
- Result
- Called before end_per_group
+ Module:pre_end_per_group(GroupName, EndData, CTHState) -> Result
+ Called before end_per_group.
- GroupName = atom()
- EndData = Config | SkipOrFail
- Config = NewConfig = [{Key,Value}]
- CTHState = NewCTHState = term()
- Result = {NewConfig | SkipOrFail, NewCTHState}
- SkipOrFail = {fail,Reason} | {skip, Reason}
- Key = atom()
- Value = term()
- Reason = term()
+ GroupName = atom()
+ EndData = Config | SkipOrFail
+ Config = NewConfig = [{Key,Value}]
+ CTHState = NewCTHState = term()
+ Result = {NewConfig | SkipOrFail, NewCTHState}
+ SkipOrFail = {fail,Reason} | {skip, Reason}
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called before
-
- end_per_group if it exists. It behaves the same way as
-
- pre_init_per_suite, but for the
-
- end_per_group function instead.
+ OPTIONAL
+
+ This function is called before
+ end_per_group
+ if it exists. It behaves the same way as
+ pre_init_per_suite,
+ but for function
+ end_per_group
+ instead.
- Module:post_end_per_group(GroupName, Config, Return, CTHState) ->
- Result
- Called after end_per_group
+ Module:post_end_per_group(GroupName, Config, Return, CTHState) -> Result
+ Called after end_per_group.
- GroupName = atom()
- Config = [{Key,Value}]
- Return = NewReturn = Config | SkipOrFail | term()
- SkipOrFail = {fail,Reason} | {skip, Reason}
- CTHState = NewCTHState = term()
- Result = {NewReturn, NewCTHState}
- Key = atom()
- Value = term()
- Reason = term()
+ GroupName = atom()
+ Config = [{Key,Value}]
+ Return = NewReturn = Config | SkipOrFail | term()
+ SkipOrFail = {fail,Reason} | {skip, Reason}
+ CTHState = NewCTHState = term()
+ Result = {NewReturn, NewCTHState}
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called after
-
- end_per_group if it exists. It behaves the same way as
-
- post_init_per_suite, but for the
-
- end_per_group function instead.
+ OPTIONAL
+
+ This function is called after
+ end_per_group
+ if it exists. It behaves the same way as
+ post_init_per_suite,
+ but for function
+ end_per_group
+ instead.
- Module:pre_end_per_suite(SuiteName, EndData, CTHState) ->
- Result
- Called before end_per_suite
+ Module:pre_end_per_suite(SuiteName, EndData, CTHState) -> Result
+ Called before end_per_suite.
- SuiteName = atom()
- EndData = Config | SkipOrFail
- Config = NewConfig = [{Key,Value}]
- CTHState = NewCTHState = term()
- Result = {NewConfig | SkipOrFail, NewCTHState}
- SkipOrFail = {fail,Reason} | {skip, Reason}
- Key = atom()
- Value = term()
- Reason = term()
+ SuiteName = atom()
+ EndData = Config | SkipOrFail
+ Config = NewConfig = [{Key,Value}]
+ CTHState = NewCTHState = term()
+ Result = {NewConfig | SkipOrFail, NewCTHState}
+ SkipOrFail = {fail,Reason} | {skip, Reason}
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called before
-
- end_per_suite if it exists. It behaves the same way as
-
- pre_init_per_suite, but for the
-
- end_per_suite function instead.
+ OPTIONAL
+
+ This function is called before
+ end_per_suite
+ if it exists. It behaves the same way as
+ pre_init_per_suite,
+ but for function
+ end_per_suite
+ instead.
- Module:post_end_per_suite(SuiteName, Config, Return, CTHState) ->
- Result
- Called after end_per_suite
+ Module:post_end_per_suite(SuiteName, Config, Return, CTHState) -> Result
+ Called after end_per_suite.
- SuiteName = atom()
- Config = [{Key,Value}]
- Return = NewReturn = Config | SkipOrFail | term()
- SkipOrFail = {fail,Reason} | {skip, Reason}
- CTHState = NewCTHState = term()
- Result = {NewReturn, NewCTHState}
- Key = atom()
- Value = term()
- Reason = term()
+ SuiteName = atom()
+ Config = [{Key,Value}]
+ Return = NewReturn = Config | SkipOrFail | term()
+ SkipOrFail = {fail,Reason} | {skip, Reason}
+ CTHState = NewCTHState = term()
+ Result = {NewReturn, NewCTHState}
+ Key = atom()
+ Value = term()
+ Reason = term()
-
- OPTIONAL
-
- This function is called after
-
- end_per_suite if it exists. It behaves the same way as
-
- post_init_per_suite, but for the
-
- end_per_suite function instead.
+ OPTIONAL
+
+ This function is called after
+ end_per_suite
+ if it exists. It behaves the same way as
+ post_init_per_suite,
+ but for function
+ end_per_suite
+ instead.
- Module:on_tc_fail(TestName, Reason, CTHState) ->
- NewCTHState
- Called after the CTH scope ends
+ Module:on_tc_fail(TestName, Reason, CTHState) -> NewCTHState
+ Called after the CTH scope ends.
- TestName = init_per_suite | end_per_suite |
- {init_per_group,GroupName} | {end_per_group,GroupName} |
- {FuncName,GroupName} | FuncName
- FuncName = atom()
- GroupName = atom()
- Reason = term()
- CTHState = NewCTHState = term()
+ TestName = init_per_suite | end_per_suite | {init_per_group,GroupName} | {end_per_group,GroupName} | {FuncName,GroupName} | FuncName
+ FuncName = atom()
+ GroupName = atom()
+ Reason = term()
+ CTHState = NewCTHState = term()
-
- OPTIONAL
-
- 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
-
- post_init_per_suite, and if a test case fails, it is called
- after
- post_end_per_testcase. If the failed test case belongs
- to a test case group, the first argument is a tuple
- {FuncName,GroupName}, otherwise simply the function name.
-
- The data which comes with the Reason follows the same format as the
- FailReason
- in the tc_done event.
- See Event Handling
- in the User's Guide for details.
+ OPTIONAL
+
+ 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:
+
+
+ If init_per_suite fails, this function is called after
+ post_init_per_suite.
+ If a test case fails, this funcion is called after
+ post_end_per_testcase.
+
+
+ If the failed test case belongs to a test case group, the first
+ argument is a tuple {FuncName,GroupName}, otherwise only
+ the function name.
+
+ The data that comes with Reason follows the same format as
+ FailReason
+ in event
+ tc_done.
+ For details, see section
+ Event Handling
+ in the User's Guide.
- Module:on_tc_skip(TestName, Reason, CTHState) ->
- NewCTHState
- Called after the CTH scope ends
+ Module:on_tc_skip(TestName, Reason, CTHState) -> NewCTHState
+ Called after the CTH scope ends.
- TestName = init_per_suite | end_per_suite |
- {init_per_group,GroupName} | {end_per_group,GroupName} |
- {FuncName,GroupName} | FuncName
- FuncName = atom()
- GroupName = atom()
- Reason = {tc_auto_skip | tc_user_skip, term()}
- CTHState = NewCTHState = term()
+ TestName = init_per_suite | end_per_suite | {init_per_group,GroupName} | {end_per_group,GroupName} | {FuncName,GroupName} | FuncName
+ FuncName = atom()
+ GroupName = atom()
+ Reason = {tc_auto_skip | tc_user_skip, term()}
+ CTHState = NewCTHState = term()
-
- OPTIONAL
-
- 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
-
- post_init_per_group, and if a test case is skipped,
- it is called after
-
- post_end_per_testcase. If the skipped test case belongs to a
- test case group, the first argument is a tuple {FuncName,GroupName},
- otherwise simply the function name.
-
- The data which comes with the Reason follows the same format as
- tc_auto_skip
- and
- tc_user_skip events.
- See Event Handling
- in the User's Guide for details.
+ OPTIONAL
+
+ 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:
+
+
+ If init_per_group is skipped, this function is
+ called after
+ post_init_per_group.
+ If a test case is skipped, this function is called after
+ post_end_per_testcase.
+
+
+ If the skipped test case belongs to a test case group, the first
+ argument is a tuple {FuncName,GroupName}, otherwise only
+ the function name.
+
+ The data that comes with Reason follows the same format as
+ events
+ tc_auto_skip
+ and
+ tc_user_skip
+ For details, see section
+ Event Handling
+ in the User's Guide.
Module:terminate(CTHState)
- Called after the CTH scope ends
+ Called after the CTH scope ends.
- CTHState = term()
+ CTHState = term()
-
- OPTIONAL
+ OPTIONAL
- This function is called at the end of a CTH's
- scope.
-
+ This function is called at the end of a CTH
+ scope.
Module:id(Opts) -> Id
- Called before the init function of a CTH
+ Called before the init function of a CTH.
- Opts = term()
- Id = term()
+ Opts = term()
+ Id = term()
-
- OPTIONAL
-
- The Id is used to uniquely identify a CTH instance,
- if two CTH's return the same Id the second CTH is ignored
- and subsequent calls to the CTH will only be made to the first
- instance. For more information see
- Installing a CTH
- in the User's Guide.
-
-
- This function should NOT have any side effects as it might
- be called multiple times by Common Test.
+ OPTIONAL
- If not implemented the CTH will act as if this function returned a
- call to make_ref/0.
-
+ The Id identifies a CTH instance uniquely. If two CTHs return
+ the same Id, the second CTH is ignored and subsequent calls to
+ the CTH are only made to the first instance. For details, see section
+ Installing a CTH
+ in the User's Guide.
+
+ This function is not to have any side effects, as it can
+ be called multiple times by Common Test.
+
+ If not implemented, the CTH acts as if this function returned a call
+ to make_ref/0.
+
-
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct_master
+
+
+
+
+
+
+ A
+ ct_master.xml
+
+ ct_master
+ Distributed test execution control for Common Test.
+
+
+
+ Distributed test execution control for Common Test.
+
+ This module exports functions for running Common Test nodes on
+ multiple hosts in parallel.
+
+
+
+
+
+ abort() -> ok
+ Stops all running tests.
+
+ Stops all running tests.
+
+
+
+
+ abort(Nodes) -> ok
+ Stops tests on specified nodes.
+
+ Nodes = atom() | [atom()]
+
+
+ Stops tests on specified nodes.
+
+
+
+
+ basic_html(Bool) -> ok
+ If set to true, the ct_master logs are written on a primitive
+ HTML format, not using the Common Test CSS style sheet.
+
+ Bool = true | false
+
+
+ If set to true, the ct_master logs are written on a
+ primitive HTML format, not using the Common Test CSS style
+ sheet.
+
+
+
+
+ get_event_mgr_ref() -> MasterEvMgrRef
+ Gets a reference to the Common Test master event
+ manager.
+
+ MasterEvMgrRef = atom()
+
+
+ Gets a reference to the Common Test master event manager.
+ The reference can be used to, for example, add a user-specific
+ event handler while tests are running.
+
+ Example:
+
+
+ gen_event:add_handler(ct_master:get_event_mgr_ref(), my_ev_h, [])
+
+
+
+
+ progress() -> [{Node, Status}]
+ Returns test progress.
+
+ Node = atom()
+ Status = finished_ok | ongoing | aborted | {error, Reason}
+ Reason = term()
+
+
+ Returns test progress. If Status is ongoing, tests
+ are running on the node and are not yet finished.
+
+
+
+
+ run(TestSpecs) -> ok
+ Equivalent to run(TestSpecs, false, [], []).
+
+ TestSpecs = string() | [SeparateOrMerged]
+
+
+ Equivalent to ct_master:run(TestSpecs,
+ false, [], []).
+
+
+
+
+ run(TestSpecs, InclNodes, ExclNodes) -> ok
+ Equivalent to run(TestSpecs, false, InclNodes, ExclNodes).
+
+
+ TestSpecs = string() | [SeparateOrMerged]
+ SeparateOrMerged = string() | [string()]
+ InclNodes = [atom()]
+ ExclNodes = [atom()]
+
+
+ Equivalent to ct_master:run(TestSpecs,
+ false, InclNodes, ExclNodes).
+
+
+
+
+ run(TestSpecs, AllowUserTerms, InclNodes, ExclNodes) -> ok
+ Tests are spawned on the nodes as specified in TestSpecs.
+
+
+ TestSpecs = string() | [SeparateOrMerged]
+ SeparateOrMerged = string() | [string()]
+ AllowUserTerms = bool()
+ InclNodes = [atom()]
+ ExclNodes = [atom()]
+
+
+ Tests are spawned on the nodes as specified in TestSpecs.
+ Each specification in TestSpec 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 InclNodes. Nodes in the ExclNodes list
+ are excluded from the test.
+
+
+
+
+ run_on_node(TestSpecs, Node) -> ok
+ Equivalent to run_on_node(TestSpecs, false, Node).
+
+ TestSpecs = string() | [SeparateOrMerged]
+ SeparateOrMerged = string() | [string()]
+ Node = atom()
+
+
+ Equivalent to
+ ct_master:run_on_node(TestSpecs,
+ false, Node).
+
+
+
+
+ run_on_node(TestSpecs, AllowUserTerms, Node) -> ok
+ Tests are spawned on Node according to TestSpecs.
+
+ TestSpecs = string() | [SeparateOrMerged]
+ SeparateOrMerged = string() | [string()]
+ AllowUserTerms = bool()
+ Node = atom()
+
+
+ Tests are spawned on Node according to TestSpecs.
+
+
+
+
+ run_test(Node, Opts) -> ok
+ Tests are spawned on Node using ct:run_test/1.
+
+ Node = atom()
+ Opts = [OptTuples]
+ 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}
+ CfgFiles = string() | [string()]
+ TestDirs = string() | [string()]
+ Suites = atom() | [atom()]
+ Cases = atom() | [atom()]
+ TestSpecs = string() | [string()]
+ LogDir = string()
+ EventHandlers = EH | [EH]
+ EH = atom() | {atom(), InitArgs} | {[atom()], InitArgs}
+ InitArgs = [term()]
+ Conns = all | [atom()]
+
+
+ Tests are spawned on Node using
+ ct:run_test/1
+
+
+
+
+
+
+
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct_netconfc
+
+
+
+
+
+
+ A
+ ct_netconfc.xml
+
+ ct_netconfc
+ NETCONF client module.
+
+
+
+ NETCONF client module.
+
+ The NETCONF client is compliant with RFC 4741 NETCONF Configuration
+ Protocol and RFC 4742 Using the NETCONF Configuration Protocol over
+ Secure SHell (SSH)..
+
+ For each server to test against, the following entry can be added to a
+ configuration file:
+
+
+ {server_id(),options()}.
+
+ The server_id() or an associated target_name() (see
+ module ct) must then be used
+ in calls to
+ ct_netconfc:open/2.
+
+ If no configuration exists for a server, a session can still be
+ opened by calling
+ ct_netconfc:open/2 with
+ all necessary options specified in the call. The first argument to
+ ct_netconfc:open/2 can
+ then be any atom.
+
+
+
+
+
+ Logging
+ The NETCONF server uses error_logger for logging of NETCONF
+ traffic. A special purpose error handler is implemented in
+ ct_conn_log_h. To use this error handler, add the
+ cth_conn_log hook in the test suite, for example:
+
+
+ suite() ->
+ [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].
+
+ conn_mod() is the name of the Common Test module
+ implementing the connection protocol, for example, ct_netconfc.
+
+ Hook option log_type specifies the type of logging:
+
+
+ raw
+ 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.
.
+
+ pretty
+ 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.
+
+ html (default)
+ The sent and received NETCONF traffic is pretty printed
+ directly in the test case HTML log.
+
+ silent
+ NETCONF traffic is not logged.
+
+
+ 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 hosts 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
+ ct_netconfc:open/2.
+
+ Option hosts has no effect if log_type is set to
+ html or silent.
+
+ The hook options can also be specified in a configuration file with
+ configuration variable ct_conn_log:
+
+
+ {ct_conn_log,[{conn_mod(),hook_options()}]}.
+
+ For example:
+
+
+ {ct_conn_log,[{ct_netconfc,[{log_type,pretty},
+ {hosts,[key_or_name()]}]}]}
+
+
+ Hook options specified in a configuration file overwrite the
+ hard-coded hook options in the test suite.
+
+
+ Logging Example 1:
+
+
+ The following ct_hooks statement causes pretty printing of
+ NETCONF traffic to separate logs for the connections named
+ nc_server1 and nc_server2. Any other connections are
+ logged to default NETCONF log.
+
+
+ suite() ->
+ [{ct_hooks, [{cth_conn_log, [{ct_netconfc,[{log_type,pretty}},
+ {hosts,[nc_server1,nc_server2]}]}
+ ]}]}].
+
+ Connections must be opened as follows:
+
+
+ open(nc_server1,[...]),
+ open(nc_server2,[...]).
+
+ Logging Example 2:
+
+
+ The following configuration file causes raw logging of all NETCONF
+ traffic in to one single text file:
+
+
+ {ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.
+
+ The ct_hooks statement must look as follows:
+
+
+ suite() ->
+ [{ct_hooks, [{cth_conn_log, []}]}].
+
+ The same ct_hooks statement without the configuration file
+ would cause HTML logging of all NETCONF connections in to the test
+ case HTML log.
+
+
+
+
+ Notifications
+
+ 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.
+
+ Specific functions to support this are
+ ct_netconfc:create_subscription/6
+ and
+ ct_netconfc:get_event_streams/3.
+ (The functions also exist with other arities.)
+
+
+
+ Data Types
+
+
+ client() = handle() | key_or_name()
+ -
+
For handle(), see module
+ ct.
+
+ error_reason() = term()
+ -
+ event_time() = {eventTime, xml_attributes(), [xs_datetime()]}
+ -
+
+ handle() = term()
+ -
+
Opaque reference for a connection (NETCONF session). For more
+ information, see module ct.
+
+
+ host() = hostname() | ip_address()
+ -
+
For hostname() and ip_address(), see module
+ kernel:inet
+
+ key_or_name() = server_id() | target_name()
+ -
+
For target_name, see module
+ ct.
+
+ netconf_db() = running | startup | candidate
+ -
+
+ notification() = {notification, xml_attributes(), notification_content()}
+ -
+
+ notification_content() = [event_time() | simple_xml()]
+ -
+
+ option() = {ssh, host()} | {port, port_number()} | {user, string()} | {password, string()} | {user_dir, string()} | {timeout, timeout()}
+ -
+
For port_number(), see module
+ kernel:inet
+
+ options() = [option()]
+ -
+
Options used for setting up an SSH connection to a NETCONF
+ server.
+
+ server_id() = atom()
+ -
+
The identity of a server, specified in a configuration
+ file.
+
+ simple_xml() = {xml_tag(), xml_attributes(), xml_content()} | {xml_tag(), xml_content()} | xml_tag()
+ -
+
This type is further described in application
+ xmerl.
+
+ stream_data() = {description, string()} | {replaySupport, string()} | {replayLogCreationTime, string()} | {replayLogAgedTime, string()}
+ -
+
For details about the data format for the string values, see
+ "XML Schema for Event Notifications" in RFC 5277.
+
+ stream_name() = string()
+ -
+
+ streams() = [{stream_name(), [stream_data()]}]
+ -
+
+ xml_attribute_tag() = atom()
+ -
+
+ xml_attribute_value() = string()
+ -
+
+ xml_attributes() = [{xml_attribute_tag(), xml_attribute_value()}]
+ -
+
+ xml_content() = [simple_xml() | iolist()]
+ -
+
+ xml_tag() = atom()
+ -
+
+ xpath() = {xpath, string()}
+ -
+
+ xs_datetime() = string()
+ -
+
This date and time identifier has the same format as the XML type
+ dateTime and is compliant with RFC 3339 Date and Time on
+ the Internet Timestamps. The format is as follows:
+
+ [-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]
+
+
+
+
+
+
+ action(Client, Action) -> Result
+ Equivalent to action(Client, Action, infinity).
+
+ Equivalent to
+ ct_netconfc:action(Client, Action,
+ infinity).
+
+
+
+
+ action(Client, Action, Timeout) -> Result
+ Executes an action.
+
+ Client = client()
+ Action = simple_xml()
+ Timeout = timeout()
+ Result = ok | {ok, [simple_xml()]} | {error, error_reason()}
+
+
+ Executes an action. If the return type is void, ok is
+ returned instead of {ok,[simple_xml()]}.
+
+
+
+
+ close_session(Client) -> Result
+ Equivalent to close_session(Client, infinity).
+
+ Equivalent to
+ ct_netconfc:close_session(Client,
+ infinity).
+
+
+
+
+ close_session(Client, Timeout) -> Result
+ Requests graceful termination of the session associated with
+ the client.
+
+ Client = client()
+ Timeout = timeout()
+ Result = ok | {error, error_reason()}
+
+
+ Requests graceful termination of the session associated with the
+ client.
+
+ When a NETCONF server receives a close-session 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
+ close-session request are ignored.
+
+
+
+
+ copy_config(Client, Source, Target) -> Result
+ Equivalent to copy_config(Client, Source, Target,
+ infinity).
+
+ Equivalent to
+ ct_netconfc:copy_config(Client,
+ Source, Target, infinity).
+
+
+
+
+ copy_config(Client, Target, Source, Timeout) -> Result
+ Copies configuration data.
+
+ Client = client()
+ Target = netconf_db()
+ Source = netconf_db()
+ Timeout = timeout()
+ Result = ok | {error, error_reason()}
+
+
+ Copies configuration data.
+
+ Which source and target options that can be issued depends on the
+ capabilities supported by the server. That is, :candidate
+ and/or :startup are required.
+
+
+
+
+ create_subscription(Client) -> term()
+ Creates a subscription for event notifications.
+
+
+
+
+ create_subscription(Client, Timeout) -> term()
+ Creates a subscription for event notifications.
+
+
+
+
+ create_subscription(Client, Stream, Timeout) -> term()
+ Creates a subscription for event notifications.
+
+
+
+
+ create_subscription(Client, StartTime, StopTime, Timeout) -> term()
+ Creates a subscription for event notifications.
+
+
+
+
+ create_subscription(Client, Stream, StartTime, StopTime, Timeout) -> term()
+ Creates a subscription for event notifications.
+
+
+
+
+ create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout) -> Result
+ Creates a subscription for event notifications.
+
+ Client = client()
+ Stream = stream_name()
+ Filter = simple_xml() | [simple_xml()]
+ StartTime = xs_datetime()
+ StopTime = xs_datetime()
+ Timeout = timeout()
+ Result = ok | {error, error_reason()}
+
+
+ Creates a subscription for event notifications.
+
+ 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 notification().
+
+
+ Stream
+ Optional parameter that indicates which stream of event
+ is of interest. If not present, events in the default NETCONF
+ stream are sent.
+ Filter
+ 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.
+ StartTime
+ Optional parameter used to trigger the replay feature and
+ indicate that the replay is to start at the time specified.
+ If StartTime is not present, this is not a replay
+ subscription.
+ It is not valid to specify start times that are later than
+ the current time. If StartTime is specified earlier
+ than the log can support, the replay begins with the earliest
+ available notification.
+ This parameter is of type dateTime and compliant to
+ RFC 3339. Implementations must support time zones.
+ StopTime
+ Optional parameter used with the optional replay feature
+ to indicate the newest notifications of interest. If
+ StopTime is not present, the notifications continues
+ until the subscription is terminated.
+ Must be used with and be later than StartTime. Values
+ of StopTime in the future are valid. This parameter is
+ of type dateTime and compliant to RFC 3339.
+ Implementations must support time zones.
+
+
+ For more details about the event notification mechanism, see
+ RFC 5277.
+
+
+
+
+ delete_config(Client, Target) -> Result
+ Equivalent to delete_config(Client, Target,
+ infinity).
+
+ Equivalent to
+ ct_netconfc:delete_config(Client, Target, infinity).
+
+
+
+
+ delete_config(Client, Target, Timeout) -> Result
+ Deletes configuration data.
+
+ Client = client()
+ Target = startup | candidate
+ Timeout = timeout()
+ Result = ok | {error, error_reason()}
+
+
+ Deletes configuration data.
+
+ The running configuration cannot be deleted and :candidate
+ or :startup must be advertised by the server.
+
+
+
+
+ edit_config(Client, Target, Config) -> Result
+ Equivalent to edit_config(Client, Target, Config, [],
+ infinity).
+
+ Equivalent to
+ ct_netconfc:edit_config(Client,
+ Target, Config, [], infinity).
+
+
+
+
+ edit_config(Client, Target, Config, OptParamsOrTimeout) -> Result
+ If OptParamsOrTimeout is a time-out value, this function is
+ equivalent to ct_netconfc:edit_config(Client, Target, Config, [],
+ Timeout).
+
+ Client = client()
+ Target = netconf_db()
+ Config = simple_xml()
+ OptParamsOrTimeout = [simple_xml()] | timeout()
+ Result = ok | {error, error_reason()}
+
+
+ If OptParamsOrTimeout is a time-out value, this function is
+ equivalent to
+ ct_netconfc:edit_config(Client,
+ Target, Config, [], Timeout).
+
+ If OptParamsOrTimeout is a list of simple XML, this
+ function is equivalent to
+ ct_netconfc:edit_config(Client,
+ Target, Config, OptParams, infinity).
+
+
+
+
+ edit_config(Client, Target, Config, OptParams, Timeout) -> Result
+ Edits configuration data.
+
+ Client = client()
+ Target = netconf_db()
+ Config = simple_xml()
+ OptParams = [simple_xml()]
+ Timeout = timeout()
+ Result = ok | {error, error_reason()}
+
+
+ Edits configuration data.
+
+ By default only the running target is available, unless the server
+ includes :candidate or :startup in its list of
+ capabilities.
+
+ OptParams can be used for specifying optional parameters
+ (default-operation, test-option, or
+ error-option) to be added to the edit-config
+ request. The value must be a list containing valid simple XML,
+ for example:
+
+
+ [{'default-operation', ["none"]},
+ {'error-option', ["rollback-on-error"]}]
+
+
+
+
+ get(Client, Filter) -> Result
+ Equivalent to get(Client, Filter, infinity).
+
+ Equivalent to
+ ct_netconfc:get(Client, Filter,
+ infinity).
+
+
+
+
+ get(Client, Filter, Timeout) -> Result
+ Gets data.
+
+ Client = client()
+ Filter = simple_xml() | xpath()
+ Timeout = timeout()
+ Result = {ok, [simple_xml()]} | {error, error_reason()}
+
+
+ Gets data.
+
+ This operation returns both configuration and state data from the
+ server.
+
+ Filter type xpath can be used only if the server supports
+ :xpath.
+
+
+
+
+ get_capabilities(Client) -> Result
+ Equivalent to get_capabilities(Client, infinity).
+
+ Equivalent to
+ ct_netconfc:get_capabilities(Client,
+ infinity).
+
+
+
+
+ get_capabilities(Client, Timeout) -> Result
+ Returns the server side capabilities.
+
+ Client = client()
+ Timeout = timeout()
+ Result = [string()] | {error, error_reason()}
+
+
+ Returns the server side capabilities.
+
+ The following capability identifiers, defined in RFC 4741 NETCONF
+ Configuration Protocol, can be returned:
+
+
+ "urn:ietf:params:netconf:base:1.0"
+ "urn:ietf:params:netconf:capability:writable-running:1.0"
+ "urn:ietf:params:netconf:capability:candidate:1.0"
+ "urn:ietf:params:netconf:capability:confirmed-commit:1.0"
+ "urn:ietf:params:netconf:capability:rollback-on-error:1.0"
+ "urn:ietf:params:netconf:capability:startup:1.0"
+ "urn:ietf:params:netconf:capability:url:1.0"
+ "urn:ietf:params:netconf:capability:xpath:1.0"
+
+
+ More identifiers can exist, for example, server-side namespace.
+
+
+
+
+ get_config(Client, Source, Filter) -> Result
+ Equivalent to get_config(Client, Source, Filter,
+ infinity).
+
+ Equivalent to
+ ct_netconfc:get_config(Client, Source, Filter, infinity).
+
+
+
+
+ get_config(Client, Source, Filter, Timeout) -> Result
+ Gets configuration data.
+
+ Client = client()
+ Source = netconf_db()
+ Filter = simple_xml() | xpath()
+ Timeout = timeout()
+ Result = {ok, [simple_xml()]} | {error, error_reason()}
+
+
+ Gets configuration data.
+
+ To be able to access another source than running, the
+ server must advertise :candidate and/or :startup.
+
+ Filter type xpath can be used only if the server supports
+ :xpath.
+
+
+
+
+ get_event_streams(Client, Timeout) -> Result
+ Equivalent to get_event_streams(Client, [], Timeout).
+
+ Equivalent to
+ ct_netconfc:get_event_streams(Client,
+ [], Timeout).
+
+
+
+
+ get_event_streams(Client, Streams, Timeout) -> Result
+ Sends a request to get the specified event streams.
+
+ Client = client()
+ Streams = [stream_name()]
+ Timeout = timeout()
+ Result = {ok, streams()} | {error, error_reason()}
+
+
+ Sends a request to get the specified event streams.
+
+ Streams is a list of stream names. The following filter is
+ sent to the NETCONF server in a get request:
+
+
+ <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
+ <streams>
+ <stream>
+ <name>StreamName1</name>
+ </stream>
+ <stream>
+ <name>StreamName2</name>
+ </stream>
+ ...
+ </streams>
+ </netconf>
+
+ If Streams is an empty list, all streams are
+ requested by sending the following filter:
+
+
+ <netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
+ <streams/>
+ </netconf>
+
+ If more complex filtering is needed, use
+ ct_netconfc:get/2 or
+ ct_netconfc:get/3 and
+ specify the exact filter according to "XML Schema for Event
+ Notifications" in RFC 5277.
+
+
+
+
+ get_session_id(Client) -> Result
+ Equivalent to get_session_id(Client, infinity).
+
+ Equivalent to
+ ct_netconfc:get_session_id(Client,
+ infinity).
+
+
+
+
+ get_session_id(Client, Timeout) -> Result
+ Returns the session Id associated with the specified
+ client.
+
+ Client = client()
+ Timeout = timeout()
+ Result = pos_integer() | {error, error_reason()}
+
+
+ Returns the session Id associated with the specified client.
+
+
+
+
+ hello(Client) -> Result
+ Equivalent to hello(Client, [], infinity).
+
+ Equivalent to
+ ct_netconfc:hello(Client, [],
+ infinity).
+
+
+
+
+ hello(Client, Timeout) -> Result
+ Equivalent to hello(Client, [], Timeout).
+
+ Equivalent to
+ ct_netconfc:hello(Client, [],
+ Timeout).
+
+
+
+
+ hello(Client, Options, Timeout) -> Result
+ Exchanges hello messages with the server.
+
+ Client = handle()
+ Options = [{capability, [string()]}]
+ Timeout = timeout()
+ Result = ok | {error, error_reason()}
+
+
+ Exchanges hello messages with the server.
+
+ Adds optional capabilities and sends a hello message to the
+ server and waits for the return.
+
+
+
+
+ kill_session(Client, SessionId) -> Result
+ Equivalent to kill_session(Client, SessionId,
+ infinity).
+
+ Equivalent to
+ ct_netconfc:kill_session(Client,
+SessionId, infinity).
+
+
+
+
+ kill_session(Client, SessionId, Timeout) -> Result
+ Forces termination of the session associated with the supplied
+ session Id.
+
+ Client = client()
+ SessionId = pos_integer()
+ Timeout = timeout()
+ Result = ok | {error, error_reason()}
+
+
+ Forces termination of the session associated with the supplied
+ session Id.
+
+ The server side must abort any ongoing operations, release any
+ locks and resources associated with the session, and close any
+ associated connections.
+
+ 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.
+
+ If the specified SessionId is equal to the current session
+ Id, an error is returned.
+
+
+
+
+ lock(Client, Target) -> Result
+ Equivalent to lock(Client, Target, infinity).
+
+ Equivalent to
+ ct_netconfc:lock(Client, Target,
+ infinity).
+
+
+
+
+ lock(Client, Target, Timeout) -> Result
+ Unlocks the configuration target.
+
+ Client = client()
+ Target = netconf_db()
+ Timeout = timeout()
+ Result = ok | {error, error_reason()}
+
+
+ Unlocks the configuration target.
+
+ Which target parameters that can be used depends on if
+ :candidate and/or :startup 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.
+
+ Operation
+ ct_netconfc:kill_session/2
+ or
+ ct_netconfc:kill_session/3
+ 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.
+
+
+
+
+ only_open(Options) -> Result
+ Opens a NETCONF session, but does not send hello.
+
+ Options = options()
+ Result = {ok, handle()} | {error, error_reason()}
+
+
+ Opens a NETCONF session, but does not send hello.
+
+ As ct_netconfc:open/1,
+ but does not send a hello message.
+
+
+
+
+ only_open(KeyOrName, ExtraOptions) -> Result
+ Opens a name NETCONF session, but does not send
+ hello.
+
+ KeyOrName = key_or_name()
+ ExtraOptions = options()
+ Result = {ok, handle()} | {error, error_reason()}
+
+
+ Opens a name NETCONF session, but does not send hello.
+
+ As ct_netconfc:open/2,
+ but does not send a hello message.
+
+
+
+
+ open(Options) -> Result
+ Opens a NETCONF session and exchanges hello messages.
+
+ Options = options()
+ Result = {ok, handle()} | {error, error_reason()}
+
+
+ Opens a NETCONF session and exchanges hello messages.
+
+ If the server options are specified in a configuration file,
+ or if a named client is needed for logging purposes (see section
+ Logging in this module), use
+ ct_netconfc:open/2
+ instead.
+
+ The opaque handler() reference returned from this
+ function is required as client identifier when calling any other
+ function in this module.
+
+ Option timeout (milliseconds) is used when setting up the
+ SSH connection and when waiting for the hello message from
+ the server. It is not used for any other purposes during the
+ lifetime of the connection.
+
+
+
+
+ open(KeyOrName, ExtraOptions) -> Result
+ Opens a named NETCONF session and exchanges hello
+ messages.
+
+ KeyOrName = key_or_name()
+ ExtraOptions = options()
+ Result = {ok, handle()} | {error, error_reason()}
+
+
+ Opens a named NETCONF session and exchanges hello
+ messages.
+
+ If KeyOrName is a configured server_id() or a
+ target_name() associated with such an Id, then the options
+ for this server are fetched from the configuration file.
+
+ Argument ExtraOptions is added to the options found in the
+ configuration file. If the same options are specified, the values
+ from the configuration file overwrite ExtraOptions.
+
+ If the server is not specified in a configuration file, use
+ ct_netconfc:open/1
+ instead.
+
+ The opaque handle() reference returned from this
+ function can be used as client identifier when calling any other
+ function in this module. However, if KeyOrName is a
+ target_name(), that is, if the server is named through a
+ call to ct:require/2
+ or a require statement in the test suite, then this name can
+ be used instead of handle().
+
+ Option timeout (milliseconds) is used when setting up the
+ SSH connection and when waiting for the hello message from
+ the server. It is not used for any other purposes during the
+ lifetime of the connection.
+
+ See also
+ ct:require/2.
+
+
+
+
+ send(Client, SimpleXml) -> Result
+ Equivalent to send(Client, SimpleXml, infinity).
+
+ Equivalent to
+ ct_netconfc:send(Client, SimpleXml,
+ infinity).
+
+
+
+
+ send(Client, SimpleXml, Timeout) -> Result
+ Sends an XML document to the server.
+
+ Client = client()
+ SimpleXml = simple_xml()
+ Timeout = timeout()
+ Result = simple_xml() | {error, error_reason()}
+
+
+ Sends an XML document to the server.
+
+ 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.
+
+
+
+
+ send_rpc(Client, SimpleXml) -> Result
+ Equivalent to send_rpc(Client, SimpleXml, infinity).
+
+ Equivalent to
+ ct_netconfc:send_rpc(Client,
+ SimpleXml, infinity).
+
+
+
+
+ send_rpc(Client, SimpleXml, Timeout) -> Result
+ Sends a NETCONF rpc request to the server.
+
+ Client = client()
+ SimpleXml = simple_xml()
+ Timeout = timeout()
+ Result = [simple_xml()] | {error, error_reason()}
+
+
+ Sends a NETCONF rpc request to the server.
+
+ The specified XML document is wrapped in a valid NETCONF rpc
+ request and sent to the server. The message-id and namespace
+ attributes are added to element rpc.
+
+ This function can be used for sending rpc requests that
+ cannot be expressed by other interface functions in this module.
+
+
+
+
+ unlock(Client, Target) -> Result
+ Equivalent to unlock(Client, Target, infinity).
+
+ Equivalent to
+ ct_netconfc:unlock(Client, Target,
+ infinity).
+
+
+
+
+ unlock(Client, Target, Timeout) -> Result
+ Unlocks the configuration target.
+
+ Client = client()
+ Target = netconf_db()
+ Timeout = timeout()
+ Result = ok | {error, error_reason()}
+
+
+ Unlocks the configuration target.
+
+ If the client earlier has acquired a lock through
+ ct_netconfc:lock/2 or
+ ct_netconfc:lock/3, this
+ operation releases the associated lock. To access another target
+ than running, the server must support :candidate
+ and/or :startup.
+
+
+
+
+
+
+
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct_property_test
+
+
+
+
+
+
+ A
+ ct_property_test.xml
+
+ ct_property_test
+ EXPERIMENTAL support in Common Test for calling
+ property-based tests.
+
+
+
+ EXPERIMENTAL support in Common Test for calling property-based
+ tests.
+
+ This module is a first step to run property-based tests in the
+ Common Test framework. A property testing tool like QuickCheck
+ or PropEr is assumed to be installed.
+
+ The idea is to have a Common Test 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 test directory of the application. The
+ test directory has a subdirectory property_test, where
+ everything needed for the property tests is collected.
+
+ A typical Common Test test suite using ct_property_test
+ is organized as follows:
+
+
+ -include_lib("common_test/include/ct.hrl").
+
+ all() -> [prop_ftp_case].
+
+ init_per_suite(Config) ->
+ ct_property_test:init_per_suite(Config).
+
+ %%%---- test case
+ prop_ftp_case(Config) ->
+ ct_property_test:quickcheck(
+ ftp_simple_client_server:prop_ftp(Config),
+ Config
+ ).
+
+
+ This is experimental code that can be changed or removed anytime
+ without any warning.
+
+
+
+
+
+
+ init_per_suite(Config) -> Config | {skip, Reason}
+ Initializes Config for property testing.
+
+ Initializes Config for property testing.
+
+ This function investigates if support is available for either
+ Quickcheck, PropEr, or Triq. The options
+ {property_dir,AbsPath} and {property_test_tool,Tool}
+ are set in the Config returned.
+
+ The function is intended to be called in function
+ init_per_suite in the test suite.
+
+ The property tests are assumed to be in subdirectory
+ property_test.
+
+
+
+
+ quickcheck(Property, Config) -> true | {fail, Reason}
+ Calls quickcheck and returns the result in a form suitable for
+ Common Test.
+
+ Calls quickcheck and returns the result in a form suitable for
+ Common Test.
+
+ This function is intended to be called in the test cases in the
+ test suite.
+
+
+
+
+
+
+
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct_rpc
+
+
+
+
+
+
+ A
+ ct_rpc.xml
+
+ ct_rpc
+ Common Test specific layer on Erlang/OTP rpc.
+
+
+
+ Common Test specific layer on Erlang/OTP rpc.
+
+
+
+
+
+ app_node(App, Candidates) -> NodeName
+ From a set of candidate nodes determines which of them is
+ running the application App.
+
+ App = atom()
+ Candidates = [NodeName]
+ NodeName = atom()
+
+
+ From a set of candidate nodes determines which of them is running
+ the application App. If none of the candidate nodes is
+ running App, the function makes the test case calling
+ this function to fail. This function is the same as calling
+ app_node(App, Candidates, true).
+
+
+
+
+ app_node(App, Candidates, FailOnBadRPC) -> NodeName
+ 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.
+
+ App = atom()
+ Candidates = [NodeName]
+ NodeName = atom()
+ FailOnBadRPC = true | false
+
+
+ Same as
+ ct_rpc: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.
+
+
+
+
+ app_node(App, Candidates, FailOnBadRPC, Cookie) -> NodeName
+ 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.
+
+ App = atom()
+ Candidates = [NodeName]
+ NodeName = atom()
+ FailOnBadRPC = true | false
+ Cookie = atom()
+
+
+ Same as
+ ct_rpc: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.
+
+ The cookie on the client node is set to Cookie for this
+ rpc operation (used to match the server node cookie).
+
+
+
+
+ call(Node, Module, Function, Args) -> term() | {badrpc, Reason}
+ Same as call(Node, Module, Function, Args, infinity).
+
+ Same as call(Node, Module, Function, Args, infinity).
+
+
+
+
+ call(Node, Module, Function, Args, TimeOut) -> term() | {badrpc, Reason}
+ Evaluates apply(Module, Function, Args) on the node
+ Node.
+
+ Node = NodeName | {Fun, FunArgs}
+ Fun = function()
+ FunArgs = term()
+ NodeName = atom()
+ Module = atom()
+ Function = atom()
+ Args = [term()]
+ Reason = timeout | term()
+
+
+ Evaluates apply(Module, Function, Args) on the node
+ Node. Returns either whatever Function returns, or
+ {badrpc, Reason} if the remote procedure call fails. If
+ Node is {Fun, FunArgs}, applying Fun to
+ FunArgs is to return a node name.
+
+
+
+
+ call(Node, Module, Function, Args, TimeOut, Cookie) -> term() | {badrpc, Reason}
+ Evaluates apply(Module, Function, Args) on the node
+ Node.
+
+ Node = NodeName | {Fun, FunArgs}
+ Fun = function()
+ FunArgs = term()
+ NodeName = atom()
+ Module = atom()
+ Function = atom()
+ Args = [term()]
+ Reason = timeout | term()
+ Cookie = atom()
+
+
+ Evaluates apply(Module, Function, Args) on the node
+ Node. Returns either whatever Function returns, or
+ {badrpc, Reason} if the remote procedure call fails. If
+ Node is {Fun, FunArgs}, applying Fun to
+ FunArgs is to return a node name.
+
+ The cookie on the client node is set to Cookie for this
+ rpc operation (used to match the server node cookie).
+
+
+
+
+ cast(Node, Module, Function, Args) -> ok
+ Evaluates apply(Module, Function, Args) on the node
+ Node.
+
+ Node = NodeName | {Fun, FunArgs}
+ Fun = function()
+ FunArgs = term()
+ NodeName = atom()
+ Module = atom()
+ Function = atom()
+ Args = [term()]
+ Reason = timeout | term()
+
+
+ Evaluates apply(Module, Function, Args) on the node
+ Node. No response is delivered and the process that makes
+ the call is not suspended until the evaluation is completed as in
+ the case of call/3,4. If Node is
+ {Fun, FunArgs}, applying Fun to FunArgs is to
+ return a node name.
+
+
+
+
+ cast(Node, Module, Function, Args, Cookie) -> ok
+ Evaluates apply(Module, Function, Args) on the node
+ Node.
+
+ Node = NodeName | {Fun, FunArgs}
+ Fun = function()
+ FunArgs = term()
+ NodeName = atom()
+ Module = atom()
+ Function = atom()
+ Args = [term()]
+ Reason = timeout | term()
+ Cookie = atom()
+
+
+ Evaluates apply(Module, Function, Args) on the node
+ Node. No response is delivered and the process that makes
+ the call is not suspended until the evaluation is completed as in
+ the case of call/3,4. If Node is
+ {Fun, FunArgs}, applying Fun to FunArgs is to
+ return a node name.
+
+ The cookie on the client node is set to Cookie for this
+ rpc operation (used to match the server node cookie).
+
+
+
+
+
+
+
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 @@
ct_run.xml
ct_run
- Program used for starting Common Test from the
- OS command line.
-
+ Program used for starting Common Test from the
+ OS command line.
The ct_run 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 ct_run
- 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.
-
- There is an interface function that corresponds to this program,
- called ct:run_test/1, for starting Common Test from the Erlang
- shell (or an Erlang program). Please see the ct man page for
- details.
+ and the Common Test application (for more information, see
+ section Installation
+ in the User's Guide). The program accepts different start flags.
+ Some flags trigger ct_run to start Common Test and
+ pass on data to it. Some flags start an Erlang node prepared for
+ running Common Test in a particular mode.
+
+ The interface function
+ ct:run_test/1,
+ corresponding to the ct_run program, is used for starting
+ Common Test from the Erlang shell (or an Erlang program).
+ For details, see the ct
+ manual page.
ct_run also accepts Erlang emulator flags. These are used
- when ct_run calls erl 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).
-
- With the optional flag:
- -erl_args
- it's possible to divide the options on the ct_run command line into
- two groups, one that Common Test should process (those preceding -erl_args),
- and one it should completely ignore and pass on directly to the emulator
- (those following -erl_args). Options preceding -erl_args that Common Test
- doesn't recognize, also get passed on to the emulator untouched.
- By means of -erl_args the user may specify flags with the same name, but
+ when ct_run calls erl 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).
+
+ With the optional flag -erl_args, options on the ct_run
+ command line can be divided into two groups:
+
+
+ - One group that Common Test is to process (those
+ preceding -erl_args).
+ - One group that Common Test is to ignore and pass on
+ directly to the emulator (those following -erl_args).
+
+
+ Options preceding -erl_args that Common Test
+ does not recognize are also passed on to the emulator untouched.
+ By -erl_args the user can specify flags with the same name, but
with different destinations, on the ct_run command line.
- If -pa or -pz flags are specified in the Common Test group of options
- (preceding -erl_args), 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 -pa and -pz flags
- following -erl_args on the command line. These directories are added
- to the code path normally (i.e. on specified form)
-
- Exit status is set before the program ends. Value 0 indicates a successful
- test result, 1 indicates one or more failed or auto-skipped test cases, and
- 2 indicates test execution failure.
-
- If ct_run is called with option:
- -help
- it prints all valid start flags to stdout.
-
+ If flags -pa or -pz are specified in the
+ Common Test group of options (preceding -erl_args),
+ relative directories are converted to absolute and reinserted into
+ the code path by Common Test. This is to avoid problems
+ loading user modules when Common Test changes working directory
+ during test runs. However, Common Test ignores flags -pa
+ and -pz following -erl_args on the command line. These
+ directories are added to the code path normally (that is, on specified
+ form).
+
+ Exit status is set before the program ends. Value 0 indicates
+ a successful test result, 1 indicates one or more failed or
+ auto-skipped test cases, and 2 indicates test execution failure.
+
+ If ct_run is called with option -help, it prints all
+ valid start flags to stdout.
+
- Run tests from command line
+ Run Tests from Command Line
- 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]
-
+ 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]
+
- Run tests using test specification
+ Run Tests using Test Specification
- 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]
-
+ 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]
+
- Run tests in web based GUI
+ Run Tests in Web-Based GUI
- 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]
+ 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]
+
- Refresh the HTML index files
+ Refresh HTML Index Files
- ct_run -refresh_logs [-logdir LogDir] [-basic_html]
+ ct_run -refresh_logs [-logdir LogDir] [-basic_html]
+
- Run CT in interactive mode
+ Run Common Test in Interactive Mode
- ct_run -shell
- [-config ConfigFile1 ConfigFile2 ... ConfigFileN]
- [-userconfig CallbackModule1 ConfigString1 and CallbackModule2
- ConfigString2 and .. and CallbackModuleN ConfigStringN]
- [-decrypt_key Key] | [-decrypt_file KeyFile]
+ ct_run -shell
+ [-config ConfigFile1 ConfigFile2 ... ConfigFileN]
+ [-userconfig CallbackModule1 ConfigString1 and CallbackModule2
+ ConfigString2 and .. and CallbackModuleN ConfigStringN]
+ [-decrypt_key Key] | [-decrypt_file KeyFile]
+
- Start a Common Test Master node
+ Start a Common Test Master Node
- ct_run -ctmaster
+ ct_run -ctmaster
- See also
- Please read the Running Test Suites
- chapter in the Common Test User's Guide for information about the meaning of the
- different start flags.
+ See Also
+ For information about the start flags, see section
+ Running Tests and Analyzing
+ Results in the User's Guide.
+
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct_slave
+
+
+
+
+
+
+ A
+ ct_slave.xml
+
+ ct_slave
+ Common Test framework functions for starting and stopping
+ nodes for Large-Scale Testing.
+
+
+
+ Common Test framework functions for starting and stopping nodes
+ for Large-Scale Testing.
+
+ This module exports functions used by the Common Test
+ Master to start and stop "slave" nodes. It is the default callback
+ module for the {init, node_start} term in the Test
+ Specification.
+
+
+
+
+
+ start(Node) -> Result
+ Starts an Erlang node with name Node on the local
+ host.
+
+ Node = atom()
+ Result = {ok, NodeName} | {error, Reason, NodeName}
+ Reason = already_started | started_not_connected | boot_timeout | init_timeout | startup_timeout | not_alive
+ NodeName = atom()
+
+
+ Starts an Erlang node with name Node on the local host.
+
+ See also
+ ct_slave:start/3.
+
+
+
+
+ start(HostOrNode, NodeOrOpts) -> Result
+ Starts an Erlang node with default options on a specified
+ host, or on the local host with specified options.
+
+ HostOrNode = atom()
+ NodeOrOpts = atom() | list()
+ Result = {ok, NodeName} | {error, Reason, NodeName}
+ Reason = already_started | started_not_connected | boot_timeout | init_timeout | startup_timeout | not_alive
+ NodeName = atom()
+
+
+ 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 start(Host, Node) when the second argument is
+ atom-valued and start(Node, Opts) when it is list-valued.
+
+ See also
+ ct_slave:start/3.
+
+
+
+
+ start(Host, Node, Opts) -> Result
+ Starts an Erlang node with name Node on host Host as
+ specified by the combination of options in Opts.
+
+ Node = atom()
+ Host = atom()
+ Opts = [OptTuples]
+ 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}]}
+ Username = string()
+ Password = string()
+ BootTimeout = integer()
+ InitTimeout = integer()
+ StartupTimeout = integer()
+ StartupFunctions = [StartupFunctionSpec]
+ StartupFunctionSpec = {Module, Function, Arguments}
+ Module = atom()
+ Function = atom()
+ Arguments = [term]
+ Monitor = bool()
+ KillIfFail = bool()
+ ErlangFlags = string()
+ EnvVar = string()
+ Value = string()
+ Result = {ok, NodeName} | {error, Reason, NodeName}
+ Reason = already_started | started_not_connected | boot_timeout | init_timeout | startup_timeout | not_alive
+ NodeName = atom()
+
+
+ Starts an Erlang node with name Node on host Host as
+ specified by the combination of options in Opts.
+
+ Options Username and Password are used to log on to the
+ remote host Host. Username, if omitted, defaults to
+ the current username. Password is empty by default.
+
+ A list of functions specified in option Startup are
+ executed after startup of the node. Notice that all used modules
+ are to be present in the code path on Host.
+
+ The time-outs are applied as follows:
+
+
+ BootTimeout
+ The time to start the Erlang node, in seconds. Defaults to
+ 3 seconds. If the node is not pingable within this time, the result
+ {error, boot_timeout, NodeName} is returned.
+ InitTimeout
+ 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
+ {error, init_timeout, NodeName} is returned.
+ StartupTimeout
+ The time to wait until the node stops to run
+ StartupFunctions. Defaults to 1 second. If this time-out
+ occurs, the result {error, startup_timeout, NodeName} is
+ returned.
+
+
+ Options:
+
+
+ monitor_master
+ Specifies if the slave node is to be stopped if the
+ master node stops. Defaults to false.
+ kill_if_fail
+ Specifies if the slave node is to be killed if a time-out
+ occurs during initialization or startup. Defaults to true.
+ Notice that the node can also be still alive it the boot time-out
+ occurred, but it is not killed in this case.
+ erlang_flags
+ Specifies which flags are added to the parameters of the
+ executable erl.
+ env
+ Specifies a list of environment variables that will extend
+ the environment.
+
+
+ Special return values:
+
+
+ {error, already_started, NodeName} if the node
+ with the specified name is already started on a specified
+ host.
+ {error, started_not_connected, NodeName} if the
+ node is started, but not connected to the master node.
+ {error, not_alive, NodeName} if the node on which
+ ct_slave:start/3 is
+ called, is not alive. Notice that NodeName is the name of
+ the current node in this case.
+
+
+
+
+
+ stop(Node) -> Result
+ Stops the running Erlang node with name Node on the local
+ host.
+
+ Node = atom()
+ Result = {ok, NodeName} | {error, Reason, NodeName}
+ Reason = not_started | not_connected | stop_timeout
+
+
+ Stops the running Erlang node with name Node on the local
+ host.
+
+
+
+
+ stop(Host, Node) -> Result
+ Stops the running Erlang node with name Node on host
+ Host.
+
+ Host = atom()
+ Node = atom()
+ Result = {ok, NodeName} | {error, Reason, NodeName}
+ Reason = not_started | not_connected | stop_timeout
+ NodeName = atom()
+
+
+ Stops the running Erlang node with name Node on host
+ Host.
+
+
+
+
+
+
+
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct_snmp
+
+
+
+
+
+
+ A
+ ct_snmp.xml
+
+ ct_snmp
+ Common Test user interface module for the SNMP application.
+
+
+
+ Common Test user interface module for the SNMP
+ application.
+
+ 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
+ ct_snmp by Common Test 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, Common Test 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.
+
+ Configurable SNMP Manager and Agent Parameters:
+
+ Manager configuration:
+
+
+ [{start_manager, boolean()}
+ Optional. Default is true.
+ {users, [{user_name(), [call_back_module(), user_data()]}]}
+ Optional.
+ {usm_users, [{usm_user_name(), [usm_config()]}]}
+ Optional. SNMPv3 only.
+ {managed_agents,[{agent_name(), [user_name(), agent_ip(), agent_port(), [agent_config()]]}]}
+ managed_agents is optional.
+ {max_msg_size, integer()}
+ Optional. Default is 484.
+ {mgr_port, integer()}
+ Optional. Default is 5000.
+ {engine _id, string()}
+ Optional. Default is "mgrEngine".
+
+
+ Agent configuration:
+
+
+ {start_agent, boolean()}
+ Optional. Default is false.
+ {agent_sysname, string()}
+ Optional. Default is "ct_test".
+ {agent_manager_ip, manager_ip()}
+ Optional. Default is localhost.
+ {agent_vsns, list()}
+ Optional. Default is [v2].
+ {agent_trap_udp, integer()}
+ Optional. Default is 5000.
+ {agent_udp, integer()}
+ Optional. Default is 4000.
+ {agent_notify_type, atom()}
+ Optional. Default is trap.
+ {agent_sec_type, sec_type()}
+ Optional. Default is none.
+ {agent_passwd, string()}
+ Optional. Default is "".
+ {agent_engine_id, string()}
+ Optional. Default is "agentEngine".
+ {agent_max_msg_size, string()}
+ Optional. Default is 484.
+
+
+ The following parameters represents the SNMP configuration files
+ context.conf, standard.conf, community.conf,
+ vacm.conf, usm.conf, notify.conf,
+ target_addr.conf, and target_params.conf. Notice that
+ all values in agent.conf can be modified by the parameters
+ listed above. All these configuration files have default values set by
+ the SNMP 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 file:consult/1 to the file.
+
+
+ {agent_contexts, [term()] | {data_dir_file, rel_path()}}
+ Optional.
+ {agent_community, [term()] | {data_dir_file, rel_path()}}
+ Optional.
+ {agent_sysinfo, [term()] | {data_dir_file, rel_path()}}
+ Optional.
+ {agent_vacm, [term()] | {data_dir_file, rel_path()}}
+ Optional.
+ {agent_usm, [term()] | {data_dir_file, rel_path()}}
+ Optional.
+ {agent_notify_def, [term()] | {data_dir_file, rel_path()}}
+ Optional.
+ {agent_target_address_def, [term()] | {data_dir_file, rel_path()}}
+ Optional.
+ {agent_target_param_def, [term()] | {data_dir_file, rel_path()}}
+ Optional.
+
+
+ Parameter MgrAgentConfName in the functions is to be a name
+ you allocate in your test suite using a require statement.
+ Example (where MgrAgentConfName = snmp_mgr_agent):
+
+
+ suite() -> [{require, snmp_mgr_agent, snmp}].
+
+ or
+
+
+ ct:require(snmp_mgr_agent, snmp).
+
+ Notice that USM users are needed for SNMPv3 configuration and are
+ not to be confused with users.
+
+ SNMP traps, inform, and report messages are handled by the user
+ callback module. For details, see the
+ SNMP application.
+
+ It is recommended to use the .hrl files created by the
+ Erlang/OTP MIB compiler to define the Object Identifiers (OIDs).
+ For example, to get the Erlang node name from erlNodeTable
+ in the OTP-MIB:
+
+
+ Oid = ?erlNodeEntry ++ [?erlNodeName, 1]
+
+ Furthermore, values can be set for SNMP application configuration
+ parameters, config, server, net_if, and so on (for
+ a list of valid parameters and types, see the User's Guide for
+ the SNMP application). This is
+ done by defining a configuration data variable on the following form:
+
+
+ {snmp_app, [{manager, [snmp_app_manager_params()]},
+ {agent, [snmp_app_agent_params()]}]}.
+
+ A name for the data must be allocated in the suite using
+ require (see the example above). Pass this name as argument
+ SnmpAppConfName to
+ ct_snmp:start/3.
+ ct_snmp specifies default values for some SNMP application
+ configuration parameters (such as {verbosity,trace} for parameter
+ config). This set of defaults is merged with the parameters
+ specified by the user. The user values override ct_snmp
+ defaults.
+
+
+
+
+ Data Types
+
+
+ agent_config() = {Item, Value}
+ -
+ agent_ip() = ip()
+ -
+ agent_name() = atom()
+ -
+ agent_port() = integer()
+ -
+ call_back_module() = atom()
+ -
+ error_index() = integer()
+ -
+ error_status() = noError | atom()
+ -
+ ip() = string() | {integer(), integer(), integer(), integer()}
+ -
+ manager_ip() = ip()
+ -
+ oid() = [byte()]
+ -
+ oids() = [oid()]
+ -
+ rel_path() = string()
+ -
+ sec_type() = none | minimum | semi
+ -
+ snmp_app_agent_params() = term()
+ -
+ snmp_app_manager_params() = term()
+ -
+ snmpreply() = {error_status(), error_index(), varbinds()}
+ -
+ user_data() = term()
+ -
+ user_name() = atom()
+ -
+ usm_config() = {Item, Value}
+ -
+ usm_user_name() = string()
+ -
+ value_type() = o('OBJECT IDENTIFIER') | i('INTEGER') | u('Unsigned32') | g('Unsigned32') | s('OCTET STRING')
+ -
+ var_and_val() = {oid(), value_type(), value()}
+ -
+ varbind() = term()
+ -
+ varbinds() = [varbind()]
+ -
+ varsandvals() = [var_and_val()]
+ -
+
+ These data types are described in the documentation for
+ the SNMP application.
+
+
+
+
+ get_next_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
+ Issues a synchronous SNMP get next request.
+
+ Agent = agent_name()
+ Oids = oids()
+ MgrAgentConfName = atom()
+ SnmpReply = snmpreply()
+
+
+ Issues a synchronous SNMP get next request.
+
+
+
+
+ get_values(Agent, Oids, MgrAgentConfName) -> SnmpReply
+ Issues a synchronous SNMP get request.
+
+ Agent = agent_name()
+ Oids = oids()
+ MgrAgentConfName = atom()
+ SnmpReply = snmpreply()
+
+
+ Issues a synchronous SNMP get request.
+
+
+
+
+ load_mibs(Mibs) -> ok | {error, Reason}
+ Loads the MIBs into agent snmp_master_agent.
+
+ Mibs = [MibName]
+ MibName = string()
+ Reason = term()
+
+
+ Loads the MIBs into agent snmp_master_agent.
+
+
+
+
+ register_agents(MgrAgentConfName, ManagedAgents) -> ok | {error, Reason}
+ Explicitly instructs the manager to handle this
+ agent.
+
+ MgrAgentConfName = atom()
+ ManagedAgents = [agent()]
+ Reason = term()
+
+
+ Explicitly instructs the manager to handle this agent. Corresponds
+ to making an entry in agents.conf.
+
+ 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.
+
+
+
+
+ register_users(MgrAgentConfName, Users) -> ok | {error, Reason}
+ Registers the manager entity (=user) responsible for specific
+ agent(s).
+
+ MgrAgentConfName = atom()
+ Users = [user()]
+ Reason = term()
+
+
+ Registers the manager entity (=user) responsible for specific
+ agent(s). Corresponds to making an entry in users.conf.
+
+ 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.
+
+
+
+
+ register_usm_users(MgrAgentConfName, UsmUsers) -> ok | {error, Reason}
+ Explicitly instructs the manager to handle this USM user.
+
+ MgrAgentConfName = atom()
+ UsmUsers = [usm_user()]
+ Reason = term()
+
+
+ Explicitly instructs the manager to handle this USM user.
+ Corresponds to making an entry in usm.conf.
+
+ 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.
+
+
+
+
+ set_info(Config) -> [{Agent, OldVarsAndVals, NewVarsAndVals}]
+ Returns a list of all successful set requests performed in the
+ test case in reverse order.
+
+ Config = [{Key, Value}]
+ Agent = agent_name()
+ OldVarsAndVals = varsandvals()
+ NewVarsAndVals = varsandvals()
+
+
+ Returns a list of all successful set requests performed in
+ the test case in reverse order. The list contains the involved user
+ and agent, the value before set, and the new value. This is
+ intended to simplify the cleanup in function end_per_testcase,
+ that is, the undoing of the set requests and their possible
+ side-effects.
+
+
+
+
+ set_values(Agent, VarsAndVals, MgrAgentConfName, Config) -> SnmpReply
+ Issues a synchronous SNMP set request.
+
+ Agent = agent_name()
+ Oids = oids()
+ MgrAgentConfName = atom()
+ Config = [{Key, Value}]
+ SnmpReply = snmpreply()
+
+
+ Issues a synchronous SNMP set request.
+
+
+
+
+ start(Config, MgrAgentConfName) -> ok
+ Equivalent to start(Config, MgrAgentConfName,
+ undefined).
+
+ Equivalent to
+ ct_snmp:start(Config, MgrAgentConfName,
+ undefined).
+
+
+
+
+ start(Config, MgrAgentConfName, SnmpAppConfName) -> ok
+ Starts an SNMP manager and/or agent.
+
+ Config = [{Key, Value}]
+ Key = atom()
+ Value = term()
+ MgrAgentConfName = atom()
+ SnmpConfName = atom()
+
+
+ Starts an SNMP manager and/or agent. In the manager case,
+ registrations of users and agents, as specified by the configuration
+ MgrAgentConfName, are performed. When using SNMPv3, called
+ USM users are also registered. Users, usm_users, and
+ managed agents can also be registered later using
+ ct_snmp:register_users/2,
+ ct_snmp:register_agents/2,
+ and
+ ct_snmp:register_usm_users/2.
+
+ The agent started is called snmp_master_agent. Use
+ ct_snmp:load_mibs/1
+ to load MIBs into the agent.
+
+ With SnmpAppConfName SNMP applications can be configured
+ with parameters config, mibs, net_if, and so on.
+ The values are merged with (and possibly override) default values
+ set by ct_snmp.
+
+
+
+
+ stop(Config) -> ok
+ Stops the SNMP manager and/or agent, and removes all files
+ created.
+
+ Config = [{Key, Value}]
+ Key = atom()
+ Value = term()
+
+
+ Stops the SNMP manager and/or agent, and removes all files
+ created.
+
+
+
+
+ unload_mibs(Mibs) -> ok | {error, Reason}
+ Unloads the MIBs from agent snmp_master_agent.
+
+ Mibs = [MibName]
+ MibName = string()
+ Reason = term()
+
+
+ Unloads the MIBs from agent snmp_master_agent.
+
+
+
+
+ unregister_agents(MgrAgentConfName) -> ok
+ Unregisters all managed agents.
+
+ MgrAgentConfName = atom()
+ Reason = term()
+
+
+ Unregisters all managed agents.
+
+
+
+
+ unregister_agents(MgrAgentConfName, ManagedAgents) -> ok
+ Unregisters the specified managed agents.
+
+ MgrAgentConfName = atom()
+ ManagedAgents = [agent_name()]
+ Reason = term()
+
+
+ Unregisters the specified managed agents.
+
+
+
+
+ unregister_users(MgrAgentConfName) -> ok
+ Unregisters all users.
+
+ MgrAgentConfName = atom()
+ Reason = term()
+
+
+ Unregisters all users.
+
+
+
+
+ unregister_users(MgrAgentConfName, Users) -> ok
+ Unregisters the specified users.
+
+ MgrAgentConfName = atom()
+ Users = [user_name()]
+ Reason = term()
+
+
+ Unregisters the specified users.
+
+
+
+
+ unregister_usm_users(MgrAgentConfName) -> ok
+ Unregisters all USM users.
+
+ MgrAgentConfName = atom()
+ Reason = term()
+
+
+ Unregisters all USM users.
+
+
+
+
+ unregister_usm_users(MgrAgentConfName, UsmUsers) -> ok
+ Unregisters the specified USM users.
+
+ MgrAgentConfName = atom()
+ UsmUsers = [usm_user_name()]
+ Reason = term()
+
+
+ Unregisters the specified USM users.
+
+
+
+
+
+
+
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct_ssh
+
+
+
+
+
+
+ A
+ ct_ssh.xml
+
+ ct_ssh
+ SSH/SFTP client module.
+
+
+
+ SSH/SFTP client module.
+
+ This module uses application SSH, which provides detailed
+ information about, for example, functions, types, and options.
+
+ Argument Server 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 ssh). Whenever
+ the connection type is sftp, use the SSH connection reference
+ only.
+
+ The following options are valid for specifying an SSH/SFTP
+ connection (that is, can be used as configuration elements):
+
+
+ [{ConnType, Addr},
+ {port, Port},
+ {user, UserName}
+ {password, Pwd}
+ {user_dir, String}
+ {public_key_alg, PubKeyAlg}
+ {connect_timeout, Timeout}
+ {key_cb, KeyCallbackMod}]
+
+ ConnType = ssh | sftp.
+
+ For other types, see
+ ssh:ssh(3).
+
+ All time-out parameters in ct_ssh functions are values in
+ milliseconds.
+
+
+
+
+ Data Types
+
+
+ connection() = handle() | target_name()
+ -
+
For target_name, see module
+ ct.
+
+ handle() = handle()
+ -
+
Handle for a specific SSH/SFTP connection, see module
+ ct.
+
+ ssh_sftp_return() = term()
+ -
+
Return value from an
+ ssh:ssh_sftp
+ function.
+
+
+
+
+
+ apread(SSH, Handle, Position, Length) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ apread(SSH, Server, Handle, Position, Length) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ apwrite(SSH, Handle, Position, Data) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ apwrite(SSH, Server, Handle, Position, Data) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ aread(SSH, Handle, Len) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ aread(SSH, Server, Handle, Len) -> Result
+ For inforamtion and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ awrite(SSH, Handle, Data) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ awrite(SSH, Server, Handle, Data) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ close(SSH, Handle) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ close(SSH, Server, Handle) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ connect(KeyOrName) -> {ok, Handle} | {error, Reason}
+ Equivalent to connect(KeyOrName, host, []).
+
+ Equivalent to
+ ct_ssh:connect(KeyOrName, host,
+ []).
+
+
+
+
+ connect(KeyOrName, ConnType) -> {ok, Handle} | {error, Reason}
+ Equivalent to connect(KeyOrName, ConnType, []).
+
+ Equivalent to
+ ct_ssh:connect(KeyOrName, ConnType,
+ []).
+
+
+
+
+ connect(KeyOrName, ConnType, ExtraOpts) -> {ok, Handle} | {error, Reason}
+ Opens an SSH or SFTP connection using the information
+ associated with KeyOrName.
+
+ KeyOrName = Key | Name
+ Key = atom()
+ Name = target_name()
+ ConnType = ssh | sftp | host
+ ExtraOpts = ssh_connect_options()
+ Handle = handle()
+ Reason = term()
+
+
+ Opens an SSH or SFTP connection using the information associated
+ with KeyOrName.
+
+ If Name (an alias name for Key) 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 Name is possible. If Key is used, the returned
+ handle must be used for subsequent calls (multiple connections can
+ be opened using the configuration data specified by Key).
+
+ For information on how to create a new Name, see
+ ct:require/2.
+
+ For target_name, see module
+ ct.
+
+ ConnType always overrides the type specified in the
+ address tuple in the configuration data (and in ExtraOpts).
+ So it is possible to, for example, open an SFTP connection
+ directly using data originally specifying an SSH connection. Value
+ host means that the connection type specified by the host
+ option (either in the configuration data or in ExtraOpts)
+ is used.
+
+ ExtraOpts (optional) are extra SSH options to be added to
+ the configuration data for KeyOrName. The extra options
+ override any existing options with the same key in the
+ configuration data. For details on valid SSH options, see
+ application SSH.
+
+
+
+
+ del_dir(SSH, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ del_dir(SSH, Server, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ delete(SSH, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ delete(SSH, Server, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ disconnect(SSH) -> ok | {error, Reason}
+ Closes an SSH/SFTP connection.
+
+ SSH = connection()
+ Reason = term()
+
+
+ Closes an SSH/SFTP connection.
+
+
+
+
+ exec(SSH, Command) -> {ok, Data} | {error, Reason}
+ Equivalent to exec(SSH, Command, DefaultTimeout).
+
+ Equivalent to
+ ct_ssh:exec(SSH, Command,
+ DefaultTimeout).
+
+
+
+
+ exec(SSH, Command, Timeout) -> {ok, Data} | {error, Reason}
+ Requests server to perform Command.
+
+ SSH = connection()
+ Command = string()
+ Timeout = integer()
+ Data = list()
+ Reason = term()
+
+
+ Requests server to perform Command. A session channel is
+ opened automatically for the request. Data is received from
+ the server as a result of the command.
+
+
+
+
+ exec(SSH, ChannelId, Command, Timeout) -> {ok, Data} | {error, Reason}
+ Requests server to perform Command.
+
+ SSH = connection()
+ ChannelId = integer()
+ Command = string()
+ Timeout = integer()
+ Data = list()
+ Reason = term()
+
+
+ Requests server to perform Command. A previously opened
+ session channel is used for the request. Data is received
+ from the server as a result of the command.
+
+
+
+
+ get_file_info(SSH, Handle) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ get_file_info(SSH, Server, Handle) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ list_dir(SSH, Path) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ list_dir(SSH, Server, Path) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ make_dir(SSH, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ make_dir(SSH, Server, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ make_symlink(SSH, Name, Target) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ make_symlink(SSH, Server, Name, Target) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ open(SSH, File, Mode) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ open(SSH, Server, File, Mode) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ opendir(SSH, Path) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ opendir(SSH, Server, Path) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ position(SSH, Handle, Location) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ position(SSH, Server, Handle, Location) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ pread(SSH, Handle, Position, Length) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ pread(SSH, Server, Handle, Position, Length) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ pwrite(SSH, Handle, Position, Data) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ pwrite(SSH, Server, Handle, Position, Data) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ read(SSH, Handle, Len) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ read(SSH, Server, Handle, Len) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ read_file(SSH, File) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ read_file(SSH, Server, File) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ read_file_info(SSH, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ read_file_info(SSH, Server, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ read_link(SSH, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ read_link(SSH, Server, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ read_link_info(SSH, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ read_link_info(SSH, Server, Name) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ receive_response(SSH, ChannelId) -> {ok, Data} | {error, Reason}
+ Equivalent to receive_response(SSH, ChannelId,
+ close).
+
+ Equivalent to
+ ct_ssh:receive_response(SSH,
+ChannelId, close).
+
+
+
+
+ receive_response(SSH, ChannelId, End) -> {ok, Data} | {error, Reason}
+ Equivalent to receive_response(SSH, ChannelId, End,
+ DefaultTimeout).
+
+ Equivalent to
+ ct_ssh:receive_response(SSH,
+ChannelId, End, DefaultTimeout).
+
+
+
+
+ receive_response(SSH, ChannelId, End, Timeout) -> {ok, Data} | {timeout, Data} | {error, Reason}
+ Receives expected data from server on the specified session
+ channel.
+
+ SSH = connection()
+ ChannelId = integer()
+ End = Fun | close | timeout
+ Timeout = integer()
+ Data = list()
+ Reason = term()
+
+
+ Receives expected data from server on the specified session
+ channel.
+
+ If End == close, 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 {timeout,Data} (where
+ Data is the data received so far).
+ If End == timeout, a time-out is expected and
+ {ok,Data} is returned both in the case of a time-out and
+ when the channel is closed.
+
+ If End is a fun, this fun is called with one argument, the
+ data value in a received ssh_cm message (see
+ ssh:ssh_connection(3).
+ The fun is to return either true to end the receiving
+ operation (and have the so far collected data returned) or
+ false to wait for more data from the server. Even if a fun
+ is supplied, the function returns immediately if the server closes
+ the channel).
+
+
+
+
+ rename(SSH, OldName, NewName) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ rename(SSH, Server, OldName, NewName) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ send(SSH, ChannelId, Data) -> ok | {error, Reason}
+ Equivalent to send(SSH, ChannelId, 0, Data,
+ DefaultTimeout).
+
+ Equivalent to ct_ssh:send(SSH,
+ ChannelId, 0, Data, DefaultTimeout).
+
+
+
+
+ send(SSH, ChannelId, Data, Timeout) -> ok | {error, Reason}
+ Equivalent to send(SSH, ChannelId, 0, Data, Timeout).
+
+ Equivalent to ct_ssh:send(SSH,
+ ChannelId, 0, Data, Timeout).
+
+
+
+
+ send(SSH, ChannelId, Type, Data, Timeout) -> ok | {error, Reason}
+ Sends data to server on specified session channel.
+
+ SSH = connection()
+ ChannelId = integer()
+ Type = integer()
+ Data = list()
+ Timeout = integer()
+ Reason = term()
+
+
+ Sends data to server on specified session channel.
+
+
+
+
+ send_and_receive(SSH, ChannelId, Data) -> {ok, Data} | {error, Reason}
+ Equivalent to send_and_receive(SSH, ChannelId, Data,
+ close).
+
+ Equivalent to
+ ct_ssh:send_and_receive(SSH,
+ ChannelId, Data, close).
+
+
+
+
+ send_and_receive(SSH, ChannelId, Data, End) -> {ok, Data} | {error, Reason}
+ Equivalent to send_and_receive(SSH, ChannelId, 0, Data, End,
+ DefaultTimeout).
+
+ Equivalent to
+ ct_ssh;send_and_receive(SSH,
+ChannelId, 0, Data, End, DefaultTimeout).
+
+
+
+
+ send_and_receive(SSH, ChannelId, Data, End, Timeout) -> {ok, Data} | {error, Reason}
+ Equivalent to send_and_receive(SSH, ChannelId, 0, Data, End,
+ Timeout).
+
+ Equivalent to
+ ct_ssh:send_and_receive(SSH,
+ChannelId, 0, Data, End, Timeout).
+
+
+
+
+ send_and_receive(SSH, ChannelId, Type, Data, End, Timeout) -> {ok, Data} | {error, Reason}
+ Sends data to server on specified session channel and waits
+ to receive the server response.
+
+ SSH = connection()
+ ChannelId = integer()
+ Type = integer()
+ Data = list()
+ End = Fun | close | timeout
+ Timeout = integer()
+ Reason = term()
+
+
+ Sends data to server on specified session channel and waits to
+ receive the server response.
+
+ For details on argument End, see
+ ct_ssh:receive_response/4.
+
+
+
+
+ session_close(SSH, ChannelId) -> ok | {error, Reason}
+ Closes an SSH session channel.
+
+ SSH = connection()
+ ChannelId = integer()
+ Reason = term()
+
+
+ Closes an SSH session channel.
+
+
+
+
+ session_open(SSH) -> {ok, ChannelId} | {error, Reason}
+ Equivalent to session_open(SSH, DefaultTimeout).
+
+ Equivalent to
+ ct_ssh:session_open(SSH,
+ DefaultTimeout).
+
+
+
+
+ session_open(SSH, Timeout) -> {ok, ChannelId} | {error, Reason}
+ Opens a channel for an SSH session.
+
+ SSH = connection()
+ Timeout = integer()
+ ChannelId = integer()
+ Reason = term()
+
+
+ Opens a channel for an SSH session.
+
+
+
+
+ sftp_connect(SSH) -> {ok, Server} | {error, Reason}
+ Starts an SFTP session on an already existing SSH
+ connection.
+
+ SSH = connection()
+ Server = pid()
+ Reason = term()
+
+
+ Starts an SFTP session on an already existing SSH connection.
+ Server identifies the new session and must be specified
+ whenever SFTP requests are to be sent.
+
+
+
+
+ subsystem(SSH, ChannelId, Subsystem) -> Status | {error, Reason}
+ Equivalent to subsystem(SSH, ChannelId, Subsystem,
+ DefaultTimeout).
+
+ Equivalent to
+ ct_ssh:subsystem(SSH, ChannelId,
+ Subsystem, DefaultTimeout).
+
+
+
+
+ subsystem(SSH, ChannelId, Subsystem, Timeout) -> Status | {error, Reason}
+ Sends a request to execute a predefined subsystem.
+
+ SSH = connection()
+ ChannelId = integer()
+ Subsystem = string()
+ Timeout = integer()
+ Status = success | failure
+ Reason = term()
+
+
+ Sends a request to execute a predefined subsystem.
+
+
+
+
+ write(SSH, Handle, Data) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ write(SSH, Server, Handle, Data) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ write_file(SSH, File, Iolist) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ write_file(SSH, Server, File, Iolist) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ write_file_info(SSH, Name, Info) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+ write_file_info(SSH, Server, Name, Info) -> Result
+ For information and other types, see ssh_sftp(3).
+
+ SSH = connection()
+ Result = ssh_sftp_return() | {error, Reason}
+ Reason = term()
+
+
+ For information and other types, see
+ ssh:ssh_sftp(3).
+
+
+
+
+
+
+
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ ct_telnet
+
+
+
+
+
+
+ A
+ ct_telnet.xml
+
+ ct_telnet
+ Common Test specific layer on top of Telnet client ct_telnet_client.erl
+
+
+
+ Common Test specific layer on top of Telnet client
+ ct_telnet_client.erl.
+
+ Use this module to set up Telnet connections, send commands, and
+ perform string matching on the result. For information about how to use
+ ct_telnet and configure connections, specifically for UNIX hosts,
+ see the
+ unix_telnet manual page.
+
+
+ Default values defined in ct_telnet:
+
+
+
+ Connection timeout (time to wait for connection) = 10
+ seconds
+ Command timeout (time to wait for a command to return) =
+ 10 seconds
+ Max number of reconnection attempts = 3
+ Reconnection interval (time to wait in between
+ reconnection attempts) = 5 seconds
+ Keep alive (sends NOP to the server every 8 sec if
+ connection is idle) = true
+ Polling limit (max number of times to poll to get a
+ remaining string terminated) = 0
+ Polling interval (sleep time between polls) = 1 second
+
+
+
+ These parameters can be modified by the user with the following
+ configuration term:
+
+
+ {telnet_settings, [{connect_timeout,Millisec},
+ {command_timeout,Millisec},
+ {reconnection_attempts,N},
+ {reconnection_interval,Millisec},
+ {keep_alive,Bool},
+ {poll_limit,N},
+ {poll_interval,Millisec}]}.
+
+ Millisec = integer(), N = integer()
+
+ Enter the telnet_settings term in a configuration file included
+ in the test and ct_telnet retrieves the information
+ automatically.
+
+ keep_alive can be specified per connection, if necessary. For
+ details, see
+ unix_telnet.
+
+
+
+
+ Logging
+
+
+ The default logging behavior of ct_telnet 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 ct_telnet function, such as expect/3.
+ However, ct_telnet can be configured to use a special purpose
+ event handler, implemented in ct_conn_log_h, for logging
+ all Telnet traffic. To use this handler, install a Common
+ Test hook named cth_conn_log. Example (using the test suite
+ information function):
+
+
+ suite() ->
+ [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].
+
+ conn_mod() is the name of the Common Test module
+ implementing the connection protocol, that is, ct_telnet.
+
+ The cth_conn_log 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.
+
+ By default, data for all Telnet connections is logged in one common
+ file (named default), 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 hosts and list the names of the servers/connections
+ to be used in the suite. The connections must be named for this to
+ work (see
+ ct_telnet:open/1,2,3,4.
+
+ Hook option log_type can be used to change the
+ cth_conn_log behavior. The default value of this option is
+ raw, which results in the behavior described above. If the value
+ is set to html, all Telnet communication is printed to the test
+ case HTML log instead.
+
+ All cth_conn_log hook options described can also be
+ specified in a configuration file with configuration variable
+ ct_conn_log.
+
+ Example:
+
+
+ {ct_conn_log, [{ct_telnet,[{log_type,raw},
+ {hosts,[key_or_name()]}]}]}
+
+
+ Hook options specified in a configuration file overwrite any
+ hard-coded hook options in the test suite.
+
+
+
+ Logging Example:
+
+ The following ct_hooks statement causes printing of Telnet
+ traffic to separate logs for the connections server1 and
+ server2. Traffic for any other connections is logged in the
+ default Telnet log.
+
+
+ suite() ->
+ [{ct_hooks,
+ [{cth_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}]}].
+
+ As previously explained, this specification can also be provided by an
+ entry like the following in a configuration file:
+
+
+ {ct_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}.
+
+ In this case the ct_hooks statement in the test suite can look
+ as follows:
+
+
+ suite() ->
+ [{ct_hooks, [{cth_conn_log, []}]}].
+
+
+
+ Data Types
+
+
+ connection() = handle() | {target_name(), connection_type()} | target_name()
+ -
+
For target_name(), see module
+ ct.
+
+ connection_type() = telnet | ts1 | ts2
+ -
+
+ handle() = handle()
+ -
+
Handle for a specific Telnet connection, see module
+ ct.
+
+ prompt_regexp() = string()
+ -
+
Regular expression matching all possible prompts for a specific
+ target type. regexp must not have any groups, that is, when
+ matching, re:run/3 (in STDLIB) must return a list with
+ one single element.
+
+
+
+
+
+ close(Connection) -> ok | {error, Reason}
+ Closes the Telnet connection and stops the process managing
+ it.
+
+ Connection = connection()
+ Reason = term()
+
+
+ Closes the Telnet connection and stops the process managing it.
+
+ A connection can be associated with a target name and/or a handle.
+ If Connection has no associated target name, it can only
+ be closed with the handle value (see
+ ct_telnet:open/4.
+
+
+
+
+ cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}
+ Equivalent to cmd(Connection, Cmd, []).
+
+ Equivalent to
+ ct_telnet:cmd(Connection, Cmd,
+ []).
+
+
+
+
+ cmd(Connection, Cmd, Opts) -> {ok, Data} | {error, Reason}
+ Sends a command through Telnet and waits for prompt.
+
+ Connection = connection()
+ Cmd = string()
+ Opts = [Opt]
+ Opt = {timeout, timeout()} | {newline, boolean()}
+ Data = [string()]
+ Reason = term()
+
+
+ Sends a command through Telnet and waits for prompt.
+
+ By default, this function adds a new line to the end of the
+ specified command. If this is not desired, use option
+ {newline,false}. This is necessary, for example, when
+ sending Telnet command sequences prefixed with character
+ Interprete As Command (IAC).
+
+ Option timeout specifies how long the client must wait
+ for prompt. If the time expires, the function returns
+ {error,timeout}. For information about the default value
+ for the command timeout, see the
+ list of default values
+ in the beginning of this module.
+
+
+
+
+ cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}
+ Equivalent to cmdf(Connection, CmdFormat, Args, []).
+
+ Equivalent to
+ ct_telnet:cmdf(Connection, CmdFormat,
+ Args, []).
+
+
+
+
+ cmdf(Connection, CmdFormat, Args, Opts) -> {ok, Data} | {error, Reason}
+ Sends a Telnet command and waits for prompt (uses a format
+ string and a list of arguments to build the command).
+
+ Connection = connection()
+ CmdFormat = string()
+ Args = list()
+ Opts = [Opt]
+ Opt = {timeout, timeout()} | {newline, boolean()}
+ Data = [string()]
+ Reason = term()
+
+
+ Sends a Telnet command and waits for prompt (uses a format string
+ and a list of arguments to build the command).
+
+ For details, see
+ ct_telnet:cmd/3.
+
+
+
+
+ expect(Connection, Patterns) -> term()
+ Equivalent to expect(Connections, Patterns, []).
+
+ Equivalent to
+ ct_telnet:expect(Connections,
+ Patterns, []).
+
+
+
+
+ expect(Connection, Patterns, Opts) -> {ok, Match} | {ok, MatchList, HaltReason} | {error, Reason}
+ Gets data from Telnet and waits for the expected
+ pattern.
+
+ Connection = connection()
+ Patterns = Pattern | [Pattern]
+ Pattern = string() | {Tag, string()} | prompt | {prompt, Prompt}
+ Prompt = string()
+ Tag = term()
+ Opts = [Opt]
+ 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}
+ IdleTimeout = infinity | integer()
+ TotalTimeout = infinity | integer()
+ N = integer()
+ HaltPatterns = Patterns
+ MatchList = [Match]
+ Match = RxMatch | {Tag, RxMatch} | {prompt, Prompt}
+ RxMatch = [string()]
+ HaltReason = done | Match
+ Reason = timeout | {prompt, Prompt}
+
+
+ Gets data from Telnet and waits for the expected pattern.
+
+ Pattern can be a POSIX regular expression. The function
+ returns when a pattern is successfully matched (at least one, in
+ the case of multiple patterns).
+
+ RxMatch is a list of matched strings. It looks as
+ follows [FullMatch, SubMatch1, SubMatch2, ...], where
+ FullMatch is the string matched by the whole regular
+ expression, and SubMatchN is the string that matched
+ subexpression number N. Subexpressions are denoted with
+ (' ') in the regular expression.
+
+ If a Tag is speciifed, the returned Match also
+ includes the matched Tag. Otherwise, only RxMatch
+ is returned.
+
+ Options:
+
+
+ idle_timeout
+ Indicates that the function must return if the Telnet
+ client is idle (that is, if no data is received) for more than
+ IdleTimeout milliseconds. Default time-out is 10
+ seconds.
+ total_timeout
+ Sets a time limit for the complete expect operation.
+ After TotalTimeout milliseconds, {error,timeout}
+ is returned. Default is infinity (that is, no time
+ limit).
+ ignore_prompt | no_prompt_check
+ >The function returns when a prompt is received, even if
+ no pattern has yet been matched, and
+ {error,{prompt,Prompt}} is returned. However, this
+ behavior can be modified with option ignore_prompt or
+ option no_prompt_check, which tells expect to
+ return only when a match is found or after a time-out.
+ ignore_prompt
+ ct_telnet ignores any prompt found. This option is
+ useful if data sent by the server can include a pattern
+ matching prompt regexp (as returned by
+ TargedMod:get_prompt_regexp/0), but is not to not cause
+ the function to return.
+ no_prompt_check
+ ct_telnet does not search for a prompt at all. This
+ is useful if, for example, Pattern itself matches the
+ prompt.
+ wait_for_prompt
+ Forces ct_telnet to wait until the prompt string
+ is received before returning (even if a pattern has already been
+ matched). This is equal to calling
+ expect(Conn, Patterns++[{prompt,Prompt}], [sequence|Opts]).
+ Notice that option idle_timeout and total_timeout
+ can abort the operation of waiting for prompt.
+ repeat | repeat, N
+ The pattern(s) must be matched multiple times. If N
+ is speciified, the pattern(s) are matched N times, and
+ the function returns HaltReason = done. This option can be
+ interrupted by one or more HaltPatterns. MatchList
+ is always returned, that is, a list of Match instead of
+ only one Match. Also HaltReason is returned.
+
+ sequence
+ 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 HaltPatterns. MatchList
+ is always returned, that is, a list of Match instead of
+ only one Match. Also HaltReason is returned.
+
+
+
+ Example 1:
+
+
+ expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[sequence,{halt,[{nnn,"NNN"}]}])
+
+ First this tries to match "ABC", and then "XYZ", but
+ if "NNN" appears, the function returns
+ {error,{nnn,["NNN"]}}. If both "ABC" and "XYZ"
+ are matched, the function returns {ok,[AbcMatch,XyzMatch]}.
+
+ Example 2:
+
+
+ expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[{repeat,2},{halt,[{nnn,"NNN"}]}])
+
+ This tries to match "ABC" or "XYZ" twice. If
+ "NNN" appears, the function returns
+ HaltReason = {nnn,["NNN"]}.
+
+ Options repeat and sequence can be combined to
+ match a sequence multiple times.
+
+
+
+
+ get_data(Connection) -> {ok, Data} | {error, Reason}
+ Gets all data received by the Telnet client since the last
+ command was sent.
+
+ Connection = connection()
+ Data = [string()]
+ Reason = term()
+
+
+ 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.
+
+ The polling feature is controlled by the configuration values
+ poll_limit and poll_interval 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 get_data call.
+
+
+
+
+ open(Name) -> {ok, Handle} | {error, Reason}
+ Equivalent to open(Name, telnet).
+
+ Equivalent to
+ ct_telnet:open(Name,
+ telnet).
+
+
+
+
+ open(Name, ConnType) -> {ok, Handle} | {error, Reason}
+ Opens a Telnet connection to the specified target
+ host.
+
+ Name = target_name()
+ ConnType = connection_type()
+ Handle = handle()
+ Reason = term()
+
+
+ Opens a Telnet connection to the specified target host.
+
+
+
+
+ open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}
+ Equivalent to open(KeyOrName, ConnType, TargetMod, []).
+
+ Equivalent to
+ ct_telnet:ct_telnet:open(KeyOrName,
+ ConnType, TargetMod, []).
+
+
+
+
+ open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle} | {error, Reason}
+ Opens a Telnet connection to the specified target
+ host.
+
+ KeyOrName = Key | Name
+ Key = atom()
+ Name = target_name()
+ ConnType = connection_type()
+ TargetMod = atom()
+ Extra = term()
+ Handle = handle()
+ Reason = term()
+
+
+ Opens a Telnet connection to the specified target host.
+
+ The target data must exist in a configuration file. The connection
+ can be associated with Name and/or the returned Handle.
+ To allocate a name for the target, use one of the following
+ alternatives:
+
+
+ ct:require/2
+ in a test case
+ A require statement in the suite information
+ function (suite/0)
+ A require statement in a test case information
+ function
+
+
+ If you want the connection to be associated with Handle only
+ (if you, for example, need to open multiple connections to a host),
+ use Key, the configuration variable name, to specify the
+ target. Notice that a connection without an associated target name
+ can only be closed with the Handle value.
+
+ TargetMod is a module that exports the functions
+ connect(Ip, Port, KeepAlive, Extra) and
+ get_prompt_regexp() for the specified TargetType
+ (for example, unix_telnet).
+
+ For target_name(), see module
+ ct.
+
+ See also
+ ct:require/2.
+
+
+
+
+ send(Connection, Cmd) -> ok | {error, Reason}
+ Equivalent to send(Connection, Cmd, []).
+
+ Equivalent to
+ ct_telnet:send(Connection, Cmd,
+ []).
+
+
+
+
+ send(Connection, Cmd, Opts) -> ok | {error, Reason}
+ Sends a Telnet command and returns immediately.
+
+ Connection = connection()
+ Cmd = string()
+ Opts = [Opt]
+ Opt = {newline, boolean()}
+ Reason = term()
+
+
+ Sends a Telnet command and returns immediately.
+
+ By default, this function adds a newline to the end of the
+ specified command. If this is not desired, option
+ {newline,false} can be used. This is necessary, for example,
+ when sending Telnet command sequences prefixed with character
+ Interprete As Command (IAC).
+
+ The resulting output from the command can be read with
+ ct_telnet:get_data/2 or
+ ct_telnet:expect/2,3.
+
+
+
+
+ sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}
+ Equivalent to sendf(Connection, CmdFormat, Args, []).
+
+ Equivalent to
+ ct_telnet:sendf(Connection, CmdFormat,
+ Args, []).
+
+
+
+
+ sendf(Connection, CmdFormat, Args, Opts) -> ok | {error, Reason}
+ Sends a Telnet command and returns immediately (uses a format
+ string and a list of arguments to build the command).
+
+ Connection = connection()
+ CmdFormat = string()
+ Args = list()
+ Opts = [Opt]
+ Opt = {newline, boolean()}
+ Reason = term()
+
+
+ Sends a Telnet command and returns immediately (uses a format
+ string and a list of arguments to build the command).
+
+
+
+
+
+ See Also
+ unix_telnet
+
+
+
+
+
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 @@
ref_man.xml
- Common Test 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&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.
-
- 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.
-
- 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.
-
- Common Test is implemented as a framework based on the OTP Test
- Server application.
+
-
@@ -83,6 +50,3 @@
-
-
-
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 @@
+
+
+
+
+
+
+ 20102012
+ Ericsson AB. All Rights Reserved.
+
+
+ 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.
+
+
+
+ unix_telnet
+
+
+
+
+
+
+ A
+ unix_telnet.xml
+
+ unix_telnet
+ Callback module for ct_telnet, for connecting to a Telnet
+ server on a UNIX host.
+
+
+
+ Callback module for
+ ct_telnet,
+ for connecting to a Telnet server on a UNIX host.
+
+ It requires the following entry in the configuration file:
+
+
+ {unix,[{telnet,HostNameOrIpAddress},
+ {port,PortNum}, % optional
+ {username,UserName},
+ {password,Password},
+ {keep_alive,Bool}]}. % optional
+
+ To communicate through Telnet to the host specified by
+ HostNameOrIpAddress, use the interface functions in
+ ct_telnet, for example,
+ open(Name) and cmd(Name,Cmd).
+
+ Name is the name you allocated to the Unix host in your
+ require statement, for example:
+
+
+ suite() -> [{require,Name,{unix,[telnet]}}].
+
+ or
+
+
+ ct:require(Name,{unix,[telnet]}).
+
+ The "keep alive" activity (that is, that Common Test 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 telnet_settings
+ (see ct_telnet).
+
+ The {port,PortNum} tuple is optional and if omitted, default
+ Telnet port 23 is used. Also the keep_alive tuple is optional,
+ and the value defauls to true (enabled).
+
+
+
+
+ connect(ConnName, Ip, Port, Timeout, KeepAlive, Extra) -> {ok, Handle} | {error, Reason}
+ Callback for ct_telnet.erl.
+
+ ConnName = target_name()
+ Ip = string() | {integer(), integer(), integer(), integer()}
+ Port = integer()
+ Timeout = integer()
+ KeepAlive = bool()
+ Extra = target_name() | {Username, Password}
+ Username = string()
+ Password = string()
+ Handle = handle()
+ Reason = term()
+
+
+ Callback for ct_telnet.erl.
+
+ Setup Telnet connection to a Unix host.
+
+ For target_name(), see
+ ct. For handle(), see
+ ct_telnet.
+
+
+
+
+ get_prompt_regexp() -> PromptRegexp
+ Callback for ct_telnet.erl.
+
+ PromptRegexp = prompt_regexp()
+
+
+ Callback for ct_telnet.erl.
+
+ Returns a suitable regexp string matching common prompts
+ for users on Unix hosts.
+
+ For prompt_regexp(), see
+ ct_telnet.
+
+
+
+
+
+ See Also
+ ct,
+ ct_telnet
+
+
+
+
+
--
cgit v1.2.3