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