Source code for robot.libraries.Process

#  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)