Python Remote Server for Robot Framework
Robot Framework remote servers allow hosting test libraries on different processes or machines than Robot Framework itself is running on. This project implements a generic remote server using the Python programming language. See the remote library interface documentation for more information about the remote interface in general as well as for a list of remote server implementations in other programming languages.
This remote server is implemented with Python and supports also Jython (JVM), IronPython (.NET) and PyPy. Remote server version 1.1 and newer support Python 2.6, 2.7, 3.3, and newer. Remote server 1.0 series supports Python versions 2.2-2.7.
Starting from the remote server version 1.1, Robot Framework's static, hybrid and dynamic library APIs are all supported. This includes setting custom name and tags for keywords using the robot.api.deco.keyword decorator, although the support for tags requires using Robot Framework 3.0.2 or newer. Earlier remote server versions support only the static and hybrid APIs and do not support the keyword decorator at all.
For most parts these APIs work exactly like when using with Robot Framework
normally. There main limitation is that logging using
logging module is currently not supported.
The easiest installation approach is using pip:
pip install robotremoteserver
Alternatively you can download the source distribution from PyPI, extract it and install the remote server using:
python setup.py install
The remote server is implemented as a class
RobotRemoteServer and it
accepts the following configuration parameters when it is initialized:
Argument Default Explanation
Test library instance or module to host. Mandatory argument.
Address to listen. Use
'0.0.0.0'to listen to all available interfaces.
Port to listen. Use
0to select a free port automatically. Can be given as an integer or as a string. The default port
8270is registered by IANA for remote server usage.
File to write the port that is used.
None(default) means no such file is written.
Deprecated since version 1.1. Use
True, start the server automatically and wait for it to be stopped. If
False, server can be started using the
servemethod. New in version 1.1.
Allow/disallow stopping the server remotely using
Stop Remote Serverkeyword and
stop_remote_serverXML-RPC method. New in version 1.1.
The remote server can be started simply by creating an instance of the server and passing a test library instance or module to it:
from robotremoteserver import RobotRemoteServer from mylibrary import MyLibrary RobotRemoteServer(MyLibrary())
By default the server listens to address 127.0.0.1 and port 8270. As discussed above, the remote server accepts various configuration parameters. Some of them are used by this example:
from robotremoteserver import RobotRemoteServer from examplelibrary import ExampleLibrary RobotRemoteServer(ExampleLibrary(), host='10.0.0.42', port=0, port_file='/tmp/remote-port.txt')
Starting from version 1.1, the server can be initialized without starting it by
using the argument
serve=False. The server can then started afterwards by
serve method explicitly. This example is functionally
equivalent to the example above:
from robotremoteserver import RobotRemoteServer from examplelibrary import ExampleLibrary server = RobotRemoteServer(ExampleLibrary(), host='10.0.0.42', port=0, port_file='/tmp/remote-port.txt', serve=False) server.serve()
The main benefit of separately initializing and starting the server is that
it makes it easier to start the server in a background thread. Servers started
in a thread work exactly like servers running in the main tread except that
stopping the server gracefully using
Ctrl-C or signals is not
supported automatically. Users must thus register signal handlers separately
Also this following example is functionally nearly equivalent to the earlier examples except. The main difference is that not all same signals are handled.
import signal import threading from examplelibrary import ExampleLibrary from robotremoteserver import RobotRemoteServer server = RobotRemoteServer(ExampleLibrary(), port=0, serve=False) signal.signal(signal.SIGINT, lambda signum, frame: server.stop()) server_thread = threading.Thread(target=server.serve) server_thread.start() while server_thread.is_alive(): server_thread.join(0.1)
If the server uses the default port
8270 or some other port is given
explicitly when configuring the server, you obviously know which port
to use when connecting the server. When using the port
0, the server
selects a free port automatically, but there are various ways how to find
out the actual port:
- Address and port that are used are printed into the console where the server is started.
port_fileargument is used, the server writes the port into the specified file where other tools can easily read it. Starting from the remote server version 1.1, the server removes the port file automatically when the server is stopped.
- Starting from the version 1.1, the server has
activatemethod that can be called to activate the server without starting it. This method returns the port that the server binds and also sets it available via the attributes discussed below.
- A started or actived server instance has
server_addressattribute that contains the address and the port as a tuple. Starting from the version 1.1 there is also
server_portattribute that contains just the port as an integer.
The remote server can be gracefully stopped using several different methods:
Ctrl-Con the console where the server is running. Not supported automatically if the server is started on a background thread.
- Sending the process
SIGHUPsignal. Does not work on Windows and not supported if the server is started on a background thread.
Stop Remote Serverkeyword. Can be disabled by using
allow_remote_stop=Falsewhen initializing the server.
stop_remote_serverfunction in the XML-RPC interface. Can be disabled with the
python -m robotremoteserver stop [uri]which uses the aforementioned
stop_remote_serverXML-RPC function internally. Can be disabled with the
- Using the
stop_remote_serverfunction provided by the
robotremoteservermodule similarly as when testing is server running. Uses the
stop_remote_serverXML-RPC function internally and can be disabled with the
- Calling the
stopmethod of the running server instance. Mainly useful when running the server on background.
Starting from the version 1.0.1, the
robotremoteserver module supports
testing is a remote server running. This can be accomplished by running
the module as a script with
test argument and an optional URI:
$ python -m robotremoteserver test Remote server running at http://127.0.0.1:8270. $ python -m robotremoteserver test http://10.0.0.42:57347 No remote server running at http://10.0.0.42:57347.
Starting from the version 1.1, the
robotremoteserver module contains
test_remote_server that can be used programmatically:
from robotremoteserver import test_remote_server if test_remote_server('http://localhost:8270'): print('Remote server running!')
robotremoteserver module can be also used to stop a remote server by
stop argument on the command line or by using the
stop_remote_server function programmatically. Testing and stopping should
work also with other Robot Framework remote server implementations.
Using the built-in Libdoc tool you can list the keywords available on the server:
$ python -m robot.libdoc Remote::http://127.0.0.1:8270 list Count Items In Directory Stop Remote Server Strings Should Be Equal
It is also possible to show the documentation on the command line by using
show. HTML documentation can be created by providing name of
an output file:
$ python -m robot.libdoc Remote::http://127.0.0.1:8270 MyLibrary.html /path/to/MyLibrary.html
The remote server project contains an example that can be studied and also executed once the library is installed. You can get the example by cloning the project on GitHub, and it is also included in the source distribution available on PyPI.