Telnet - Documentation

Version: 2.1.2

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.

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.

Importing

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

Shortcuts

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

Keywords

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.

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	myhost.net
Login	john	secret
Write	some command
Open Connection	yourhost.com	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	myhost.net
# 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.