Version: 2.6.3
Scope: test suite
Named arguments: not supported


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. See Open Connection and Switch Connection for details on how to handle multiple simultaneous connections. The responses are expected to be ASCII encoded and all non-ASCII characters are silently ignored.


Arguments Documentation
timeout=3.0, newline=CRLF, prompt=None, prompt_is_regexp=False Telnet library can be imported with optional arguments. Initialization parameters are used as default values when new connections are opened with Open Connection keyword. They can also be set after opening the connection using the Set Timeout, Set Newline and Set Prompt keywords. See these keywords for more information. Examples (use only one of these):
Setting Value Value Value Value Value Comment
Library Telnet # default values
Library Telnet 0.5 # set only timeout
Library Telnet LF # set only newline
Library Telnet 2.0 LF # set timeout and newline
Library Telnet 2.0 CRLF $ # set also prompt
Library Telnet 2.0 LF ($|~) True # set prompt with simple regexp


Close All Connections  ·  Close Connection  ·  Execute Command  ·  Login  ·  Open Connection  ·  Read  ·  Read Until  ·  Read Until Prompt  ·  Read Until Regexp  ·  Set Default Log Level  ·  Set Newline  ·  Set Prompt  ·  Set Timeout  ·  Switch Connection  ·  Write  ·  Write Bare  ·  Write Until Expected Output


Keyword Arguments Documentation
Close All Connections Closes all open connections and empties the connection cache. After this keyword, new indexes got from the Open Connection keyword are reset to 1. This keyword should be used in a test or suite teardown to make sure all connections are closed.
Close Connection loglevel=None Closes the current Telnet connection and returns any remaining output. See Read for more information on loglevel.
Execute Command command, loglevel=None Executes given command and reads and returns everything until prompt. This is a convenience keyword; following two are functionally identical:
${out} = Execute Command Some command
Write Some command
${out} = Read Until Prompt
This keyword expects a prompt to be set, see Read Until Prompt for details. See Read for more information on loglevel.
Login username, password, login_prompt=login: , password_prompt=Password: Logs in to the Telnet server with the given user information. The login keyword reads from the connection until login_prompt is encountered and then types the user name. Then it reads until password_prompt is encountered and types the password. The rest of the output (if any) is also read, and all the text that has been read is returned as a single string. If a prompt has been set to this connection, either with Open Connection or Set Prompt, this keyword reads the output until the prompt is found. Otherwise, the keyword sleeps for a second and reads everything that is available.
Open Connection host, alias=None, port=23, timeout=None, newline=None, prompt=None, prompt_is_regexp=False Opens a new Telnet connection to the given host and port. Possible already opened connections are cached. Returns the index of this connection, which can be used later to switch back to the connection. The index starts from 1 and is reset back to it when the Close All Connections keyword is used. The optional alias is a name for the connection, and it can be used for switching between connections, similarly as the index. See Switch Connection for more details about that. The timeout, newline, prompt and prompt_is_regexp arguments get default values when the library is taken into use, but setting them here overrides those values for this connection. See importing for more information.
Read loglevel=None Reads and returns/logs everything that is currently available in the output. The read message is always returned and logged. The default log level is either 'INFO', or the level set with Set Default Log Level. loglevel can be used to override the default log level, and the available levels are TRACE, DEBUG, INFO, and WARN.
Read Until expected, loglevel=None Reads from the current output, until expected is encountered. Text up to and including the match is returned. If no match is found, the keyword fails. See Read for more information on loglevel.
Read Until Prompt loglevel=None Reads from the current output, until a prompt is found. The prompt must have been set, either in the library import or at login time, or by using the Set Prompt keyword. See Read for more information on loglevel.
Read Until Regexp *expected Reads from the current output, until a match to a regexp in expected. Expected is a list of regular expression patterns as strings, or compiled regular expressions. The keyword returns the text up to and including the first match to any of the regular expressions. If the last argument in *expected is a valid log level, it is used as loglevel in the keyword Read. Examples:
Read Until Regexp (#|$)
Read Until Regexp first_regexp second_regexp
Read Until Regexp some regexp DEBUG
Set Default Log Level level Sets the default log level used by all read keywords. The possible values are TRACE, DEBUG, INFO and WARN. The default is INFO. The old value is returned and can be used to restore it later, similarly as with Set Timeout.
Set Newline newline Sets the newline used by the Write keyword. 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
Correct newline to use depends on the system and the default value is 'CRLF'. The old newline is returned and can be used to restore it later. See Set Prompt or Set Timeout for an example.
Set Prompt prompt, prompt_is_regexp=False Sets the prompt used in this connection to prompt. If prompt_is_regexp is a non-empty string, the given prompt is considered to be a regular expression. The old prompt is returned and can be used to restore it later. Example:
${prompt} ${regexp} = Set Prompt $
Do Something
Set Prompt ${prompt} ${regexp}
Set Timeout timeout Sets the timeout used in read operations to the given value. timeout is given in Robot Framework's time format (e.g. 1 minute 20 seconds) that is explained in the User Guide. Read operations that expect some output to appear (Read Until, Read Until Regexp, Read Until Prompt) use this timeout and fail if the expected output has not appeared when this timeout expires. The old timeout is returned and can be used to restore it later. Example:
${tout} = Set Timeout 2 minute 30 seconds
Do Something
Set Timeout ${tout}
Switch Connection index_or_alias Switches between active connections using an index or alias. The index is got from Open Connection keyword, and an alias can be given to it. Returns the index of previously active connection. Example:
Open Connection
Login john secret
Write some command
Open Connection 2nd conn
Login root password
Write another cmd
${old index}= Switch Connection 1 # index
Write something
Switch Connection 2nd conn # alias
Write whatever
Switch Connection ${old index} # back to original again
[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.
${id} = Open Connection
# Do something ...
Switch Connection ${id}
Write text, loglevel=None Writes the given text over the connection and appends a newline. Consumes the written text (until the appended newline) from the output and returns it. The given text must not contain newlines. Note: This keyword does not return the possible output of the executed command. To get the output, one of the Read XXX keywords must be used. See Read for more information on loglevel.
Write Bare text Writes the given text over the connection without appending a newline. Does not consume the written text.
Write Until Expected Output text, expected, timeout, retry_interval, loglevel=None Writes the given text repeatedly, until expected appears in the output. text is written without appending a newline. retry_interval defines the time waited before writing text again. text is consumed from the output before expected is tried to be read. If expected does not appear in the output within timeout, this keyword fails. See Read for more information on loglevel. Example:
Write Until Expected Output ps -ef| grep myprocess\n myprocess
... 5s 0.5s
This writes the 'ps -ef | grep myprocess\n', until 'myprocess' appears on 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.