Process
Robot Framework library for running processes.
This library utilizes Python's subprocess module and its Popen class.
The library has following main usages:
- Running processes in system and waiting for their completion using Run Process keyword.
- Starting processes on background using Start Process.
- Waiting started process to complete using Wait For Process or stopping them with Terminate Process or Terminate All Processes.
Table of contents
- Specifying command and arguments
- Process configuration
- Active process
- Result object
- Boolean arguments
- Example
- Keywords
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 afterwards.
| 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:<name> | Overrides the named environment variable(s) only. |
| stdout | Path of a file where to write standard output. |
| stderr | Path of a file where to write standard error. |
| stdin | Configure process standard input. New in RF 4.1.2. |
| output_encoding | Encoding to use when reading command outputs. |
| alias | Alias given to the process. |
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
By default the child process will get a copy of the parent process's environment variables. 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.
Support for the special value DEVNULL is new in Robot Framework 3.2.
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 PIPE | Make stdin a pipe that can be written to. This is the default. |
String NONE | Inherit stdin from the parent process. This value is case-insensitive. |
| 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 internally mapped directly to subprocess.PIPE and None, respectively, when calling subprocess.Popen. The default behavior may change from PIPE to NONE in future releases. If you depend on the PIPE behavior, it is a good idea to use it explicitly.
Examples:
| Run Process | command | stdin=NONE |
| 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.
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 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. |
Considering OFF and 0 false is new in Robot Framework 3.1.