Robot Framework SSHLibrary

3.8.0 · active · verified Thu Apr 16

Robot Framework SSHLibrary is a test library for SSH and SFTP operations. It provides keywords for executing commands, interacting with interactive shells, transferring files and directories via SFTP, and asserting the existence of files and directories on remote machines. The library is operating system independent and currently supports Python 3.6 or newer (older versions like 3.8.0 also supported Python 2.7 and 3.4+). It maintains an active release cadence with regular updates and enhancements.

Common errors

```
SSHLibrary Exception: Timeout opening tunnel
```
cause The SSH connection could not be established or the tunnel creation timed out within the default or specified timeout period, often due to network issues or slow server response.

fix Increase the timeout values for both library import and the `Open Connection` keyword. Example: `Library SSHLibrary 30s` and `Open Connection ${HOST} port=${PORT} timeout=60s`.
```
Authentication failed for user 'username'
```
cause Incorrect username/password, invalid public key, server configuration issues (e.g., password-less login not working as expected), or incompatible Paramiko version.

fix Double-check credentials. If using public key, verify key path and permissions. For password-less root logins, consider trying `pip uninstall paramiko` then `pip install paramiko-ng` as a workaround (as `paramiko` sometimes has issues with this specific scenario). Ensure the correct login keyword (`Login` vs. `Login With Public Key`) is used.
```
Connection not open.
```
cause Attempting to use SSHLibrary keywords that require an active connection (e.g., `Execute Command`, `Put File`) before a successful `Login` has occurred, or after a connection has been explicitly closed.

fix Ensure `Open Connection` and `Login` keywords are called successfully before any connection-dependent keywords. For example, `Open Connection ${HOST}` followed by `Login ${USERNAME} ${PASSWORD}`.
```
gaierror: [Errno -2] Name or service not known
```
cause The hostname provided to `Open Connection` cannot be resolved to an IP address by the system's DNS resolver.

fix Verify the hostname is correct and reachable from the test runner machine. Use an IP address instead of a hostname if DNS resolution is problematic. Check network configuration and DNS settings.
```
Logging into 'host,port=XXXX:22' as 'user'
```
cause Incorrect syntax when specifying the port argument in `Open Connection`. Using a comma instead of spaces between arguments.

fix Robot Framework uses multiple spaces as a separator for arguments. Change `Open Connection ${HOST},port=${PORT}` to `Open Connection ${HOST} port=${PORT}`.

Warnings

breaking SSHLibrary 3.0.0 introduced Python 3 support (Python 2.7, 3.4+). Older versions of SSHLibrary may not be compatible with newer Python 3 versions, and newer SSHLibrary versions (e.g., 3.8.0 onwards) officially support Python 3.6+.
Fix: Ensure your Python environment matches the SSHLibrary version's requirements. Upgrade SSHLibrary and Python if necessary.
breaking In SSHLibrary 3.0.0, the `Login with Public Key` keyword arguments changed. Specifically, the `delay` argument must now be provided as a named argument (e.g., `delay=1s`).
Fix: Update calls to `Login with Public Key` to use named arguments for `delay`.
breaking Prior to SSHLibrary 3.1.0, all non-empty strings, including 'no' and 'none', were considered `True` for boolean arguments. This behavior was aligned with Robot Framework 3.0.3, where 'none' is considered `False`.
Fix: If using string boolean arguments (e.g., 'True', 'False', 'yes', 'no'), ensure to upgrade to SSHLibrary 3.1.0 or newer for correct boolean evaluation, especially for 'no'/'none' values.
gotcha Connections or command executions can hang or time out (e.g., 'SSHLibrary Exception: Timeout opening tunnel') due to insufficient default timeouts or network latency.
Fix: Explicitly set timeouts. Use `Library SSHLibrary timeout=30s` during import, `Open Connection host=${HOST} timeout=1min`, `Login username=${USER} password=${PASS} delay=1s`, and `Execute Command command timeout=30s`.
gotcha The `path_separator` argument (used by keywords like `Get File`, `Put Directory`) defaults to '/' (Unix-like). On Windows SSH servers, this may need to be explicitly set to '\\' (doubled backslash in Robot Framework data) if the server uses backslashes.
Fix: Configure the `path_separator` during library import or using `Set Default Configuration` or `Open Connection`: `Library SSHLibrary path_separator=\\\` or `Open Connection ${HOST} path_separator=\\\`.

Install

pip install robotframework-sshlibrary Install for Python
apk add gcc make openssl-dev musl-dev libffi-dev && pip install robotframework-sshlibrary Install for Alpine Linux (Docker)

Imports

SSHLibrary
wrong:
```
from SSHLibrary import SSHLibrary
```
correct:
```
*** Settings ***
Library    SSHLibrary
```
Robot Framework libraries are imported using the 'Library' setting in the Settings section of a .robot file, not with Python-style 'from import'.

Quickstart

This example connects to a remote SSH server using environment variables for credentials, executes a simple `ls -l /tmp` command, logs the output, asserts a part of the output, and then closes the connection. Set `SSH_HOST`, `SSH_PORT`, `SSH_USERNAME`, and `SSH_PASSWORD` environment variables before running.

*** Settings ***
Documentation    Demonstrates SSHLibrary connection and command execution.
Library          SSHLibrary

*** Variables ***
${SSH_HOST}      ${OS_ENVIRONMENT_SSH_HOST}
${SSH_PORT}      ${OS_ENVIRONMENT_SSH_PORT}
${SSH_USERNAME}  ${OS_ENVIRONMENT_SSH_USERNAME}
${SSH_PASSWORD}  ${OS_ENVIRONMENT_SSH_PASSWORD}

*** Test Cases ***
Execute Remote Command
    [Tags]    SSH
    Open Connection    ${SSH_HOST}    port=${SSH_PORT}
    Login              ${SSH_USERNAME}    ${SSH_PASSWORD}
    ${output}=         Execute Command    ls -l /tmp
    Log To Console     Command Output: ${output}
    Should Contain     ${output}          total
    Close Connection

view raw JSON →