Robot Framework Libraries¶

etr provides the following Robot libraries that provides additional keywords when using the robot plugin:

EtrUtils
EtrJson
EtrProcess

Notational conventions:

Positional and thus mandatory arguments are enclosed with <>, e.g. <timeout>.
Optional and thus keyword arguments are enclosed with [], e.g. [interval]. When used the optional argument is passed as interval=VALUE.

`EtrUtils`¶

Keywords¶

Get Random Port: Returns a random free port.

Example:

*** Settings ***
Library         EtrUtils

*** Test Cases ***

Example Test
    ${port} =  Get Random Port
    Start Process  myServer  --port  ${port}

Wait For Connection <host> <port> <timeout> [reason] [interval]: Wait for TCP connection to be accepted on host on port or give up specified time timeout. timout must be be in Robot Framework’s time format, e.g. 2 s, 1 min, 1 minute 2 seconds.

Example:

*** Settings ***
Library         EtrUtils

*** Test Cases ***

Example
    # In this example we assume the web-server is started in
    # e.g. a suite setup.
    Wait For Connection   localhost   80   6s   reason=Wait for web server

Wait For Path <pathname> <timeout> [reason] [interval]: Wait for path element pathname (e.g. file or directory) to exist or give up specified time timout must be be in Robot Framework’s time format, e.g. 2 s, 1 min, 1 minute 2 seconds.

Example:

*** Settings ***
Library         Process
Library         EtrUtils

*** Test Cases ***

Example
    # Start process that should write pid-file when it is started.
    Start Process  <daemon writing daemon.pid>
    # Now we wait for the PID file to be created
    Wait For Path  daemon.pid  6s   reason=Wait for pidfile

`EtrJson`¶

Robot library that provides JSON-related keywords.

New in version 3.0.

Keywords¶

Decode Json <input str>: Decodes <input str> and returns JSON result. Decoded objects use robot robot.utils.DotDict type which supports dot-access: ${dict.key}.

Example:

*** Settings ***
Library         EtrJson

*** Test Cases ***

Example Test
    # Decode simple string
    ${value} =  Decode Json  "hi"
    Should Be Equal As Strings  "hi"  ${value}

    # Decode JSON object, which is represented as as DotDict
    ${value} =  Decode Json  {"key": "value"}
    # Normal dictionary style
    Should Be Equal As Strings  "value"  ${value["key"]}
    # Dot-access
    Should Be Equal As Strings  "value"  ${value.key}

Encode Json <input> [pretty]: Encodes <input> and returns JSON string. Optionally pretty-printing the result if the optional parameter pretty is True.

Example:

*** Settings ***
Library         EtrJson

*** Test Cases ***

Example Test
    # Encode simple string
    ${r} =  Encode Json  string
    Should Be Equal  "string"  ${r}

    # Create a dictionary to encode
    ${int} =  Convert To Integer  1
    &{dict} =  Create Dictionary  int-key=${int}  string-key=string

    ${r} =  Encode Json  ${dict}
    Should Be Equal As Strings  ${r}  {"int-key": 1, "string-key": "string"}

`EtrProcess`¶

New in version 3.1.

The Robot library EtrProcess is a drop-in replacement of the standard library Process with reasonable default behavior added.

It can automatically kill running processes during end of suite execution.
It can automatically set up file based buffers for stdout and stderr, for safety and convenience.

Note

The file based buffers are important to use to prevent pipe-buffer exhaustion, that may occur if outputs are not continuously read. When pipe buffer is full it may then block the process when attempting to write the full buffer(s).

Behaviour¶

Cleanup

The process cleanup is configured with the library option cleanup and is enabled by default. The behaviour is equivalent to:

*** Settings ***
Library  Process
Suite Teardown  Terminate All Processes  kill=True

*** Test Cases ***
Example

To disable automatic cleanup set cleanup=False:

*** Settings ***
Library  EtrProcess  cleanup=False

Log Files

