OperatingSystem - Documentation

Introduction

This test library enables multiple operating-system-related tasks.

Shortcuts

Copy Directory  Copy File  Count Directories In Directory  Count Files In Directory  Count Items In Directory  Create Dir  Create Directory  Create File  Directory Should Be Empty  Directory Should Exist  Directory Should Not Be Empty  Directory Should Not Exist  Empty Directory  Environment Variable Should Be Set  Environment Variable Should Not Be Set  File Should Be Empty  File Should Exist  File Should Not Be Empty  File Should Not Exist  Get Environment Variable  Get File  Get File Size  Get File With Encoding  Get Modified Time  Grep File  Join Path  Join Paths  List Directories In Directory  List Directory  List Files In Directory  Log File  Move Directory  Move File  Normalize Path  Read Process Output  Remove Directory  Remove Environment Variable  Remove File  Remove Files  Run  Run And Return Rc  Run And Return Rc And Output  Set Environment Variable  Set Modified Time  Should Exist  Should Not Exist  Split Extension  Split Path  Start Process  Stop All Processes  Stop Process  Switch Process  Touch  Wait Until Created  Wait Until Removed 

Keywords

Keyword Arguments Documentation
Copy Directory source, destination Copies the source directory into the destination.

If the destination exists, the source is copied under it. Otherwise
the destination directory and the possible missing intermediate
directories are created.
Copy File source, destination Copies the source file into a new destination.

1) If the destination is an existing file, the source file is copied
over it.
2) If the destination is an existing directory, the source file is
copied into it. A possible file with the same name is overwritten.
3) If the destination does not exist and it ends with a path separator
('/' in UNIX-like systems, '\' in Windows), it is considered a
directory. That directory is created and a source file copied into it.
Possible missing intermediate directories are also created.
4) If the destination does not exist and it does not end with a path
separator, it is considered a file. If the path to the file does not
exist, it is created.
Count Directories In Directory path, pattern=None, pattern_type=simple Returns the number of subdirectories in the given directory.

The arguments 'pattern' and 'pattern_type' have the same semantics as
in the 'List Directory' keyword. The count is returned as an integer, so
it must be checked e.g. with the built-in keyword
'Should Be Equal As Integers'.
Count Files In Directory path, pattern=None, pattern_type=simple Returns the number of files in the given directory.

The arguments 'pattern' and 'pattern_type' have the same semantics as
in the 'List Directory' keyword. The count is returned as an integer, so
it must be checked e.g. with the built-in keyword
'Should Be Equal As Integers'.
Count Items In Directory path, pattern=None, pattern_type=simple Returns the number of all items in the given directory.

The arguments 'pattern' and 'pattern_type' have the same semantics as
in the 'List Directory' keyword. The count is returned as an integer, so
it must be checked e.g. with the built-in keyword
'Should Be Equal As Integers'.
Create Dir path Creates a directory, and all the intermediate ones, with the given path.

Passes if the directory does not exist and fails if the path does not
point to a regular file (e.g. it points to a directory).
Create Directory path Creates a directory, and all the intermediate ones, with the given path.

Passes if the directory does not exist and fails if the path does not
point to a regular file (e.g. it points to a directory).
Create File path, content=, mode=overwrite Creates a file to the given path with the given content.

If the mode contains any of the strings 'False', 'No', "Don't"
(case-insensitive, so e.g. "Do not" also works) the keyword fails,
if the file already exists and the file is not overwritten. If it
contains the word 'Append'(case-insensitive), the content is appended.
Otherwise the file is overwritten.

If the directory where to create file does not exist it, and possible
intermediate missing directories, are created.
Directory Should Be Empty path, msg=None Fails unless the specified directory is empty.

The default error message can be overridden with the 'msg' argument.
Directory Should Exist path, msg=None Fails unless the given path points to an existing directory.

The path can be given as an exact path or as a pattern where
'*'        - matches everything
'?'        - matches any single character
'[chars]'  - matches any character inside square brackets (e.g. '[abc]'
matches either 'a', 'b' or 'c')
'[!chars]' - matches any character not inside square brackets

The default error message can be overridden with the 'msg' argument.
Directory Should Not Be Empty path, msg=None Fails if the specified directory is empty.

