From ce832d038eeb9a1fe150adacfda8a0a33f73fce9 Mon Sep 17 00:00:00 2001 From: Georg Pfuetzenreuter Date: Wed, 24 May 2023 01:19:16 +0200 Subject: [PATCH] Update README Add sections about installation, usage, testing and licensing. Signed-off-by: Georg Pfuetzenreuter --- README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/README.md b/README.md index 45010a1..70b1be2 100644 --- a/README.md +++ b/README.md @@ -2,4 +2,83 @@ This is intended to be a replacement for [KitchenCI](https://test-kitchen.chef.io/) and [kitchen-salt](https://github.com/saltstack/kitchen-salt), focussing on testing SaltStack states using Vagrant and Pytest/Testinfra. +## Installation +So far, a packaged installation is possible on openSUSE Tumbleweed: + +``` +$ zypper ar -f https://download.opensuse.org/repositories/home:/crameleon:/Scullery/openSUSE_Tumbleweed/home:crameleon:Scullery.repo +$ zypper in scullery +``` + +This will pull in `vagrant`, `vagrant-libvirt`, `python3-vagrant`, `python3-pytest` and `python3-pytest-testinfra` as dependencies. + +Installation on Leap 15.4 is possible, however will currently cause dependency issues with the needed `python-vagrant` library. + +It is possible to run `scullery.py` from a Git checkout of this repository if the dependencies are resolved manually. + +Currently the script behaves purely as a console application and imports as a Python module are not supported. + +## Basic usage + +``` +scullery -h +usage: scullery [-h] [--debug] [--config CONFIG] [--env] --suite SUITE [--stop | --test | --status | --refresh] [--force-stop] + +options: + -h, --help show this help message and exit + --debug Print extremely verbose output + --config CONFIG Specify the configuration file to use + --env Write environment file for direct use of Vagrant + --suite SUITE Specify the suite to run + --stop Stop running machines + --test Start machines and run tests + --status Get Vagrant deployment status + --refresh Re-sync files and re-run bootstrap scripts + --force-stop Invoke Vagrant destruction without having detected any running VM's +``` + +## Command line examples + +* To run a complete test suite: + `$ scullery --suite --test` + +* To create Vagrant VM's without invoking the tests: + `$ scullery --suite ` + +* To refresh the VM's Salt files: + `$ scullery --suite --refresh` + +* To stop the VM's and tidy up: + `$ scullery --suite --stop` + +## Interacting with Vagrant + +It is possible to directly interact with the Vagrant environment templated by Scullery. To do so, generate an environment file by adding `--env` to any command line call - for example: + +`$ scullery --suite --env` + +This will write a `.scullery_env` file to the current working directory. Export the environment variables in the file using your Shell, afterwards use `vagrant` like you normally would. Example for `bash`/`sh`: + +``` +$ set -a; . .scullery_env; set +a +$ vagrant ssh # or any other Vagrant command +``` + +Do not forget to unset the exported variables before you call Scullery with a different `--suite`! + +## Hacking + +To test Scullery itself, call Pytest with your favourite arguments from the repository root: + +``` +$ pytest -v -rx -x tests/*.py +``` + +Make sure to not have _any_ other Scullery based Vagrant VM's running in the same Libvirt session and no `SCULLERY_*` or `VAGRANT_*` variables exported in your shell. + +The complete test suite takes about 30 minutes to execute on an Intel i7-6820HQ CPU with SSHD storage. If you want to test only certain functionality, simply add `-k `. + +## License + +This project is licensed under the European Union Public License found in the file `LICENSE`.