From cc632d9abcc1f885a047c2bdacb6a6ed55dc81ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Sachse?= <joerg.sachse@slub-dresden.de>
Date: Fri, 9 Sep 2022 08:42:20 +0200
Subject: [PATCH] doc: add molecule Readme file for easy testing

---
 molecule/README.md | 108 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 molecule/README.md

diff --git a/molecule/README.md b/molecule/README.md
new file mode 100644
index 0000000..fdb41fe
--- /dev/null
+++ b/molecule/README.md
@@ -0,0 +1,108 @@
+# Testing with Molecule
+
+## Prerequisites
+
+In order to be able to use the tests, you need to have some software packages installed. You may need sudo privileges for some of these operations.
+
+There are two ways to accomplish this.
+
+### Option 1: use `molecule-skel` (SLUB staff only)
+
+1. Clone the project at [molecule-skel](https://git.slub-dresden.de/slub-referat-2-3/molecule-skel): `git clone https://git.slub-dresden.de/slub-referat-2-3/molecule-skel.git`
+2. Switch to the `molecule-skel` repository directory and run `./install_testenv.sh`.
+3. PROFIT!
+
+ Check the `README.md` over at [molecule-skel](https://git.slub-dresden.de/slub-referat-2-3/molecule-skel) for details on how to use that. It's easy, I promise.
+
+### Option 2: manual installation
+
+Run these steps on your terminal.
+
+```bash
+### install VirtualBox
+# do NOT use distribution packages, as they may be too old!
+# process documented at https://www.virtualbox.org/wiki/Linux_Downloads
+#
+# add GPG key
+wget -q https://www.virtualbox.org/download/oracle_vbox.asc -O- | sudo apt-key add -
+# add repository URL
+sudo echo "deb [arch=amd64] https://download.virtualbox.org/virtualbox/debian stretch contrib" > /etc/apt/sources.d/virtualbox.list
+# update sources and install VirtualBox
+sudo apt update; sudo apt-get install virtualbox-6.1
+
+### install Vagrant
+# do NOT use distribution packages, as they may be too old!
+# 
+# download Debian package from Hashicorp
+wget https://releases.hashicorp.com/vagrant/2.2.9/vagrant_2.2.9_x86_64.deb
+# install package
+sudo dpkg -i vagrant_2.2.9_x86_64.deb
+
+### install Molecule et. al.
+# prepare directories
+mkdir ~/python-envs/ && cd ~/python-env/
+# create Python Virtual Environment with Python3 interpreter (Python2 is deprecated!)
+virtualenv -p python3 molecule-env
+# enter the Virtual Environment in your current shell (other shells will be unaffected)
+source molecule-env/bin/activate
+# install packages
+pip3 install molecule ansible testinfra ansible-lint molecule-vagrant molecule-docker
+
+# leave the Virtual Environment only when you're done
+deactivate
+```
+
+You can find suitable documentation at the respective vendors' websites.
+* [Vagrant Installation Guide](https://www.vagrantup.com/docs/installation/)
+* [VirtualBox Installation Guide](https://www.virtualbox.org/wiki/Downloads)
+* [Molecule Installation Guide](https://molecule.readthedocs.io/en/stable/installation.html)
+
+## Initialising a new Molecule scenario
+
+If you have already created a role without the Molecule test framework or you want to add test scenarios, you can use:
+```bash
+molecule init scenario --scenario-name <my_scenario> --driver [azure|delegated|docker|ec2|gce|linode|lxc|lxd|openstack|vagrant] --verifier-name [ansible|testinfra]
+```
+
+If you need any help with the options, please use:
+```bash
+molecule init role --help
+```
+
+## Running Tests
+
+Molecule helps with creating a test infrastructure, running tests against it and removing the test infrastructure afterwards.
+
+Various test environments are separated into so-called "scenarios" that can be based on different OSses, drivers, verifiers or might just differ in a minor detail. 
+
+In the simplest configuration, the `molecule/` directory only contains one `default/` directory that contains the default scenario. This scenario is run if no other scenario is chosen using the `-s` CLI option.
+
+This is the basic usage of Molecule:
+```bash
+# create test infrastructure
+cd <role_directory>
+molecule create
+# run playbooks against test infrastructure
+molecule converge
+# run idempotence tests
+molecule idempotence
+# run tests, if they exist
+molecule verify
+# remove test infrastructure
+molecule destroy
+
+# run all steps at once:
+molecule test
+```
+
+It has proven helpful to use Vagrant to create a snapshot of the VM after the creation phase has completed. Just like this:
+```bash
+# First, get UUID of the VM
+vagrant global-status
+# Then, create the snapshot
+vagrant snapshot save <uuid> <snapshot_name>
+# To restore the snapshot, use
+vagrant snapshot restore <uuid> <snapshot_name>
+# And to remove the snapshot, use
+vagrant snapshot delete <uuid> <snapshot_name>
+```
-- 
GitLab