From bf6c2ff6625c45bc6c65c112719879078292ee22 Mon Sep 17 00:00:00 2001 From: Peter Andersson Date: Wed, 29 Jan 2014 09:39:04 +0100 Subject: Add documentation about logging in the ct_telnet module --- lib/common_test/src/ct_telnet.erl | 267 +++++++++++++++++++------------------- 1 file changed, 133 insertions(+), 134 deletions(-) (limited to 'lib/common_test') diff --git a/lib/common_test/src/ct_telnet.erl b/lib/common_test/src/ct_telnet.erl index 698915b37c..b4d82a53cf 100644 --- a/lib/common_test/src/ct_telnet.erl +++ b/lib/common_test/src/ct_telnet.erl @@ -17,146 +17,145 @@ %% %CopyrightEnd% %% -%%% @doc 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. -%%% See the unix_telnet manual page for information about how to use -%%% ct_telnet, and configure connections, specifically for unix hosts.

-%%%

The following default values are defined in ct_telnet:

-%%% 
-%%% Connection timeout = 10 sec (time to wait for connection)
-%%% Command timeout = 10 sec (time to wait for a command to return)
-%%% Max no of reconnection attempts = 3
-%%% Reconnection interval = 5 sek (time to wait in between reconnection attempts)
-%%% Keep alive = true (will send NOP to the server every 10 sec if connection is idle)
-%%%

These parameters can be altered 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}]}.
-%%%

Millisec = integer(), N = integer()

-%%%

Enter the telnet_settings term in a configuration -%%% file included in the test and ct_telnet will retrieve the information -%%% automatically. Note that keep_alive may be specified per connection if -%%% required. See unix_telnet for details.

-%%% -%%% @end -%%% -%%% == Logging == -%%% -%%% `ct_telnet' can be configured to uses the `error_logger' for logging telnet -%%% 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 your test suite, e.g. -%%% -%%% -%%% ``` -%%% suite() -> -%%% [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}]. -%%%''' -%%% -%%% `conn_mod()' is the name of the common_test module implementing -%%% the connection protocol, i.e. `ct_telnet'. -%%% -%%% The hook option `log_type' specifies the type of logging: -%%% -%%%
-%%%
`raw'
-%%%
The sent and received telnet 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.
-%%% -%%%
`html (default)'
-%%%
The sent and received telnet traffic is pretty printed -%%% directly in the test case HTML log.
-%%% -%%%
`silent'
-%%%
Telnet traffic is not logged.
-%%%
-%%% -%%% By default, all telnet traffic is logged in one single log -%%% file. However, it is possible to have different connections logged -%%% in separate files. To do this, use the hook option `hosts' and -%%% list the names of the servers/connections that will be used in the -%%% suite. Note that the connections must be named for this to work. -%%% -%%% The `hosts' option has no effect if `log_type' is set to `html' or -%%% `silent'. -%%% -%%% The hook options can also be specified in a configuration file with -%%% the configuration variable `ct_conn_log': -%%% -%%% ``` -%%% {ct_conn_log,[{conn_mod(),hook_options()}]}. -%%% ''' -%%% -%%% For example: +%% @doc Common Test specific layer on top of telnet client `ct_telnet_client.erl' %% -%%% ``` -%%% {ct_conn_log,[{ct_telnet,[{log_type,raw}, -%%% {hosts,[key_or_name()]}]}]} -%%% ''' -%%% -%%% Note that hook options specified in a configuration file -%%% will overwrite any hardcoded hook options in the test suite. +%%

Use this module to set up telnet connections, send commands and +%% perform string matching on the result. +%% See the `unix_telnet' manual page for information about how to use +%% `ct_telnet', and configure connections, specifically for unix hosts.

+%%

The following default values are defined in `ct_telnet':

+%% 
+%% Connection timeout = 10 sec (time to wait for connection)
+%% Command timeout = 10 sec (time to wait for a command to return)
+%% Max no of reconnection attempts = 3
+%% Reconnection interval = 5 sek (time to wait in between reconnection attempts)
+%% Keep alive = true (will send NOP to the server every 10 sec if connection is idle)
+%%

These parameters can be altered 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}]}.
+%%

Millisec = integer(), N = integer()

+%%

Enter the telnet_settings term in a configuration +%% file included in the test and ct_telnet will retrieve the information +%% automatically. Note that `keep_alive' may be specified per connection if +%% required. See `unix_telnet' for details.

