1ct_telnet(3) Erlang Module Definition ct_telnet(3)
2
6 ct_telnet - Common Test specific layer on top of Telnet client ct_tel‐
7 net_client.erl
8
10 Common Test specific layer on top of Telnet client ct_tel‐
11 net_client.erl.
12 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 Default values defined in ct_telnet:
19 * Connection timeout (time to wait for connection) = 10 seconds
21 * Command timeout (time to wait for a command to return) = 10 seconds
23 * Max number of reconnection attempts = 3
25 * Reconnection interval (time to wait in between reconnection
27 attempts) = 5 seconds
28 * Keep alive (sends NOP to the server every 8 sec if connection is
30 idle) = true
31 * Polling limit (max number of times to poll to get a remaining
33 string terminated) = 0
34 * Polling interval (sleep time between polls) = 1 second
36 * The TCP_NODELAY option for the telnet socket is disabled (set to
38 false) per default
39 These parameters can be modified by the user with the following config‐
41 uration term:
42 {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 Millisec = integer(), N = integer()
53 Enter the telnet_settings term in a configuration file included in the
55 test and ct_telnet retrieves the information automatically.
56 keep_alive can be specified per connection, if necessary. For details,
58 see unix_telnet.
59
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 suite() ->
72 [{ct_hooks, [{cth_conn_log, [{conn_mod(),hook_options()}]}]}].
73 conn_mod() is the name of the Common Test module implementing the con‐
75 nection protocol, that is, ct_telnet.
76 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 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 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 All cth_conn_log hook options described can also be specified in a con‐
96 figuration file with configuration variable ct_conn_log.
97 Example:
99 {ct_conn_log, [{ct_telnet,[{log_type,raw},
101 {hosts,[key_or_name()]}]}]}
102 Note:
104 Hook options specified in a configuration file overwrite any hard-coded
105 hook options in the test suite.
106 Logging Example:
109 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 suite() ->
115 [{ct_hooks,
116 [{cth_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}]}].
117 As previously explained, this specification can also be provided by an
119 entry like the following in a configuration file:
120 {ct_conn_log, [{ct_telnet,[{hosts,[server1,server2]}]}]}.
122 In this case the ct_hooks statement in the test suite can look as fol‐
124 lows:
125 suite() ->
127 [{ct_hooks, [{cth_conn_log, []}]}].
128
130 connection() = handle() | {target_name(), connection_type()} | tar‐
131 get_name():
132 For target_name(), see module ct.
135 connection_type() = telnet | ts1 | ts2:
137 handle() = handle():
140 Handle for a specific Telnet connection, see module ct.
143 prompt_regexp() = string():
145 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
153 close(Connection) -> ok | {error, Reason}
154 Types:
156 Connection = connection()
158 Reason = term()
159 Closes the Telnet connection and stops the process managing it.
161 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 cmd(Connection, Cmd) -> {ok, Data} | {error, Reason}
167 Equivalent to ct_telnet:cmd(Connection, Cmd, []).
169 cmd(Connection, Cmd, Opts) -> {ok, Data} | {error, Reason}
171 Types:
173 Connection = connection()
175 Cmd = string()
176 Opts = [Opt]
177 Opt = {timeout, timeout()} | {newline, boolean() | string()}
178 Data = [string()]
179 Reason = term()
180 Sends a command through Telnet and waits for prompt.
182 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 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 cmdf(Connection, CmdFormat, Args) -> {ok, Data} | {error, Reason}
198 Equivalent to ct_telnet:cmdf(Connection, CmdFormat, Args, []).
200 cmdf(Connection, CmdFormat, Args, Opts) -> {ok, Data} | {error, Reason}
202 Types:
204 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 Sends a Telnet command and waits for prompt (uses a format
214 string and a list of arguments to build the command).
215 For details, see ct_telnet:cmd/3.
217 expect(Connection, Patterns) -> term()
219 Equivalent to ct_telnet:expect(Connections, Patterns, []).
221 expect(Connection, Patterns, Opts) -> {ok, Match} | {ok, MatchList,
223 HaltReason} | {error, Reason}
224 Types:
226 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 Gets data from Telnet and waits for the expected pattern.
249 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 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 If a Tag is specified, the returned Match also includes the
261 matched Tag. Otherwise, only RxMatch is returned.
262 Options:
264 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 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 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 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 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 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 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 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 Example 1:
316 expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[sequence,{halt,[{nnn,"NNN"}]}])
318 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 Example 2:
325 expect(Connection,[{abc,"ABC"},{xyz,"XYZ"}],[{repeat,2},{halt,[{nnn,"NNN"}]}])
327 This tries to match "ABC" or "XYZ" twice. If "NNN" appears, the
329 function returns HaltReason = {nnn,["NNN"]}.
330 Options repeat and sequence can be combined to match a sequence
332 multiple times.
333 get_data(Connection) -> {ok, Data} | {error, Reason}
335 Types:
337 Connection = connection()
339 Data = [string()]
340 Reason = term()
341 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 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 open(Name) -> {ok, Handle} | {error, Reason}
355 Equivalent to ct_telnet:open(Name, telnet).
357 open(Name, ConnType) -> {ok, Handle} | {error, Reason}
359 Types:
361 Name = target_name()
363 ConnType = connection_type()
364 Handle = handle()
365 Reason = term()
366 Opens a Telnet connection to the specified target host.
368 open(KeyOrName, ConnType, TargetMod) -> {ok, Handle} | {error, Reason}
370 Equivalent to ct_telnet:ct_telnet:open(KeyOrName, ConnType, Tar‐
372 getMod, []).
373 open(KeyOrName, ConnType, TargetMod, Extra) -> {ok, Handle} | {error,
375 Reason}
376 Types:
378 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 Opens a Telnet connection to the specified target host.
389 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 * ct:require/2 in a test case
396 * A require statement in the suite information function
398 (suite/0)
399 * A require statement in a test case information function
401 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 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 For target_name(), see module ct.
413 See also ct:require/2.
415 send(Connection, Cmd) -> ok | {error, Reason}
417 Equivalent to ct_telnet:send(Connection, Cmd, []).
419 send(Connection, Cmd, Opts) -> ok | {error, Reason}
421 Types:
423 Connection = connection()
425 Cmd = string()
426 Opts = [Opt]
427 Opt = {newline, boolean() | string()}
428 Reason = term()
429 Sends a Telnet command and returns immediately.
431 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 The resulting output from the command can be read with ct_tel‐
441 net:get_data/2 or ct_telnet:expect/2,3.
442 sendf(Connection, CmdFormat, Args) -> ok | {error, Reason}
444 Equivalent to ct_telnet:sendf(Connection, CmdFormat, Args, []).
446 sendf(Connection, CmdFormat, Args, Opts) -> ok | {error, Reason}
448 Types:
450 Connection = connection()
452 CmdFormat = string()
453 Args = list()
454 Opts = [Opt]
455 Opt = {newline, boolean() | string()}
456 Reason = term()
457 Sends a Telnet command and returns immediately (uses a format
459 string and a list of arguments to build the command).
460 For details, see ct_telnet:send/3.
462
464 unix_telnet
465Ericsson AB common_test 1.18.2 ct_telnet(3)