🕷️ Crawler Inspector

# Opening library documentation failed - Verify that you have **JavaScript enabled** in your browser. - Make sure you are using a **modern enough browser**. If using Internet Explorer, version 11 is required. - Check are there messages in your browser's **JavaScript error log**. Please report the problem if you suspect you have encountered a bug. - [en]() - [fi]() - [fr]() - [it]() - [nl]() - [pt-br]() - [pt-pt]() ✕ #### Keywords (15) \+ - [Get Process Id](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Id) - [Get Process Object](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Object) - [Get Process Result](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Result) - [Is Process Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Is%20Process%20Running) - [Join Command Line](https://robotframework.org/robotframework/latest/libraries/Process.html#Join%20Command%20Line) - [Process Should Be Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20Should%20Be%20Running) - [Process Should Be Stopped](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20Should%20Be%20Stopped) - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Send Signal To Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Send%20Signal%20To%20Process) - [Split Command Line](https://robotframework.org/robotframework/latest/libraries/Process.html#Split%20Command%20Line) - [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) - [Switch Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Switch%20Process) - [Terminate All Processes](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20All%20Processes) - [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) - [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) | | | |---|---| | Library version: | 7\.4.2 | | Library scope: | GLOBAL | ## Introduction Robot Framework library for running processes. The library has following main usages: - Running processes in system and waiting for their completion using the [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) keyword. - Starting processes on background using the [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) keyword. - Waiting started process to complete using [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) or stopping them with [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) or [Terminate All Processes](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20All%20Processes). This library provides various benefits over using `Run` and other similar keywords in the [OperatingSystem](http://robotframework.org/robotframework/latest/libraries/OperatingSystem.html) library: - Better [process configuration](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20configuration). - Convenient [result object](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) with all result information (rc, stdout, stderr). - Support for background processes, process termination, sending signals and so on. This library utilizes Python's [subprocess](http://docs.python.org/library/subprocess.html) module and its [Popen](http://docs.python.org/library/subprocess.html#popen-constructor) class. ### Table of contents - [Specifying command and arguments](https://robotframework.org/robotframework/latest/libraries/Process.html#Specifying%20command%20and%20arguments) - [Process configuration](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20configuration) - [Active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process) - [Result object](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) - [Example](https://robotframework.org/robotframework/latest/libraries/Process.html#Example) - [Keywords](https://robotframework.org/robotframework/latest/libraries/Process.html#Keywords) ## Specifying command and arguments Both [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) and [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Running%20processes%20in%20shell), 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | \${tools}\${/}prog.py | argument | second arg with spaces | | | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | java | \-jar | \${jars}\${/}example.jar | \--option | value | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | prog.py "one arg" && tool.sh | shell=yes | cwd=\${tools} | | | Possible non-string arguments are converted to strings automatically. ## Process configuration [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) and [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) keywords can be configured using optional configuration arguments. These arguments must be given after other arguments passed to these keywords and must use the `name=value` syntax. Available configuration arguments are listed below and discussed further in the subsequent sections. | Name | Explanation | |---|---| | shell | Specify whether to run the command in a shell or not. | | cwd | Specify the working directory. | | env | Specify environment variables given to the process. | | \*\*env\_extra | Override named environment variables using `env:<name>=<value>` syntax. | | stdout | Path to a file where to write standard output. | | stderr | Path to 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 | A custom name given to the process. | Note that possible equal signs in other arguments passed to [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) and [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) must be escaped with a backslash like `name\=value`. See [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Specifying%20command%20and%20arguments) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Standard%20output%20and%20error%20streams), when redirected to files, are also relative to the current working directory possibly set using the `cwd` argument. Example: | | | | | |---|---|---|---| | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | env=\${environ} | | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | env:http\_proxy=10.144.1.10:8080 | env:PATH=%{PATH}\${:}\${PROGDIR} | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | 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 typically works fine, but there can be problems if the amount of output is large or unlimited. Prior to Robot Framework 7.3 the limit was smaller than nowadays and reaching it caused a deadlock. 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 output. This can also be useful if other processes or other keywords need to read or manipulate the output somehow. Given `stdout` and `stderr` paths are relative to the [current working directory](https://robotframework.org/robotframework/latest/libraries/Process.html#Current%20working%20directory). Forward slashes in the given paths are automatically converted to backslashes on Windows. Regardless are outputs redirected to files or not, they are accessible through the [result object](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) returned when the process ends. Commands are expected to write outputs using the console encoding, but [output encoding](https://robotframework.org/robotframework/latest/libraries/Process.html#Output%20encoding) can be configured using the `output_encoding` argument if needed. As a special feature, it is possible to redirect the standard error to the standard output by using `stderr=STDOUT`. If you are not interested in output at all, you can explicitly ignore it 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 even a huge amount of output cannot cause problems, but naturally the output is not available after execution either. Examples: | | | | | | |---|---|---|---|---| | \${result} = | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | stdout=\${TEMPDIR}/stdout.txt | stderr=\${TEMPDIR}/stderr.txt | | Log Many | stdout: \${result.stdout} | stderr: \${result.stderr} | | | | \${result} = | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | stderr=STDOUT | | | Log | all output: \${result.stdout} | | | | | \${result} = | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | stdout=DEVNULL | stderr=DEVNULL | Note that the created output files are not automatically removed after execution. 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 [subprocess.Popen](https://docs.python.org/3/library/subprocess.html#subprocess.Popen). Examples: | | | | |---|---|---| | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | command | stdin=PIPE | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | command | stdin=\${CURDIR}/stdin.txt | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Standard%20output%20and%20error%20streams) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) will be invalid. Examples: | | | | | |---|---|---|---| | [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) | program | output\_encoding=UTF-8 | | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | stdout=\${path} | output\_encoding=SYSTEM | ### Alias A custom name given to the process that can be used when selecting the [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). Examples: | | | | | | |---|---|---|---|---| | [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) | program | alias=example | | | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process), but [Switch Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Switch%20Process) can be used to activate a different process. Using [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) or the process object returned by it. ## Result object [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process), [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) and [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Result) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | | | Should Be Equal | \${result.rc} | 0 | type=int | | 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} | | | Notice that in `stdout` and `stderr` content possible trailing newline is removed and `\r\n` converted to `\n` automatically. If you need to see the original process output, redirect it to a file using [process configuration](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20configuration) and read it from there. ## 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 ``` ## Keywords ## [Get Process Id](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Id "Link to this keyword") #### Arguments handle \= None [Popen]("Click") \| [str]("Click") \| [None]("Click") #### Return Type int #### Documentation Returns the process ID (pid) of the process as an integer. If `handle` is not given, uses the current [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) like `${process.pid}`. ## [Get Process Object](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Object "Link to this keyword") #### Arguments handle \= None [Popen]("Click") \| [str]("Click") \| [None]("Click") #### Return Type [Popen]("Click") #### Documentation Return the underlying `subprocess.Popen` object. If `handle` is not given, uses the current [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). Starting from Robot Framework 5.0, [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) returns the created `subprocess.Popen` object, not a generic handle, making this keyword mostly redundant. ## [Get Process Result](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Result "Link to this keyword") #### Arguments handle \= None [Popen]("Click") \| [str]("Click") \| [None]("Click") rc \= False [bool]("Click") stdout \= False [bool]("Click") stderr \= False [bool]("Click") stdout\_path \= False [bool]("Click") stderr\_path \= False [bool]("Click") #### Return Type ProcessResult \| int \| str \| tuple\[int \| str, ...\] #### Documentation Returns the specified [result object](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) must be finished either with [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) or [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) before using this keyword. If no other arguments than the optional `handle` are given, a whole [result object](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) is returned. If one or more of the other arguments are given any true value, only the specified attributes of the [result object](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) are returned. These attributes are always returned in the same order as arguments are specified in the keyword signature. 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. ## [Is Process Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Is%20Process%20Running "Link to this keyword") #### Arguments handle \= None [Popen]("Click") \| [str]("Click") \| [None]("Click") #### Return Type bool #### Documentation Checks is the process running or not. If `handle` is not given, uses the current [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). Returns `True` if the process is still running and `False` otherwise. ## [Join Command Line](https://robotframework.org/robotframework/latest/libraries/Process.html#Join%20Command%20Line "Link to this keyword") #### Arguments \* command [Sequence]("Click")\[[str]("Click")\] \| [str]("Click") #### Return Type str #### Documentation 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. Command to join can be given as individual arguments or as a list. Giving command as individual arguments: | | | | | |---|---|---|---| | \${cmd} = | Join Command Line | \--option | value with spaces | | Should Be Equal | \${cmd} | \--option "value with spaces" | | Giving command as a list: | | | | | |---|---|---|---| | VAR | @{arguments} | \--option | value with spaces | | \${cmd} = | Join Command Line | \${arguments} | | | Should Be Equal | \${cmd} | \--option "value with spaces" | | ## [Process Should Be Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20Should%20Be%20Running "Link to this keyword") #### Arguments handle \= None [Popen]("Click") \| [str]("Click") \| [None]("Click") error\_message \= Process is not running. [str]("Click") #### Documentation Verifies that the process is running. If `handle` is not given, uses the current [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). Fails if the process has stopped. ## [Process Should Be Stopped](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20Should%20Be%20Stopped "Link to this keyword") #### Arguments handle \= None [Popen]("Click") \| [str]("Click") \| [None]("Click") error\_message \= Process is running. [str]("Click") #### Documentation Verifies that the process is not running. If `handle` is not given, uses the current [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). Fails if the process is still running. ## [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process "Link to this keyword") #### Arguments command [str]("Click") \* arguments [str]("Click") \| [Secret]("Click") 🏷 cwd \= None [str]("Click") \| [None]("Click") 🏷 shell \= False [bool]("Click") 🏷 stdout \= None [str]("Click") \| [None]("Click") 🏷 stderr \= None [str]("Click") \| [None]("Click") 🏷 stdin \= None [str]("Click") \| [Secret]("Click") \| [Path]("Click") \| [int]("Click") \| IOBase \| [None]("Click") 🏷 output\_encoding \= CONSOLE [str]("Click") 🏷 alias \= None [str]("Click") \| [None]("Click") 🏷 timeout \= None [timedelta]("Click") \| [None]("Click") 🏷 on\_timeout \= terminate [Literal]("Click")\['continue', 'terminate', 'kill'\] 🏷 env \= None [dict]("Click")\[[str]("Click"), [str]("Click") \| [Secret]("Click")\] \| [None]("Click") \*\* env\_extra [str]("Click") \| [Secret]("Click") #### Return Type [ProcessResult]("Click") #### Documentation 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Specifying%20command%20and%20arguments) for more details. The started process can be configured using `cwd`, `shell`, `stdout`, `stderr`, `stdin`, `output_encoding`, `alias`, `env` and `env_extra` parameters that are documented in the [Process configuration](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20configuration) section. Configuration related to waiting for processes consists of `timeout` and `on_timeout` parameters that have same semantics than with the [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) keyword. Process outputs are, by default, written into in-memory buffers. This typically works fine, but there can be problems if the amount of output is large or unlimited. To avoid such problems, outputs can be redirected to files using the `stdout` and `stderr` configuration parameters. For more information see the [Standard output and error streams](https://robotframework.org/robotframework/latest/libraries/Process.html#Standard%20output%20and%20error%20streams) section. Returns a [result object](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) containing information about the execution. Note that possible equal signs in `command` and `arguments` must be escaped with a backslash (e.g. `name\=value`). 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). ## [Send Signal To Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Send%20Signal%20To%20Process "Link to this keyword") #### Arguments signal [int]("Click") \| [str]("Click") handle \= None [Popen]("Click") \| [str]("Click") \| [None]("Click") group \= False [bool]("Click") #### Documentation Sends the given `signal` to the specified process. If `handle` is not given, uses the current [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Running%20processes%20in%20shell), 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, give the `group` argument a true value. ## [Split Command Line](https://robotframework.org/robotframework/latest/libraries/Process.html#Split%20Command%20Line "Link to this keyword") #### Arguments command [str]("Click") escaping \= False [bool]("Click") #### Return Type list\[str\] #### Documentation 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 doubling backslashes in Windows paths and elsewhere. Examples: | | | | |---|---|---| | @{cmd} = | Split Command Line | \--option "value with spaces" | | Should Be True | \$cmd == \['--option', 'value with spaces'\] | | ## [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process "Link to this keyword") #### Arguments command [str]("Click") \* arguments [str]("Click") \| [Secret]("Click") 🏷 cwd \= None [str]("Click") \| [None]("Click") 🏷 shell \= False [bool]("Click") 🏷 stdout \= None [str]("Click") \| [None]("Click") 🏷 stderr \= None [str]("Click") \| [None]("Click") 🏷 stdin \= None [str]("Click") \| [Secret]("Click") \| [Path]("Click") \| [int]("Click") \| IOBase \| [None]("Click") 🏷 output\_encoding \= CONSOLE [str]("Click") 🏷 alias \= None [str]("Click") \| [None]("Click") 🏷 env \= None [dict]("Click")\[[str]("Click"), [str]("Click") \| [Secret]("Click")\] \| [None]("Click") \*\* env\_extra [str]("Click") \| [Secret]("Click") #### Return Type [Popen]("Click") #### Documentation Starts a new process on background. See [Specifying command and arguments](https://robotframework.org/robotframework/latest/libraries/Process.html#Specifying%20command%20and%20arguments) and [Process configuration](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20configuration) sections for more information about the arguments, and [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). Returns the created [subprocess.Popen](https://docs.python.org/3/library/subprocess.html#popen-objects) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) | \${command} | alias=example | | \# Other keywords | | | | \${result} = | [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) | example | Use returned `Popen` object: | | | | |---|---|---| | \${process} = | [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) | \${command} | | Log | PID: \${process.pid} | | | \# Other keywords | | | | \${result} = | [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) | \${process} | Use started process in a pipeline with another process: | | | | | | | |---|---|---|---|---|---| | \${process} = | [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) | python | \-c | print('Hello, world!') | | | \${result} = | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | python | \-c | import sys; print(sys.stdin.read().upper().strip()) | stdin=\${process.stdout} | | [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) | \${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](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Object) separately. ## [Switch Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Switch%20Process "Link to this keyword") #### Arguments handle [Popen]("Click") \| [str]("Click") \| [None]("Click") #### Documentation Makes the specified process the current [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). The handle can be an identifier returned by [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) 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 | | | ## [Terminate All Processes](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20All%20Processes "Link to this keyword") #### Arguments kill \= False [bool]("Click") #### Documentation 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, Tries to terminate processes gracefully by default, but can be configured to forcefully kill them immediately. See [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) that this keyword uses internally for more details. ## [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process "Link to this keyword") #### Arguments handle \= None [Popen]("Click") \| [str]("Click") \| [None]("Click") kill \= False [bool]("Click") #### Return Type [ProcessResult]("Click") #### Documentation Stops the process gracefully or forcefully. If `handle` is not given, uses the current [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). By default, first tries to stop the process gracefully. If the process does not stop in 30 seconds, or the `kill` argument is given a true value, 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) containing information about the execution similarly as [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process). On Unix-like machines graceful termination is done using `TERM (15)` signal and forceful kill using `KILL (9)`. Use [Send Signal To Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Send%20Signal%20To%20Process) 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 forceful kill using Win32 API function `TerminateProcess()`. In this case forceful kill only stops the main process, not possible child processes. Examples: | | | | | |---|---|---|---| | \${result} = | Terminate Process | | | | Should Be Equal As Integers | \${result.rc} | \-15 | \# On Unixes | | Terminate Process | myproc | kill=true | | ## [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process "Link to this keyword") #### Arguments handle \= None [Popen]("Click") \| [str]("Click") \| [None]("Click") timeout \= None [timedelta]("Click") \| [None]("Click") on\_timeout \= continue [Literal]("Click")\['continue', 'terminate', 'kill'\] #### Return Type ProcessResult \| None #### Documentation 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process). If `handle` is not given, uses the current [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). `timeout` defines the maximum time to wait for the process. It can be given in [various time formats](http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#time-format) supported by Robot Framework, for example, `42`, `42 s`, or `1 minute 30 seconds`. The timeout is ignored if it is `None` (default), 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) 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 | | Note: If Robot Framework's test or keyword timeout is exceeded while this keyword is waiting for the process to end, the process is killed to avoid leaving it running on the background. This is new in Robot Framework 7.3. ## Data types ## boolean (Standard) #### Documentation Strings `TRUE`, `YES`, `ON`, `1` and possible localization specific "true strings" are converted to Boolean `True`, the empty string, strings `FALSE`, `NO`, `OFF` and `0` and possibly localization specific "false strings" are converted to Boolean `False`, and the string `NONE` is converted to the Python `None` object. Other strings and all other values are passed as-is, allowing keywords to handle them specially if needed. All string comparisons are case-insensitive. Examples: `TRUE` (converted to `True`), `off` (converted to `False`), `example` (used as-is) #### Converted Types - string - integer - float - None #### Usages - [Get Process Result](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Result) - [Is Process Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Is%20Process%20Running) - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Send Signal To Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Send%20Signal%20To%20Process) - [Split Command Line](https://robotframework.org/robotframework/latest/libraries/Process.html#Split%20Command%20Line) - [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) - [Terminate All Processes](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20All%20Processes) - [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) ## dictionary (Standard) #### Documentation Strings must be Python [dictionary](https://docs.python.org/library/stdtypes.html#dict) literals. They are converted to actual dictionaries using the [ast.literal\_eval](https://docs.python.org/library/ast.html#ast.literal_eval) function. They can contain any values `ast.literal_eval` supports, including dictionaries and other collections. Any mapping is accepted and converted to a `dict`. If the type has nested types like `dict[str, int]`, items are converted to those types automatically. This in new in Robot Framework 6.0. Examples: `{'a': 1, 'b': 2}`, `{'key': 1, 'nested': {'key': 2}}` #### Converted Types - string - Mapping #### Usages - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) ## integer (Standard) #### Documentation Conversion is done using Python's [int](https://docs.python.org/library/functions.html#int) built-in function. Floating point numbers are accepted only if they can be represented as integers exactly. For example, `1.0` is accepted and `1.1` is not. It is possible to use hexadecimal, octal and binary numbers by prefixing values with `0x`, `0o` and `0b`, respectively. Spaces and underscores can be used as visual separators for digit grouping purposes. Examples: `42`, `-1`, `0b1010`, `10 000 000`, `0xBAD_C0FFEE` #### Converted Types - string - float #### Usages - [Get Process Id](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Id) - [Get Process Result](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Result) - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Send Signal To Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Send%20Signal%20To%20Process) - [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) ## list (Standard) #### Documentation Strings must be Python [list](https://docs.python.org/library/stdtypes.html#list) or [tuple](https://docs.python.org/library/stdtypes.html#tuple) literals. They are converted using the [ast.literal\_eval](https://docs.python.org/library/ast.html#ast.literal_eval) function and possible tuples converted further to lists. They can contain any values `ast.literal_eval` supports, including lists and other collections. If the argument is a list, it is used without conversion. Tuples and other sequences are converted to lists. If the type has nested types like `list[int]`, items are converted to those types automatically. Examples: `['one', 'two']`, `[('one', 1), ('two', 2)]` Support to convert nested types is new in Robot Framework 6.0. Support for tuple literals is new in Robot Framework 7.4. #### Converted Types - string - Sequence #### Usages - [Split Command Line](https://robotframework.org/robotframework/latest/libraries/Process.html#Split%20Command%20Line) ## Literal (Standard) #### Documentation Only specified values are accepted. Values can be strings, integers, bytes, Booleans, enums and None, and used arguments are converted using the value type specific conversion logic. Strings are case, space, underscore and hyphen insensitive, but exact matches have precedence over normalized matches. #### Converted Types - Any #### Usages - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) ## None (Standard) #### Documentation String `NONE` (case-insensitive) and the empty string are converted to the Python `None` object. Other values cause an error. Converting the empty string is new in Robot Framework 7.4. #### Converted Types - string #### Usages - [Get Process Id](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Id) - [Get Process Object](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Object) - [Get Process Result](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Result) - [Is Process Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Is%20Process%20Running) - [Process Should Be Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20Should%20Be%20Running) - [Process Should Be Stopped](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20Should%20Be%20Stopped) - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Send Signal To Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Send%20Signal%20To%20Process) - [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) - [Switch Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Switch%20Process) - [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) - [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) ## Path (Standard) #### Documentation Strings are converted [Path](https://docs.python.org/library/pathlib.html) objects. On Windows `/` is converted to `\` automatically. Examples: `/tmp/absolute/path`, `relative/path/to/file.ext`, `name.txt` #### Converted Types - string - PurePath #### Usages - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) ## Popen (Custom) #### Documentation [subprocess.Popen](https://docs.python.org/library/subprocess.html#popen-objects) object. Returned by [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process). Can be used as a `handle` with keywords like [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) when working with multiple concurrent processes. Attributes like `pid` and `stdin` can also be accessed directly. Examples: | | | | |---|---|---| | \${process} = | [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) | \${command} | | Log | PID: \${process.pid} | | | \# Oher keywords | | | | \${result} = | [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) | \${process} | #### Usages - [Get Process Id](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Id) - [Get Process Object](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Object) - [Get Process Result](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Result) - [Is Process Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Is%20Process%20Running) - [Process Should Be Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20Should%20Be%20Running) - [Process Should Be Stopped](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20Should%20Be%20Stopped) - [Send Signal To Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Send%20Signal%20To%20Process) - [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) - [Switch Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Switch%20Process) - [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) - [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) ## ProcessResult (Custom) #### Documentation An object containing process execution results in its attributes. | 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | | | Should Be Equal | \${result.rc} | 0 | type=int | | 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} | | | Notice that in `stdout` and `stderr` content possible trailing newline is removed and `\r\n` converted to `\n` automatically. If you need to see the original process output, redirect it to a file using [process configuration](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20configuration) and read it from there. #### Usages - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) ## Secret (Standard) #### Documentation Encapsulates secret values to avoid them being shown in Robot Framework logs. The value is required to be [robot.api.types.Secret](https://robot-framework.readthedocs.io/en/master/autodoc/robot.utils.html#robot.utils.secret.Secret) object. These objects encapsulate confidential values so that they are not exposed in log files. How to create them is explained in the [User Guide](https://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#secret-variables). New in Robot Framework 7.4. #### Converted Types - string #### Usages - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) ## Sequence (Standard) #### Documentation Strings must be Python [list](https://docs.python.org/library/stdtypes.html#list) or [tuple](https://docs.python.org/library/stdtypes.html#tuple) literals. They are converted to actual lists or tuples using the [ast.literal\_eval](https://docs.python.org/library/ast.html#ast.literal_eval) function. They can contain any values `ast.literal_eval` supports, including lists and other collections. Any sequence is accepted without conversion. An exception is that if the used type is `MutableSequence`, immutable values are converted to lists. If the type has nested types like `Sequence[int]`, items are converted to those types automatically. Examples: `['one', 'two']`, `(1, 2, 3)` Support to convert nested types is new in Robot Framework 6.0. Support for tuple literals is new in Robot Framework 7.4. #### Converted Types - string - Sequence #### Usages - [Join Command Line](https://robotframework.org/robotframework/latest/libraries/Process.html#Join%20Command%20Line) ## string (Standard) #### Documentation All arguments are converted to Unicode strings. Most values are converted simply by using `str(value)`. An exception is that bytes are mapped directly to Unicode code points with same ordinals. This means that, for example, `b"hyv\xe4"` becomes `"hyvä"`. Converting bytes specially is new Robot Framework 7.4. #### Converted Types - Any #### Usages - [Get Process Id](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Id) - [Get Process Object](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Object) - [Get Process Result](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Result) - [Is Process Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Is%20Process%20Running) - [Join Command Line](https://robotframework.org/robotframework/latest/libraries/Process.html#Join%20Command%20Line) - [Process Should Be Running](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20Should%20Be%20Running) - [Process Should Be Stopped](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20Should%20Be%20Stopped) - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Send Signal To Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Send%20Signal%20To%20Process) - [Split Command Line](https://robotframework.org/robotframework/latest/libraries/Process.html#Split%20Command%20Line) - [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) - [Switch Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Switch%20Process) - [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) - [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) ## timedelta (Standard) #### Documentation Strings are expected to represent a time interval in one of the time formats Robot Framework supports: - a number representing seconds like `42` or `10.5` - a time string like `1 hour 2 seconds` or `1h 2s` - a "timer" string like `01:02` (1 minute 2 seconds) or `01:00:03` (1 hour 3 seconds) Integers and floats are considered to be seconds. See the [Robot Framework User Guide](https://robotframework.org/robotframework/) for more details about the supported time formats. #### Converted Types - string - integer - float #### Usages - [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) - [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) ## tuple (Standard) #### Documentation Strings must be Python [tuple](https://docs.python.org/library/stdtypes.html#tuple) or [list](https://docs.python.org/library/stdtypes.html#list) literals. They are converted using the [ast.literal\_eval](https://docs.python.org/library/ast.html#ast.literal_eval) function and possible lists converted further to tuples. They can contain any values `ast.literal_eval` supports, including tuples and other collections. If the argument is a tuple, it is used without conversion. Lists and other sequences are converted to tuples. If the type has nested types like `tuple[str, int, int]`, items are converted to those types automatically. Examples: `('one', 'two')`, `(('one', 1), ('two', 2))` Support to convert nested types is new in Robot Framework 6.0. Support for list literals is new in Robot Framework 7.4. #### Converted Types - string - Sequence #### Usages - [Get Process Result](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Result) Generated by [Libdoc](http://robotframework.org/robotframework/#built-in-tools) on 2026-03-03T16:39:18+00:00. [Process image/svg+xml](https://robotframework.org/robotframework/latest/libraries/Process.html#library-documentation-top)

