Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/encukou/pytest-multihost

Utility for writing multi-host tests for pytest
https://github.com/encukou/pytest-multihost

Last synced: 26 days ago
JSON representation

Utility for writing multi-host tests for pytest

Awesome Lists containing this project

README 

        
A pytest plugin for multi-host testing.



Downloading

-----------



Release tarballs will be made available for download from Pagure Releases:

    https://pagure.io/releases/python-pytest-multihost/



The goal is to include this project in Fedora repositories. Until that happens,

you can use testing builds from COPR – see "Developer links" below.



You can also install using pip:

    https://pypi.python.org/pypi/pytest-multihost



Usage

-----



This plugin takes a description of your infrastructure,

and provides, via a fixture, Host objects that commands can be called on.



It is intended as a general base for a framework; any project using it will

need to extend it for its own needs.



The object provided to tests is a Config object, which has (among others)

these attributes::



    test_dir – directory to store test-specific data in,

               defaults to /root/multihost_tests

    ipv6 – true if connecting via IPv6



    domains – the list of domains



Hosts to run on are arranged in domains, which have::



    name – the DNS name of the domain

    type – a string specifying the type of the domain ('default' by default)



    config – the Config this domain is part of

    hosts – list of hosts in this domain



And the hosts have::



    role – type of this host; should encode the OS and installed packages

    hostname – fully qualified hostname, usually reachable from other hosts

    shortname – first component of hostname

    external_hostname – hostname used to connect to this host

    ip – IP address



    domain – the Domain this host is part of



    transport – allows operations like uploading and downloading files

    run_command() – runs the given command on the host



For each object – Config, Domain, Host – one can provide subclasses

to modify the behavior (for example, FreeIPA would add Host methods

to run a LDAP query or to install an IPA server).

Each object has from_dict and to_dict methods, which can add additional

attributes – for example, Config.ntp_server.



To use the multihost plugin in tests, create a fixture listing the domains

and what number of which host role is needed::



    import pytest

    from pytest_multihost import make_multihost_fixture



    @pytest.fixture(scope='class')

    def multihost(request):

        mh = make_multihost_fixture(

            request,

            descriptions=[

                {

                    'type': 'ipa',

                    'hosts': {

                        'master': 1,

                        'replica': 2,

                    },

                },

            ],

        )

        return mh



If not enough hosts are available, all tests that use the fixture are skipped.



The object returned from ``make_multihost_fixture`` only has the "config"

attribute.

Users are expected to add convenience attributes.

For example, FreeIPA, which typically uses a single domain with one master,

several replicas and some clients, would do::



    from pytest_multihost import make_multihost_fixture



    @pytest.fixture(scope='class')

    def multihost(request):

        mh = make_multihost_fixture(request, descriptions=[

                {

                    'type': 'ipa',

                    'hosts': {

                        'master': 1,

                        'replica': 1,

                        'client': 1,

                    },

                },

            ],

        )



        # Set convenience attributes

        mh.domain = mh.config.domains[0]

        [mh.master] = mh.domain.hosts_by_role('master')

        mh.replicas = mh.domain.hosts_by_role('replica')

        mh.clients = mh.domain.hosts_by_role('client')



        # IPA-specific initialization/teardown of the hosts

        request.cls().install(mh)

        request.addfinalizer(lambda: request.cls().uninstall(mh))



        # Return the fixture

        return mh



As with any pytest fixture, this can be used by getting it as

a function argument.

For a simplified example, FreeIPA usage could look something like this::



    class TestMultihost(object):

        def install(self, multihost):

            multihost.master.run_command(['ipa-server-install'])



        def uninstall(self, multihost):

            multihost.master.run_command(['ipa-server-install', '--uninstall'])



        def test_installed(self, multihost):

            multihost.master.run_command(['ipa', 'ping'])



The description of infrastructure is provided in a JSON or YAML file,

which is named on the py.test command line. For example::



    ssh_key_filename: ~/.ssh/id_rsa

    domains:

      - name: adomain.test

        type: test-a

        hosts:

          - name: master

            ip: 192.0.2.1

            role: master

          - name: replica1

            ip: 192.0.2.2

            role: replica

          - name: replica2

            ip: 192.0.2.3

            role: replica

            external_hostname: r2.adomain.test

          - name: client1

            ip: 192.0.2.4

            role: client

          - name: extra

            ip: 192.0.2.6

            role: extrarole

      - name: bdomain.test

        type: test-b

        hosts:

          - name: master.bdomain.test

            ip='192.0.2.65

            role: master



$ py.test --multihost-config=/path/to/configfile.yaml



To use YAML files, the PyYAML package is required. Without it only JSON files

can be used.



Encoding and bytes/text

-----------------------



When writing files or issuing commands, bytestrings are passed through

unchanged, and text strings (``unicode`` in Python 2) are encoded using

a configurable encoding (``utf-8`` by default).



When reading files, bytestrings are returned by default,

but an encoding can be given to get a test string.



For command output, separate ``stdout_bytes`` and ``stdout_text`` attributes

are provided.

The latter uses a configurable encoding (``utf-8` by default).



Contributing

------------



The project is happy to accept patches!

Please file any patches as Pull Requests on the project's `Pagure repo`_.

Any development discussion should be in Pagure Pull Requests and Issues.



Developer links

---------------



  * Bug tracker: https://pagure.io/python-pytest-multihost/issues

  * Code browser: https://pagure.io/python-pytest-multihost/tree/master

  * git clone https://pagure.io/python-pytest-multihost.git

  * Unstable packages for Fedora: https://copr.fedoraproject.org/coprs/pviktori/pytest-plugins/



To release, update version in setup.py, add a Git tag like "v0.3",

and run `make tarball`.

Running `make upload` will put the tarball to Fedora Hosted and PyPI,

and a SRPM on Fedorapeople, if you have the rights.

Running `make release` will upload and fire a COPR build.



.. _Pagure repo: https://pagure.io/python-pytest-multihost