Welcome to the ansible-pylibssh Testing Guide!
This page contains information on how to test ansible-pylibssh locally as well as some notes of how the automated testing and linting is implemented.
All build and test processes use tox-centric workflow. So first of all, let’s install it:
$ python -m pip install 'tox >= 3.19.0' --user
This will install tox in user-global
site-packages. To make it
discoverable, you may need to add export
PATH="$HOME/.local/bin:$PATH" to your
The examples below will use the
syntax (CLI option
-m) to avoid the
need to put scripts into the search
While the example above uses pip, alternatively you may install tox via your OS package manager (e.g. apt, dnf, emerge, packman, yum, zypper etc.).
It is important to have at least version 3.8.0 because it’ll allow tox to auto-provison a newer version of itself just for ansible-pylibssh.
Tox will take care of the Python dependencies but it’s up to you to make the external ecosystem dependencies available.
ansible-pylibssh’s core dependency is libssh. ansible-pylibssh links against it and so the development headers must be present on your system for build to succeed.
The next external build-time dependency is
using it requires presense of GCC.
Consult with your OS’s docs to figure out how to get it onto
- Installing ansible-pylibssh
Installation from source
Getting the source code¶
Once you sort out the toolchain, get ansible-pylibssh’s source:
$ git clone https://github.com/ansible/pylibssh.git ~/src/github/ansible/pylibssh $ # or, if you use SSH: $ git clone email@example.com:ansible/pylibssh.git ~/src/github/ansible/pylibssh $ cd ~/src/github/ansible/pylibssh [dir:pylibssh] $
All following commands assume the working dir to be the
Git checkout folder (
~/src/github/ansible/pylibssh in the example)
To run tests under your current Python interpreter, run:
[dir:pylibssh] $ python -m tox
If you want to target some other Python version, do:
[dir:pylibssh] $ python -m tox -e py38
In the CI, the testing is done slightly differently. First, the Python package distributions are built with:
[dir:pylibssh] $ python -m tox -e build-dists
Then, they are tested in a matrix of separate jobs across different OS and CPython version combinations:
[dir:pylibssh] $ python -m tox -e test-binary-dists
Quality and sanity¶
Additionally, there’s a separate workflow that runs linting-related checks that can be reproduced locally as follows:
[dir:pylibssh] $ python -m tox -e build-docs # Sphinx docs build [dir:pylibssh] $ python -m tox -e lint # pre-commit.com tool
Besides testing and linting, ansible-pylibssh also has GitHub Actions workflows CI/CD set up to publish those same Python package distributions after they’ve been tested.
devel get published to
https://test.pypi.org/project/ansible-pylibssh/ and tagged
commits are published to
Besides, if you want to test your project against unreleased versions of ansible-pylibssh, you may want to go for nightlies.
We publish nightlies on tags and pushes to devel. They are hosted on a GitHub Pages based index generated by dumb-pypi.
The web view is @ https://ansible.github.io/pylibssh/.
$ pip install \ --extra-index-url=https://ansible.github.io/pylibssh/simple/ \ --pre \ ansible-pylibssh