Process

Library version: 3.2.2

Library scope: GLOBAL
Named arguments: supported

Introduction
Robot Framework test library for running processes.

This library utilizes Python's subprocess module and its Popen class.

The library has following main usages:

• Running processes in system and waiting for their completion using Run
Process keyword.
• Starting processes on background using Start Process.
• Waiting started process to complete using Wait For Process or stopping them
with Terminate Process or Terminate All Processes.

Table of contents

• Specifying command and arguments

• Process configuration
• Active process
• Result object
• Boolean arguments
• Example
• Shortcuts
• Keywords

Specifying command and arguments

Both Run Process and Start Process accept the command to execute and all arguments
passed to the command as separate arguments. This makes usage convenient and also
allows these keywords to automatically escape possible spaces and other special
characters in commands and arguments. Notice that if a command accepts options that
themselves accept values, these options and their values must be given as separate
arguments.

When running processes in shell, it is also possible to give the whole command to
execute as a single string. The command can then contain multiple commands to be
run together. When using this approach, the caller is responsible on escaping.

Examples:
Run
${tools}${/}prog.py argument second arg with spaces
Process
Run --
java -jar ${jars}${/}example.jar value
Process option
Run prog.py "one arg" &&
shell=yes cwd=${tools}
Process tool.sh

Possible non-string arguments are converted to strings automatically.

Process configuration
Run Process and Start Process keywords can be configured using optional
**configuration keyword arguments. Configuration arguments must be given after
other arguments passed to these keywords and must use syntax like name=value.
Available configuration arguments are listed below and discussed further in sections
afterwards.

Name Explanation
shell Specifies whether to run the command in shell or not.
cwd Specifies the working directory.
env Specifies environment variables given to the process.
env:<name> Overrides the named environment variable(s) only.
stdout Path of a file where to write standard output.
stderr Path of a file where to write standard error.
output_encoding Encoding to use when reading command outputs.
alias Alias given to the process.

Note that because **configuration is passed using name=value syntax, possible

equal signs in other arguments passed to Run Process and Start Process must be
escaped with a backslash like name\=value. See Run Process for an example.

Running processes in shell

The shell argument specifies whether to run the process in a shell or not. By default
shell is not used, which means that shell specific commands, like copy and dir on
Windows, are not available. You can, however, run shell scripts and batch files
without using a shell.

Giving the shell argument any non-false value, such as shell=True, changes the
program to be executed in a shell. It allows using the shell capabilities, but can also
make the process invocation operating system dependent. Having a shell between the
actually started process and this library can also interfere communication with the
process such as stopping it and reading its outputs. Because of these problems, it is
recommended to use the shell only when absolutely necessary.
When using a shell it is possible to give the whole command to execute as a single
string. See Specifying command and arguments section for examples and more details
in general.

Current working directory

By default the child process will be executed in the same directory as the parent
process, the process running tests, is executed. This can be changed by giving an
alternative location using the cwd argument. Forward slashes in the given path are
automatically converted to backslashes on Windows.

Standard output and error streams, when redirected to files, are also relative to the
current working directory possibly set using the cwd argument.

Example:

Run Process prog.exe cwd=${ROOT}/directory stdout=stdout.txt

Environment variables

By default the child process will get a copy of the parent process's environment
variables. The env argument can be used to give the child a custom environment as a
Python dictionary. If there is a need to specify only certain environment variable, it is
possible to use the env:<name>=<value> format to set or override only that named
variables. It is also possible to use these two approaches together.

Examples:

Run
progra
Proces env=${environ}
m
s
Run
progra env:http_proxy=10.144.1.10: env:PATH=%{PATH}${:}${PROG
Proces
m 8080 DIR}
s
Run
progra
Proces env=${environ} env:EXTRA=value
m
s

Standard output and error streams

By default processes are run so that their standard output and standard error streams
are kept in the memory. This works fine normally, but if there is a lot of output, the
output buffers may get full and the program can hang. Additionally on Jython,
everything written to these in-memory buffers can be lost if the process is terminated.

To avoid the above mentioned problems, it is possible to use stdout and stderr
arguments to specify files on the file system where to redirect the outputs. This can
also be useful if other processes or other keywords need to read or manipulate the
outputs somehow.

Given stdout and stderr paths are relative to the current working directory.
Forward slashes in the given paths are automatically converted to backslashes on
Windows.

As a special feature, it is possible to redirect the standard error to the standard output
by using stderr=STDOUT.