The default error message can be overridden with the 'msg' argument.
Directory Should Not Exist path, msg=None Fails if the given path points to an existing file.

The path can be given as an exact path or as a pattern where
'*'        - matches everything
'?'        - matches any single character
'[chars]'  - matches any character inside square brackets (e.g. '[abc]'
matches either 'a', 'b' or 'c')
'[!chars]' - matches any character not inside square brackets

The default error message can be overridden with the 'msg' argument.
Empty Directory path Deletes all the content (incl. subdirs) from the given directory.
Environment Variable Should Be Set name, msg=None Fails if the specified environment variable is not set.

The default error message can be overridden with the 'msg' argument.
Environment Variable Should Not Be Set name, msg=None Fails if the specified environment variable is set.

The default error message can be overridden with the 'msg' argument.
File Should Be Empty path, msg=None Fails unless the specified file is empty.

The default error message can be overridden with the 'msg' argument.
File Should Exist path, msg=None Fails unless the given path points to an existing file.

The path can be given as an exact path or as a pattern where
'*'        - matches everything
'?'        - matches any single character
'[chars]'  - matches any character inside square brackets (e.g. '[abc]'
matches either 'a', 'b' or 'c')
'[!chars]' - matches any character not inside square brackets

The default error message can be overridden with the 'msg' argument.
File Should Not Be Empty path, msg=None Fails if the specified directory is empty.

The default error message can be overridden with the 'msg' argument.
File Should Not Exist path, msg=None Fails if the given path points to an existing file.

The path can be given as an exact path or as a pattern where
'*'        - matches everything
'?'        - matches any single character
'[chars]'  - matches any character inside square brackets (e.g. '[abc]'
matches either 'a', 'b' or 'c')
'[!chars]' - matches any character not inside square brackets

The default error message can be overridden with the 'msg' argument.
Get Environment Variable name, default=None Returns the value of an environment variable with the given name.

If no such environment variable is set, returns the default value, if
given. Otherwise fails the test case.

Note that you can also access environment variables directly using
the variable syntax %{ENV_VAR_NAME}.
Get File path, encoding=UTF-8 Returns the contents of a specified file.

This keyword reads the specified file and returns the contents.
'encoding' defines the encoding of the file. By default, the value is
'UTF-8', which means that UTF-8 and ASCII-encoded files are
read correctly.
Get File Size path Returns file size as an integer in bytes
Get File With Encoding path, encoding=UTF-8 Deprecated. Will be removed in Robot 1.9

This keyword reads the specified file and returns the contents.
'encoding' defines the encoding of the file. By default, the value is
'UTF-8', which means that UTF-8 and ASCII-encoded files are
read correctly.
Get Modified Time path, format=timestamp Returns the last modification time of a file or directory.

How time is returned is determined based on the given 'format' string as
follows. Note that all checks are case-insensitive.

- If 'format' contains the word 'epoch', the time is returned in seconds
after the UNIX epoch. The return value is always an integer.
- If 'format' contains any of the words 'year', 'month', 'day', 'hour',
'min' or 'sec', only the selected parts are returned. The order of the
returned parts is always the one in the previous sentence and the
order of the words in 'format' is not significant. The parts are
returned as zero-padded strings (e.g. May -> '05').
- Otherwise (and by default) the time is returned as a timestamp string
in the format '2006-02-24 15:08:31'.

Examples (when the modified time of the ${CURDIR} is
2006-03-29 15:06:21):
${time} = Get Modified Time ${CURDIR}
${secs} = Get Modified Time ${CURDIR} epoch
${year} = Get Modified Time ${CURDIR} return year
${y} ${d} = Get Modified Time ${CURDIR} year,day
@{time} = Get Modified Time ${CURDIR} year,month,day,hour,min,sec
=>
${time} = '2006-03-29 15:06:21'
${secs} = 1143637581
${year} = '2006'
${y} = '2006', ${d} = '29'
@{time} = [ '2006', '03', '29', '15', '06', '21' ]
Grep File path, pattern, pattern_type=literal string, encoding=UTF-8 Returns the contents of a specified file grepped using 'pattern'.

