Telnet

Library version: 3.2.2

Library scope: SUITE
Named arguments: supported

Introduction
A test library providing communication over Telnet connections.

Telnet is Robot Framework's standard library that makes it possible to connect to

Telnet servers and execute commands on the opened connections.

Table of contents

• Connections
• Writing and reading
• Configuration
• Terminal emulation
• Logging
• Time string format
• Boolean arguments
• Importing
• Shortcuts
• Keywords

Connections
The first step of using Telnet is opening a connection with Open Connection
keyword. Typically the next step is logging in with Login keyword, and in the end the
opened connection can be closed with Close Connection.

It is possible to open multiple connections and switch the active one using Switch
Connection. Close All Connections can be used to close all the connections, which is
especially useful in suite teardowns to guarantee that all connections are always
closed.

Writing and reading

After opening a connection and possibly logging in, commands can be executed or
text written to the connection for other reasons using Write and Write Bare keywords.
The main difference between these two is that the former adds a configurable newline
after the text automatically.
After writing something to the connection, the resulting output can be read using
Read, Read Until, Read Until Regexp, and Read Until Prompt keywords. Which one
to use depends on the context, but the latest one is often the most convenient.

As a convenience when running a command, it is possible to use Execute Command

that simply uses Write and Read Until Prompt internally. Write Until Expected
Output is useful if you need to wait until writing something produces a desired output.

Written and read text is automatically encoded/decoded using a configured encoding.

The ANSI escape codes, like cursor movement and color codes, are normally returned
as part of the read operation. If an escape code occurs in middle of a search pattern it
may also prevent finding the searched string. Terminal emulation can be used to
process these escape codes as they would be if a real terminal would be in use.

Configuration
Many aspects related the connections can be easily configured either globally or per
connection basis. Global configuration is done when library is imported, and these
values can be overridden per connection by Open Connection or with setting specific
keywords Set Timeout, Set Newline, Set Prompt, Set Encoding, Set Default Log
Level and Set Telnetlib Log Level.

Values of environ_user, window_size, terminal_emulation, and terminal_type

can not be changed after opening the connection.

Timeout

Timeout defines how long is the maximum time to wait when reading output. It is
used internally by Read Until, Read Until Regexp, Read Until Prompt, and Login
keywords. The default value is 3 seconds.

Connection Timeout

Connection Timeout defines how long is the maximum time to wait when opening the
telnet connection. It is used internally by Open Connection. The default value is the
system global default timeout.

New in Robot Framework 2.9.2.

Newline

Newline defines which line separator Write keyword should use. The default value is
CRLF that is typically used by Telnet connections.

Newline can be given either in escaped format using \n and \r or with special LF and
CR syntax.

Examples:
Set Newline \n
Set Newline CRLF

Prompt

Often the easiest way to read the output of a command is reading all the output until
the next prompt with Read Until Prompt. It also makes it easier, and faster, to verify
did Login succeed.

Prompt can be specified either as a normal string or a regular expression. The latter is
especially useful if the prompt changes as a result of the executed commands. Prompt
can be set to be a regular expression by giving prompt_is_regexp argument a true
value (see Boolean arguments).

Examples:

Open Connection lolcathost prompt=$