Regardless are outputs redirected to files or not, they are accessible through the result
object returned when the process ends. Commands are expected to write outputs using
the console encoding, but output encoding can be configured using the
output_encoding argument if needed.

If you are not interested in outputs at all, you can explicitly ignore them by using a
special value DEVNULL both with stdout and stderr. For example, stdout=DEVNULL
is the same as redirecting output on console with > /dev/null on UNIX-like
operating systems or > NUL on Windows. This way the process will not hang even if
there would be a lot of output, but naturally output is not available after execution
either.

Support for the special value DEVNULL is new in Robot Framework 3.2.

Examples:

${resu stdout=${TEMPDIR}/st stderr=${TEMPDIR}/st

Run Process program
lt} = dout.txt derr.txt
stdout: stderr:
Log
${result.std ${result.std
Many
out} err}
${resu
Run Process program stderr=STDOUT
lt} =
all output:
Log ${result.std
out}
${resu
Run Process program stdout=DEVNULL stderr=DEVNULL
lt} =

Note that the created output files are not automatically removed after the test run. The
user is responsible to remove them if needed.

Output encoding

Executed commands are, by default, expected to write outputs to the standard output
and error streams using the encoding used by the system console. If the command
uses some other encoding, that can be configured using the output_encoding
argument. This is especially useful on Windows where the console uses a different
encoding than rest of the system, and many commands use the general system
encoding instead of the console encoding.

The value used with the output_encoding argument must be a valid encoding and
must match the encoding actually used by the command. As a convenience, it is
possible to use strings CONSOLE and SYSTEM to specify that the console or system
encoding is used, respectively. If produced outputs use different encoding then
configured, values got through the result object will be invalid.

Examples:

Start Process program output_encoding=UTF-8

Run Process program stdout=${path} output_encoding=SYSTEM

The support to set output encoding is new in Robot Framework 3.0.

Alias

A custom name given to the process that can be used when selecting the active
process.

Examples:

Start Process program alias=example

Run Process python -c print 'hello' alias=hello

Active process
The test library keeps record which of the started processes is currently active. By
default it is latest process started with Start Process, but Switch Process can be used to
select a different one. 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 the identifier returned by Start Process or an alias explicitly given
to Start Process or Run Process.

Result object
Run Process, Wait For Process and Terminate Process keywords return a result object
that contains information about the process execution as its attributes. The same result
object, or some of its attributes, can also be get using Get Process Result keyword.
Attributes available in the object are documented in the table below.

Attribute Explanation
rc Return code of the process as an integer.
stdout Contents of the standard output stream.
stderr Contents of the standard error stream.
stdout_path Path where stdout was redirected or None if not redirected.
stderr_path Path where stderr was redirected or None if not redirected.

Example:

${result} = Run Process program

Should Be Equal As Integers ${result.rc} 0
Should Match ${result.stdout} Some t?xt*
Should Be Empty ${result.stderr}
${stdout} = Get File ${result.stdout_path}
Should Be Equal ${stdout} ${result.stdout}
File Should Be Empty ${result.stderr_path}

Boolean arguments
Some keywords accept arguments that are handled as Boolean values true or false. If
such an argument is given as a string, it is considered false if it is an empty string or
equal to FALSE, NONE, NO, OFF or 0, case-insensitively. Other strings are considered
true regardless their value, and other argument types are tested using the same rules as
in Python.

True examples:

Terminate Process kill=True # Strings are generally true.

Terminate Process kill=yes # Same as the above.
Terminate Process kill=${TRUE} # Python True is true.
Terminate Process kill=${42} # Numbers other than 0 are true.

False examples:

Terminate Process kill=False # String false is false.

Terminate Process kill=no # Also string no is false.
Terminate Process kill=${EMPTY} # Empty string is false.
Terminate Process kill=${FALSE} # Python False is false.

Considering string NONE false is new in Robot Framework 3.0.3 and considering also
OFF and 0 false is new in Robot Framework 3.1.

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

Shortcuts
List style: Compact Expanded
Get Process Id
Get Process Object
Get Process Result
Is Process Running
Join Command Line
Process Should Be Running
Process Should Be Stopped
Run Process
Send Signal To Process
Split Command Line
Start Process
Switch Process
Terminate All Processes
Terminate Process
Wait For Process