This keyword reads the specified file and returns only lines matching
the 'pattern'. 'encoding' defines the encoding of the file. By default,
the value is 'UTF-8', which means that UTF-8 and ASCII-encoded files are
read correctly.

'pattern_type' defines how the given pattern is interpreted as explained
below. 'pattern_type' argument is case-insensitive and may contain other
text. For example, 'regexp', 'REGEXP' and 'Pattern is a regexp' are all
considered equal.

- If 'pattern_type' contains either the string 'simple' or 'glob', the
'pattern' is considered a simple pattern and lines returned only if
they match it. (1)
- If 'pattern_type' contains either the string 'regular expression' or
'regexp', the 'pattern' is considered a regular expression and only
lines matching it returned. (2)
- If 'pattern_type' contains the string 'case insensitive' the 'pattern'
is considered a literal string and lines returned, if they contain the
string, regardless of the case.
- Otherwise the pattern is considered a literal string and lines
returned, if they contain the string exactly. This is the default.

1) Simple pattern matching is similar as matching files in a shell, and
it is always case-sensitive. In the pattern, '*' matches to anything
and '?' matches to any single character.

2) Regular expression check is done using the Python 're' module,
which has a pattern syntax derived from Perl and thus also very similar to the
one in Java. See the following documents from more details about regexps
in general and their Python implementation in particular.

're' Module Documentation: http://docs.python.org/lib/module-re.html
Regular Expression HOWTO: http://www.amk.ca/python/howto/regex/

Note that if you want to use flags (e.g. re.IGNORECASE), you have to
embed them into the pattern (e.g. '(?i)pattern'). Note also that
backslash is an escape character in Robot Framework test data, and
possible backslashes in patterns must thus be escaped with another
backslash (e.g. '\\d\\w+').
Join Path base, *parts Joins the given path part(s) to the given base path.

The path separator ('/' or '\') is inserted when needed and the
possible absolute paths handled as expected. The resulted path is also
normalized.

Examples (assuming a UNIX environment):
${path} = Join Path my path
${p2} = Join Path my/ path/
${p3} = Join Path my path my file.txt
${p4} = Join Path my /path
${p5} = Join Path /my/path/ .. path2
=>
${path} = 'my/path'
${p2} = 'my/path'
${p3} = 'my/path/my/file.txt'
${p4} = '/path'
${p5} = '/my/path2'
Join Paths base, *paths Joins given paths with base and returns resulted paths.

Examples (assuming a UNIX environment):
@{p1} = Join Path base example other
@{p2} = Join Path /my/base /example other
@{p3} = Join Path my/base example/path/ other one/more
=>
@{p1} = [ 'base/example', 'base/other' ]
@{p2} = [ '/example', '/my/base/other' ]
@{p3} = [ 'my/base/example/path', 'my/base/other', 'my/base/one/more' ]
List Directories In Directory path, pattern=None, pattern_type=simple, absolute=False A wrapper for 'List Directory' that returns only directories.
List Directory path, pattern=None, pattern_type=simple, absolute=False Returns items from the given directory, optionally filtered with
'pattern'.

File and directory names are returned in case-sensitive alphabetical
order, e.g. 'A Name', 'Second', 'a lower case name', 'one more'].
Implicit directories '.' and '..' are not returned. The returned items
are automatically logged.

By default, the file and directory names are returned relative to the
given path (e.g. 'file.txt'). If you want them be returned in the
absolute format (e.g. '/home/robot/file.txt'), set the 'absolute'
argument value to 'True', 'Yes' or 'absolute' (case-insensitive).

If no 'pattern' is given, all item names are returned. If 'pattern' is
given, only names matching it are returned. 'pattern_type' defines how
the given pattern is interpreted, as explained below.

- If 'pattern_type' contains the string 'simple' (case-insensitive), the
'pattern' is considered a simple pattern and items returned only if
they match it. This is the default. (1)
- If 'pattern_type' contains either the string 'regular expression' or
'regexp' (case-insensitive), the 'pattern' is considered a regular
expression and only items matching it returned. (2)
- Otherwise the pattern is considered a literal string and items
returned, if they contain the string.

1) Simple pattern matching is similar as matching files in a shell, and
it is always case-sensitive. The special characters are listed below.

