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 ct_telnet may be used specifically with 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)
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}]}.
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.
DATA TYPES
connection() = handle() | {target_name() (see module ct), connection_type()} | target_name() (see module ct)
connection_type() = telnet | ts1 | ts2
handle() = handle() (see module ct_gen_conn)
Handle for a specific telnet connection.
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.
Functions
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 a node.
open(Name, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}
Equivalent to open(Name, ConnType, TargetMod, []).
open(Name, ConnType, TargetMod, Extra) -> {ok, Handle} | {error, Reason}
Name = target_name() (see module ct)
ConnType = connection_type()
TargetMod = atom()
Extra = term()
Handle = handle()
Open a telnet connection to the specified target.
The target must exist in a config file, and Name
is the name allocated to the target - either with
ct:require/2
or with a require
statement
in the test suite default data or the test case info function.
TargetMod
is a module which exports the functions
connect(Ip,Port,Extra)
and get_prompt_regexp()
for the given TargetType
.
close(Connection) -> ok | {error, Reason}
Connection = connection() (see module ct_telnet)
Close the telnet connection and stop the process managing it.
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). -----------------------------------------------------------------
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.
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).
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
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 function will always return when a prompt is found, unless
the ignore_prompt
options is used.
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 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.