Testing Guide¶
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.
Mandatory tooling¶
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
Note
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 ~/.bashrc
or ~/.zshrc
.
The examples below will use the runpy
syntax (CLI option -m
) to avoid the
need to put scripts into the search PATH
.
Tip
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 Cython
and using it
requires presense of GCC.
Consult with your OS’s docs to figure out how to get it onto
your machine.
See also
- 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 git@github.com:ansible/pylibssh.git ~/src/github/ansible/pylibssh
$ cd ~/src/github/ansible/pylibssh
[dir:pylibssh] $
Attention
All following commands assume the working dir to be the
Git checkout folder (~/src/github/ansible/pylibssh
in the example)
Running tests¶
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
Continuous integration¶
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
Continuous delivery¶
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.
Commits from devel
get published to
https://test.pypi.org/project/ansible-pylibssh/ and tagged
commits are published to
https://pypi.org/project/ansible-pylibssh/.
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