'*'        - matches everything
'?'        - matches any single character
'[chars]'  - matches any character inside square brackets (e.g. '[abc]'
matches either 'a', 'b' or 'c')
'[!chars]' - matches any character not inside square brackets

Simple pattern matching is implemented using the Python 'fnmatch' module's
'fnmatchcase' method. For more information, see its documentation at
http://docs.python.org/lib/module-fnmatch.html.

2) Regular expression check is done using the Python 're' module, which
has a pattern syntax derived from Perl and thus also very similar to the
one in Java. See the following documents for more details about regexps
in general and their Python implementation in particular.

're' Module Documentation: http://docs.python.org/lib/module-re.html
Regular Expression HOWTO: http://www.amk.ca/python/howto/regex/

Note that if you want to use flags (e.g. re.IGNORECASE), you have to
embed them into the pattern (e.g. '(?i)pattern'). Note also that a
backslash is an escape character in Robot Framework test data, and
possible backslashes in patterns must thus be escaped with another
backslash (e.g. '\\d\\w+').
List Files In Directory path, pattern=None, pattern_type=simple, absolute=False A wrapper for 'List Directory' that returns only files.
Log File path, encoding=UTF-8 Wrapper for 'Get File' that also logs the returned file.

The file is logged with the INFO level. If you want something else,
just use 'Get File' and the built-in keyword 'Log' with the desired
level.
Move Directory source, destination Moves the source directory into a destination.

If a destination exists, the source is moved under it. Oherwise the
destination directory and the possible missing intermediate directories
are created.
Move File source, destination Moves the source file into a new destination.

The destination may be a file or a directory. In the latter case, the
file's original basename is kept. If the destination file exists, it is
overwritten. The missing intermediate directories are NOT created.
Normalize Path path Normalizes the given path.

Examples (assuming a UNIX environment):
${path} = Normalize Path abc
${p2} = Normalize Path abc/
${p3} = Normalize Path abc/../def
${p4} = Normalize Path abc/./def
${p5} = Normalize Path abc//def
=>
${path} = 'abc'
${p2} = 'abc'
${p3} = 'def'
${p4} = 'abc/def'
${p5} = 'abc/def'
Read Process Output mode=stdout Waits for the process to finish and returns its output.

'mode' defines which outputs are returned. If it contains 'stdout',
the standard output is returned. If it contains 'stderr', the  standard
error is returned. If it contains 'stderr' and 'stdout' or 'both', the
standard output and standard error are returned.

If the mode contains only 'stdout', but there are contents on stderr,
this keyword fails.

Note that although the process is finished, it is not removed from the
process list. Trying to read from a stopped process nevertheless
fails. To reset the process list (and indexes and aliases),
'Stop All Processes' must be used.

See 'Start Process' and 'Switch Process' for more information.
Remove Directory path, recursive=no Removes the directory pointed to by the given 'path'.

If the second argument 'recursive' contains any of the words 'yes',
'true' or 'recursive' (case-insensitive), all of the directory contents
are also removed. Otherwise removing fails, if the directory is not
empty.

If the directory pointed to by the 'path' does not exist, the keyword
passes, but it fails, if the 'path' points to a file.
Remove Environment Variable name Deletes the specified environment variable.

Does nothing if the environment variable is not set.
Remove File path Removes a file with the given path.

Passes if the file does not exist, but fails if the path does not point
to a regular file (e.g. it points to a directory).

The path can be given as an exact path or as a pattern where
'*'        - matches everything
'?'        - matches any single character
'[chars]'  - matches any character inside square brackets (e.g. '[abc]'
matches either 'a', 'b' or 'c')
'[!chars]' - matches any character not inside square brackets
Remove Files *paths Uses 'Remove File' to remove multiple files one-by-one.
Run command, return_mode=stdout Runs the given command in the system and returns a return code and/or stdout.

'return_mode' defines how the return code (rc) and the standard output
(stdout) are returned as explained below. All checks are
case-insensitive.
* If it contains the word 'rc' and either the word 'stdout' or 'output', both
the rc and stdout are returned.
* Otherwise, if it contains the word 'rc', only the rc is returned.
* Otherwise, and by default, only the stdout is returned.

