Telnet
A 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
- 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.
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 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 encodedreplace
: 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 Connection | lolcathost | terminal_emulation=True | terminal_type=vt100 | window_size=400x100 |
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 Connection | lolcathost | terminal_emulation=True | # Strings are generally true. |
Open Connection | lolcathost | terminal_emulation=yes | # Same as the above. |
Open Connection | lolcathost | terminal_emulation=${TRUE} | # Python True is true. |
Open Connection | lolcathost | terminal_emulation=${42} | # Numbers other than 0 are true. |
False examples:
Open Connection | lolcathost | terminal_emulation=False | # String false is false. |
Open Connection | lolcathost | terminal_emulation=no | # Also string no is false. |
Open Connection | lolcathost | terminal_emulation=${EMPTY} | # Empty string is false. |
Open Connection | lolcathost | terminal_emulation=${FALSE} | # Python False is 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
Telnet library can be imported with optional configuration parameters.
Configuration parameters are used as default values when new connections are opened with Open Connection keyword. They can also be overridden after opening the connection using the Set ... keywords. See these keywords as well as Configuration, Terminal emulation and Logging sections above for more information about these parameters and their possible values.
See Time string format and Boolean arguments sections for information about using arguments accepting times and Boolean values, respectively.
Examples (use only one of these):
Setting | Value | Value | Value | Value | Comment |
---|---|---|---|---|---|
Library | Telnet | # default values | |||
Library | Telnet | 5 seconds | # set only timeout | ||
Library | Telnet | newline=LF | encoding=ISO-8859-1 | # set newline and encoding using named arguments | |
Library | Telnet | prompt=$ | # set prompt | ||
Library | Telnet | prompt=(> |# ) | prompt_is_regexp=yes | # set prompt as a regular expression | |
Library | Telnet | terminal_emulation=True | terminal_type=vt100 | window_size=400x100 | # use terminal emulation with defined window size and terminal type |
Library | Telnet | telnetlib_log_level=NONE | # disable logging messages from the underlying telnetlib |