From dc114404c3987054b64814a60f1897df57be5462 Mon Sep 17 00:00:00 2001 From: Seth Grover Date: Mon, 25 Nov 2024 14:55:19 -0700 Subject: [PATCH] major documentation writing --- README.md | 294 +++++++++++++++++++++++++++------- pyproject.toml | 2 +- src/maltest/__init__.py | 11 ++ src/maltest/maltest.py | 34 +++- src/maltest/tests/conftest.py | 37 +++++ src/maltest/utils.py | 10 +- 6 files changed, 323 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 19359fc..1a93302 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,21 @@ -# Malcolm-Test +# malcolm-test -[![Latest Version](https://img.shields.io/pypi/v/malcolm-test)](https://pypi.python.org/pypi/malcolm-test/) - -**Malcolm-Test** serves to run an instance of [Malcolm](https://idaholab.github.io/Malcolm/) and verifying the results of system tests executed against it. It consists mostly of a [control script](#MalcolmVMInitScript), TOML files containing provisioning steps for virtual machine creation, and the test files themselves. See [this issue](https://github.com/idaholab/Malcolm/issues/11) in the Malcolm repository for the discussion leading up to its creation. - -This project makes use of: - -* [Virter](https://github.com/LINBIT/virter) for the creation and execution of libvirt-based virtual machines running Malcolm -* [pytest](https://docs.pytest.org/en/stable/) for the testing framework +`malcolm-test` serves to run an instance of [Malcolm](https://idaholab.github.io/Malcolm/) and verify the results of system tests executed against it. It consists mostly of a [control script](#MalcolmVMInitScript), TOML files containing provisioning steps for virtual machine creation, and the test files themselves. See [this issue](https://github.com/idaholab/Malcolm/issues/11) in the Malcolm repository for the discussion leading up to its creation. -## Package source highlights (under `src/maltest`) - -* 🐍 [`maltest.py`](#MalcolmVMInitScript) - A Python script for running Malcolm in a VM with virter (see below) -* 🗁 `virter/` - A directory structure containing TOML files for [provisioning](https://github.com/LINBIT/virter/blob/master/doc/provisioning.md) the virter VMs in which Malcolm will run. Its subdirectories are arranged thusly: - - 🗁 `debian-12/` - A directory matching the name of the virter image (supplied to [`maltest.py`](#MalcolmVMInitScript) with the `-i`/`--image` argument) - + 🗁 `init/` - TOML files for the initial steps of provisioning the OS (before setting up and starting Malcolm) - + 🗁 `fini/` - TOML files for the final stages of provisioning the OS (after shutting down Malcolm) - - 🗁 `malcolm-init/` - Distribution-agnostic provisioning TOML files for setting up Malcolm prior to starting it - - 🗁 `malcolm-fini/` - Distribution-agnostic provisioning TOML files for tearing down Malcolm after tests are complete -* 🗁 `tests/` - A directory structure containing the test definitions, built using the [pytest](https://docs.pytest.org/en/stable/) framework +* [Installation](#Installation) +* [Usage](#Usage) + - [Examples](#UsageExamples) + + [Provisioning a Malcolm VM and Running the Tests From Scratch](#FromScratch) + + [Provisioning a Malcolm VM For Reuse With Subsequent Test Runs](#BuildAndReuse) + + [Starting a Malcolm VM and Leaving It Running For Subsequent Test Runs](#LongRunning) + - [Cleaning Up](#Cleanup) +* [Source Code](#PackageSource) +* [Creating Tests](#TestCreation) ## Installation +[![Latest Version](https://img.shields.io/pypi/v/malcolm-test)](https://pypi.python.org/pypi/malcolm-test/) + Using `pip`, to install the latest [release from PyPI](https://pypi.org/project/malcolm-test/): ``` @@ -30,57 +24,58 @@ python3 -m pip install -U malcolm-test Or to install directly from GitHub: - ``` python3 -m pip install -U 'git+https://github.com/idaholab/Malcolm-Test' ``` -## The `malcolm-test` script +This project makes use of: + +* [virter](https://github.com/LINBIT/virter) for the creation and execution of libvirt-based virtual machines running Malcolm +* [pytest](https://docs.pytest.org/en/stable/) for the testing framework -`maltest.py` is a Python script for Linux that uses [virter](https://github.com/LINBIT/virter) (a command line tool for simple creation and cloning of virtual machines) to run an instance of [Malcolm](https://idaholab.github.io/Malcolm/) against which automated system tests can be run. +pytest will be installed as a dependency by `pip`, but you will need to install and configure virter prior to running `mmalcolm-test`. See [its GitHub page](https://github.com/LINBIT/virter) for instructions. -When [installed](#Installation) via pip, this script may be executed as `malcolm-test` from the Linux command line. +## Usage + +When [installed](#Installation) via pip, this script may be executed as `malcolm-test` from the Linux command line. ### Usage ``` -usage: maltest.py +usage: malcolm-test See README.md for usage details. options: -h, --help show this help message and exit --verbose, -v Increase verbosity (e.g., -v, -vv, etc.) - -r [true|false], --rm [true|false] - Remove virtual Malcolm instance after execution is complete + --version [true|false] + Show script version and exit Malcolm Git repo: - -g , --github-url + -g, --github-url Malcolm repository url (e.g., https://github.com/idaholab/Malcolm) - -b , --github-branch + -b, --github-branch Malcolm repository branch (e.g., main) Virtual machine specifications: - -c , --cpus - Number of CPUs for virtual Malcolm instance - -m , --memory + -c, --cpus Number of CPUs for virtual Malcolm instance + -m, --memory System memory (GB) for virtual Malcolm instance - -d , --disk - Disk size (GB) for virtual Malcolm instance - -i , --image - Malcolm virtual instance base image name (e.g., debian-12) + -d, --disk Disk size (GB) for virtual Malcolm instance + -i, --image Malcolm virtual instance base image name (e.g., debian-12) --image-user Malcolm virtual instance base image username (e.g., debian) --vm-name-prefix Prefix for Malcolm VM name (e.g., malcolm) --existing-vm Name of an existing virter VM to use rather than starting up a new one - --vm-provision [true|false] - Perform VM provisioning + --vm-provision-os [true|false] + Perform VM provisioning (OS-specific) --vm-provision-malcolm [true|false] Perform VM provisioning (Malcolm-specific) --vm-provision-path - Path containing subdirectories with TOML files for VM provisioning (e.g., /home/tlacuache/.asdf/installs/python/3.12.7/lib/python3.12/site-packages/maltest/virter) + Path containing subdirectories with TOML files for VM provisioning --build-vm The name for a new VM image to build and commit instead of running one --build-vm-keep-layers [true|false] Don't remove intermediate layers when building a new VM image @@ -88,28 +83,217 @@ Virtual machine specifications: Malcolm runtime configuration: --container-image-file Malcolm container images .tar.xz file for installation (instead of "docker pull") - -s [true|false], --start [true|false] + -s, --start [true|false] Start Malcolm once provisioning is complete (default true) + -r, --rm [true|false] + Remove virtual Malcolm instance after execution is complete + --stay-up [true|false] + Stay running until CTRL+C or SIGKILL is received --sleep Seconds to sleep after init before starting Malcolm (default 30) + +Testing configuration: + --test-path Path containing test definitions + -p, --pcap-path + Path containing PCAP files used by tests (UPLOAD_ARTIFACTS in tests should resolve relative to this path) + -t, --run-tests [true|false] + Run test suite once Malcolm is started +``` + +### Examples + +Here are some examples of use cases for `malcolm-test`. The output here is shown without verbose logging enabled; increasing the level of verbosity with `-v`, `-vv`, etc., can provide more information about the operations being performed. + +#### Provisioning a Malcolm VM and Running the Tests From Scratch + +To provision the Malcolm VM from scratch, run the tests, then discard the VM: + +```bash +$ malcolm-test --rm --pcap-path /path/to/Malcolm-Test-PCAP +====================== test session starts ====================== +platform linux -- Python 3.13.0, pytest-8.3.3, pluggy-1.5.0 +rootdir: <...> +collected 4 items + +<...>/site-packages/maltest/tests/test_malcolm_db_health.py . [ 25%] +<...>/site-packages/maltest/tests/test_malcolm_exists.py . [ 50%] +<...>/site-packages/maltest/tests/test_malcolm_pcap.py . [ 75%] +<...>/site-packages/maltest/tests/test_malcolm_response.py . [100%] + +====================== 4 passed in 0.26s ====================== +``` + +Explanation of arguments: + +* `--rm`: discard the VM after running the tests +* `--pcap-path /path/to/Malcolm-Test-PCAP`: specify the path to the upload artifacts used by the tests + +#### Provisioning a Malcolm VM For Reuse With Subsequent Test Runs + +Depending on the use case, because a complete from-scratch provisioning of the Malcolm VM can take a **long time** (due to installing packages, pulling Malcolm container images, waiting for startup, etc.), building a Malcolm image that can then be reused for multiple test runs may be useful. The steps to do this might look like this: + +To build and provision a new Malcolm VM image and tag it as `malcolm-testing`: + +```bash +$ malcolm-test --build-vm malcolm-testing +``` + +To run the tests using this already-provisioned VM image, then shut it down: + +```bash +$ virter image ls +Name Top Layer Created +malcolm-testing sha256:fd2320408c79045dca9aa914f50858f686a740bd053d481c7f33b670d0d3f4c9 3 minutes ago + +$ malcolm-test \ + --rm \ + --image malcolm-testing \ + --vm-provision-os false \ + --vm-provision-malcolm false \ + --pcap-path /path/to/Malcolm-Test-PCAP +====================== test session starts ====================== +platform linux -- Python 3.13.0, pytest-8.3.3, pluggy-1.5.0 +rootdir: <...> +collected 4 items + +<...>/site-packages/maltest/tests/test_malcolm_db_health.py . [ 25%] +<...>/site-packages/maltest/tests/test_malcolm_exists.py . [ 50%] +<...>/site-packages/maltest/tests/test_malcolm_pcap.py . [ 75%] +<...>/site-packages/maltest/tests/test_malcolm_response.py . [100%] + +====================== 4 passed in 0.62s ====================== ``` -### Example +Explanation of arguments: + +* `--rm`: discard the VM after running the tests +* `--image malcolm-testing`: use the `malcolm-testing` image already built instead of building one from scratch +* `--vm-provision-os false`: since the image is already provisioned, skip VM provisioning steps +* `--vm-provision-malcolm false`: since the image already configured Malcolm, skip Malcolm provisioning steps +* `--pcap-path /path/to/Malcolm-Test-PCAP`: specify the path to the upload artifacts used by the tests + +#### Starting a Malcolm VM and Leaving It Running For Subsequent Test Runs + +During test development, or in other instances where you wish to run the tests over and over again without bringing Malcolm up and down, this could be accomplished as described below. + +In one shell session start a Malcolm VM using the already-provisioned image, keeping Malcolm running until interrupted, without running the tests: + +```bash +$ malcolm-test \ + --stay-up \ + --rm \ + --image malcolm-testing \ + --vm-provision-os false \ + --vm-provision-malcolm false \ + --run-tests false +``` + +Explanation of arguments: + +* `--stay-up`: keep Malcolm up until interrupted (with CTRL+C or SIGKILL) +* `--rm`: discard the VM after shutting down +* `--image malcolm-testing`: use the `malcolm-testing` image already built instead of building one from scratch +* `--vm-provision-os false`: since the image is already provisioned, skip VM provisioning steps +* `--vm-provision-malcolm false`: since the image already configured Malcolm, skip Malcolm provisioning steps +* `--run-tests false`: don't run the tests with this instance of `malcolm-test`, just start Malcolm and wait + +In another shell session, connecting to the existing running Malcolm instance for a test run: -*with INFO-level `-vv` verbosity, output reduced for length* +```bash +$ virter vm ls +Name ID Access Network +malcolm-nearby-satyr 254 default +$ malcolm-test \ + --rm false \ + --start false \ + --sleep 0 \ + --existing-vm malcolm-nearby-satyr \ + --vm-provision-os false \ + --vm-provision-malcolm false \ + --run-tests \ + --pcap-path /path/to/Malcolm-Test-PCAP +====================== test session starts ====================== +platform linux -- Python 3.13.0, pytest-8.3.3, pluggy-1.5.0 +rootdir: <...> +collected 4 items + +<...>/site-packages/maltest/tests/test_malcolm_db_health.py . [ 25%] +<...>/site-packages/maltest/tests/test_malcolm_exists.py . [ 50%] +<...>/site-packages/maltest/tests/test_malcolm_pcap.py . [ 75%] +<...>/site-packages/maltest/tests/test_malcolm_response.py . [100%] + +====================== 4 passed in 0.25s ====================== ``` -2024-10-25 12:42:51 INFO: /home/user/Malcolm-Test/maltest.py -2024-10-25 12:42:51 INFO: Arguments: ['-vv', '--rm', '--github-url', 'https://github.com/idaholab/Malcolm', '--github-branch', 'main'] -2024-10-25 12:42:51 INFO: Arguments: Namespace(verbose=20, removeAfterExec=True, repoUrl='https://github.com/idaholab/Malcolm', repoBranch='main', vmCpuCount=8, vmMemoryGigabytes=31, vmDiskGigabytes=64, vmImage='debian-12', vmImageUsername='debian', vmNamePrefix='malcolm', vmExistingName='', vmProvision=True, vmProvisionPath='/home/user/Malcolm-Test/virter', containerImageFile='', startMalcolm=True, postInitSleep=30) -2024-10-25 12:42:51 INFO: ['virter', 'vm', 'run', 'debian-12', '--id', '0', '--name', 'malcolm-126', '--vcpus', '8', '--memory', '31GB', '--bootcapacity', '64GB', '--user', 'debian', '--wait-ssh'] -2024-10-25 12:43:04 INFO: malcolm-126 -2024-10-25 12:43:04 INFO: ['virter', 'vm', 'exec', 'malcolm-126', '--provision', '/home/user/Malcolm-Test/virter/debian-12/init/00-apt-init.toml', '--set', 'env.VERBOSE=false', '--set', 'env.REPO_URL=https://github.com/idaholab/Malcolm', '--set', 'env.REPO_BRANCH=main'] -2024-10-25 12:44:27 INFO: malcolm-126 out: Linux malcolm-126 6.1.0-26-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.112-1 (2024-09-30) x86_64 -… -2024-10-25 12:44:27 INFO: malcolm-126 out: Installing system packages... -… -2024-10-25 13:03:37 INFO: malcolm-126 out: Pulling Malcolm container images... -… -2024-10-25 13:05:11 INFO: malcolm-126 out: Waiting for Malcolm to become ready... -2024-10-25 13:06:34 INFO: Malcolm is started and ready to process data + +* `--rm false`: don't destroy the VM after running the tests (the other instance of `malcolm-test` will handle that) +* `--start false`: since Malcolm was already started by the other instance of `malcolm-test`, don't attempt to start it +* `--sleep 0`: since Malcolm was already started, there is no need to sleep before beginning test execution +* `--existing-vm malcolm-nearby-satyr`: specify the name of the existing running VM obtained by `virter vm ls` +* `--vm-provision-os false`: since the image is already provisioned, skip VM provisioning steps +* `--vm-provision-malcolm false`: since the image already configured Malcolm, skip Malcolm provisioning steps +* `--run-tests`: run the test suite +* `--pcap-path /path/to/Malcolm-Test-PCAP`: specify the path to the upload artifacts used by the tests + +Repeat the previous command as many times as needed as you adjust your tests. When finished, return to the first shell session and press CTRL+C to terminate and discard the Malcolm VM. + +### Cleaning Up + +If the `malcolm-test` script exits uncleanly for some reason and leaves orphaned running VMs, they can be cleaned up like this: + +```bash +$ virter vm ls +Name ID Access Network +malcolm-nearby-satyr 254 default + +$ virter vm rm malcolm-nearby-satyr ``` + +To list and clean up any leftover Malcolm image tags: + +```bash +$ virter image ls +Name Top Layer Created +rested-krill sha256:cd98ad4f552ce98f2a9ab0429b5fbb701483bc2980b590c5c91ebca2a8935f99 27 minutes ago +robust-condor sha256:e5306d90f825787b8142dcc94816902dfee4698fe9c00bc55aa4406eb5d830f5 26 minutes ago +up-quagga sha256:3889161a396f8f6ef41c0605323af07e2a9820cc980660563551a4488f0a7a3c 23 minutes ago +malcolm-testing sha256:fd2320408c79045dca9aa914f50858f686a740bd053d481c7f33b670d0d3f4c9 3 minutes ago + +$ virter image rm rested-krill robust-condor up-quagga +``` + +## Source Code + +Package source highlights (under [`./src/maltest`](src/maltest)): + +* 🐍 [`maltest.py`](#Usage) - A Python script for running Malcolm in a VM with virter +* 🗁 `virter/` - A directory structure containing TOML files for [provisioning](https://github.com/LINBIT/virter/blob/master/doc/provisioning.md) the virter VMs in which Malcolm will run. Its subdirectories are arranged thusly: + - 🗁 `debian-12/` - A directory matching the name of the virter image (supplied to [`maltest.py`](#MalcolmVMInitScript) with the `-i`/`--image` argument) + + 🗁 `init/` - TOML files for the initial steps of provisioning the OS (before setting up and starting Malcolm) + + 🗁 `fini/` - TOML files for the final stages of provisioning the OS (after shutting down Malcolm) + - 🗁 `malcolm-init/` - Distribution-agnostic provisioning TOML files for setting up Malcolm prior to starting it + - 🗁 `malcolm-fini/` - Distribution-agnostic provisioning TOML files for tearing down Malcolm after tests are complete +* 🗁 `tests/` - A directory structure containing the test definitions, built using the [pytest](https://docs.pytest.org/en/stable/) framework + +## Creating Tests + +`malcolm-test` uses the [`pytest` framework](https://docs.pytest.org/en/stable/index.html). Please familiarize yourself with `pytest` as you begin developing new tests for the project. + +New tests should be placed in the [`./src/maltest/tests/`](src/maltest/tests/) directory. Tests have access to the connection information for the running Malcolm instance through [fixtures](https://docs.pytest.org/en/stable/reference/fixtures.html#conftest-py-sharing-fixtures-across-multiple-files) provided by [`./src/maltest/tests/conftest.py`](src/maltest/tests/conftest.py). + +See the following tests for examples of how to access and use these fixtures: + +* [test_malcolm_response.py](src/maltest/tests/test_malcolm_response.py) - querying the [Malcolm API](https://idaholab.github.io/Malcolm/docs/api.html#API) using the [Requests](https://requests.readthedocs.io/en/latest/) library +* [test_malcolm_db_health.py](src/maltest/tests/test_malcolm_db_health.py) - querying the [data store](https://idaholab.github.io/Malcolm/docs/opensearch-instances.html#OpenSearchInstance) directly using the [OpenSearch](https://opensearch.org/docs/latest/clients/python-low-level/) or [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html) client + +Use `UPLOAD_ARTIFACTS` to specify a PCAP file required by your test. This example test would succeed if both `foobar.pcap` and `barbaz.pcap` were uploaded to Malcolm and their hashes stored in the global `pcap_hash_map`: + +```python +UPLOAD_ARTIFACTS = ['foobar.pcap', 'barbaz.pcap'] + +def test_malcolm_pcap_hash( + pcap_hash_map, +): + assert all([pcap_hash_map.get(x, None) for x in UPLOAD_ARTIFACTS]) +``` + +As PCAP files are uploaded to Malcolm by `malcolm-test`, they are [hashed](https://docs.python.org/3/library/hashlib.html#hashlib.shake_256) and stored in `pcap_hash_map` which maps the PCAP filename to its hash. The PCAP file is renamed to the hex-representation of the hash digest and the file extension (e.g., if the contents of `foobar.pcap` hashed to `52b92cdcec4af0e1`, the file would be uploaded as `52b92cdcec4af0e1.pcap`). This is done to ensure that conflicting PCAP filenames among different tests are resolved prior to processing. Since Malcolm automatically [assigns tags](https://idaholab.github.io/Malcolm/docs/upload.html#Tagging) to uploaded PCAP files, this hash should be used as a filter for the `tags` field for any network log-based queries for data related to that PCAP file. This way your tests can have reproducible outputs without being affected by PCAPs for other tests. diff --git a/pyproject.toml b/pyproject.toml index 0583d5e..e5c7d09 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "malcolm-test" -version = "0.5.1" +version = "0.6.0" authors = [ { name="Seth Grover", email="mero.mero.guero@gmail.com" }, ] diff --git a/src/maltest/__init__.py b/src/maltest/__init__.py index e4309d4..332b749 100644 --- a/src/maltest/__init__.py +++ b/src/maltest/__init__.py @@ -1,3 +1,14 @@ +""" +malcolm-test serves to run an instance of Malcolm (https://idaholab.github.io/Malcolm/) +and verify the results of system tests executed against it. + +This package contains the following modules: +- maltest: contains the CLI interface and high-level execution logic +- utils: contains classes used for managing and interfacing with Malcolm VM +""" + +# -*- coding: utf-8 -*- + from importlib.metadata import version, PackageNotFoundError from maltest.utils import MALTEST_PROJECT_NAME diff --git a/src/maltest/maltest.py b/src/maltest/maltest.py index e0efd57..b3abb40 100755 --- a/src/maltest/maltest.py +++ b/src/maltest/maltest.py @@ -1,3 +1,7 @@ +""" +malcolm-test module containing the CLI interface and high-level execution logic +""" + #!/usr/bin/env python3 # -*- coding: utf-8 -*- @@ -24,20 +28,35 @@ ShuttingDown, ) -################################################################################################### script_name = os.path.basename(__file__) script_path = os.path.dirname(os.path.realpath(__file__)) -################################################################################################### -# handle sigint/sigterm and set a global shutdown variable def shutdown_handler(signum, frame): + """ + shutdown_handler: Signal handler for interrupting program execution with SIGKILL or SIGINT, + setting ShuttingDown to True + + Args: + signum - The signal number (e.g., signal.SIGINT for Ctrl-C) + frame - The current stack frame + + Returns: + None + """ ShuttingDown[0] = True -################################################################################################### -# main def main(): + """ + main: Main program execution + + Args: + None (see --help for command-line arguments) + + Returns: + 0 for success, non-0 for error + """ global ShuttingDown parser = argparse.ArgumentParser( @@ -76,7 +95,7 @@ def main(): dest='repoUrl', metavar='', type=str, - default=os.getenv('MALCOLM_REPO_URL', 'idaholab'), + default=os.getenv('MALCOLM_REPO_URL', 'https://github.com/idaholab/Malcolm'), help='Malcolm repository url (e.g., https://github.com/idaholab/Malcolm)', ) repoArgGroup.add_argument( @@ -228,7 +247,7 @@ def main(): default=True, help=f'Start Malcolm once provisioning is complete (default true)', ) - parser.add_argument( + configArgGroup.add_argument( '-r', '--rm', dest='removeAfterExec', @@ -409,7 +428,6 @@ def main(): return exitCode -################################################################################################### if __name__ == '__main__': if main() > 0: sys.exit(0) diff --git a/src/maltest/tests/conftest.py b/src/maltest/tests/conftest.py index 7cb529a..644cb1b 100644 --- a/src/maltest/tests/conftest.py +++ b/src/maltest/tests/conftest.py @@ -1,6 +1,13 @@ +""" +provides fixtures usable by all pytests in the system + +See https://docs.pytest.org/en/stable/reference/fixtures.html#conftest-py-sharing-fixtures-across-multiple-files +""" + # -*- coding: utf-8 -*- import pytest + from maltest.utils import ( get_malcolm_vm_info, get_pcap_hash_map, @@ -12,24 +19,54 @@ @pytest.fixture def malcolm_vm_info(): + """ + malcolm_vm_info: fixture wrapping .utils.get_malcolm_vm_info + + Returns: + see .utils.get_malcolm_vm_info + """ yield get_malcolm_vm_info() @pytest.fixture def pcap_hash_map(): + """ + pcap_hash_map: fixture wrapping .utils.get_pcap_hash_map + + Returns: + see .utils.get_pcap_hash_map + """ yield get_pcap_hash_map() @pytest.fixture def malcolm_http_auth(): + """ + malcolm_http_auth: fixture wrapping .utils.get_malcolm_http_auth + + Returns: + see .utils.get_malcolm_http_auth + """ yield get_malcolm_http_auth() @pytest.fixture def database_objs(): + """ + database_objs: fixture wrapping .utils.get_database_objs + + Returns: + see .utils.get_database_objs + """ yield get_database_objs() @pytest.fixture def malcolm_url(): + """ + malcolm_url: fixture wrapping .utils.get_malcolm_url + + Returns: + see .utils.get_malcolm_url + """ yield get_malcolm_url() diff --git a/src/maltest/utils.py b/src/maltest/utils.py index a9ba371..5df043f 100644 --- a/src/maltest/utils.py +++ b/src/maltest/utils.py @@ -1,3 +1,12 @@ +""" +malcolm-test module containing classes used for managing and interfacing with a Malcolm VM + +The classes of interest in this module include: + +- MalcolmTestCollection - A pytest plugin used to gather the list of tests to be run +- MalcolmVM - Represents a Malcolm instance running inside a virter-managed libvirt virtual machine +""" + # -*- coding: utf-8 -*- import ast @@ -325,7 +334,6 @@ def __init__(self, username=None, password=None): self.DatabaseInitArgs['basic_auth'] = (username, password) -################################################################################################### class MalcolmTestCollection(object): """ MalcolmTestCollection: A pytest plugin (https://docs.pytest.org/en/stable/how-to/writing_plugins.html)