The rc is returned as an integer. It must thus be checked e.g. with the
keyword 'Should Be Equal As Integers' instead of 'Should Be Equal' (both
are built-in keywords). Return codes are positive integers within the
range from 0 to 255 as returned by the command (if the command returns
some other value, the system maps it into this range).

The returned output contains everything written into the stdout by the
command. Many commands add an extra newline (\n) after the output to
ease reading it in the console. To ease processing the returned
output, Robot Framework strips this possible newline.

The possible standard error (stderr) from the executed command is NOT
captured by this keyword or other parts of Robot. If catching stderr is
important, it must be redirected into stdout or some file. The former
can be achieved (both in Windows and UNIX-like systems) with the syntax
'my_command 2>&1' and the latter with 'my_command 2>stderr.txt'.

Examples:
${output} = Run ls -lhF /tmp
Log ${output}
${rc} = Run ${CURDIR}${/}script.py Return RC
Should Be Equal As Integers ${rc} 0
${rc} ${out} = Run /opt/script.py 2>&1 RC,Output
Fail Unless ${rc} > 0
Contains ${out} TEST PASSED
Run And Return Rc command Wrapper for 'Run' keyword that returns only the return code.

Following two examples are equivalent but the latter is easier to
understand and thus recommended.

${rc} = Run my_command RC
${rc} = Run and Return RC my_command
Run And Return Rc And Output command Wrapper for the 'Run' keyword that returns the return code and output.

The following two examples are equivalent, but the latter is easier to
understand and thus recommended.

${rc} ${output} = Run my_command RC, Output
${rc} ${output} = Run and Return RC and Output my_command

Note that similarly as the normal 'Run', this keyword only returns the
standard output and not the standard error. Use either the format
'my_command 2>/tmp/stderr.txt' to redirect the stderr into a specific
file or 'my_command 2>&1' to return it along with the stdout.
Set Environment Variable name, value Sets an environment variable to a specified value.
Set Modified Time path, mtime Sets the file modification time.

Changes the modification and access times of the given file to the value
determined by 'mtime'. There are four different ways to give 'mtime'.

1) If 'mtime' is a floating point number, it is interpreted as
seconds since epoch (Jan 1, 1970 0:00:00). This documentation is written
about 1177654467 seconds since epoch.

2) If 'mtime' is a valid timestamp, that time will be used.
Valid timestamp formats are 'YYYY-MM-DD hh:mm:ss' and 'YYYYMMDD hhmmss'.

3) If 'mtime' is equal to 'NOW' (case-insensitive), the current time is
used.

4) If 'mtime' is in the format 'NOW - 1 day' or 'NOW + 1 hour 30 min',
the current time plus/minus the time specified with the time string is
used. The time string format is described in section Time format in
Robot Framework User Guide.

Examples:
Set Modified Time /path/file 1177654467 #(2007-04-27 9:14:27)
Set Modified Time /path/file 2007-04-27 9:14:27
Set Modified Time /path/file NOW # The time of execution
Set Modified Time /path/file NOW - 1d # 1 day subtraced from NOW
Set Modified Time /path/file NOW + 1h 2min 3s # 1h 2min 3s added to NOW
Should Exist path, msg=None Fails unless the given path (file or directory) exists.

The path can be given as an exact path or as a pattern where
'*'        - matches everything
'?'        - matches any single character
'[chars]'  - matches any character inside square brackets (e.g. '[abc]'
matches either 'a', 'b' or 'c')
'[!chars]' - matches any character not inside square brackets

The default error message can be overridden with the 'msg' argument.
Should Not Exist path, msg=None Fails if the given path (file or directory) exists.

The path can be given as an exact path or as a pattern where
'*'        - matches everything
'?'        - matches any single character
'[chars]'  - matches any character inside square brackets (e.g. '[abc]'
matches either 'a', 'b' or 'c')
'[!chars]' - matches any character not inside square brackets

The default error message can be overridden with the 'msg' argument.
Split Extension path Splits the extension from the given path.

The given path is first normalized (e.g. a possible trailing path
separator removed, special directories '..' and '.' removed).
The splitted parts are returned as separate components. If the path
contains no extension, an empty string is returned for it.

