From 144a33531f7b5f209513e0d8e60be7c36e962f9c Mon Sep 17 00:00:00 2001
From: Anders Ingemann <anders@ingemann.de>
Date: Sun, 13 Dec 2015 21:44:05 +0100
Subject: [PATCH] Add documentation for integration test providers

---
 CHANGELOG.rst                          |  1 +
 tests/integration/providers/README.rst | 39 ++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index eaabc2c..42e7c9a 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -11,6 +11,7 @@ Anders Ingemann:
 	  The image name is now specified on the top level of the manifest with "name"
 	* Provider docs have been greatly improved. All now list their special options.
 	* All manifest option documentation is now accompanied by an example.
+	* Added documentation for the integration test providers
 
 2015-11-13
 ----------
diff --git a/tests/integration/providers/README.rst b/tests/integration/providers/README.rst
index e69de29..9a2f3be 100644
--- a/tests/integration/providers/README.rst
+++ b/tests/integration/providers/README.rst
@@ -0,0 +1,39 @@
+Integration testing providers are implemented on top of the abstraction
+that is the testing harness.
+
+Implementation
+--------------
+At their most basic level all they need to implement is
+the ``boot_image()`` function, which, when called, boots the image
+that has been bootstrapped. It should yield something the test can use to
+ascertain whether the image has been successfully bootstrapped
+(i.e. a reference to the bootlog or an object with various functions to
+interact with the booted instance). How this is implemented is up to the
+individual provider.
+
+A ``prepare_bootstrap()`` function may also be implemented, to ensure that the
+bootstrapping process can succeed (i.e. create the AWS S3 into which an image
+should be uploaded).
+
+Both functions are generators that yield, so that they may clean up any created
+resources, once testing is done (or failed, so remember to wrap ``yield`` in a
+``try:.. finally:..``).
+
+Debugging
+---------
+When developing an integration test provider, debugging through multiple
+invocations of ``tox`` can be cumbersome. A short test script, which sets
+up logging and invokes a specific test can be used instead:
+
+
+Example:
+
+.. code:: python
+
+    #!/usr/bin/env python
+
+    from tests.integration.docker_tests import test_stable
+    from bootstrapvz.base.main import setup_loggers
+
+    setup_loggers({'--log': '-', '--color': 'default', '--debug': True})
+    test_stable()