ct_telnet(3erl) Erlang Module Definition ct_telnet(3erl)
NAME
ct_telnet - Common Test specific layer on top of Telnet client ct_tel-
net_client.erl
DESCRIPTION
Common Test specific layer on top of Telnet client ct_tel-
net_client.erl.
Use this module to set up Telnet connections, send commands, and per-
form 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 at-
tempts) = 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
* The TCP_NODELAY option for the telnet socket is disabled (set to
false) per default
These parameters can be modified by the user with the following config-
uration term:
{telnet_settings, [{connect_timeout,Millisec},
{command_timeout,Millisec},
{reconnection_attempts,N},
{reconnection_interval,Millisec},
{keep_alive,Bool},
{poll_limit,N},
{poll_interval,Millisec},
{tcp_nodelay,Bool}]}.
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 con-
figured to use a special purpose event handler, implemented in
ct_conn_log_h, for logging all Telnet traffic. To use this handler, in-
stall 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 con-
nection 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_tel-
net: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 con-
figuration file with configuration variable ct_conn_log.
Example:
{ct_conn_log, [{ct_telnet,[{log_type,raw},
{hosts,[key_or_name()]}]}]}
Note:
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 fol-
lows:
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 sin-
gle element.
EXPORTS
close(Connection) -> ok | {error, Reason}
Types:
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 han-
dle. 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 ct_telnet:cmd(Connection, Cmd, []).
cmd(Connection, Cmd, Opts) -> {ok, Data} | {error, Reason}
Types:
Connection = connection()
Cmd = string()
Opts = [Opt]
Opt = {timeout, timeout()} | {newline, boolean() | string()}
Data = [string()]
Reason = term()
Sends a command through Telnet and waits for prompt.
By default, this function adds "\n" 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 se-
quences prefixed with character Interpret As Command (IAC). Op-
tion {newline,string()} can also be used if a different line end
than "\n" is required, for instance {newline,"\r\n"}, to add
both carriage return and newline characters.
Option timeout specifies how long the client must wait for
prompt. If the time expires, the function returns {error,time-
out}. 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 ct_telnet:cmdf(Connection, CmdFormat, Args, []).
cmdf(Connection, CmdFormat, Args, Opts) -> {ok, Data} | {error, Reason}
Types:
Connection = connection()
CmdFormat = string()
Args = list()
Opts = [Opt]
Opt = {timeout, timeout()} | {newline, boolean() | string()}
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 ct_telnet:expect(Connections, Patterns, []).
expect(Connection, Patterns, Opts) -> {ok, Match} | {ok, MatchList,
HaltReason} | {error, Reason}
Types:
Connection = connection()
Patterns = Pattern | [Pattern]
Pattern = string() | {Tag, string()} | prompt | {prompt,
Prompt}
Prompt = string()
Tag = term()
Opts = [Opt]
Opt = {idle_timeout, IdleTimeout} | {total_timeout, Total-
Timeout} | repeat | {repeat, N} | sequence | {halt, HaltPat-
terns} | 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 [Full-
Match, 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 specified, 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. De-
fault 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_reg-
exp/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 use-
ful 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, Pat-
terns++[{prompt,Prompt}], [sequence|Opts]). Notice that op-
tion 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 spec-
ified, 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 HaltRea-
son 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,[Abc-
Match,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}
Types:
Connection = connection()
Data = [string()]
Reason = term()
Gets all data received by the Telnet client since the last com-
mand was sent. Only newline-terminated strings are returned. If
the last received string has not yet been terminated, the con-
nection can be polled automatically until the string is com-
plete.
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 ct_telnet:open(Name, telnet).
open(Name, ConnType) -> {ok, Handle} | {error, Reason}
Types:
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 ct_telnet:ct_telnet:open(KeyOrName, ConnType, Tar-
getMod, []).
open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle} | {error,
Reason}
Types:
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 connec-
tion can be associated with Name and/or the returned Handle. To
allocate a name for the target, use one of the following alter-
natives:
* 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 speci-
fied TargetType (for example, unix_telnet).
For target_name(), see module ct.
See also ct:require/2.
send(Connection, Cmd) -> ok | {error, Reason}
Equivalent to ct_telnet:send(Connection, Cmd, []).
send(Connection, Cmd, Opts) -> ok | {error, Reason}
Types:
Connection = connection()
Cmd = string()
Opts = [Opt]
Opt = {newline, boolean() | string()}
Reason = term()
Sends a Telnet command and returns immediately.
By default, this function adds "\n" 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 com-
mand sequences prefixed with character Interpret As Command
(IAC). Option {newline,string()} can also be used if a different
line end than "\n" is required, for instance {newline,"\r\n"},
to add both carriage return and newline characters.
The resulting output from the command can be read with ct_tel-
net:get_data/2 or ct_telnet:expect/2,3.
sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}
Equivalent to ct_telnet:sendf(Connection, CmdFormat, Args, []).
sendf(Connection, CmdFormat, Args, Opts) -> ok | {error, Reason}
Types:
Connection = connection()
CmdFormat = string()
Args = list()
Opts = [Opt]
Opt = {newline, boolean() | string()}
Reason = term()
Sends a Telnet command and returns immediately (uses a format
string and a list of arguments to build the command).
For details, see ct_telnet:send/3.
SEE ALSO
unix_telnet
Ericsson AB common_test 1.19 ct_telnet(3erl)