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. 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

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

Functions

close(Connection) -> ok | {error, Reason}

Connection = connection() (see module ct_telnet)

Close the telnet connection and stop the process managing it.

A connection may be associated with a target name and/or a handle. If Connection has no associated target name, it may only be closed with the handle value (see the open/4 function).

cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}

Equivalent to cmd(Connection, Cmd, DefaultTimeout).

cmd(Connection, Cmd, Timeout) -> {ok, Data} | {error, Reason}

Connection = connection() (see module ct_telnet)
Cmd = string()
Timeout = integer()
Data = [string()]

Send a command via telnet and wait for prompt.

cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}

Equivalent to cmdf(Connection, CmdFormat, Args, DefaultTimeout).

cmdf(Connection, CmdFormat, Args, Timeout) -> {ok, Data} | {error, Reason}

Connection = connection() (see module ct_telnet)
CmdFormat = string()
Args = list()
Timeout = integer()
Data = [string()]

Send a telnet command and wait for prompt (uses a format string and list of arguments to build the command).

end_gen_log() -> term()

expect(Connection, Patterns) -> term()

Equivalent to expect(Connections, Patterns, []).

expect(Connection, Patterns, Opts) -> {ok, Match} | {ok, MatchList, HaltReason} | {error, Reason}

Connection = connection() (see module ct_telnet)
Patterns = Pattern | [Pattern]
Pattern = string() | {Tag, string()} | prompt | {prompt, Prompt}
Prompt = string()
Tag = term()
Opts = [Opt]
Opt = {timeout, Timeout} | repeat | {repeat, N} | sequence | {halt, HaltPatterns} | ignore_prompt | no_prompt_check
Timeout = integer()
N = integer()
HaltPatterns = Patterns
MatchList = [Match]
Match = RxMatch | {Tag, RxMatch} | {prompt, Prompt}
RxMatch = [string()]
HaltReason = done | Match
Reason = timeout | {prompt, Prompt}

Get data from telnet and wait for the expected pattern.

Pattern can be a POSIX regular expression. If more than one pattern is given, the function returns when the first match is found.

RxMatch is a list of matched strings. It looks like this: [FullMatch, SubMatch1, SubMatch2, ...] where FullMatch is the string matched by the whole regular expression and SubMatchN is the string that matched subexpression no N. Subexpressions are denoted with '(' ')' in the regular expression

If a Tag is given, the returned Match will also include the matched Tag. Else, only RxMatch is returned.

The timeout option indicates that the function shall return if the telnet client is idle (i.e. if no data is received) for more than Timeout milliseconds. Default timeout is 10 seconds.

The function will always return when a prompt is found, unless any of the ignore_prompt or no_prompt_check options are used, in which case it will return when a match is found or after a timeout.

If the ignore_prompt option is used, ct_telnet will ignore any prompt found. This option is useful if data sent by the server could include a pattern that would match the prompt regexp (as returned by TargedMod:get_prompt_regexp/0), but which should not cause the function to return.

If the no_prompt_check option is used, ct_telnet will not search for a prompt at all. This is useful if, for instance, the Pattern itself matches the prompt.

The repeat option indicates that the pattern(s) shall be matched multiple times. If N is given, the pattern(s) will be matched N times, and the function will return with HaltReason = done.

The sequence option indicates that all patterns shall be matched in a sequence. A match will not be concluded untill all patterns are matched.

Both repeat and sequence can be interrupted by one or more HaltPatterns. When sequence or repeat is used, there will always be a MatchList returned, i.e. a list of Match instead of only one Match. There will also be a HaltReason returned.

Examples:
expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}], [sequence,{halt,[{nnn,"NNN"}]}]).
will try to match "ABC" first and then "XYZ", but if "NNN" appears the function will return {error,{nnn,["NNN"]}}. If both "ABC" and "XYZ" are matched, the function will return {ok,[AbcMatch,XyzMatch]}.

expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}], [{repeat,2},{halt,[{nnn,"NNN"}]}]).
will try to match "ABC" or "XYZ" twice. If "NNN" appears the function will return with HaltReason = {nnn,["NNN"]}.

The repeat and sequence options can be combined in order to match a sequence multiple times.

format_data(How, X2) -> term()

get_data(Connection) -> {ok, Data} | {error, Reason}

Connection = connection() (see module ct_telnet)
Data = [string()]

Get all data which has been received by the telnet client since last command was sent.

log(Name, String, Args) -> term()

log(State, Action, String, Args) -> term()

open(Name) -> {ok, Handle} | {error, Reason}

Equivalent to open(Name, telnet).

open(Name, ConnType) -> {ok, Handle} | {error, Reason}

Name = target_name()
ConnType = connection_type() (see module ct_telnet)
Handle = handle() (see module ct_telnet)

Open a telnet connection to the specified target host.

open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}

Equivalent to open(KeyOrName, ConnType, TargetMod, []).

open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle} | {error, Reason}

KeyOrName = Key | Name
Key = atom()
Name = target_name() (see module ct)
ConnType = connection_type()
TargetMod = atom()
Extra = term()
Handle = handle()

Open a telnet connection to the specified target host.

The target data must exist in a configuration file. The connection may be associated with either Name and/or the returned Handle. To allocate a name for the target, use ct:require/2 in a test case, or use a require statement in the suite info function (suite/0), or in a test case info function. If you want the connection to be associated with Handle only (in case you need to open multiple connections to a host for example), simply use Key, the configuration variable name, to specify the target. Note that a connection that has no associated target name can only be closed with the handle value.

TargetMod is a module which exports the functions connect(Ip,Port,KeepAlive,Extra) and get_prompt_regexp() for the given TargetType (e.g. unix_telnet).

See also: ct:require/2.

send(Connection, Cmd) -> ok | {error, Reason}

Connection = connection() (see module ct_telnet)
Cmd = string()

Send a telnet command and return immediately.

The resulting output from the command can be read with get_data/1 or expect/2/3.

sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}

Connection = connection() (see module ct_telnet)
CmdFormat = string()
Args = list()

Send a telnet command and return immediately (uses a format string and a list of arguments to build the command).

ct_telnet

Common Test specific layer on top of telnet client ct_telnet_client.erl

Functions

close(Connection) -> ok | {error, Reason}

cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}

cmd(Connection, Cmd, Timeout) -> {ok, Data} | {error, Reason}

cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}

cmdf(Connection, CmdFormat, Args, Timeout) -> {ok, Data} | {error, Reason}

end_gen_log() -> term()

expect(Connection, Patterns) -> term()

expect(Connection, Patterns, Opts) -> {ok, Match} | {ok, MatchList, HaltReason} | {error, Reason}

format_data(How, X2) -> term()

get_data(Connection) -> {ok, Data} | {error, Reason}

log(Name, String, Args) -> term()

log(State, Action, String, Args) -> term()

open(Name) -> {ok, Handle} | {error, Reason}

open(Name, ConnType) -> {ok, Handle} | {error, Reason}

open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}

open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle} | {error, Reason}

send(Connection, Cmd) -> ok | {error, Reason}

sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}

start_gen_log(Heading) -> term()

See also