Robot Framework library for running processes.
This library utilizes Python's [http://docs.python.org/library/subprocess.html|subprocess] module and its [http://docs.python.org/library/subprocess.html#popen-constructor|Popen] class.
The library has following main usages:
- Running processes in system and waiting for their completion using
Run Processkeyword. - Starting processes on background using
Start Process. - Waiting started process to complete using
Wait For Processor stopping them withTerminate ProcessorTerminate All Processes.
== Table of contents ==
%TOC%
= Specifying command and arguments =
Both Run Process and Start Process accept the command to execute and
all arguments passed to the command as separate arguments. This makes usage
convenient and also allows these keywords to automatically escape possible
spaces and other special characters in commands and arguments. Notice that
if a command accepts options that themselves accept values, these options
and their values must be given as separate arguments.
When running processes in shell, it is also possible to give the whole
command to execute as a single string. The command can then contain
multiple commands to be run together. When using this approach, the caller
is responsible on escaping.
Examples:
| Run Process | ${tools}${/}prog.py | argument | second arg with spaces |
| Run Process | java | -jar | ${jars}${/}example.jar | --option | value |
| Run Process | prog.py "one arg" && tool.sh | shell=yes | cwd=${tools} |
Possible non-string arguments are converted to strings automatically.
= Process configuration =
Run Process and Start Process keywords can be configured using
optional **configuration keyword arguments. Configuration arguments
must be given after other arguments passed to these keywords and must
use syntax like name=value. Available configuration arguments are
listed below and discussed further in sections afterward.
| = Name = | = Explanation = |
| shell | Specifies whether to run the command in shell or not. |
| cwd | Specifies the working directory. |
| env | Specifies environment variables given to the process. |
| env:
Note that because **configuration is passed using name=value syntax,
possible equal signs in other arguments passed to Run Process and
Start Process must be escaped with a backslash like name\=value.
See Run Process for an example.
== Running processes in shell ==
The shell argument specifies whether to run the process in a shell or
not. By default, shell is not used, which means that shell specific commands,
like copy and dir on Windows, are not available. You can, however,
run shell scripts and batch files without using a shell.
Giving the shell argument any non-false value, such as shell=True,
changes the program to be executed in a shell. It allows using the shell
capabilities, but can also make the process invocation operating system
dependent. Having a shell between the actually started process and this
library can also interfere communication with the process such as stopping
it and reading its outputs. Because of these problems, it is recommended
to use the shell only when absolutely necessary.
When using a shell it is possible to give the whole command to execute
as a single string. See Specifying command and arguments section for
examples and more details in general.
== Current working directory ==
By default, the child process will be executed in the same directory
as the parent process, the process running Robot Framework, is executed. This
can be changed by giving an alternative location using the cwd argument.
Forward slashes in the given path are automatically converted to
backslashes on Windows.
Standard output and error streams, when redirected to files,
are also relative to the current working directory possibly set using
the cwd argument.
Example:
| Run Process | prog.exe | cwd=${ROOT}/directory | stdout=stdout.txt |
== Environment variables ==
The child process will get a copy of the parent process's environment
variables by default. The env argument can be used to give the
child a custom environment as a Python dictionary. If there is a need
to specify only certain environment variable, it is possible to use the
env:<name>=<value> format to set or override only that named variables.
It is also possible to use these two approaches together.
Examples:
| Run Process | program | env=${environ} |
| Run Process | program | env:http_proxy=10.144.1.10:8080 | env:PATH=%{PATH}${:}${PROGDIR} |
| Run Process | program | env=${environ} | env:EXTRA=value |
== Standard output and error streams ==
By default, processes are run so that their standard output and standard error streams are kept in the memory. This works fine normally, but if there is a lot of output, the output buffers may get full and the program can hang.
To avoid the above-mentioned problems, it is possible to use stdout
and stderr arguments to specify files on the file system where to
redirect the outputs. This can also be useful if other processes or
other keywords need to read or manipulate the outputs somehow.
Given stdout and stderr paths are relative to the current working
directory. Forward slashes in the given paths are automatically converted
to backslashes on Windows.
As a special feature, it is possible to redirect the standard error to
the standard output by using stderr=STDOUT.
Regardless are outputs redirected to files or not, they are accessible
through the result object returned when the process ends. Commands are
expected to write outputs using the console encoding, but output encoding
can be configured using the output_encoding argument if needed.
If you are not interested in outputs at all, you can explicitly ignore them
by using a special value DEVNULL both with stdout and stderr. For
example, stdout=DEVNULL is the same as redirecting output on console
with > /dev/null on UNIX-like operating systems or > NUL on Windows.
This way the process will not hang even if there would be a lot of output,
but naturally output is not available after execution either.
Examples:
| ${result} = | Run Process | program | stdout=${TEMPDIR}/stdout.txt | stderr=${TEMPDIR}/stderr.txt |
| Log Many | stdout: ${result.stdout} | stderr: ${result.stderr} |
| ${result} = | Run Process | program | stderr=STDOUT |
| Log | all output: ${result.stdout} |
| ${result} = | Run Process | program | stdout=DEVNULL | stderr=DEVNULL |
Note that the created output files are not automatically removed after the test run. The user is responsible to remove them if needed.
== Standard input stream ==
The stdin argument makes it possible to pass information to the standard
input stream of the started process. How its value is interpreted is
explained in the table below.
| = Value = | = Explanation = |
| String NONE | Inherit stdin from the parent process. This is the default. |
| String PIPE | Make stdin a pipe that can be written to. |
| Path to a file | Open the specified file and use it as the stdin. |
| Any other string | Create a temporary file with the text as its content and use it as the stdin. |
| Any non-string value | Used as-is. Could be a file descriptor, stdout of another process, etc. |
Values PIPE and NONE are case-insensitive and internally mapped to
subprocess.PIPE and None, respectively, when calling
[https://docs.python.org/3/library/subprocess.html#subprocess.Popen|subprocess.Popen].
Examples:
| Run Process | command | stdin=PIPE |
| Run Process | command | stdin=${CURDIR}/stdin.txt |
| Run Process | command | stdin=Stdin as text. |
The support to configure stdin is new in Robot Framework 4.1.2. Its default
value used to be PIPE until Robot Framework 7.0.
== Output encoding ==
Executed commands are, by default, expected to write outputs to the
standard output and error streams using the encoding used by the
system console. If the command uses some other encoding, that can be
configured using the output_encoding argument. This is especially
useful on Windows where the console uses a different encoding than rest
of the system, and many commands use the general system encoding instead
of the console encoding.
The value used with the output_encoding argument must be a valid
encoding and must match the encoding actually used by the command. As a
convenience, it is possible to use strings CONSOLE and SYSTEM
to specify that the console or system encoding is used, respectively.
If produced outputs use different encoding then configured, values got
through the result object will be invalid.
Examples:
| Start Process | program | output_encoding=UTF-8 |
| Run Process | program | stdout=${path} | output_encoding=SYSTEM |
== Alias ==
A custom name given to the process that can be used when selecting the
active process.
Examples:
| Start Process | program | alias=example |
| Run Process | python | -c | print('hello') | alias=hello |
= Active process =
The library keeps record which of the started processes is currently active.
By default it is the latest process started with Start Process,
but Switch Process can be used to activate a different process. Using
Run Process does not affect the active process.
The keywords that operate on started processes will use the active process
by default, but it is possible to explicitly select a different process
using the handle argument. The handle can be an alias explicitly
given to Start Process or the process object returned by it.
= Result object =
Run Process, Wait For Process and Terminate Process keywords return a
result object that contains information about the process execution as its
attributes. The same result object, or some of its attributes, can also
be get using Get Process Result keyword. Attributes available in the
object are documented in the table below.
| = Attribute = | = Explanation = |
| rc | Return code of the process as an integer. |
| stdout | Contents of the standard output stream. |
| stderr | Contents of the standard error stream. |
| stdout_path | Path where stdout was redirected or None if not redirected. |
| stderr_path | Path where stderr was redirected or None if not redirected. |
Example:
| ${result} = | Run Process | program |
| Should Be Equal As Integers | ${result.rc} | 0 |
| Should Match | ${result.stdout} | Some t?xt* |
| Should Be Empty | ${result.stderr} | |
| ${stdout} = | Get File | ${result.stdout_path} |
| Should Be Equal | ${stdout} | ${result.stdout} |
| File Should Be Empty | ${result.stderr_path} | |
= 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
[http://docs.python.org/library/stdtypes.html#truth|rules as in Python].
True examples:
| Terminate Process | kill=True | # Strings are generally true. |
| Terminate Process | kill=yes | # Same as the above. |
| Terminate Process | kill=${TRUE} | # Python True is true. |
| Terminate Process | kill=${42} | # Numbers other than 0 are true. |
False examples:
| Terminate Process | kill=False | # String false is false. |
| Terminate Process | kill=no | # Also string no is false. |
| Terminate Process | kill=${EMPTY} | # Empty string is false. |
| Terminate Process | kill=${FALSE} | # Python False is false. |
= Example =
| * Settings
| Library Process
| Suite Teardown Terminate All Processes kill=True
|
| Test Cases ***
| Example
| Start Process program arg1 arg2 alias=First
| ${handle} = Start Process command.sh arg | command2.sh shell=True cwd=/path
| ${result} = Run Process ${CURDIR}/script.py
| Should Not Contain ${result.stdout} FAIL
| Terminate Process ${handle}
| ${result} = Wait For Process First
| Should Be Equal As Integers ${result.rc} 0
Source code in src/robot/libraries/Process.py
Runs a process and waits for it to complete.
command and *arguments specify the command to execute and
arguments passed to it. See Specifying command and arguments for
more details.
**configuration contains additional configuration related to
starting processes and waiting for them to finish. See Process
configuration for more details about configuration related to starting
processes. Configuration related to waiting for processes consists of
timeout and on_timeout arguments that have same semantics as
with Wait For Process keyword. By default, there is no timeout, and
if timeout is defined the default action on timeout is terminate.
Process outputs are, by default, written into in-memory buffers.
If there is a lot of output, these buffers may get full causing
the process to hang. To avoid that, process outputs can be redirected
using the stdout and stderr configuration parameters. For more
information see the Standard output and error streams section.
Returns a result object containing information about the execution.
Note that possible equal signs in *arguments must be escaped
with a backslash (e.g. name\=value) to avoid them to be passed in
as **configuration.
Examples: | ${result} = | Run Process | python | -c | print('Hello, world!') | | Should Be Equal | ${result.stdout} | Hello, world! | | ${result} = | Run Process | ${command} | stdout=${CURDIR}/stdout.txt | stderr=STDOUT | | ${result} = | Run Process | ${command} | timeout=1min | on_timeout=continue | | ${result} = | Run Process | java -Dname\=value Example | shell=True | cwd=${EXAMPLE} |
This keyword does not change the active process.
Source code in src/robot/libraries/Process.py
Starts a new process on background.
See Specifying command and arguments and Process configuration
for more information about the arguments, and Run Process keyword
for related examples. This includes information about redirecting
process outputs to avoid process handing due to output buffers getting
full.
Makes the started process new active process. Returns the created
[https://docs.python.org/3/library/subprocess.html#popen-constructor |
subprocess.Popen] object which can be used later to activate this
process. Popen attributes like pid can also be accessed directly.
Processes are started so that they create a new process group. This allows terminating and sending signals to possible child processes.
Examples:
Start process and wait for it to end later using an alias:
| Start Process | ${command} | alias=example |
| # Other keywords |
| ${result} = | Wait For Process | example |
Use returned Popen object:
| ${process} = | Start Process | ${command} |
| Log | PID: ${process.pid} |
| # Other keywords |
| ${result} = | Terminate Process | ${process} |
Use started process in a pipeline with another process:
| ${process} = | Start Process | python | -c | print('Hello, world!') |
| ${result} = | Run Process | python | -c | import sys; print(sys.stdin.read().upper().strip()) | stdin=${process.stdout} |
| Wait For Process | ${process} |
| Should Be Equal | ${result.stdout} | HELLO, WORLD! |
Returning a subprocess.Popen object is new in Robot Framework 5.0.
Earlier versions returned a generic handle and getting the process object
required using Get Process Object separately.
Source code in src/robot/libraries/Process.py
Checks is the process running or not.
If handle is not given, uses the current active process.
Returns True if the process is still running and False otherwise.
Source code in src/robot/libraries/Process.py
Verifies that the process is running.
If handle is not given, uses the current active process.
Fails if the process has stopped.
Source code in src/robot/libraries/Process.py
Verifies that the process is not running.
If handle is not given, uses the current active process.
Fails if the process is still running.
Source code in src/robot/libraries/Process.py
Waits for the process to complete or to reach the given timeout.
The process to wait for must have been started earlier with
Start Process. If handle is not given, uses the current
active process.
timeout defines the maximum time to wait for the process. It can be
given in
[http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format|
various time formats] supported by Robot Framework, for example, 42,
42 s, or 1 minute 30 seconds. The timeout is ignored if it is
Python None (default), string NONE (case-insensitively), zero,
or negative.
on_timeout defines what to do if the timeout occurs. Possible values
and corresponding actions are explained in the table below. Notice
that reaching the timeout never fails the test.
| = Value = | = Action = | | continue | The process is left running (default). | | terminate | The process is gracefully terminated. | | kill | The process is forcefully stopped. |
See Terminate Process keyword for more details how processes are
terminated and killed.
If the process ends before the timeout or it is terminated or killed,
this keyword returns a result object containing information about
the execution. If the process is left running, Python None is
returned instead.
Examples: | # Process ends cleanly | | | | ${result} = | Wait For Process | example | | Process Should Be Stopped | example | | | Should Be Equal As Integers | ${result.rc} | 0 | | # Process does not end | | | | ${result} = | Wait For Process | timeout=42 secs | | Process Should Be Running | | | | Should Be Equal | ${result} | ${NONE} | | # Kill non-ending process | | | | ${result} = | Wait For Process | timeout=1min 30s | on_timeout=kill | | Process Should Be Stopped | | | | Should Be Equal As Integers | ${result.rc} | -9 |
Source code in src/robot/libraries/Process.py
Stops the process gracefully or forcefully.
If handle is not given, uses the current active process.
By default first tries to stop the process gracefully. If the process
does not stop in 30 seconds, or kill argument is given a true value,
(see Boolean arguments) kills the process forcefully. Stops also all
the child processes of the originally started process.
Waits for the process to stop after terminating it. Returns a result
object containing information about the execution similarly as Wait
For Process.
On Unix-like machines graceful termination is done using TERM (15)
signal and killing using KILL (9). Use Send Signal To Process
instead if you just want to send either of these signals without
waiting for the process to stop.
On Windows graceful termination is done using CTRL_BREAK_EVENT
event and killing using Win32 API function TerminateProcess().
Examples: | ${result} = | Terminate Process | | | Should Be Equal As Integers | ${result.rc} | -15 | # On Unixes | | Terminate Process | myproc | kill=true |
Limitations: - On Windows forceful kill only stops the main process, not possible child processes.
Source code in src/robot/libraries/Process.py
Terminates all still running processes started by this library.
This keyword can be used in suite teardown or elsewhere to make sure that all processes are stopped,
By default tries to terminate processes gracefully, but can be
configured to forcefully kill them immediately. See Terminate Process
that this keyword uses internally for more details.
Source code in src/robot/libraries/Process.py
Sends the given signal to the specified process.
If handle is not given, uses the current active process.
Signal can be specified either as an integer as a signal name. In the
latter case it is possible to give the name both with or without SIG
prefix, but names are case-sensitive. For example, all the examples
below send signal INT (2):
| Send Signal To Process | 2 | | # Send to active process | | Send Signal To Process | INT | | | | Send Signal To Process | SIGINT | myproc | # Send to named process |
This keyword is only supported on Unix-like machines, not on Windows.
What signals are supported depends on the system. For a list of
existing signals on your system, see the Unix man pages related to
signal handling (typically man signal or man 7 signal).
By default sends the signal only to the parent process, not to possible
child processes started by it. Notice that when running processes in
shell, the shell is the parent process and it depends on the system
does the shell propagate the signal to the actual started process.
To send the signal to the whole process group, group argument can
be set to any true value (see Boolean arguments).
Source code in src/robot/libraries/Process.py
Returns the process ID (pid) of the process as an integer.
If handle is not given, uses the current active process.
Starting from Robot Framework 5.0, it is also possible to directly access
the pid attribute of the subprocess.Popen object returned by
Start Process like ${process.pid}.
Source code in src/robot/libraries/Process.py
Return the underlying subprocess.Popen object.
If handle is not given, uses the current active process.
Starting from Robot Framework 5.0, Start Process returns the created
subprocess.Popen object, not a generic handle, making this keyword
mostly redundant.
Source code in src/robot/libraries/Process.py
Returns the specified result object or some of its attributes.
The given handle specifies the process whose results should be
returned. If no handle is given, results of the current active
process are returned. In either case, the process must have been
finishes before this keyword can be used. In practice this means
that processes started with Start Process must be finished either
with Wait For Process or Terminate Process before using this
keyword.
If no other arguments than the optional handle are given, a whole
result object is returned. If one or more of the other arguments
are given any true value, only the specified attributes of the
result object are returned. These attributes are always returned
in the same order as arguments are specified in the keyword signature.
See Boolean arguments section for more details about true and false
values.
Examples: | Run Process | python | -c | print('Hello, world!') | alias=myproc | | # Get result object | | | | ${result} = | Get Process Result | myproc | | Should Be Equal | ${result.rc} | ${0} | | Should Be Equal | ${result.stdout} | Hello, world! | | Should Be Empty | ${result.stderr} | | | # Get one attribute | | | | ${stdout} = | Get Process Result | myproc | stdout=true | | Should Be Equal | ${stdout} | Hello, world! | | # Multiple attributes | | | | ${stdout} | ${stderr} = | Get Process Result | myproc | stdout=yes | stderr=yes | | Should Be Equal | ${stdout} | Hello, world! | | Should Be Empty | ${stderr} | |
Although getting results of a previously executed process can be handy in general, the main use case for this keyword is returning results over the remote library interface. The remote interface does not support returning the whole result object, but individual attributes can be returned without problems.
Source code in src/robot/libraries/Process.py
Makes the specified process the current active process.
The handle can be an identifier returned by Start Process or
the alias given to it explicitly.
Example: | Start Process | prog1 | alias=process1 | | Start Process | prog2 | alias=process2 | | # currently active process is process2 | | Switch Process | process1 | | # now active process is process1 |
Source code in src/robot/libraries/Process.py
Splits command line string into a list of arguments.
String is split from spaces, but argument surrounded in quotes may contain spaces in them.
If escaping is given a true value, then backslash is treated as
an escape character. It can escape unquoted spaces, quotes inside
quotes, and so on, but it also requires using doubling backslashes
in Windows paths and elsewhere.
Examples: | @{cmd} = | Split Command Line | --option "value with spaces" | | Should Be True | $cmd == ['--option', 'value with spaces'] |
Source code in src/robot/libraries/Process.py
Joins arguments into one command line string.
In resulting command line string arguments are delimited with a space, arguments containing spaces are surrounded with quotes, and possible quotes are escaped with a backslash.
If this keyword is given only one argument and that is a list-like object, then the values of that list are joined instead.
Example: | ${cmd} = | Join Command Line | --option | value with spaces | | Should Be Equal | ${cmd} | --option "value with spaces" |