Process
Returns the process ID (pid) of the process as an integer.
Arguments
| Argument | Type | Default value |
|---|---|---|
| handle | None |
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}.
Return the underlying subprocess.Popen object.
Arguments
| Argument | Type | Default value |
|---|---|---|
| handle | None |
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.
Returns the specified result object or some of its attributes.
Arguments
| Argument | Type | Default value |
|---|---|---|
| handle | None | |
| rc | False | |
| stdout | False | |
| stderr | False | |
| stdout_path | False | |
| stderr_path | False |
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.
Checks is the process running or not.
Arguments
| Argument | Type | Default value |
|---|---|---|
| handle | None |
If handle is not given, uses the current active process.
Returns True if the process is still running and False otherwise.
Joins arguments into one command line string.
Arguments
| Argument | Type | Default value |
|---|---|---|
| args | null |
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.
Usage
| ${cmd} = | Join Command Line | --option | value with spaces |
| Should Be Equal | ${cmd} | --option "value with spaces" |
Verifies that the process is running.
Arguments
| Argument | Type | Default value |
|---|---|---|
| handle | None | |
| error_message | Process is not running. |
If handle is not given, uses the current active process.
Fails if the process has stopped.
Verifies that the process is not running.
Arguments
| Argument | Type | Default value |
|---|---|---|
| handle | None | |
| error_message | Process is running. |
If handle is not given, uses the current active process.
Fails if the process is still running.
Runs a process and waits for it to complete.
Arguments
| Argument | Type | Default value |
|---|---|---|
| command | null | |
| arguments | null | |
| configuration | null |
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.
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} | stderr=STDOUT | timeout=10s |
| ${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.
Sends the given signal to the specified process.
Arguments
| Argument | Type | Default value |
|---|---|---|
| signal | null | |
| handle | None | |
| group | False |
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).
Splits command line string into a list of arguments.
Arguments
| Argument | Type | Default value |
|---|---|---|
| args | null | |
| escaping | False |
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 double backslashes when using Windows paths.
Examples:
| @{cmd} = | Split Command Line | --option "value with spaces" |
| Should Be True | $cmd == ['--option', 'value with spaces'] |
Starts a new process on background.
Arguments
| Argument | Type | Default value |
|---|---|---|
| command | null | |
| arguments | null | |
| configuration | null |
See Specifying command and arguments and Process configuration for more information about the arguments, and Run Process keyword for related examples.
Makes the started process new active process. Returns the created subprocess.Popen object which can be be used later to active 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 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.
Makes the specified process the current active process.
Arguments
| Argument | Type | Default value |
|---|---|---|
| handle | null |
The handle can be an identifier returned by Start Process or the alias given to it explicitly.
Usage
| Start Process | prog1 | alias=process1 |
| Start Process | prog2 | alias=process2 |
| # currently active process is process2 | ||
| Switch Process | process1 | |
| # now active process is process1 |
Terminates all still running processes started by this library.
Arguments
| Argument | Type | Default value |
|---|---|---|
| kill | False |
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.
Stops the process gracefully or forcefully.
Arguments
| Argument | Type | Default value |
|---|---|---|
| handle | None | |
| kill | False |
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.
Waits for the process to complete or to reach the given timeout.
Arguments
| Argument | Type | Default value |
|---|---|---|
| handle | None | |
| timeout | None | |
| on_timeout | continue |
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 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 |
Ignoring timeout if it is string NONE, zero, or negative is new in Robot Framework 3.2.