Examples (assuming a UNIX environment):
${path} ${ext} = Split Extension file.extension
${p2} ${e2} = Split Extension path/file.ext
${p3} ${e3} = Split Extension path/file
${p4} ${e4} = Split Extension p1/../p2/file.ext
=>
${path} = 'file', ${ext} = 'extension'
${p2} = 'path/file', ${e2} = 'ext'
${p3} = 'path/file', ${e3} = ''
${p4} = 'p2/file', ${e4} = 'ext'
Split Path path Splits the given path from the last path separator ('/' or '\').

The given path is first normalized (e.g. a possible trailing path
separator is removed, special directories '..' and '.' removed).
The splitted parts are returned as separate components.

Examples (assuming a UNIX environment):
${path1} ${dir} = Split Path abc/def
${path2} ${file} = Split Path abc/def/ghi.txt
${path3} ${d2}  = Split Path abc/../def/ghi/
=>
${path1} = 'abc', ${dir} = 'def'
${path2} = 'abc/def', ${file} = 'ghi.txt'
${path3} = 'def', ${d2} = 'ghi'
Start Process command, stdin=, alias=None Starts the given command as a background process.

Starts the process in the background and sets this process as the
current process. The following calls of the keywords
'Read Process Output' and 'Stop Process' affect this process, unless
the keyword 'Switch Process' is used. Then these keywords affect the
selected process.

If the command needs input, it can be defined with the 'stdin' argument.
It is not possible to give input to the command later.

Returns the index of this process. The indexing starts from 1, and it
can be used to switch between the processes with the 'Switch Process'
keyword. To end all processes and reset indexing, the
'Stop All Processes' keyword must be used.

The optional 'alias' is a name for this process that may be used with
'Switch Process' instead of the returned index.

Example:
Start Process longlasting.sh
Do Something
${stdout}= Read Process Output
Should Contain ${stdout} Expected text
[Teardown] Stop All Processes
Stop All Processes Stops all the processes and removes them from the process list.

Resets the indexing that 'Start Process' uses. All aliases are also
deleted.
Stop Process Stops the current process without reading from it.

Stopping a process does not remove it from the process list. To reset
the process list (and indexes and aliases), 'Stop All Processes' must be
used.

See 'Start Process' and 'Switch Process' for more information.
Switch Process index_or_alias Switches the current process to the process found with 'index_or_alias'.

The index is the return value of the 'Start Process' keyword and an
alias may have been defined to it.
Touch path Emulates the UNIX touch command.

Creates a file, if it does not exist. Otherwise changes its access and
modification times to the current time.

Fails if used with the directories or the parent directory of the given
file does not exist.
Wait Until Created path, timeout=1 minute Waits until the given file or directory is created.

The path can be given as an exact path or as a pattern where
'*'        - matches everything
'?'        - matches any single character
'[chars]'  - matches any character inside square brackets (e.g. '[abc]'
matches either 'a', 'b' or 'c')
'[!chars]' - matches any character not inside square brackets

If the path is a pattern, the keyword returns when an item matching to
the pattern is created.

The optional 'timeout' can be used to control the maximum time of waiting.
The timeout is given as a timeout string, e.g. in the format '15 min' or
'1min 10s'. The time string format is described in section Time formt in
Robot Framework User Guide.

If the timeout is negative, the keyword is never timed-out. The keyword
returns immediately, if the file/directory already exist.
Wait Until Removed path, timeout=1 minute Waits until the given file or directory is removed.

The path can be given as an exact path or as a pattern where
'*'        - matches everything
'?'        - matches any single character
'[chars]'  - matches any character inside square brackets (e.g. '[abc]'
matches either 'a', 'b' or 'c')
'[!chars]' - matches any character not inside square brackets

If the path is a pattern, the keyword waits until all matching items are
removed.

The optional 'timeout' can be used to control the maximum time of waiting.
The timeout is given as a timeout string, e.g. in a format '15 min' or
'1min 10s'. The time string format is described in section Time format in
Robot Framework.

If the timeout is negative, the keyword is never timed out. The keyword
returns immediately, if the file/directory does not exist in the first
place.

Altogether 55 keywords. Documentation generated 20080617 18:44:23.