%% -%%% === Logging example 1 === -%%% -%%% The following `ct_hooks' statement will cause raw printing of -%%% telnet traffic to separate logs for the connections named -%%% `server1' and `server2'. Any other connections will be logged -%%% to default telnet log. -%%% -%%% ``` -%%% suite() -> -%%% [{ct_hooks, [{cth_conn_log, [{ct_telnet,[{log_type,raw}}, -%%% {hosts,[server1,server2]}]} -%%% ]}]}]. -%%%''' -%%% -%%% === Logging example 2 === -%%% -%%% The following configuration file will cause raw logging of all -%%% telnet traffic into one single text file. -%%% -%%% ``` -%%% {ct_conn_log,[{ct_telnet,[{log_type,raw}]}]}. -%%% ''' -%%% -%%% The `ct_hooks' statement must look like this: -%%% -%%% ``` -%%% suite() -> -%%% [{ct_hooks, [{cth_conn_log, []}]}]. -%%% ''' -%%% -%%% The same `ct_hooks' statement without the configuration file would -%%% cause HTML logging of all telnet connections into the test case -%%% HTML log. -%%% -%%% Note that if the `cth_conn_log' hook is not added, telnet -%%% traffic is still logged in the test case log files (on the legacy -%%% `ct_telnet' format). - +%% == Logging == +%% +%% `ct_telnet' can be configured to uses the `error_logger' for logging telnet +%% 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 your test suite, e.g: +%% +%% +%% ``` +%% suite() -> +%% [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}]. +%%''' +%% +%% `conn_mod()' is the name of the common_test module implementing +%% the connection protocol, i.e. `ct_telnet'. +%% +%% The hook option `log_type' specifies the type of logging: +%% +%%
+%%
`raw'
+%%
The sent and received telnet 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.
+%% +%%
`html (default)'
+%%
The sent and received telnet traffic is pretty printed +%% directly in the test case HTML log.
+%% +%%
`silent'
+%%
Telnet traffic is not logged.
+%%
+%% +%% By default, all telnet traffic is logged in one single log +%% file. However, it is possible to have different connections logged +%% in separate files. To do this, use the hook option `hosts' and +%% list the names of the servers/connections that will be used in the +%% suite. Note that the connections must be named for this to work +%% (see the `open' function below). +%% +%% The `hosts' option has no effect if `log_type' is set to `html' or +%% `silent'. +%% +%% The hook options can also be specified in a configuration file with +%% the configuration variable `ct_conn_log': +%% +%% ``` +%% {ct_conn_log,[{conn_mod(),hook_options()}]}. +%% ''' +%% +%% For example: +%% +%% ``` +%% {ct_conn_log,[{ct_telnet,[{log_type,raw}, +%% {hosts,[key_or_name()]}]}]} +%% ''' +%% +%% Note that hook options specified in a configuration file +%% will overwrite any hardcoded hook options in the test suite. +%% +%% === Logging example 1 === +%% +%% The following `ct_hooks' statement will cause raw printing of +%% telnet traffic to separate logs for the connections named +%% `server1' and `server2'. Any other connections will be logged +%% to default telnet log. +%% +%% ``` +%% suite() -> +%% [{ct_hooks, [{cth_conn_log, [{ct_telnet,[{log_type,raw}}, +%% {hosts,[server1,server2]}]} +%% ]}]}]. +%%''' +%% +%% === Logging example 2 === +%% +%% The following configuration file will cause raw logging of all +%% telnet traffic into one single text file. +%% +%% ``` +%% {ct_conn_log,[{ct_telnet,[{log_type,raw}]}]}. +%% ''' +%% +%% The `ct_hooks' statement must look like this: +%% +%% ``` +%% suite() -> +%% [{ct_hooks, [{cth_conn_log, []}]}]. +%% ''' +%% +%% The same `ct_hooks' statement without the configuration file would +%% cause HTML logging of all telnet connections into the test case +%% HTML log. +%% +%% Note that if the `cth_conn_log' hook is not added, telnet +%% traffic is still logged in the test case HTML log file (on the legacy +%% `ct_telnet' format). +%% @end -%%% @type connection_type() = telnet | ts1 | ts2 +%% @type connection_type() = telnet | ts1 | ts2 -%%% @type connection() = handle() | -%%% {ct:target_name(),connection_type()} | ct:target_name() +%% @type connection() = handle() | +%% {ct:target_name(),connection_type()} | ct:target_name() -%%% @type handle() = ct_gen_conn:handle(). Handle for a -%%% specific telnet connection. +%% @type handle() = ct_gen_conn:handle(). Handle for a +%% specific telnet connection. -%%% @type prompt_regexp() = string(). A regular expression which -%%% matches all possible prompts for a specific type of target. The -%%% regexp must not have any groups i.e. when matching, re:run/3 shall -%%% return a list with one single element. -%%% -%%% @see unix_telnet +%% @type prompt_regexp() = string(). A regular expression which +%% matches all possible prompts for a specific type of target. The +%% regexp must not have any groups i.e. when matching, re:run/3 shall +%% return a list with one single element. +%% +%% @see unix_telnet -module(ct_telnet). -- cgit v1.2.3