cleantest

A testing framework for developers who need clean environments in a hurry
Explore cleantest docs »

About

cleantest is a testing framework for quickly bringing up testing environments using the test authors hypervisor of choice. It was created out of NucciTheBoss's desire to efficiently test snap packages, Python code, and Juju charms without needing to make potentially system breaking modifications to the underlying host operating system.

Below is an outline of currently supported operating systems, Python versions, and hypervisors:

Supported operating systems
Supported python versions
Supported hypervisors

Getting started

Installing cleantest

The recommended way to install cleantest is by downloading the published package on PyPI:

pip install cleantest

For those who wish to use the latest, bleeding-edge, and potentially unstable version cleantest of cleantest, the following command can be used to install cleantest from the main branch of this repository:

git clone https://github.com/NucciTheBoss/cleantest.git
cd cleantest
python3 -m pip install .

Configuring a test environment provider

Before you can start using cleantest to run tests, you need to set up a test environment provider. Currently, the only supported environment provider is LXD. You can set LXD up on your system using the following commands:

sudo snap install lxd
lxd init --auto

Run your first test

You can use any testing framework of your choice with cleantest, but this example will use pytest:

pip install pytest

Here is a test written using cleantest that you can download:

📋 test.py

#!/usr/bin/env python3

"""A basic test"""

from cleantest.provider import lxd


@lxd(preserve=False)
def do_something():
    import sys

    try:
        import urllib
        sys.exit(0)
    except ImportError:
        sys.exit(1)


class TestSuite:
    def test_do_something(self) -> None:
        for name, result in do_something():
            assert result.exit_code == 0

With the test file downloaded, run the test using pytest:

pytest test.py

Where to next?

Please the see the documentation for more information on all that you can do with cleantest.

Contributing

Please read through the contributing guidelines if you are interested in contributing to cleantest. Included are guidelines for opening issues, code formatting standards, and how to submit contributions to cleantest.

License

Code and documentation copyright © 2023 Jason C. Nucciarone. Please see the Apache-2.0 license for more details.

Roadmap

Here are my (NucciTheBoss's) goals to get cleantest to release version 1.0.0:

We are sort of the way there on fully support multiple Linux distributions. The big hang-up now is just ensuring that the current macros and utilities are compatible with the new distributions and writing integration tests to ensure that the distributions actually work with cleantest.

Note: cleantest can boot these new distributions but support might be slightly flaky.

• Add support for injecting tests into LXD
• Add support for multiple distros:
  • Ubuntu
  • Debian
  • CentOS
  • Rocky
  • Fedora
  • Arch
• Enable support for running parallel tests with LXD
• Better test logging capabilities
• Support for a select few popular packaging formats:
  • Snap
  • Pip
  • Charm libraries
  • Debs, Rpms, Pacs, etc.
  • Apptainer
• Robust hook mechanism -> i.e. an actual specification for hooks.
• Comprehensive documentation