Library version: | 3.1.1 |
---|---|
Library scope: | global |
Named arguments: | supported |
A test library providing keywords for OS related tasks.
OperatingSystem
is Robot Framework's standard library that enables various operating system related tasks to be performed in the system where Robot Framework is running. It can, among other things, execute commands (e.g. Run), create and remove files and directories (e.g. Create File, Remove Directory), check whether files or directories exists or contain something (e.g. File Should Exist, Directory Should Be Empty) and manipulate environment variables (e.g. Set Environment Variable).
Because Robot Framework uses the backslash (\
) as an escape character in the test data, using a literal backslash requires duplicating it like in c:\\path\\file.txt
. That can be inconvenient especially with longer Windows paths, and thus all keywords expecting paths as arguments convert forward slashes to backslashes automatically on Windows. This also means that paths like ${CURDIR}/path/file.txt
are operating system independent.
Notice that the automatic path separator conversion does not work if the path is only a part of an argument like with Run and Start Process keywords. In these cases the built-in variable ${/}
that contains \
or /
, depending on the operating system, can be used instead.
Some keywords allow their arguments to be specified as glob patterns where:
* |
matches any string, even an empty string |
? |
matches any single character |
[chars] |
matches one character in the bracket |
[!chars] |
matches one character not in the bracket |
[a-z] |
matches one character from the range in the bracket |
[!a-z] |
matches one character not from the range in the bracket |
Unless otherwise noted, matching is case-insensitive on case-insensitive operating systems such as Windows.
Starting from Robot Framework 2.9.1, globbing is not done if the given path matches an existing file even if it would contain a glob pattern.
Paths beginning with ~
or ~username
are expanded to the current or specified user's home directory, respectively. The resulting path is operating system dependent, but typically e.g. ~/robot
is expanded to C:\Users\<user>\robot
on Windows and /home/<user>/robot
on Unixes.
The ~username
form does not work on Jython.
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:
Remove Directory | ${path} | recursive=True | # Strings are generally true. |
Remove Directory | ${path} | recursive=yes | # Same as the above. |
Remove Directory | ${path} | recursive=${TRUE} | # Python True is true. |
Remove Directory | ${path} | recursive=${42} | # Numbers other than 0 are true. |
False examples:
Remove Directory | ${path} | recursive=False | # String false is false. |
Remove Directory | ${path} | recursive=no | # Also string no is false. |
Remove Directory | ${path} | recursive=${EMPTY} | # Empty string is false. |
Remove Directory | ${path} | recursive=${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.
Setting | Value |
---|---|
Library | OperatingSystem |
Variable | Value |
---|---|
${PATH} | ${CURDIR}/example.txt |
Test Case | Action | Argument | Argument |
---|---|---|---|
Example | Create File | ${PATH} | Some text |
File Should Exist | ${PATH} | ||
Copy File | ${PATH} | ~/file.txt | |
${output} = | Run | ${TEMPDIR}${/}script.py arg |
Keyword | Arguments | Documentation | ||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Append To Environment Variable | name, *values, **config | Appends given If the environment variable already exists, values are added after it, and otherwise a new environment variable is created. Values are, by default, joined together using the operating system path separator ( Examples (assuming
| ||||||||||||||||||||||||||||||||
Append To File | path, content, encoding=UTF-8 | Appends the given content to the specified file. If the file does not exists, this keyword works exactly the same way as Create File. | ||||||||||||||||||||||||||||||||
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 the destination. Source must be a path to an existing file or a glob pattern (see Pattern matching) that matches exactly one file. How the destination is interpreted is explained below. 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 as the source is overwritten. 3) If the destination does not exist and it ends with a path separator ( 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. The resulting destination path is returned since Robot Framework 2.9.2. See also Copy Files, Move File, and Move Files. | ||||||||||||||||||||||||||||||||
Copy Files | *sources_and_destination | Copies specified files to the target directory. Source files can be given as exact paths and as glob patterns (see Pattern matching). At least one source must be given, but it is not an error if it is a pattern that does not match anything. Last argument must be the destination directory. If the destination does not exist, it will be created. Examples:
See also Copy File, Move File, and Move Files. | ||||||||||||||||||||||||||||||||
Count Directories In Directory | path, pattern=None | Wrapper for Count Items In Directory returning only directory count. | ||||||||||||||||||||||||||||||||
Count Files In Directory | path, pattern=None | Wrapper for Count Items In Directory returning only file count. | ||||||||||||||||||||||||||||||||
Count Items In Directory | path, pattern=None | Returns and logs the number of all items in the given directory. The argument | ||||||||||||||||||||||||||||||||
Create Binary File | path, content | Creates a binary file with the given content. If content is given as a Unicode string, it is first converted to bytes character by character. All characters with ordinal below 256 can be used and are converted to bytes with same values. Using characters with higher ordinal is an error. Byte strings, and possible other types, are written to the file as is. If the directory for the file does not exist, it is created, along with missing intermediate directories. Examples:
Use Create File if you want to create a text file using a certain encoding. File Should Not Exist can be used to avoid overwriting existing files. | ||||||||||||||||||||||||||||||||
Create Directory | path | Creates the specified directory. Also possible intermediate directories are created. Passes if the directory already exists, but fails if the path exists and is not a directory. | ||||||||||||||||||||||||||||||||
Create File | path, content=, encoding=UTF-8 | Creates a file with the given content and encoding. If the directory for the file does not exist, it is created, along with missing intermediate directories. See Get File for more information about possible Examples:
Use Append To File if you want to append to an existing file and Create Binary File if you need to write bytes without encoding. File Should Not Exist can be used to avoid overwriting existing files. The support for | ||||||||||||||||||||||||||||||||
Directory Should Be Empty | path, msg=None | Fails unless the specified directory is empty. The default error message can be overridden with the | ||||||||||||||||||||||||||||||||
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 glob pattern. The pattern matching syntax is explained in introduction. The default error message can be overridden with the | ||||||||||||||||||||||||||||||||
Directory Should Not Be Empty | path, msg=None | Fails if the specified directory is empty. The default error message can be overridden with the | ||||||||||||||||||||||||||||||||
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 glob pattern. The pattern matching syntax is explained in introduction. The default error message can be overridden with the | ||||||||||||||||||||||||||||||||
Empty Directory | path | Deletes all the content from the given directory. Deletes both files and sub-directories, but the specified directory itself if not removed. Use Remove Directory if you want to remove the whole 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 | ||||||||||||||||||||||||||||||||
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 | ||||||||||||||||||||||||||||||||
File Should Be Empty | path, msg=None | Fails unless the specified file is empty. The default error message can be overridden with the | ||||||||||||||||||||||||||||||||
File Should Exist | path, msg=None | Fails unless the given The path can be given as an exact path or as a glob pattern. The pattern matching syntax is explained in introduction. The default error message can be overridden with the | ||||||||||||||||||||||||||||||||
File Should Not Be Empty | path, msg=None | Fails if the specified directory is empty. The default error message can be overridden with the | ||||||||||||||||||||||||||||||||
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 glob pattern. The pattern matching syntax is explained in introduction. The default error message can be overridden with the | ||||||||||||||||||||||||||||||||
Get Binary File | path | Returns the contents of a specified file. This keyword reads the specified file and returns the contents as is. See also Get File. | ||||||||||||||||||||||||||||||||
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. Returned variables are automatically decoded to Unicode using the system encoding. Note that you can also access environment variables directly using the variable syntax | ||||||||||||||||||||||||||||||||
Get Environment Variables | Returns currently available environment variables as a dictionary. Both keys and values are decoded to Unicode using the system encoding. Altering the returned dictionary has no effect on the actual environment variables. | |||||||||||||||||||||||||||||||||
Get File | path, encoding=UTF-8, encoding_errors=strict | Returns the contents of a specified file. This keyword reads the specified file and returns the contents. Line breaks in content are converted to platform independent form. See also Get Binary File.
Support for | ||||||||||||||||||||||||||||||||
Get File Size | path | Returns and logs file size as an integer in bytes. | ||||||||||||||||||||||||||||||||
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 1) If 2) If 3) Otherwise, and by default, the time is returned as a timestamp string in the format Examples (when the modified time of
=>
| ||||||||||||||||||||||||||||||||
Grep File | path, pattern, encoding=UTF-8, encoding_errors=strict | Returns the lines of the specified file that match the This keyword reads a file from the file system using the defined A line matches if it contains the Examples:
If more complex pattern matching is needed, it is possible to use Get File in combination with String library keywords like Get Lines Matching Regexp. | ||||||||||||||||||||||||||||||||
Join Path | base, *parts | Joins the given path part(s) to the given base path. The path separator ( Examples:
=>
| ||||||||||||||||||||||||||||||||
Join Paths | base, *paths | Joins given paths with base and returns resulted paths. See Join Path for more information. Examples:
=>
| ||||||||||||||||||||||||||||||||
List Directories In Directory | path, pattern=None, absolute=False | Wrapper for List Directory that returns only directories. | ||||||||||||||||||||||||||||||||
List Directory | path, pattern=None, absolute=False | Returns and logs items in a directory, optionally filtered with File and directory names are returned in case-sensitive alphabetical order, e.g. File and directory names are returned relative to the given path (e.g. If Examples (using also other List Directory variants):
| ||||||||||||||||||||||||||||||||
List Files In Directory | path, pattern=None, absolute=False | Wrapper for List Directory that returns only files. | ||||||||||||||||||||||||||||||||
Log Environment Variables | level=INFO | Logs all environment variables using the given log level. Environment variables are also returned the same way as with Get Environment Variables keyword. | ||||||||||||||||||||||||||||||||
Log File | path, encoding=UTF-8, encoding_errors=strict | 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. See Get File for more information about | ||||||||||||||||||||||||||||||||
Move Directory | source, destination | Moves the source directory into a destination. Uses Copy Directory keyword internally, and | ||||||||||||||||||||||||||||||||
Move File | source, destination | Moves the source file into the destination. Arguments have exactly same semantics as with Copy File keyword. Destination file path is returned since Robot Framework 2.9.2. If the source and destination are on the same filesystem, rename operation is used. Otherwise file is copied to the destination filesystem and then removed from the original filesystem. See also Move Files, Copy File, and Copy Files. | ||||||||||||||||||||||||||||||||
Move Files | *sources_and_destination | Moves specified files to the target directory. Arguments have exactly same semantics as with Copy Files keyword. See also Move File, Copy File, and Copy Files. | ||||||||||||||||||||||||||||||||
Normalize Path | path, case_normalize=False | Normalizes the given path.
Examples:
=>
On Windows result would use | ||||||||||||||||||||||||||||||||
Remove Directory | path, recursive=False | Removes the directory pointed to by the given If the second argument If the directory pointed to by the | ||||||||||||||||||||||||||||||||
Remove Environment Variable | *names | Deletes the specified environment variable. Does nothing if the environment variable is not set. It is possible to remove multiple variables by passing them to this keyword as separate arguments. | ||||||||||||||||||||||||||||||||
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 glob pattern. The pattern matching syntax is explained in introduction. If the path is a pattern, all files matching it are removed. | ||||||||||||||||||||||||||||||||
Remove Files | *paths | Uses Remove File to remove multiple files one-by-one. Example:
| ||||||||||||||||||||||||||||||||
Run | command | Runs the given command in the system and returns the output. The execution status of the command is not checked by this keyword, and it must be done separately based on the returned output. If the execution return code is needed, either Run And Return RC or Run And Return RC And Output can be used. The standard error stream is automatically redirected to the standard output stream by adding The returned output contains everything written into the standard output or error streams by the command (unless either of them is redirected explicitly). Many commands add an extra newline ( Examples:
TIP: Run Process keyword provided by the Process library supports better process configuration and is generally recommended as a replacement for this keyword. | ||||||||||||||||||||||||||||||||
Run And Return Rc | command | Runs the given command in the system and returns the return code. The return code (RC) is returned as a positive integer in range from 0 to 255 as returned by the executed command. On some operating systems (notable Windows) original return codes can be something else, but this keyword always maps them to the 0-255 range. Since the RC is an integer, it must be checked e.g. with the keyword Should Be Equal As Integers instead of Should Be Equal (both are built-in keywords). Examples:
See Run and Run And Return RC And Output if you need to get the output of the executed command. TIP: Run Process keyword provided by the Process library supports better process configuration and is generally recommended as a replacement for this keyword. | ||||||||||||||||||||||||||||||||
Run And Return Rc And Output | command | Runs the given command in the system and returns the RC and output. The return code (RC) is returned similarly as with Run And Return RC and the output similarly as with Run. Examples:
TIP: Run Process keyword provided by the Process library supports better process configuration and is generally recommended as a replacement for this keyword. | ||||||||||||||||||||||||||||||||
Set Environment Variable | name, value | Sets an environment variable to a specified value. Values are converted to strings automatically. Set variables are automatically encoded using the system encoding. | ||||||||||||||||||||||||||||||||
Set Modified Time | path, mtime | Sets the file modification and access times. Changes the modification and access times of the given file to the value determined by 1) If 2) If 3) If 4) If 5) If Examples:
| ||||||||||||||||||||||||||||||||
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 glob pattern. The pattern matching syntax is explained in introduction. The default error message can be overridden with the | ||||||||||||||||||||||||||||||||
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 glob pattern. The pattern matching syntax is explained in introduction. The default error message can be overridden with the | ||||||||||||||||||||||||||||||||
Split Extension | path | Splits the extension from the given path. The given path is first normalized (e.g. possible trailing path separators removed, special directories Examples:
=>
| ||||||||||||||||||||||||||||||||
Split Path | path | Splits the given path from the last path separator ( The given path is first normalized (e.g. a possible trailing path separator is removed, special directories Examples:
=>
| ||||||||||||||||||||||||||||||||
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 glob pattern. The pattern matching syntax is explained in introduction. If the path is a pattern, the keyword returns when an item matching it is created. The optional If the timeout is negative, the keyword is never timed-out. The keyword returns immediately, if the path already exists. | ||||||||||||||||||||||||||||||||
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 glob pattern. The pattern matching syntax is explained in introduction. If the path is a pattern, the keyword waits until all matching items are removed. The optional If the timeout is negative, the keyword is never timed-out. The keyword returns immediately, if the path does not exist in the first place. |