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') 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