Add local testing aids and documentation

This change adds contributing documentation to illustrate how
developers can test roles using molecule on local machines.
To assist in local testing an rc environment file has been
added to the project root which will ensure ansible is
configured to use resources out of this project.

Change-Id: I237f743aa85fac9eb56a4c7aac54a7545cc125db
Signed-off-by: Kevin Carter <kevin@cloudnull.com>

ansible-test-env.rc

@@ -0,0 +1,23 @@
+export TRIPLEO_ANSIBLE_WORKPATH="$(dirname $(readlink -f ${BASH_SOURCE[0]}))"
+export ANSIBLE_STDOUT_CALLBACK=debug
+export ANSIBLE_ACTION_PLUGINS="${TRIPLEO_ANSIBLE_WORKPATH}/tripleo_ansible/ansible_plugins/action"
+export ANSIBLE_CALLBACK_PLUGINS="${TRIPLEO_ANSIBLE_WORKPATH}/tripleo_ansible/ansible_plugins/callback"
+export ANSIBLE_FILTER_PLUGINS="${TRIPLEO_ANSIBLE_WORKPATH}/tripleo_ansible/ansible_plugins/filter"
+export ANSIBLE_LIBRARY="${TRIPLEO_ANSIBLE_WORKPATH}/tripleo_ansible/ansible_plugins/modules"
+export ANSIBLE_MODULE_UTILS="${TRIPLEO_ANSIBLE_WORKPATH}/tripleo_ansible/ansible_plugins/module_utils"
+export ANSIBLE_ROLES_PATH="${TRIPLEO_ANSIBLE_WORKPATH}/tripleo_ansible/roles"
+export ANSIBLE_INVENTORY="${TRIPLEO_ANSIBLE_WORKPATH}/tests/hosts.ini"
+export ANSIBLE_RETRY_FILES_ENABLED="0"
+export ANSIBLE_LOAD_CALLBACK_PLUGINS="1"
+
+function unset-ansible-test-env {
+  for i in $(env | grep ANSIBLE_ | awk -F'=' '{print $1}'); do
+    unset ${i}
+  done
+  unset TRIPLEO_ANSIBLE_WORKPATH
+  echo -e "Ansible test environment deactivated.\n"
+  unset -f unset-ansible-test-env
+}
+
+echo -e "Ansible test environment is now active"
+echo -e "Run 'unset-ansible-test-env' to deactivate.\n"

doc/source/contributing.rst

@@ -95,3 +95,62 @@ the virtual environment before running the playbook.
 
     $ . ~/bin/venvs/ansible/bin/activate
     (ansible)$ ansible-playbook -i localhost, role-addition.yml -e role_name=${NEWROLENAME}
+
+
+Local testing of new roles
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Role based testing with molecule can be executed from within the
+role directory.
+
+.. note::
+
+    Most tests require docker for container based testing. If Docker
+    is not available on the local workstation it will need to be
+    installed prior to executing most molecule based tests.
+
+
+.. note::
+
+    The script `bindep-install`, in the **scripts** path, is
+    available and will install all system dependencies.
+
+
+Before running basic molecule tests, it is recommended to install all
+of the python dependencies in a virtual environment.
+
+.. code-block:: console
+
+    $ python -m virtualenv --system-site-packages "${HOME}/test-python"
+    $ ${HOME}/test-python/bin/pip install -r requirements.txt \
+                                          -r test-requirements.txt
+    $ source ${HOME}/test-python/bin/activate
+
+
+To run a basic molecule test, simply source the `ansibe-test-env.rc`
+file from the project root, and then execute the following commands.
+
+.. code-block:: console
+
+    (test-python) $ cd tripleo_ansible/roles/${NEWROLENAME}/
+    (test-python) $ molecule test --all
+
+
+If a role has more than one scenario, a specific scenario can be
+specified on the command line. Running specific scenarios will
+help provide developer feedback faster. To pass-in a scenario use
+the `--scenario-name` flag with the name of the desired scenario.
+
+.. code-block:: console
+
+    (test-python) $ cd tripleo_ansible/roles/${NEWROLENAME}/
+    (test-python) $ molecule test --scenario-name ${EXTRA_SCENARIO_NAME}
+
+
+When debugging molecule tests its sometimes useful to use the
+`--debug` flag. This flag will provide extra verbose output about
+test being executed and running the environment.
+
+.. code-block:: console
+
+    (test-python) $ molecule --debug test