# Copyright 2008-2015 Nokia Networks
# Copyright 2016- Robot Framework Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import os
import signal as signal_module
import subprocess
import sys
import time
from collections.abc import Sequence
from datetime import timedelta
from io import IOBase
from pathlib import Path
from tempfile import NamedTemporaryFile
from typing import Literal, Union
from robot.api import logger
from robot.api.deco import library
from robot.api.types import Secret
from robot.errors import TimeoutExceeded
from robot.utils import (
cmdline2list, ConnectionCache, console_decode, console_encode, NormalizedDict,
secs_to_timestr, system_decode, system_encode, WINDOWS
)
from robot.version import get_version
LOCALE_ENCODING = "locale" if sys.version_info >= (3, 10) else None
Handle = Union[subprocess.Popen, str, None]
Stdin = Union[str, Secret, Path, int, IOBase, None]
OnTimeout = Literal["continue", "terminate", "kill"]
[docs]
class ProcessResult:
r"""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:
```robotframework
*** Test Cases ***
Run process
${result} = Run Process python -c print("Hello!")
Should Be Equal ${result.rc} 0 type=int
Should Be Equal ${result.stdout} Hello!
Should Be Empty ${result.stderr}
```
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] and read it from there.
"""
def __init__(
self,
process,
stdout,
stderr,
stdin=None,
rc=None,
output_encoding=None,
streams_to_close=(),
):
self._process = process
self.stdout_path = self._get_path(stdout)
self.stderr_path = self._get_path(stderr)
self.rc = rc
self._output_encoding = output_encoding
self._stdout = None
self._stderr = None
self._custom_streams = [
stream
for stream in (stdout, stderr, stdin)
if self._is_custom_stream(stream)
]
self._streams_to_close = streams_to_close
def _get_path(self, stream):
return stream.name if self._is_custom_stream(stream) else None
def _is_custom_stream(self, stream):
return stream not in (subprocess.PIPE, subprocess.STDOUT, None)
@property
def stdout(self):
if self._stdout is None:
self._read_stdout()
return self._stdout
@stdout.setter
def stdout(self, stdout):
self._stdout = self._format_output(stdout)
@property
def stderr(self):
if self._stderr is None:
self._read_stderr()
return self._stderr
@stderr.setter
def stderr(self, stderr):
self._stderr = self._format_output(stderr)
def _read_stdout(self):
self._stdout = self._read_stream(self.stdout_path, self._process.stdout)
def _read_stderr(self):
self._stderr = self._read_stream(self.stderr_path, self._process.stderr)
def _read_stream(self, stream_path, stream):
if stream_path:
stream = open(stream_path, "rb")
elif not self._is_open(stream):
return ""
try:
content = stream.read()
except OSError:
content = ""
finally:
if stream_path:
stream.close()
return self._format_output(content)
def _is_open(self, stream):
return stream and not stream.closed
def _format_output(self, output):
if output is None:
return None
output = console_decode(output, self._output_encoding).replace("\r\n", "\n")
if output.endswith("\n"):
output = output[:-1]
return output
[docs]
def close_streams(self):
if self._is_open(self._process.stdout):
self._read_stdout()
if self._is_open(self._process.stderr):
self._read_stderr()
for stream in self._streams_to_close:
stream.close()
self._streams_to_close = ()
def __str__(self):
return f"<result object with rc {self.rc}>"
[docs]
class ProcessConfiguration:
def __init__(
self,
cwd=None,
shell=False,
stdout=None,
stderr=None,
stdin=None,
output_encoding="CONSOLE",
alias=None,
env=None,
**env_extra,
):
self.cwd = os.path.normpath(cwd) if cwd else os.path.abspath(".")
self.shell = shell
self.alias = alias
self.output_encoding = output_encoding
self.streams_to_close = []
self.stdout_stream = self._new_stream(stdout)
self.stderr_stream = self._get_stderr(stderr, stdout, self.stdout_stream)
self.stdin_stream = self._get_stdin(stdin)
self.secret_env_keys = []
self.env = self._construct_env(env, env_extra)
def _new_stream(self, name):
if not name:
return subprocess.PIPE
if name == "DEVNULL":
stream = open(os.devnull, "w", encoding=LOCALE_ENCODING)
else:
path = os.path.normpath(os.path.join(self.cwd, name))
stream = open(path, "w", encoding=LOCALE_ENCODING)
self.streams_to_close.append(stream)
return stream
def _get_stderr(self, stderr, stdout, stdout_stream):
if stderr and stderr in ["STDOUT", stdout]:
if stdout_stream == subprocess.PIPE:
return subprocess.STDOUT
return stdout_stream
return self._new_stream(stderr)
def _get_stdin(self, stdin):
if isinstance(stdin, Path):
stdin = str(stdin)
elif isinstance(stdin, Secret):
stdin = stdin.value
elif not isinstance(stdin, str):
return stdin
elif stdin.upper() == "NONE":
return None
elif stdin == "PIPE":
return subprocess.PIPE
path = os.path.normpath(os.path.join(self.cwd, stdin))
if os.path.isfile(path):
stdin_file = open(path, encoding=LOCALE_ENCODING)
else:
stdin_file = NamedTemporaryFile(prefix="stdin-")
stdin_file.write(console_encode(stdin, self.output_encoding, force=True))
stdin_file.seek(0)
self.streams_to_close.append(stdin_file)
return stdin_file
def _construct_env(self, env, extra):
env = self._get_initial_env(env, extra)
if env is None:
return None
if WINDOWS:
env = NormalizedDict(env, spaceless=False)
self._add_to_env(env, extra)
if WINDOWS:
env = {key.upper(): env[key] for key in env}
return env
def _get_initial_env(self, env, extra):
if env:
result = {}
for name, value in env.items():
name = system_encode(name)
if isinstance(value, Secret):
result[name] = system_encode(value.value)
self.secret_env_keys.append(name)
else:
result[name] = system_encode(value)
return result
if extra:
return os.environ.copy()
return None
def _add_to_env(self, env, extra):
for name, value in extra.items():
if not name.startswith("env:"):
raise RuntimeError(
f"Keyword argument '{name}' is not supported by this keyword."
)
name = system_encode(name[4:])
if isinstance(value, Secret):
env[name] = system_encode(value.value)
self.secret_env_keys.append(name)
else:
env[name] = system_encode(value)
[docs]
def get_command(self, command, arguments):
command = [system_encode(item) for item in (command, *arguments)]
if not self.shell:
return command
if arguments:
return subprocess.list2cmdline(command)
return command[0]
@property
def popen_config(self):
config = {
"stdout": self.stdout_stream,
"stderr": self.stderr_stream,
"stdin": self.stdin_stream,
"shell": self.shell,
"cwd": self.cwd,
"env": self.env,
}
self._add_process_group_config(config)
return config
def _add_process_group_config(self, config):
if hasattr(os, "setsid"):
config["start_new_session"] = True
if hasattr(subprocess, "CREATE_NEW_PROCESS_GROUP"):
config["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
@property
def result_config(self):
return {
"stdout": self.stdout_stream,
"stderr": self.stderr_stream,
"stdin": self.stdin_stream,
"output_encoding": self.output_encoding,
"streams_to_close": tuple(self.streams_to_close),
}
def __str__(self):
if self.secret_env_keys:
secret_env = dict.fromkeys(self.secret_env_keys, str(Secret("")))
env = {**self.env, **secret_env}
else:
env = self.env
return f"""\
cwd: {self.cwd}
shell: {self.shell}
stdout: {self._stream_name(self.stdout_stream)}
stderr: {self._stream_name(self.stderr_stream)}
stdin: {self._stream_name(self.stdin_stream)}
alias: {self.alias}
env: {env}"""
def _stream_name(self, stream):
if hasattr(stream, "name"):
return stream.name
return {
subprocess.PIPE: "PIPE",
subprocess.STDOUT: "STDOUT",
None: "None",
}.get(stream, stream)
# Dummy argument converter for providing type documentation to Popen.
def _popen_documentation(value):
"""[subprocess.Popen] object.
Returned by [Start Process]. Can be used as a `handle` with keywords
like [Wait For Process] when working with multiple concurrent processes.
Attributes like `pid` and `stdin` can also be accessed directly.
Examples:
```robotframework
*** Test Cases ***
Popen Object
${process} = Start Process ${command}
Log PID: ${process.pid}
# Later
${result} = Terminate Process ${process}
```
"""
return value
[docs]
@library(
version=get_version(),
scope="GLOBAL",
doc_format="MARKDOWN",
converters={
ProcessResult: lambda value: value,
subprocess.Popen: _popen_documentation,
},
auto_keywords=True,
)
class Process:
r"""Robot Framework library for running processes.
The library has following main usages:
- Running processes in the system and waiting for their completion using
the [Run Process] keyword.
- Starting processes on background using the [Start Process] keyword.
- Waiting started process to complete using [Wait For Process] or
stopping them with [Terminate Process] or [Terminate All Processes].
This library provides various benefits over using `Run` and other similar
keywords in the [OperatingSystem] library:
- Better [process configuration].
- Convenient [result object] with all result information (`rc`, `stdout`,
`stderr`).
- Support for background processes, process termination, sending signals
and so on.
This library uses Python's standard [subprocess] module internally.
### Table of contents
%TOC%
# Specifying command and arguments
Both [Run Process] and [Start Process] accept the command to execute and
all arguments passed to the command as separate arguments. This makes usage
convenient and also allows these keywords to automatically escape possible
spaces and other special characters in commands and arguments. Notice that
if a command accepts options that themselves accept values, these options
and their values must be given as separate arguments.
When [running processes in shell], it is also possible to give the whole
command to execute as a single string. The command can then contain
multiple commands to be run together. When using this approach, the caller
is responsible on escaping.
Examples:
```robotframework
*** Test Cases ***
Command and arguments separately
Run Process python -c print("Hello!")
Run Process ${tools}/prog.py argument second arg with spaces
Command and arguments as single string
Run Process prog.py "one arg" && tool.sh shell=True 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 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 | Whether to run the command in a shell or not. |
| cwd | Directory where to run the command. |
| env | Environment variables as a dictionary. |
| **env_extra | 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 the [Run Process]
and [Start Process] keywords must be escaped with a backslash like `name\=value`.
See the [Run Process] keyword 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.
Using `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 the [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.
When [standard output and error streams] are redirected to files,
file paths are relative to the current working directory as well.
Example:
```robotframework
*** Test Cases ***
Current working directory
Run Process prog.exe cwd=${ROOT}/directory stdout=stdout.txt
```
## Environment variables
The child process will get a copy of the parent process's environment
variables by default. The `env` argument can be used to give the
child a custom environment as a Python dictionary. If there is a need
to specify only certain environment variable, it is possible to use the
`env:<name>=<value>` format to set or override only that named variables.
It is also possible to use these two approaches together.
Examples:
```robotframework
*** Test Cases ***
Environment variables
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 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].
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] 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.
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 outputs 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:
```robotframework
*** Test Cases ***
Redirect stdout and stderr
${result} = Run Process program stdout=${TMP}/stdout.txt stderr=${TMP}/stderr.txt
Merge stderr to stdout
${result} = Run Process program stderr=STDOUT
Discard output
${result} = Run Process 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 | Write the text to a temporary file and use it as the stdin. |
| Any other 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.
Examples:
```robotframework
*** Test Cases ***
Stdin as file
Run Process command stdin=${CURDIR}/stdin.txt
Stdin as text
Run Process command stdin=Stdin as text.
Stdin from other process
${process} = Start Process command1
Run Process command2 stdin=${process.stdout}
```
The [Examples] section has an executable example where output of a process
is passed to another using `stdin`.
The support to configure `stdin` is new in Robot Framework 4.1.2. Its default
value used to be `PIPE` until Robot Framework 7.0.
## Output encoding
Executed commands are, by default, expected to write outputs to the
[standard output and error streams] using the encoding used by the
system console. If the command uses some other encoding, that can be
configured using the `output_encoding` argument. This is especially
useful on Windows where the console can use 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:
```robotframework
*** Test Cases ***
Output encoding
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:
```robotframework
*** Test Cases ***
Alias
Start Process program alias=MyProgram
# Later
Wait For Process MyProgram
```
# 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:
```robotframework
*** Test Cases ***
Result object
${result} = Run Process python -c print("Hello!")
Should Be Equal ${result.rc} 0 type=int
Should Be Equal ${result.stdout} Hello!
Should Be Empty ${result.stderr}
```
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] and read it from there.
# Examples
These examples can be executed locally.
```robotframework
*** Settings ***
Library Process
Suite Teardown Terminate All Processes kill=True
*** Test Cases ***
Simple execution
${result} = Run Process python -c print("Hello, world!")
Should Be Equal ${result.stdout} Hello, world!
Background processes and process configuration
${process} = Start Process python -c print("Hello!")
Start Process
... python -c "import time; time.sleep(3)" && python -c "print('Hi!')"
... stdout=${CURDIR}/stdout.txt
... stderr=STDOUT
... shell=True
... alias=Slow
${result1} = Run Process python -c print("Moi!")
Should Be Equal ${result1.stdout} Moi!
${result2} = Wait For Process ${process}
Should Be Equal ${result2.stdout} Hello!
${result3} = Wait For Process Slow
Should Be Equal ${result3.stdout} Hi!
Pipeline
${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!
```
[OperatingSystem]: https://robotframework.org/robotframework/latest/libraries/OperatingSystem.html
[subprocess]: https://docs.python.org/library/subprocess.html
[subprocess.Popen]: https://docs.python.org/3/library/subprocess.html#popen-objects
"""
TERMINATE_TIMEOUT = 30
KILL_TIMEOUT = 10
def __init__(self):
self._processes = ConnectionCache[subprocess.Popen]("No active process.")
self._results: dict[subprocess.Popen, ProcessResult] = {}
[docs]
def run_process(
self,
command: str,
*arguments: "str | Secret",
cwd: "str | None" = None,
shell: bool = False,
stdout: "str | None" = None,
stderr: "str | None" = None,
stdin: Stdin = None,
output_encoding: str = "CONSOLE",
alias: "str | None" = None,
timeout: "timedelta | None" = None,
on_timeout: OnTimeout = "terminate",
env: "dict[str, str | Secret] | None" = None,
**env_extra: "str | Secret",
) -> ProcessResult:
r"""Runs a process and waits for it to complete.
Args:
command: Command to execute.
*arguments: Arguments passed to the command.
cwd: Working directory of the process.
shell: Whether to run the command in a shell.
stdout: Path to file for standard output.
stderr: Path to file for standard error.
stdin: Process standard input configuration.
output_encoding: Encoding for reading command outputs.
alias: Custom name for the process.
timeout: Maximum time to wait for the process.
on_timeout: Action when timeout occurs.
env: Environment variables as a Python dictionary.
**env_extra: Override named environment variables using
`env:<name>=<value>` syntax.
Returns:
Result object containing execution results.
`command` and `arguments` specify the command to execute and arguments
passed to it. See the [Specifying command and arguments] section for
more details.
The started process can be configured using the `cwd`, `shell`, `stdout`,
`stderr`, `stdin`, `output_encoding`, `env`, `env_extra` and `alias`
parameters that are documented in the [Process configuration] section.
Configuration related to waiting for processes consists of `timeout`
and `on_timeout` parameters that have same semantics than with the
[Wait For Process] 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. See the [Standard output and error streams] section for
more information.
Note that possible equal signs in `command` and `arguments` must
be escaped with a backslash (e.g. `name\=value`).
This keyword does not change the [active process].
Examples:
```robotframework
*** Test Cases ***
Run process
${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=1 minute on_timeout=continue
${result} = Run Process java -Dname\=value Example shell=True cwd=${EXAMPLE}
```
"""
current = self._processes.current
try:
handle = self.start_process(
command,
*arguments,
cwd=cwd,
shell=shell,
stdout=stdout,
stderr=stderr,
stdin=stdin,
output_encoding=output_encoding,
alias=alias,
env=env,
**env_extra,
)
return self.wait_for_process(handle, timeout, on_timeout)
finally:
self._processes.current = current
[docs]
def start_process(
self,
command: str,
*arguments: "str | Secret",
cwd: "str | None" = None,
shell: bool = False,
stdout: "str | None" = None,
stderr: "str | None" = None,
stdin: Stdin = None,
output_encoding: str = "CONSOLE",
alias: "str | None" = None,
env: "dict[str, str | Secret] | None" = None,
**env_extra: "str | Secret",
) -> subprocess.Popen:
"""Starts a new process on background.
Args:
command: Command to execute.
*arguments: Arguments passed to the command.
cwd: Working directory for the process.
shell: Whether to run the command in a shell.
stdout: Path to file for standard output.
stderr: Path to file for standard error.
stdin: Process standard input configuration.
output_encoding: Encoding for reading command outputs.
alias: Custom name for the process.
env: Environment variables as a Python dictionary.
**env_extra: Override named environment variables using
`env:<name>=<value>` syntax.
Returns:
Created [subprocess.Popen] object which can be used later to activate
this process. `Popen` attributes like `pid` can also be accessed directly.
See the [Specifying command and arguments] and [Process configuration]
sections for more information about the arguments, and the [Run Process]
keyword for related examples. This includes information about redirecting
process outputs to avoid process handing due to output buffers getting
full.
Processes are started so that they create a new process group. This
allows terminating and sending signals to possible child processes.
Makes the started process new [active process].
Examples:
```robotframework
*** Test Cases ***
Start process and wait using alias
Start Process ${command} alias=example
# Later
${result} = Wait For Process example
Start process and terminate using process object
${process} = Start Process ${command}
Log PID: ${process.pid}
# Later
Terminate Process ${process}
```
See the [Examples] section for examples starting multiple processes
and creating process pipelines.
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 the [Get Process Object] keyword separately.
"""
config = ProcessConfiguration(
cwd=cwd,
shell=shell,
stdout=stdout,
stderr=stderr,
stdin=stdin,
output_encoding=output_encoding,
alias=alias,
env=env,
**env_extra,
)
actual_arguments = []
logged_arguments = []
for arg in arguments:
actual_arguments.append(arg.value if isinstance(arg, Secret) else arg)
logged_arguments.append(str(arg))
self._log_start(config.get_command(command, logged_arguments), config)
process = subprocess.Popen(
config.get_command(command, actual_arguments), **config.popen_config
)
self._results[process] = ProcessResult(process, **config.result_config)
self._processes.register(process, alias=config.alias)
return self._processes.current
def _log_start(self, command: "str | list[str]", config: ProcessConfiguration):
if isinstance(command, list):
command = self.join_command_line(*command)
logger.info(f"Starting process:\n{system_decode(command)}")
logger.debug(f"Process configuration:\n{config}")
[docs]
def is_process_running(self, handle: Handle = None) -> bool:
"""Checks is the process running or not.
Args:
handle: Process handle or alias. Uses the current [active process]
by default.
Returns:
`True` if the process is still running and `False` otherwise.
"""
return self._processes[handle].poll() is None
[docs]
def process_should_be_running(
self,
handle: Handle = None,
error_message: str = "Process is not running.",
):
"""Verifies that the process is running.
Args:
handle: Process handle or alias. Uses the current [active process]
by default.
error_message: Message used if verification fails.
Raises:
AssertionError: If the process has stopped.
"""
if not self.is_process_running(handle):
raise AssertionError(error_message)
[docs]
def process_should_be_stopped(
self,
handle: Handle = None,
error_message: str = "Process is running.",
):
"""Verifies that the process is not running.
Args:
handle: Process handle or alias. Uses the current [active process]
by default.
error_message: Message used if verification fails.
Raises:
AssertionError: If the process is still running.
"""
if self.is_process_running(handle):
raise AssertionError(error_message)
[docs]
def wait_for_process(
self,
handle: Handle = None,
timeout: "timedelta | None" = None,
on_timeout: OnTimeout = "continue",
) -> "ProcessResult | None":
"""Waits for the process to complete or to reach the given timeout.
Args:
handle: Process handle or alias. Uses the current [active process]
by default.
timeout: Maximum time to wait for the process.
on_timeout: What to do if the process does not end within the `timeout`.
Returns:
Result object if the process ends, `None` if it is left running.
The process to wait for must have been started earlier using the
[Start Process] keyword.
`timeout` defines the maximum time to wait for the process. It can be
given in formats like `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 the [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.
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.
Examples:
```robotframework
*** Test Cases ***
Process ends cleanly
${result} = Wait For Process example
Process Should Be Stopped example
Should Be Equal ${result.rc} 0 type=int
Process does not end
${result} = Wait For Process timeout=42 secods
Process Should Be Running
Should Be Equal ${result} None type=None
Kill non-ending process
${result} = Wait For Process timeout=1min 30s on_timeout=kill
Should Be Equal ${result.rc} -9 type=int
```
"""
process = self._processes[handle]
logger.info("Waiting for process to complete.")
timeout = timeout.total_seconds() if timeout else -1
if timeout > 0 and not self._process_is_stopped(process, timeout):
logger.info(f"Process did not complete in {secs_to_timestr(timeout)}.")
return self._manage_process_timeout(handle, on_timeout.lower())
return self._wait(process)
def _manage_process_timeout(
self,
handle: subprocess.Popen,
on_timeout: str,
) -> "ProcessResult | None":
if on_timeout == "terminate":
return self.terminate_process(handle)
if on_timeout == "kill":
return self.terminate_process(handle, kill=True)
logger.info("Leaving process intact.")
return None
def _wait(self, process: subprocess.Popen) -> ProcessResult:
result = self._results[process]
# Popen.communicate() does not like closed stdin/stdout/stderr PIPEs.
# Due to us using a timeout, we only need to care about stdin.
# https://github.com/python/cpython/issues/131064
if process.stdin and process.stdin.closed:
process.stdin = None
# Timeout is used with communicate() to support Robot's timeouts.
while True:
try:
result.stdout, result.stderr = process.communicate(timeout=0.1)
except subprocess.TimeoutExpired:
continue
except TimeoutExceeded:
logger.info("Timeout exceeded.")
self._kill(process)
raise
else:
break
result.rc = process.returncode
result.close_streams()
logger.info("Process completed.")
return result
[docs]
def terminate_process(
self,
handle: Handle = None,
kill: bool = False,
) -> ProcessResult:
"""Stops the process gracefully or forcefully.
Args:
handle: Process handle or alias. Uses the current [active process]
by default.
kill: Whether to forcefully kill the process.
Returns:
Result object containing information about the execution.
Raises:
RuntimeError: If terminating processes is not supported by the
used Python version, or if forceful kill fails.
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] containing information about the execution similarly
as [Wait For Process].
On Unix-like machines graceful termination is done using the `TERM (15)`
signal and forceful kill 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 the `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.
"""
process = self._processes[handle]
if not hasattr(process, "terminate"):
raise RuntimeError(
"Terminating processes is not supported by this Python version."
)
terminator = self._kill if kill else self._terminate
try:
terminator(process)
except OSError:
if not self._process_is_stopped(process, self.KILL_TIMEOUT):
raise
logger.debug("Ignored OSError because process was stopped.")
return self._wait(process)
def _kill(self, process: subprocess.Popen):
logger.info("Forcefully killing process.")
if hasattr(os, "killpg"):
os.killpg(process.pid, signal_module.SIGKILL)
else:
process.kill()
if not self._process_is_stopped(process, self.KILL_TIMEOUT):
raise RuntimeError("Failed to kill process.")
def _terminate(self, process: subprocess.Popen):
logger.info("Gracefully terminating process.")
# Sends signal to the whole process group both on POSIX and on Windows
# if supported by the interpreter.
if hasattr(os, "killpg"):
os.killpg(process.pid, signal_module.SIGTERM)
elif hasattr(signal_module, "CTRL_BREAK_EVENT"):
process.send_signal(signal_module.CTRL_BREAK_EVENT)
else:
process.terminate()
if not self._process_is_stopped(process, self.TERMINATE_TIMEOUT):
logger.info("Graceful termination failed.")
self._kill(process)
[docs]
def terminate_all_processes(self, kill: bool = False):
"""Terminates all still running processes started by this library.
Args:
kill: Whether to forcefully kill processes.
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 the
[Terminate Process] keyword that this keyword uses internally for
more details.
"""
for process in self._processes:
if self.is_process_running(process):
self.terminate_process(process, kill=kill)
self.__init__()
[docs]
def send_signal_to_process(
self,
signal: "int | str",
handle: Handle = None,
group: bool = False,
):
"""Sends the given `signal` to the specified process.
Args:
signal: The signal to send, either as an integer or signal name.
handle: Process handle or alias. Uses the current [active process]
by default.
group: Whether to send the signal to the whole process group.
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)`.
```robotframework
*** Test Cases ***
Send signal
Send Signal To Process 2
Send Signal To Process INT
Send Signal To Process SIGINT myproc
```
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.
"""
if os.sep == "\\":
raise RuntimeError("This keyword does not work on Windows.")
process = self._processes[handle]
signum = self._get_signal_number(signal)
logger.info(f"Sending signal {signal} ({signum}).")
if group and hasattr(os, "killpg"):
os.killpg(process.pid, signum)
elif hasattr(process, "send_signal"):
process.send_signal(signum)
else:
raise RuntimeError(
"Sending signals is not supported by this Python version."
)
def _get_signal_number(self, int_or_name: "int | str") -> int:
try:
return int(int_or_name)
except ValueError:
return self._convert_signal_name_to_number(int_or_name)
def _convert_signal_name_to_number(self, name: str) -> int:
try:
return getattr(
signal_module, name if name.startswith("SIG") else "SIG" + name
)
except AttributeError:
raise RuntimeError(f"Unsupported signal '{name}'.")
[docs]
def get_process_id(self, handle: Handle = None) -> int:
"""Returns the process ID (pid) of the process as an integer.
Args:
handle: Process handle or alias. Uses the current [active process]
by default.
Returns:
Process ID as an integer.
Starting from Robot Framework 5.0, it is also possible to directly access
the `pid` attribute of the [subprocess.Popen] object returned by the
[Start Process] keyword like `${process.pid}`.
"""
return self._processes[handle].pid
[docs]
def get_process_object(self, handle: Handle = None) -> subprocess.Popen:
"""Return the underlying `subprocess.Popen` object.
Args:
handle: Process handle or alias. Uses the current [active process]
by default.
Returns:
The underlying [subprocess.Popen] object.
Starting from Robot Framework 5.0, the [Start Process] keyword returns
the created [subprocess.Popen] object directly. That makes this keyword
mostly redundant.
"""
return self._processes[handle]
[docs]
def get_process_result(
self,
handle: Handle = None,
rc: bool = False,
stdout: bool = False,
stderr: bool = False,
stdout_path: bool = False,
stderr_path: bool = False,
) -> "ProcessResult | int | str | tuple[int | str, ...]":
"""Returns the specified [result object] or some of its attributes.
Args:
handle: Process handle or alias. Uses the current [active process]
by default.
rc: If true, return the return code.
stdout: If true, return the standard output.
stderr: If true, return the standard error.
stdout_path: If true, return the stdout path.
stderr_path: If true, return the stderr path.
Returns:
A result object, a single attribute, or a tuple of attributes
depending on which arguments are given.
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.
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.
Examples:
```robotframework
*** Test Cases ***
Get process result
Run Process python -c print('Hello, world!') alias=myproc
# Get result object
${result} = Get Process Result myproc
Should Be Equal ${result.rc} 0 type=int
Should Be Equal ${result.stdout} Hello, world!
# Get one attribute
${stdout} = Get Process Result myproc stdout=Trye
Should Be Equal ${stdout} Hello, world!
# Get multiple attributes
${stdout} ${stderr} = Get Process Result myproc rc=True stderr=True
Should Be Equal ${rc} 0 type=int
Should Be Equal ${stdout} Hello, world!
```
"""
result = self._results[self._processes[handle]]
if result.rc is None:
raise RuntimeError(
"Getting results of unfinished processes is not supported."
)
attributes = self._get_result_attributes(
result, rc, stdout, stderr, stdout_path, stderr_path
)
if not attributes:
return result
if len(attributes) == 1:
return attributes[0]
return attributes
def _get_result_attributes(self, result, *includes):
attributes = (
result.rc,
result.stdout,
result.stderr,
result.stdout_path,
result.stderr_path,
)
return tuple(attr for attr, incl in zip(attributes, includes) if incl)
[docs]
def switch_process(self, handle: Handle):
"""Makes the specified process the current [active process].
Args:
handle: Process handle or alias to activate.
The handle can be the process object returned by the [Start Process]
keyword or the `alias` given to it explicitly.
Example:
```robotframework
*** Test Cases ***
Switch Active Process
Start Process prog1 alias=process1
Start Process prog2 alias=process2
# The active process is 'process2' at this point.
Switch Process process1
# Now active process is 'process1'.
```
"""
self._processes.switch(handle)
def _process_is_stopped(self, process: subprocess.Popen, timeout: float) -> bool:
stopped = lambda: process.poll() is not None
max_time = time.time() + timeout
while time.time() <= max_time and not stopped():
time.sleep(min(0.1, timeout))
return stopped()
[docs]
def split_command_line(self, command: str, escaping: bool = False) -> "list[str]":
"""Splits command line string into a list of arguments.
Args:
command: Command line string to split.
escaping: Whether to treat backslash as an escape character.
Returns:
List of command line 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:
```robotframework
*** Test Cases ***
Parse Command Line
@{cmd} = Split Command Line --option "value with spaces"
Should Be Equal ${cmd} ['--option', 'value with spaces'] type=list
```
"""
return cmdline2list(command, escaping=escaping)
[docs]
def join_command_line(self, *command: "Sequence[str] | str") -> str:
"""Joins arguments into one command line string.
Args:
*command: Arguments to join, either as individual strings or as a list.
Returns:
Joined 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.
Examples:
```robotframework
*** Test Cases ***
Command as individual arguments
${cmd} = Join Command Line --option value with spaces
Should Be Equal ${cmd} --option "value with spaces"
Command as list
VAR @{arguments} --option value with spaces
${cmd} = Join Command Line ${arguments}
Should Be Equal ${cmd} --option "value with spaces"
```
"""
parts = []
for part in command:
if isinstance(part, str):
parts.append(part)
else:
parts.extend(part)
return subprocess.list2cmdline(parts)