The library provides default values for the optional arguments stdout and stderr to the standard library Process, all other behaviour remains the same, including doing nothing if user provides values for the arguments. See below for how to disable this.

There are two modes of operation for when a process is created with Run Process or Start Process:

The argument save_outputs=False (default) and no arguments are provided for stdout and/or

stderr:: For the unspecified arguments a temporary file is created and used as a buffer for the output. The temporary files are deleted at suite end.

The argument save_outputs=True:

For the unspecified stdout and/or stderr the outputs are saved persistently to

${OUTPUT_DIR} (see details below).

The names of the output files are logged in the Robot log/report and is also available in the process result structure attributes stdout_path and stderr_path, e.g.:

*** Settings ***
Library  EtrProcess
Library  OperatingSystem

*** Test Cases ***

Example
     ${result} =  Run Process  echo  Hello
     ...   alias=foo
     ...   shell=True
     # Using  Get File  is not necessary as output can be accessed via ${result.stdout}
     ${contents} =  Get File  ${result.stdout_path}
     Should Be Equal  ${result.stdout}  ${contents}

Usage¶

Replace Library Process with Library EtrProcess in the settings section of the robot test.

Warning

Using both Process and EtrProcess in the same file may lead to strange behaviour and is not supported.

If requested to save logs persistently with save_outputs=True the file name patterns use the process alias if provided, otherwise an internal sequence number is used instead:

${OUTPUT_DIR}${/}EtrProcess-<alias or sequence number>.stdout for stdout, e.g. logs/EtrProcess-myproc.stdout or logs/EtrProcess-1.stdout.
${OUTPUT_DIR}${/}EtrProcess-<alias or sequence number>.stderr for stderr, e.g. logs/EtrProcess-myproc.stderr or logs/EtrProcess-1.stderr.

Note

${OUTPUT_DIR} is set to the logs directory in the module test root when executed by etr.

The library is otherwise identical to Process except that if stdout or stderr are not provided, they will be set automatically. The following two examples are functionally equivalent and demonstrates what EtrProcess does.

Using the standard library Process:

*** Settings ***
Library         Process

*** Test Cases ***

Example Test
    # Process with alias and persistent storage:
    ${result} =  Run Process  executable  arg2  arg2
    ...  alias=myproc
    ...  stdout=${OUTPUT_DIR}${/}EtrProcess-myproc.stdout
    ...  stderr=${OUTPUT_DIR}${/}EtrProcess-myproc.stderr

    #  Process without alias and temporary storage:
    ${result} =  Run Process  executable  arg2  arg2
    ...  stdout=${TEMPDIR}${/}EtrProcess-72hafh.stdout
    ...  stderr=${TEMPDIR}${/}EtrProcess-2852ya.stderr

    # Continue test ...

    # Remove temporary files when we are done
    Remove Files
    ...  ${TEMPDIR}${/}EtrProcess-72hafh.stdout
    ...  ${TEMPDIR}${/}EtrProcess-2852ya.stderr

And using the EtrProcess library:

*** Settings ***
Library         EtrProcess

*** Test Cases ***

Example Test
    # Process with alias and persistent storage:
    ${result} =  Run Process  executable  arg2  arg2
    ...  alias=myproc
    ...  save_outputs=True

    #  Process without alias and temporary storage:
    ${result} =  Run Process  executable  arg2  arg2

To disable file buffering, specify ${null} for stdout and stderr:

*** Test Cases ***
Example
     # Run process without any file-backed buffers
     ${result} =  Run Process  executable  arg2  arg2
     ...   stdout=${null}
     ...   stderr=${null}

Keywords¶

For documentation on available keywords for EtrProcess, see the Process library documentation on the Robot Framework home page.

Robot Framework Libraries¶

EtrUtils¶

Keywords¶

EtrJson¶

Keywords¶

EtrProcess¶

Behaviour¶

Usage¶

Keywords¶

`EtrUtils`¶

`EtrJson`¶

`EtrProcess`¶