Set Prompt (> |# ) prompt_is_regexp=true

Encoding

To ease handling text containing non-ASCII characters, all written text is encoded and
read text decoded by default. The default encoding is UTF-8 that works also with
ASCII. Encoding can be disabled by using a special encoding value NONE. This is
mainly useful if you need to get the bytes received from the connection as-is.

Notice that when writing to the connection, only Unicode strings are encoded using
the defined encoding. Byte strings are expected to be already encoded correctly.
Notice also that normal text in test data is passed to the library as Unicode and you
need to use variables to use bytes.

It is also possible to configure the error handler to use if encoding or decoding

characters fails. Accepted values are the same that encode/decode functions in Python
strings accept. In practice the following values are the most useful:

• ignore: ignore characters that cannot be encoded (default)

• strict: fail if characters cannot be encoded
• replace: replace characters that cannot be encoded with a replacement
character

Examples:

Open Connection lolcathost encoding=Latin1 encoding_errors=strict

Set Encoding ISO-8859-15
Set Encoding errors=ignore
Default log level

Default log level specifies the log level keywords use for logging unless they are
given an explicit log level. The default value is INFO, and changing it, for example, to
DEBUG can be a good idea if there is lot of unnecessary output that makes log files big.

Terminal type

By default the Telnet library does not negotiate any specific terminal type with the
server. If a specific terminal type, for example vt100, is desired, the terminal type can
be configured in importing and with Open Connection.

Window size

Window size for negotiation with the server can be configured when importing the
library and with Open Connection.

USER environment variable

Telnet protocol allows the USER environment variable to be sent when connecting to
the server. On some servers it may happen that there is no login prompt, and on those
cases this configuration option will allow still to define the desired username. The
option environ_user can be used in importing and with Open Connection.

Terminal emulation
Telnet library supports terminal emulation with Pyte. Terminal emulation will process
the output in a virtual screen. This means that ANSI escape codes, like cursor
movements, and also control characters, like carriage returns and backspaces, have the
same effect on the result as they would have on a normal terminal screen. For
example the sequence acdc\x1b[3Dbba will result in output abba.

Terminal emulation is taken into use by giving terminal_emulation argument a true

value (see Boolean arguments) either in the library initialization or with Open
Connection.

As Pyte approximates vt-style terminal, you may also want to set the terminal type as
vt100. We also recommend that you increase the window size, as the terminal
emulation will break all lines that are longer than the window row length.

When terminal emulation is used, the newline and encoding can not be changed
anymore after opening the connection.

Examples:

Open
lolcatho terminal_emulation=T terminal_type=vt1 window_size=400x
Connectio
st rue 00 100
n
As a prerequisite for using terminal emulation, you need to have Pyte installed. Due to
backwards incompatible changes in Pyte, different Robot Framework versions support
different Pyte versions:

• Pyte 0.6 and newer are supported by Robot Framework 3.0.3. Latest Pyte
version can be installed (or upgraded) with pip install --upgrade pyte.
• Pyte 0.5.2 and older are supported by Robot Framework 3.0.2 and earlier. Pyte
0.5.2 can be installed with pip install pyte==0.5.2.

Logging
All keywords that read something log the output. These keywords take the log level to
use as an optional argument, and if no log level is specified they use the configured
default value.

The valid log levels to use are TRACE, DEBUG, INFO (default), and WARN. Levels below
INFO are not shown in log files by default whereas warnings are shown more
prominently.

The telnetlib module used by this library has a custom logging system for logging
content it sends and receives. By default these messages are written using TRACE
level, but the level is configurable with the telnetlib_log_level option either in
the library initialization, to the Open Connection or by using the Set Telnetlib Log
Level keyword to the active connection. Special level NONE con be used to disable the
logging altogether.

Time string format

Timeouts and other times used must be given as a time string using format like 15
seconds or 1min 10s. If the timeout is given as just a number, for example, 10 or
1.5, it is considered to be seconds. The time string format is described in more detail
in an appendix of Robot Framework User Guide.

Boolean arguments
Some keywords accept arguments that are handled as Boolean values true or false. If
such an argument is given as a string, it is considered false if it is an empty string or
equal to FALSE, NONE, NO, OFF or 0, case-insensitively. Other strings are considered
true regardless their value, and other argument types are tested using the same rules as
in Python.

True examples:

Open # Strings are generally

lolcathost terminal_emulation=True
Connection true.
Open
lolcathost terminal_emulation=yes # Same as the above.
Connection
Open
lolcathost terminal_emulation=${TRUE} # Python True is true.
Connection
Open # Numbers other than 0
lolcathost terminal_emulation=${42}
Connection are true.

False examples:

Open # String false is

lolcathost terminal_emulation=False
Connection false.
Open # Also string no is
lolcathost terminal_emulation=no
Connection false.
Open # Empty string is
lolcathost terminal_emulation=${EMPTY}
Connection false.
Open # Python False is
lolcathost terminal_emulation=${FALSE}
Connection false.

Considering string NONE false is new in Robot Framework 3.0.3 and considering also
OFF and 0 false is new in Robot Framework 3.1.

Importing
Arguments Documentation
timeout=3
Telnet library can be imported with optional configuration
seconds,
parameters.
newline=CRLF,
prompt=None,
prompt_is_regex Configuration parameters are used as default values when new
p=False, connections are opened with Open Connection keyword. They
encoding=UTF- can also be overridden after opening the connection using the Set
8, ... keywords. See these keywords as well as Configuration,
encoding_errors= Terminal emulation and Logging sections above for more
ignore, information about these parameters and their possible values.
default_log_level
=INFO, See Time string format and Boolean arguments sections for
window_size=No information about using arguments accepting times and Boolean
ne, values, respectively.
environ_user=No
ne, Examples (use only one of these):
terminal_emulati
on=False, Sett Val Com
Value Value Value
terminal_type=N ing ue ment
one, #
telnetlib_log_lev Libr Tel defaul
el=TRACE, ary net t
connection_time values
out=None
 # set
Libr Tel only
5 seconds
ary net timeo
ut
# set
newli
ne and
encod
Libr Tel encoding=IS ing
newline=LF
ary net O-8859-1 using
name
d
argum
ents
# set
Libr Tel
prompt=$ promp
ary net
t
# set
promp
t as a
Libr Tel prompt_is_re
prompt=(> |# ) regula
ary net gexp=yes
r
expres
sion
# use
termin
al
emula
tion
with
Libr Tel terminal_emulat terminal_type window_size define
ary net ion=True =vt100 =400x100 d
windo
w size
and
termin
al
type
#
disabl
e
loggin
Libr Tel telnetlib_log_le
g
ary net vel=NONE
messa
ges
from
the
 underl
ying
telnetl
ib

Shortcuts
List style: Compact Expanded
Close All Connections
Close Connection
Execute Command
Login
Open Connection
Read
Read Until
Read Until Prompt
Read Until Regexp
Set Default Log Level
Set Encoding
Set Newline
Set Prompt
Set Telnetlib Log Level
Set Timeout
Switch Connection
Write
Write Bare
Write Control Character
Write Until Expected Output

Keywords
Keyword Arguments Documentation
Closes all open connections and empties
the connection cache.

If multiple connections are opened, this

keyword should be used in a test or suite
Close All teardown to make sure that all connections
Connection are closed. It is not an error is some of the
s connections have already been closed by
Close Connection.

After this keyword, new indexes returned

by Open Connection keyword are reset to
1.
Close Closes the current Telnet connection.
loglevel=None
Connection
 Remaining output in the connection is read,
logged, and returned. It is not an error to
close an already closed connection.

Use Close All Connections if you want to

make sure all opened connections are
closed.

See Logging section for more information

about log levels.
Executes the given command and reads,
logs, and returns everything until the
prompt.

This keyword requires the prompt to be

configured either in importing or with
Open Connection or Set Prompt keyword.

This is a convenience keyword that uses

Write and Read Until Prompt internally.
command, Following two examples are thus
Execute
loglevel=None, functionally identical:
Command
strip_prompt=False
${out} = Execute Command pwd
Write pwd
${out} = Read Until Prompt

See Logging section for more information

about log levels and Read Until Prompt for
more information about the strip_prompt
parameter.
Logs in to the Telnet server with the given
user information.

This keyword reads from the connection

username, until the login_prompt is encountered and
password, then types the given username. Then it
login_prompt=login: , reads until the password_prompt and types
password_prompt=Passwo the given password. In both cases a
Login
rd: , newline is appended automatically and the
login_timeout=1 second, connection specific timeout used when
login_incorrect=Login waiting for outputs.
incorrect
How logging status is verified depends on
whether a prompt is set for this connection
or not:
 1) If the prompt is set, this keyword reads
the output until the prompt is found using
the normal timeout. If no prompt is found,
login is considered failed and also this
keyword fails. Note that in this case both
login_timeout and login_incorrect
arguments are ignored.

2) If the prompt is not set, this keywords

sleeps until login_timeout and then reads
all the output available on the connection.
If the output contains login_incorrect
text, login is considered failed and also this
keyword fails.

See Configuration section for more

information about setting newline, timeout,
and prompt.
Opens a new Telnet connection to the given
host and port.

The timeout, newline, prompt,

prompt_is_regexp, encoding,
host,
default_log_level, window_size,
alias=None,
environ_user, terminal_emulation,
port=23,
terminal_type and
timeout=None,
telnetlib_log_level arguments get
newline=None,
prompt=None, default values when the library is imported.
prompt_is_regexp=False, Setting them here overrides those values
Open encoding=None, for the opened connection. See
Connection encoding_errors=None, Configuration, Terminal emulation and
default_log_level=None, Logging sections for more information
window_size=None, about these parameters and their possible
environ_user=None, values.
terminal_emulation=None,
terminal_type=None, Possible already opened connections are
telnetlib_log_level=None, cached and it is possible to switch back to
connection_timeout=None them using Switch Connection keyword. It
is possible to switch either using explicitly
given alias or using index returned by this
keyword. Indexing starts from 1 and is
reset back to it by Close All Connections
keyword.
Reads everything that is currently available
in the output.
Read loglevel=None
Read output is both returned and logged.
See Logging section for more information
about log levels.
 Reads output until expected text is
encountered.

Text up to and including the match is

returned and logged. If no match is found,
expected, this keyword fails. How much to wait for
Read Until
loglevel=None the output depends on the configured
timeout.

See Logging section for more information

about log levels. Use Read Until Regexp if
more complex matching is needed.
Reads output until the prompt is
encountered.

This keyword requires the prompt to be

configured either in importing or with
Open Connection or Set Prompt keyword.

By default, text up to and including the

prompt is returned and logged. If no
prompt is found, this keyword fails. How
much to wait for the output depends on the
Read Until loglevel=None, configured timeout.
Prompt strip_prompt=False
If you want to exclude the prompt from the
returned output, set strip_prompt to a true
value (see Boolean arguments). If your
prompt is a regular expression, make sure
that the expression spans the whole prompt,
because only the part of the output that
matches the regular expression is stripped
away.

See Logging section for more information

about log levels.
Reads output until any of the expected
regular expressions match.

This keyword accepts any number of

regular expressions patterns or compiled
Python regular expression objects as
Read Until
*expected arguments. Text up to and including the
Regexp
first match to any of the regular expressions
is returned and logged. If no match is
found, this keyword fails. How much to
wait for the output depends on the
configured timeout.
 If the last given argument is a valid log
level, it is used as loglevel similarly as
with Read Until keyword.

See the documentation of Python re module

for more information about the supported
regular expression syntax. Notice that
possible backslashes need to be escaped in
Robot Framework test data.

Examples:

Read Until
(#|$)
Regexp
Read Until
first_regexp second_regexp
Regexp
Read Until \\d{4}-\\d{2}-
DEBUG
Regexp \\d{2}
Sets the default log level used for logging
in the current connection.

The old default log level is returned and

Set Default
level can be used to restore the log level later.
Log Level
See Configuration section for more
information about global and connection
specific configuration.
Sets the encoding to use for writing and
reading in the current connection.

The given encoding specifies the encoding

to use when written/read text is
encoded/decoded, and errors specifies the
error handler to use if encoding/decoding
fails. Either of these can be omitted and in
that case the old value is not affected. Use
string NONE to disable encoding altogether.
Set encoding=None,
Encoding errors=None
See Configuration section for more
information about encoding and error
handlers, as well as global and connection
specific configuration in general.

The old values are returned and can be used

to restore the encoding and the error
handler later. See Set Prompt for a similar
example.
 If terminal emulation is used, the encoding
can not be changed on an open connection.
Sets the newline used by Write keyword in
the current connection.

The old newline is returned and can be

used to restore the newline later. See Set
Timeout for a similar example.
Set
newline
Newline
If terminal emulation is used, the newline
can not be changed on an open connection.

See Configuration section for more

information about global and connection
specific configuration.
Sets the prompt used by Read Until Prompt
and Login in the current connection.

If prompt_is_regexp is given a true value

(see Boolean arguments), the given prompt
is considered to be a regular expression.

The old prompt is returned and can be used

to restore the prompt later.

Example:

prompt, ${prompt} ${regexp} = Set Prompt $

Set Prompt
prompt_is_regexp=False
Do Something
Set Prompt ${prompt} ${regexp}

See the documentation of Python re module

for more information about the supported
regular expression syntax. Notice that
possible backslashes need to be escaped in
Robot Framework test data.

See Configuration section for more

information about global and connection
specific configuration.
Sets the log level used for logging in the
underlying telnetlib.
Set
Telnetlib level
Note that telnetlib can be very noisy
Log Level
thus using the level NONE can shutdown the
messages generated by this library.
 Sets the timeout used for waiting output in
the current connection.

Read operations that expect some output to

appear (Read Until, Read Until Regexp,
Read Until Prompt, Login) use this timeout
and fail if the expected output does not
appear before this timeout expires.

The timeout must be given in time string

format. The old timeout is returned and can
be used to restore the timeout later.
Set
timeout
Timeout Example:

Set 2 minute 30
${old} =
Timeout seconds
Do
Something
Set Timeout ${old}

See Configuration section for more

information about global and connection
specific configuration.
Switches between active connections using
an index or an alias.

Aliases can be given to Open Connection

keyword which also always returns the
connection index.

This keyword returns the index of previous

active connection.

Switch Example:
index_or_alias
Connection
Open
Connectio myhost.net
n
Login john secret
some
Write
command
Open
yourhost.co 2nd
Connectio
m conn
n
 passwor
Login root
d
Write another cmd
${old Switch #
1
index}= Connection index
Write something
Switch
Connectio 2nd conn # alias
n
Write whatever
# back
Switch
${old to
Connectio
index} origina
n
l
[Teardown Close All
] Connections

The example above expects that there were

no other open connections when opening
the first one, because it used index 1 when
switching to the connection later. If you are
not sure about that, you can store the index
into a variable as shown below.

Open
${index} = myhost.net
Connection
Do Something
Switch
${index}
Connection
Writes the given text plus a newline into
the connection.

The newline character sequence to use can

be configured both globally and per
connection basis. The default value is CRLF.

text, This keyword consumes the written text,

Write
loglevel=None until the added newline, from the output
and logs and returns it. The given text itself
must not contain newlines. Use Write Bare
instead if either of these features causes a
problem.

Note: This keyword does not return the

possible output of the executed command.
 To get the output, one of the Read ...
keywords must be used. See Writing and
reading section for more details.

See Logging section for more information

about log levels.
Writes the given text, and nothing else, into
the connection.
Write Bare text
This keyword does not append a newline
nor consume the written text. Use Write if
these features are needed.
Writes the given control character into the
connection.

The control character is prepended with an

IAC (interpret as command) character.

The following control character names are

supported: BRK, IP, AO, AYT, EC, EL,
Write NOP. Additionally, you can use arbitrary
Control character numbers to send any control character.
Character
Example:

Write Control # Send Break

BRK
Character command
# Send No
Write Control
241 operation
Character
command
Writes the given text repeatedly, until
expected appears in the output.

text is written without appending a

newline and it is consumed from the output
before trying to find expected. If
text,
expected does not appear in the output
Write Until expected,
within timeout, this keyword fails.
Expected timeout,
Output retry_interval,
retry_interval defines the time to wait
loglevel=None
expected to appear before writing the
text again. Consuming the written text is
subject to the normal configured timeout.

Both timeout and retry_interval must

be given in time string format. See Logging
 section for more information about log
levels.

Example:

Write Until
ps -ef| grep
Expected myprocess
myprocess\r\n
Output
... 5s 0.5 s

The above example writes command ps -

ef | grep myprocess\r\n until
myprocess appears in the output. The
command is written every 0.5 seconds and
the keyword fails if myprocess does not
appear in the output in 5 seconds.

Altogether 20 keywords.
Generated by Libdoc on 2020-09-01 21:22:50.