Keywords
Keyw
Arguments Documentation
ord
Returns the process ID (pid) of the process as an integer.
Get
If handle is not given, uses the current active process.
Proces handle=None
s Id
Notice that the pid is not the same as the handle returned
by Start Process that is used internally by this library.
Get
Return the underlying subprocess.Popen object.
Proces
handle=None
s
If handle is not given, uses the current active process.
Object
Get handle=None, Returns the specified result object or some of its attributes.
Proces rc=False,
s stdout=False, The given handle specifies the process whose results
Result stderr=False, should be returned. If no handle is given, results of the
stdout_path=Fal current active process are returned. In either case, the
se, process must have been finishes before this keyword can
stderr_path=Fal be used. In practice this means that processes started with
se Start Process must be finished either with Wait For Process
or Terminate Process before using this keyword.

If no other arguments than the optional handle are given, a

whole result object is returned. If one or more of the other
arguments are given any true value, only the specified
attributes of the result object are returned. These attributes
are always returned in the same order as arguments are
specified in the keyword signature. See Boolean arguments
section for more details about true and false values.

Examples:

Run print
alias=myp
Proces python -c 'Hello,
roc
s world!'
# Get
result
object
${resul Get Process mypr
t} = Result oc
Should
Be ${result.rc} ${0}
Equal
Hello
Should
${result.std ,
Be
out} world
Equal
!
Should
${result.std
Be
err}
Empty
# Get
one
attribut
e
${stdo Get Process mypr stdout=t
ut} = Result oc rue
Hello
Should
,
Be ${stdout}
world
Equal
!
 #
Multipl
e
attribut
es
Get
Proce
${stdo stdout=ye stderr=
${stderr} = ss myproc
ut} s yes
Resul
t
Hello
Should
,
Be ${stdout}
world
Equal
!
Should
Be ${stderr}
Empty

Although getting results of a previously executed process

can be handy in general, the main use case for this
keyword is returning results over the remote library
interface. The remote interface does not support returning
the whole result object, but individual attributes can be
returned without problems.
Checks is the process running or not.
Is
Proces
If handle is not given, uses the current active process.
s handle=None
Runni
Returns True if the process is still running and False
ng
otherwise.
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.
Join
Comm If this keyword is given only one argument and that is a list
*args
and like object, then the values of that list are joined instead.
Line
Example:

Join
value with
${cmd} = Command --option
spaces
Line
 Should Be --option "value
${cmd}
Equal with spaces"

New in Robot Framework 2.9.2.

Proces
Verifies that the process is running.
s handle=None,
Should error_message=
If handle is not given, uses the current active process.
Be Process is not
Runni running.
Fails if the process has stopped.
ng
Proces
Verifies that the process is not running.
s handle=None,
Should error_message=
If handle is not given, uses the current active process.
Be Process is
Stoppe running.
Fails if the process is still running.
d
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 for more details.

**configuration contains additional configuration

related to starting processes and waiting for them to finish.
See Process configuration for more details about
configuration related to starting processes. Configuration
related to waiting for processes consists of timeout and
on_timeout arguments that have same semantics as with
Wait For Process keyword. By default there is no timeout,
and if timeout is defined the default action on timeout is
Run command, terminate.
Proces *arguments,
s **configuration Returns a result object containing information about the
execution.

Note that possible equal signs in *arguments must be

escaped with a backslash (e.g. name\=value) to avoid
them to be passed in as **configuration.

Examples:

${res Run print 'Hello,

python -c
ult} = Process world!'
Shoul
${result.st Hello,
d Be
dout} world!
Equal
 ${res Run ${comma stderr=ST
timeout=10s
ult} = Process nd} DOUT
${res Run ${comma timeout=1 on_timeout=c
ult} = Process nd} min ontinue
java -
${res Run Dname\= cwd=${EXA
shell=True
ult} = Process value MPLE}
Example

This keyword does not change the active process.

Sends the given signal to the specified process.

If handle is not given, uses the current active process.

Signal can be specified either as an integer as a signal

name. In the latter case it is possible to give the name both
with or without SIG prefix, but names are case-sensitive.
For example, all the examples below send signal INT (2):

Send Signal To # Send to active

2
Process process
Send Signal To
INT
Process
Send Send Signal To # Send to named
Signal signal, SIGINT myproc
Process process
To handle=None,
Proces group=False
s This keyword is only supported on Unix-like machines, not
on Windows. What signals are supported depends on the
system. For a list of existing signals on your system, see
the Unix man pages related to signal handling (typically
man signal or man 7 signal).

By default sends the signal only to the parent process, not

