updated default and Xenial-specific testinfra docs

docs/development/testing_configuration_tests.rst

@@ -3,7 +3,7 @@
 Testing: Configuration Tests
 ============================
 
-Testinfra_ tests verify the end state of the Vagrant machines. Any
+Testinfra_ tests verify the end state of the staging VMs. Any
 changes to the Ansible configuration should have a corresponding
 spectest.
 
@@ -16,6 +16,7 @@ Installation
 
     pip install -r securedrop/requirements/develop-requirements.txt
 
+
 Running the Config Tests
 ------------------------
 
@@ -27,26 +28,35 @@ For the staging VMs:
 .. code:: sh
 
     make build-debs
-    vagrant up /staging/
+    make staging
+
+The VMs will be set up using either the libvirt or virtualbox Vagrant VM provider,
+depending on your system settings. You'll need to use the appropriate commands below
+based on your choice of provider. 
+
+Then, to run the tests:
 
-Running all VMs concurrently may cause performance
-problems if you have less than 8GB of RAM. You can isolate specific
-machines for faster testing:
+libvirt:
+~~~~~~~~
 
 .. code:: sh
+
+   molecule verify -s libvirt-staging
 
-    ./testinfra/test.py app-staging
-    ./testinfra/test.py mon-staging
+virtualbox:
+~~~~~~~~~~~
 
-.. note:: The config tests for the ``app-prod`` and ``mon-prod`` hosts are
-          incomplete. Further changes are necessary to run the tests via
-          SSH over Authenticated Tor Hidden Service (ATHS), for both local
-          testing via Vagrant and automated testing via CI.
+.. code:: sh
+
+   molecule verify -s virtualbox-staging
 
 Test failure against any host will generate a report with informative output
-about the specific test that triggered the error. The wrapper script
+about the specific test that triggered the error. Molecule
 will also exit with a non-zero status code.
 
+.. note:: To build and test the VMs with one command, use the Molecule ``test``
+  action: ``molecule test -s libvirt-staging --destroy=never``, or ``molecule test -s virtualbox-staging --destroy=never``. 
+
 Updating the Config Tests
 -------------------------
 
@@ -56,19 +66,19 @@ sure to add a corresponding spectest to validate that state after a
 new provisioning run. Tests import variables from separate YAML files
 than the Ansible playbooks: ::
 
-    testinfra/vars/
+    molecule/testinfra/staging/vars/
     ├── app-prod.yml
     ├── app-staging.yml
-    ├── build.yml
     ├── mon-prod.yml
-    └── mon-staging.yml
+    ├── mon-staging.yml
+    └── staging.yml
 
 Any variable changes in the Ansible config should have a corresponding
 entry in these vars files. These vars are dynamically loaded for each
-host via the ``testinfra/conftest.py`` file. Make sure to add your tests to
-relevant location for the host you plan to test: ::
+host via the ``molecule/testinfra/staging/conftest.py`` file. Make sure to add 
+your tests to the relevant location for the host you plan to test: ::
 
-    testinfra/app/
+    molecule/testinfra/staging/app/
     ├── apache
     │   ├── test_apache_journalist_interface.py
     │   ├── test_apache_service.py
@@ -80,23 +90,24 @@ relevant location for the host you plan to test: ::
     └── test_ossec.py
 
 In the example above, to add a new test for the ``app-staging`` host,
-add a new file to the ``testinfra/spec/app-staging`` directory.
+add a new file to the ``testinfra/staging/app`` directory.
 
 .. tip:: Read :ref:`updating_ossec_rules` to learn how to write tests for the
          OSSEC rules.
 
 Config Test Layout
 ------------------
 
-The config tests are mostly broken up according to machines in the
-Vagrantfile: ::
+With some exceptions, the config tests are broken up according to platform definitions in the
+Molecule configuration: ::
 
-    testinfra/
+    molecule/testinfra/staging
     ├── app
     ├── app-code
-    ├── build
     ├── common
-    └── mon
+    ├── mon 
+    ├── ossec
+    └── vars
 
 Ideally the config tests would be broken up according to roles,
 mirroring the Ansible configuration. Prior to the reorganization of

docs/development/xenial_support.rst

@@ -13,22 +13,58 @@ based on Xenial.
 Running the Xenial dev env
 --------------------------
 
+If you're using the libvirt Vagrant provider, you'll need a libvirt-format Xenial
+base image. To set one up, run the following commands:
+
+.. code:: sh
+
+   vagrant box add bento/ubuntu-16.04  # choose the virtualbox option
+   vagrant mutate bento/ubuntu-16.04 mutate libvirt
+
+
 Due to packaging logic changes, you'll need to build the Debian packages
 with overrides enabled for Xenial support. Then run the Xenial scenario.
 
-.. code::
+.. code:: sh
 
    make build-debs-xenial
    make staging-xenial
 
-The VMs will be available. Further debugging likely required; you can
-log into the machines with e.g.:
 
-.. code::
+The VMs will now be available.  Depending your choice of VM provider, you can
+log into the machines with the following commands:
+
+libvirt:
+~~~~~~~~
+
+.. code:: sh
 
    molecule login -s libvirt-staging-xenial -h app-staging
 
-Depending on the error, simply re-running the ``make staging-xenial`` target
+virtualbox:
+~~~~~~~~~~~
+
+.. code:: sh
+
+   molecule login -s virtualbox-staging-xenial -h app-staging
+
+To run the testinfra tests against the Xenial enviroment, you can use the commands:
+
+libvirt:
+~~~~~~~~
+
+.. code:: sh
+
+  molecule verify -s libvirt-staging-xenial
+
+virtualbox:
+~~~~~~~~~~~
+
+.. code:: sh
+
+  molecule verify -s virtualbox-staging-xenial
+
+If you encounter errors, re-running the ``make staging-xenial`` target
 may help. Naturally, we want the process to be error-free reliably.
 
 
@@ -61,9 +97,9 @@ PAM logic
     resolves. More research required.
 
 Config tests
-    The testinfra config test suite expects Trusty throughout. We'll need
-    to update that logic to refer to LSB codename instead, and assert
-    that the target platform is one of either Trusty or Xenial.
+    The testinfra config test suite runs slightly different checks for
+    Trusty and Xenial where appropriate. Care should be taken to preserve
+    functionality of the config tests against both distros.
 
 More detailed research notes on evaluating Xenial support can be found
 in the following GitHub issues: