1ct_telnet(3)               Erlang Module Definition               ct_telnet(3)
2
3
4

NAME

6       ct_telnet  - Common Test specific layer on top of Telnet client ct_tel‐
7       net_client.erl
8

DESCRIPTION

10       Common  Test  specific  layer  on  top   of   Telnet   client   ct_tel‐
11       net_client.erl.
12
13       Use  this  module to set up Telnet connections, send commands, and per‐
14       form string matching on the result. For information about  how  to  use
15       ct_telnet  and  configure connections, specifically for UNIX hosts, see
16       the unix_telnet manual page.
17
18       Default values defined in ct_telnet:
19
20         * Connection timeout (time to wait for connection) = 10 seconds
21
22         * Command timeout (time to wait for a command to return) = 10 seconds
23
24         * Max number of reconnection attempts = 3
25
26         * Reconnection  interval  (time  to  wait  in  between   reconnection
27           attempts) = 5 seconds
28
29         * Keep  alive  (sends  NOP to the server every 8 sec if connection is
30           idle) = true
31
32         * Polling limit (max number of times  to  poll  to  get  a  remaining
33           string terminated) = 0
34
35         * Polling interval (sleep time between polls) = 1 second
36
37         * The  TCP_NODELAY  option  for the telnet socket is disabled (set to
38           false) per default
39
40       These parameters can be modified by the user with the following config‐
41       uration term:
42
43        {telnet_settings, [{connect_timeout,Millisec},
44                           {command_timeout,Millisec},
45                           {reconnection_attempts,N},
46                           {reconnection_interval,Millisec},
47                           {keep_alive,Bool},
48                           {poll_limit,N},
49                           {poll_interval,Millisec},
50                           {tcp_nodelay,Bool}]}.
51
52       Millisec = integer(), N = integer()
53
54       Enter  the telnet_settings term in a configuration file included in the
55       test and ct_telnet retrieves the information automatically.
56
57       keep_alive can be specified per connection, if necessary. For  details,
58       see unix_telnet.
59

LOGGING

61       The default logging behavior of ct_telnet is to print information about
62       performed operations, commands, and their corresponding results to  the
63       test  case HTML log. The following is not printed to the HTML log: text
64       strings sent from the Telnet server that are not explicitly received by
65       a  ct_telnet function, such as expect/3. However, ct_telnet can be con‐
66       figured  to  use  a  special  purpose  event  handler,  implemented  in
67       ct_conn_log_h,  for  logging  all  Telnet traffic. To use this handler,
68       install a Common Test hook named cth_conn_log. Example (using the  test
69       suite information function):
70
71        suite() ->
72            [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].
73
74       conn_mod()  is the name of the Common Test module implementing the con‐
75       nection protocol, that is, ct_telnet.
76
77       The cth_conn_log hook performs unformatted logging of Telnet data to  a
78       separate  text  file. All Telnet communication is captured and printed,
79       including any data sent from the server. The link to this text file  is
80       located at the top of the test case HTML log.
81
82       By  default,  data  for  all Telnet connections is logged in one common
83       file (named default), which can get messy,  for  example,  if  multiple
84       Telnet  sessions are running in parallel. Therefore a separate log file
85       can be created for each connection. To configure this, use hook  option
86       hosts  and  list the names of the servers/connections to be used in the
87       suite. The connections must be named for  this  to  work  (see  ct_tel‐
88       net:open/1,2,3,4).
89
90       Hook  option  log_type can be used to change the cth_conn_log behavior.
91       The default value of this option is raw, which results in the  behavior
92       described  above. If the value is set to html, all Telnet communication
93       is printed to the test case HTML log instead.
94
95       All cth_conn_log hook options described can also be specified in a con‐
96       figuration file with configuration variable ct_conn_log.
97
98       Example:
99
100        {ct_conn_log, [{ct_telnet,[{log_type,raw},
101                                   {hosts,[key_or_name()]}]}]}
102
103   Note:
104       Hook options specified in a configuration file overwrite any hard-coded
105       hook options in the test suite.
106
107
108       Logging Example:
109
110       The following ct_hooks statement causes printing of Telnet  traffic  to
111       separate  logs for the connections server1 and server2. Traffic for any
112       other connections is logged in the default Telnet log.
113
114        suite() ->
115            [{ct_hooks,
116              [{cth_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}]}].
117
118       As previously explained, this specification can also be provided by  an
119       entry like the following in a configuration file:
120
121        {ct_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}.
122
123       In  this case the ct_hooks statement in the test suite can look as fol‐
124       lows:
125
126        suite() ->
127            [{ct_hooks, [{cth_conn_log, []}]}].
128

DATA TYPES

130         connection() = handle() | {target_name(), connection_type()}  |  tar‐
131         get_name():
132
133
134           For target_name(), see module ct.
135
136         connection_type() = telnet | ts1 | ts2:
137
138
139         handle() = handle():
140
141
142           Handle for a specific Telnet connection, see module ct.
143
144         prompt_regexp() = string():
145
146
147           Regular  expression  matching  all  possible prompts for a specific
148           target type. regexp must not have any groups, that is, when  match‐
149           ing,  re:run/3  (in STDLIB) must return a list with one single ele‐
150           ment.
151

EXPORTS

153       close(Connection) -> ok | {error, Reason}
154
155              Types:
156
157                 Connection = connection()
158                 Reason = term()
159
160              Closes the Telnet connection and stops the process managing it.
161
162              A connection can be associated with a target name and/or a  han‐
163              dle. If Connection has no associated target name, it can only be
164              closed with the handle value (see ct_telnet:open/4).
165
166       cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}
167
168              Equivalent to ct_telnet:cmd(Connection, Cmd, []).
169
170       cmd(Connection, Cmd, Opts) -> {ok, Data} | {error, Reason}
171
172              Types:
173
174                 Connection = connection()
175                 Cmd = string()
176                 Opts = [Opt]
177                 Opt = {timeout, timeout()} | {newline, boolean() | string()}
178                 Data = [string()]
179                 Reason = term()
180
181              Sends a command through Telnet and waits for prompt.
182
183              By default, this function adds "\n" to the end of the  specified
184              command.  If  this  is  not desired, use option {newline,false}.
185              This is necessary, for  example,  when  sending  Telnet  command
186              sequences  prefixed  with  character Interpret As Command (IAC).
187              Option {newline,string()} can also be used if a  different  line
188              end than "\n" is required, for instance {newline,"\r\n"}, to add
189              both carriage return and newline characters.
190
191              Option timeout specifies how  long  the  client  must  wait  for
192              prompt.  If  the time expires, the function returns {error,time‐
193              out}. For information about the default value  for  the  command
194              timeout, see the list of default values in the beginning of this
195              module.
196
197       cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}
198
199              Equivalent to ct_telnet:cmdf(Connection, CmdFormat, Args, []).
200
201       cmdf(Connection, CmdFormat, Args, Opts) -> {ok, Data} | {error, Reason}
202
203              Types:
204
205                 Connection = connection()
206                 CmdFormat = string()
207                 Args = list()
208                 Opts = [Opt]
209                 Opt = {timeout, timeout()} | {newline, boolean() | string()}
210                 Data = [string()]
211                 Reason = term()
212
213              Sends a Telnet command and  waits  for  prompt  (uses  a  format
214              string and a list of arguments to build the command).
215
216              For details, see ct_telnet:cmd/3.
217
218       expect(Connection, Patterns) -> term()
219
220              Equivalent to ct_telnet:expect(Connections, Patterns, []).
221
222       expect(Connection,  Patterns,  Opts)  ->  {ok, Match} | {ok, MatchList,
223       HaltReason} | {error, Reason}
224
225              Types:
226
227                 Connection = connection()
228                 Patterns = Pattern | [Pattern]
229                 Pattern = string() | {Tag,  string()}  |  prompt  |  {prompt,
230                 Prompt}
231                 Prompt = string()
232                 Tag = term()
233                 Opts = [Opt]
234                 Opt  =  {idle_timeout,  IdleTimeout} | {total_timeout, Total‐
235                 Timeout} | repeat | {repeat, N} | sequence | {halt,  HaltPat‐
236                 terns}  | ignore_prompt | no_prompt_check | wait_for_prompt |
237                 {wait_for_prompt, Prompt}
238                 IdleTimeout = infinity | integer()
239                 TotalTimeout = infinity | integer()
240                 N = integer()
241                 HaltPatterns = Patterns
242                 MatchList = [Match]
243                 Match = RxMatch | {Tag, RxMatch} | {prompt, Prompt}
244                 RxMatch = [string()]
245                 HaltReason = done | Match
246                 Reason = timeout | {prompt, Prompt}
247
248              Gets data from Telnet and waits for the expected pattern.
249
250              Pattern can be a POSIX regular expression. The function  returns
251              when  a  pattern  is  successfully matched (at least one, in the
252              case of multiple patterns).
253
254              RxMatch is a list of matched strings. It looks as follows [Full‐
255              Match, SubMatch1, SubMatch2, ...], where FullMatch is the string
256              matched by the whole regular expression, and  SubMatchN  is  the
257              string  that  matched subexpression number N. Subexpressions are
258              denoted with '(' ')' in the regular expression.
259
260              If a Tag is specified, the  returned  Match  also  includes  the
261              matched Tag. Otherwise, only RxMatch is returned.
262
263              Options:
264
265                idle_timeout:
266                  Indicates that the function must return if the Telnet client
267                  is idle (that is, if no data  is  received)  for  more  than
268                  IdleTimeout milliseconds. Default time-out is 10 seconds.
269
270                total_timeout:
271                  Sets  a  time limit for the complete expect operation. After
272                  TotalTimeout  milliseconds,  {error,timeout}  is   returned.
273                  Default is infinity (that is, no time limit).
274
275                ignore_prompt | no_prompt_check:
276                  >The  function returns when a prompt is received, even if no
277                  pattern has yet been matched, and {error,{prompt,Prompt}} is
278                  returned. However, this behavior can be modified with option
279                  ignore_prompt or option no_prompt_check, which tells  expect
280                  to return only when a match is found or after a time-out.
281
282                ignore_prompt:
283                  ct_telnet ignores any prompt found. This option is useful if
284                  data sent by the  server  can  include  a  pattern  matching
285                  prompt  regexp  (as  returned  by  TargedMod:get_prompt_reg‐
286                  exp/0), but is not to not cause the function to return.
287
288                no_prompt_check:
289                  ct_telnet does not search for a prompt at all. This is  use‐
290                  ful if, for example, Pattern itself matches the prompt.
291
292                wait_for_prompt:
293                  Forces ct_telnet to wait until the prompt string is received
294                  before  returning  (even  if  a  pattern  has  already  been
295                  matched).   This  is  equal  to  calling  expect(Conn,  Pat‐
296                  terns++[{prompt,Prompt}],  [sequence|Opts]).   Notice   that
297                  option  idle_timeout  and total_timeout can abort the opera‐
298                  tion of waiting for prompt.
299
300                repeat | repeat, N:
301                  The pattern(s) must be matched multiple times. If N is spec‐
302                  ified,  the pattern(s) are matched N times, and the function
303                  returns HaltReason = done. This option can be interrupted by
304                  one or more HaltPatterns. MatchList is always returned, that
305                  is, a list of Match instead of only one Match. Also HaltRea‐
306                  son is returned.
307
308                sequence:
309                  All  patterns  must be matched in a sequence. A match is not
310                  concluded until all patterns are matched. This option can be
311                  interrupted by one or more HaltPatterns. MatchList is always
312                  returned, that is, a list  of  Match  instead  of  only  one
313                  Match. Also HaltReason is returned.
314
315              Example 1:
316
317               expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[sequence,{halt,[{nnn,"NNN"}]}])
318
319              First  this  tries  to match "ABC", and then "XYZ", but if "NNN"
320              appears, the function  returns  {error,{nnn,["NNN"]}}.  If  both
321              "ABC"  and  "XYZ"  are  matched,  the function returns {ok,[Abc‐
322              Match,XyzMatch]}.
323
324              Example 2:
325
326               expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[{repeat,2},{halt,[{nnn,"NNN"}]}])
327
328              This tries to match "ABC" or "XYZ" twice. If "NNN" appears,  the
329              function returns HaltReason = {nnn,["NNN"]}.
330
331              Options  repeat and sequence can be combined to match a sequence
332              multiple times.
333
334       get_data(Connection) -> {ok, Data} | {error, Reason}
335
336              Types:
337
338                 Connection = connection()
339                 Data = [string()]
340                 Reason = term()
341
342              Gets all data received by the Telnet client since the last  com‐
343              mand  was sent. Only newline-terminated strings are returned. If
344              the last received string has not yet been terminated,  the  con‐
345              nection  can  be  polled  automatically until the string is com‐
346              plete.
347
348              The polling feature is controlled by  the  configuration  values
349              poll_limit  and  poll_interval  and is by default disabled. This
350              means that the function immediately returns all complete strings
351              received and saves a remaining non-terminated string for a later
352              get_data call.
353
354       open(Name) -> {ok, Handle} | {error, Reason}
355
356              Equivalent to ct_telnet:open(Name, telnet).
357
358       open(Name, ConnType) -> {ok, Handle} | {error, Reason}
359
360              Types:
361
362                 Name = target_name()
363                 ConnType = connection_type()
364                 Handle = handle()
365                 Reason = term()
366
367              Opens a Telnet connection to the specified target host.
368
369       open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}
370
371              Equivalent to ct_telnet:ct_telnet:open(KeyOrName, ConnType, Tar‐
372              getMod, []).
373
374       open(KeyOrName,  ConnType,  TargetMod, Extra) -> {ok, Handle} | {error,
375       Reason}
376
377              Types:
378
379                 KeyOrName = Key | Name
380                 Key = atom()
381                 Name = target_name()
382                 ConnType = connection_type()
383                 TargetMod = atom()
384                 Extra = term()
385                 Handle = handle()
386                 Reason = term()
387
388              Opens a Telnet connection to the specified target host.
389
390              The target data must exist in a configuration file. The  connec‐
391              tion  can be associated with Name and/or the returned Handle. To
392              allocate a name for the target, use one of the following  alter‐
393              natives:
394
395                * ct:require/2 in a test case
396
397                * A  require  statement  in  the  suite  information  function
398                  (suite/0)
399
400                * A require statement in a test case information function
401
402              If you want the connection to be associated with Handle only (if
403              you,  for example, need to open multiple connections to a host),
404              use Key, the configuration variable name, to specify the target.
405              Notice  that  a connection without an associated target name can
406              only be closed with the Handle value.
407
408              TargetMod is a module that  exports  the  functions  connect(Ip,
409              Port,  KeepAlive,  Extra) and get_prompt_regexp() for the speci‐
410              fied TargetType (for example, unix_telnet).
411
412              For target_name(), see module ct.
413
414              See also ct:require/2.
415
416       send(Connection, Cmd) -> ok | {error, Reason}
417
418              Equivalent to ct_telnet:send(Connection, Cmd, []).
419
420       send(Connection, Cmd, Opts) -> ok | {error, Reason}
421
422              Types:
423
424                 Connection = connection()
425                 Cmd = string()
426                 Opts = [Opt]
427                 Opt = {newline, boolean() | string()}
428                 Reason = term()
429
430              Sends a Telnet command and returns immediately.
431
432              By default, this function adds "\n" to the end of the  specified
433              command.  If  this is not desired, option {newline,false} can be
434              used. This is necessary, for example, when sending  Telnet  com‐
435              mand  sequences  prefixed  with  character  Interpret As Command
436              (IAC). Option {newline,string()} can also be used if a different
437              line  end  than "\n" is required, for instance {newline,"\r\n"},
438              to add both carriage return and newline characters.
439
440              The resulting output from the command can be read  with  ct_tel‐
441              net:get_data/2 or ct_telnet:expect/2,3.
442
443       sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}
444
445              Equivalent to ct_telnet:sendf(Connection, CmdFormat, Args, []).
446
447       sendf(Connection, CmdFormat, Args, Opts) -> ok | {error, Reason}
448
449              Types:
450
451                 Connection = connection()
452                 CmdFormat = string()
453                 Args = list()
454                 Opts = [Opt]
455                 Opt = {newline, boolean() | string()}
456                 Reason = term()
457
458              Sends  a  Telnet  command and returns immediately (uses a format
459              string and a list of arguments to build the command).
460
461              For details, see ct_telnet:send/3.
462

SEE ALSO

464       unix_telnet
465
466
467
468Ericsson AB                    common_test 1.18                   ct_telnet(3)
Impressum