to possible child processes started by it. Notice that when
running processes in shell, the shell is the parent process
and it depends on the system does the shell propagate the
signal to the actual started process.

To send the signal to the whole process group, group

argument can be set to any true value (see Boolean
arguments). This is not supported by Jython, however.
Splits command line string into a list of arguments.
Split
Comm args,
String is split from spaces, but argument surrounded in
and escaping=False
quotes may contain spaces in them. If escaping is given a
Line
true value, then backslash is treated as an escape character.
 It can escape unquoted spaces, quotes inside quotes, and so
on, but it also requires using double backslashes when
using Windows paths.

Examples:

--option "value
@{cmd} = Split Command Line
with spaces"
Should Be $cmd == ['--option',
True 'value with spaces']

New in Robot Framework 2.9.2.

Starts a new process on background.

See Specifying command and arguments and Process

configuration for more information about the arguments,
and Run Process keyword for related examples.
Start command,
Proces *arguments, Makes the started process new active process. Returns an
s **configuration identifier that can be used as a handle to activate the started
process if needed.

Processes are started so that they create a new process

group. This allows sending signals to and terminating also
possible child processes. This is not supported on Jython.
Makes the specified process the current active process.

The handle can be an identifier returned by Start Process or

the alias given to it explicitly.

Example:
Switch
Proces handle Start Process prog1 alias=process1
s
Start Process prog2 alias=process2
# currently active process is
process2
Switch Process process1
# now active process is process1
Terminates all still running processes started by this
library.
Termi
nate
This keyword can be used in suite teardown or elsewhere
All kill=False
to make sure that all processes are stopped,
Proces
ses
By default tries to terminate processes gracefully, but can
be configured to forcefully kill them immediately. See
 Terminate Process that this keyword uses internally for
more details.
Stops the process gracefully or forcefully.

If handle is not given, uses the current active process.

By default first tries to stop the process gracefully. If the

process does not stop in 30 seconds, or kill argument is
given a true value, (see Boolean arguments) kills the
process forcefully. Stops also all the child processes of the
originally started process.

Waits for the process to stop after terminating it. Returns a

result object containing information about the execution
similarly as Wait For Process.

On Unix-like machines graceful termination is done using

TERM (15) signal and killing using KILL (9). Use Send
Signal To Process instead if you just want to send either of
these signals without waiting for the process to stop.
Termi On Windows graceful termination is done using
nate handle=None, CTRL_BREAK_EVENT event and killing using Win32 API
Proces kill=False
function TerminateProcess().
s
Examples:

Terminate
${result} =
Process
Should Be Equal As # On
${result.rc} -15
Integers Unixes
Terminate Process myproc kill=true

Limitations:

• Graceful termination is not supported on Windows

when using Jython. Process is killed instead.
• Stopping the whole process group is not supported
when using Jython.
• On Windows forceful kill only stops the main
process, not possible child processes.

Wait handle=None,
Waits for the process to complete or to reach the given
For timeout=None,
timeout.
Proces on_timeout=co
s ntinue
The process to wait for must have been started earlier with
Start Process. If handle is not given, uses the current
active process.

timeout defines the maximum time to wait for the process.

It can be given in various time formats supported by Robot
Framework, for example, 42, 42 s, or 1 minute 30
seconds. The timeout is ignored if it is Python None
(default), string NONE (case-insensitively), zero, or
negative.

on_timeout defines what to do if the timeout occurs.

Possible values and corresponding actions are explained in
the table below. Notice that reaching the timeout never
fails the test.

Value Action
continue The process is left running (default).
terminate The process is gracefully terminated.
kill The process is forcefully stopped.

See Terminate Process keyword for more details how

processes are terminated and killed.

If the process ends before the timeout or it is terminated or

killed, this keyword returns a result object containing
information about the execution. If the process is left
running, Python None is returned instead.

Examples:

# Process
ends
cleanly
Wait For
${result} = example
Process
Process
Should Be example
Stopped
Should Be
Equal As ${result.rc} 0
Integers
# Process
does not
end
 Wait For timeout=42
${result} =
Process secs
Process
Should Be
Running
Should Be
${result} ${NONE}
Equal
# Kill non-
ending
process
Wait For timeout=1min
${result} = on_timeout=kill
Process 30s
Process
Should Be
Stopped
Should Be
Equal As ${result.rc} -9
Integers

Ignoring timeout if it is string NONE, zero, or negative is

new in Robot Framework 3.2.

Altogether 15 keywords.
Generated by Libdoc on 2020-09-01 21:22:49.