Robot Framework library for running processes. The library has following main usages: - Running processes in system and waiting for their completion using the [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) keyword. - Starting processes on background using the [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) keyword. - Waiting started process to complete using [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) or stopping them with [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) or [Terminate All Processes](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20All%20Processes). This library provides various benefits over using `Run` and other similar keywords in the [OperatingSystem](http://robotframework.org/robotframework/latest/libraries/OperatingSystem.html) library: - Better [process configuration](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20configuration). - Convenient [result object](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) with all result information (rc, stdout, stderr). - Support for background processes, process termination, sending signals and so on. This library utilizes Python's [subprocess](http://docs.python.org/library/subprocess.html) module and its [Popen](http://docs.python.org/library/subprocess.html#popen-constructor) class. ### Table of contents - [Specifying command and arguments](https://robotframework.org/robotframework/latest/libraries/Process.html#Specifying%20command%20and%20arguments) - [Process configuration](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20configuration) - [Active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process) - [Result object](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) - [Example](https://robotframework.org/robotframework/latest/libraries/Process.html#Example) - [Keywords](https://robotframework.org/robotframework/latest/libraries/Process.html#Keywords) ## Specifying command and arguments Both [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) and [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Running%20processes%20in%20shell), 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | \${tools}\${/}prog.py | argument | second arg with spaces | | | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | java | \-jar | \${jars}\${/}example.jar | \--option | value | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | prog.py "one arg" && tool.sh | shell=yes | cwd=\${tools} | | | Possible non-string arguments are converted to strings automatically. ## Process configuration [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) and [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) keywords can be configured using optional configuration arguments. These arguments must be given after other arguments passed to these keywords and must use the `name=value` syntax. Available configuration arguments are listed below and discussed further in the subsequent sections. | Name | Explanation | |---|---| | shell | Specify whether to run the command in a shell or not. | | cwd | Specify the working directory. | | env | Specify environment variables given to the process. | | \*\*env\_extra | Override named environment variables using `env:<name>=<value>` syntax. | | stdout | Path to a file where to write standard output. | | stderr | Path to 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 | A custom name given to the process. | Note that possible equal signs in other arguments passed to [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) and [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) must be escaped with a backslash like `name\=value`. See [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Specifying%20command%20and%20arguments) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Standard%20output%20and%20error%20streams), when redirected to files, are also relative to the current working directory possibly set using the `cwd` argument. Example: | | | | | |---|---|---|---| | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | env=\${environ} | | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | env:http\_proxy=10.144.1.10:8080 | env:PATH=%{PATH}\${:}\${PROGDIR} | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | 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 typically works fine, but there can be problems if the amount of output is large or unlimited. Prior to Robot Framework 7.3 the limit was smaller than nowadays and reaching it caused a deadlock. 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 output. This can also be useful if other processes or other keywords need to read or manipulate the output somehow. Given `stdout` and `stderr` paths are relative to the [current working directory](https://robotframework.org/robotframework/latest/libraries/Process.html#Current%20working%20directory). Forward slashes in the given paths are automatically converted to backslashes on Windows. Regardless are outputs redirected to files or not, they are accessible through the [result object](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) returned when the process ends. Commands are expected to write outputs using the console encoding, but [output encoding](https://robotframework.org/robotframework/latest/libraries/Process.html#Output%20encoding) can be configured using the `output_encoding` argument if needed. As a special feature, it is possible to redirect the standard error to the standard output by using `stderr=STDOUT`. If you are not interested in output at all, you can explicitly ignore it 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 even a huge amount of output cannot cause problems, but naturally the output is not available after execution either. Examples: | | | | | | |---|---|---|---|---| | \${result} = | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | stdout=\${TEMPDIR}/stdout.txt | stderr=\${TEMPDIR}/stderr.txt | | Log Many | stdout: \${result.stdout} | stderr: \${result.stderr} | | | | \${result} = | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | stderr=STDOUT | | | Log | all output: \${result.stdout} | | | | | \${result} = | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | stdout=DEVNULL | stderr=DEVNULL | Note that the created output files are not automatically removed after execution. 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 [subprocess.Popen](https://docs.python.org/3/library/subprocess.html#subprocess.Popen). Examples: | | | | |---|---|---| | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | command | stdin=PIPE | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | command | stdin=\${CURDIR}/stdin.txt | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Standard%20output%20and%20error%20streams) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Result%20object) will be invalid. Examples: | | | | | |---|---|---|---| | [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) | program | output\_encoding=UTF-8 | | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | stdout=\${path} | output\_encoding=SYSTEM | ### Alias A custom name given to the process that can be used when selecting the [active process](https://robotframework.org/robotframework/latest/libraries/Process.html#Active%20process). Examples: | | | | | | |---|---|---|---|---| | [Start Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) | program | alias=example | | | | [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process), but [Switch Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Switch%20Process) can be used to activate a different process. Using [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Start%20Process) or the process object returned by it. ## Result object [Run Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process), [Wait For Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Wait%20For%20Process) and [Terminate Process](https://robotframework.org/robotframework/latest/libraries/Process.html#Terminate%20Process) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Get%20Process%20Result) 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](https://robotframework.org/robotframework/latest/libraries/Process.html#Run%20Process) | program | | | Should Be Equal | \${result.rc} | 0 | type=int | | 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} | | | Notice that in `stdout` and `stderr` content possible trailing newline is removed and `\r\n` converted to `\n` automatically. If you need to see the original process output, redirect it to a file using [process configuration](https://robotframework.org/robotframework/latest/libraries/Process.html#Process%20configuration) and read it from there. ## 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 ```