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/ct_telnet.xml | 601 ++++++++++++++++++++++++++++++++++ 1 file changed, 601 insertions(+) create mode 100644 lib/common_test/doc/src/ct_telnet.xml (limited to 'lib/common_test/doc/src/ct_telnet.xml') 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

+
+ + + + -- cgit v1.2.3