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