Move Testing from main README into the docs

README.rst

@@ -3,8 +3,8 @@ cloudbridge
 
 cloudbridge aims to provide a simple layer of abstraction over
 different cloud providers, reducing or eliminating the need to write
-conditional code for each cloud. It is currently
-under development and is in a Pre-Alpha state.
+conditional code for each cloud. It is currently under development and is in
+the Alpha state.
 
 .. image:: https://landscape.io/github/gvlproject/cloudbridge/master/landscape.svg?style=flat
    :target: https://landscape.io/github/gvlproject/cloudbridge/master
@@ -34,8 +34,9 @@ under development and is in a Pre-Alpha state.
 Usage example
 ~~~~~~~~~~~~~
 
-The simplest possible example for doing something useful with cloudbridge would
-look like the following.
+To `get started`_ with cloudbridge, export your cloud access credentials
+(e.g., AWS_ACCESS_KEY and AWS_SECRET_KEY for your AWS credentials) and start
+exploring the API:
 
 .. code-block:: python
 
@@ -44,9 +45,6 @@ look like the following.
   provider = CloudProviderFactory().create_provider(ProviderList.AWS, {})
   print(provider.security.key_pairs.list())
 
-In the example above, the AWS_ACCESS_KEY and AWS_SECRET_KEY environment
-variables must be set to your AWS credentials.
-
 
 Documentation
 ~~~~~~~~~~~~~
@@ -56,27 +54,28 @@ Documentation can be found at https://cloudbridge.readthedocs.org.
 Design Goals
 ~~~~~~~~~~~~
 
-1. Create a cloud abstraction layer which minimises or eliminates the need for
-cloud specific special casing (i.e., Not require clients to write ``if EC2 do x
-else if OPENSTACK do y``.)
+ 1. Create a cloud abstraction layer which minimises or eliminates the need for
+    cloud specific special casing (i.e., Not require clients to write
+    ``if EC2 do x else if OPENSTACK do y``.)
 
-2. Have a suite of conformance tests which are comprehensive enough that goal 1
-can be achieved. This would also mean that clients need not manually test
-against each provider to make sure their application is compatible.
+ 2. Have a suite of conformance tests which are comprehensive enough that goal
+    1 can be achieved. This would also mean that clients need not manually test
+    against each provider to make sure their application is compatible.
 
-3. Opt for a minimum set of features that a cloud provider will support, instead
-of  a lowest common denominator approach. This means that reasonably mature
-clouds like Amazon and OpenStack are used as the benchmark against which
-functionality & features are determined. Therefore, there is a definite
-expectation that the cloud infrastructure will support a compute service with
-support for images and snapshots and various machine sizes. The cloud
-infrastructure will very likely support block storage, although this is
-currently optional. It may optionally support object storage.
+ 3. Opt for a minimum set of features that a cloud provider will support,
+    instead of  a lowest common denominator approach. This means that reasonably
+    mature clouds like Amazon and OpenStack are used as the benchmark against
+    which functionality & features are determined. Therefore, there is a
+    definite expectation that the cloud infrastructure will support a compute
+    service with support for images and snapshots and various machine sizes.
+    The cloud infrastructure will very likely support block storage, although
+    this is currently optional. It may optionally support object storage.
 
-4. Make the cloudbridge layer as thin as possible without compromising goal 1.
-By wrapping the cloud provider's native SDK and doing the minimal work necessary
-to adapt the interface, we can achieve greater development speed and reliability
-since the native provider SDK is most likely to have both properties.
+ 4. Make the cloudbridge layer as thin as possible without compromising goal 1.
+    By wrapping the cloud provider's native SDK and doing the minimal work
+    necessary to adapt the interface, we can achieve greater development speed
+    and reliability since the native provider SDK is most likely to have both
+    properties.
 
 
 Contributing
@@ -102,49 +101,9 @@ object is defined via an abstract interface (see
 defined interface. If adding a completely new provider, take a look at the
 `provider development page`_ in the documentation.
 
-Running tests
-~~~~~~~~~~~~~
-To run the test suite locally, install `tox`_ with :code:`pip install tox`
-and run ``tox`` command. This will run all the tests for
-all the environments defined in file ``tox.ini``. In order to properly run the
-tests, you should have all the environment variables listed in
-``tox.ini`` file (under ``passenv``) exported.
-
-If you’d like to run the tests on a specific environment only, use a command
-like such: ``tox -e py27`` (or ``python setup.py test`` directly). If you'd
-like to run the tests for a specific cloud only, you should export env var
-``CB_TEST_PROVIDER`` and specify the desired provider name (e.g., ``aws`` or
-``openstack``) and then run the ``tox`` command.
-
-Note that running the tests may create various cloud resources, for which you
-may incur costs. For the AWS cloud, there is also a mock provider that will
-simulate AWS resources. It is used by default when running the test suite. To
-disable it, set the following environment variable:
-``export CB_USE_MOCK_PROVIDERS=No``.
-
-Testing philosophy
-~~~~~~~~~~~~~~~~~~
-Our testing goals are to:
-
-1. Write one set of tests that all provider implementations must pass.
-
-2. Make that set of tests a 'conformance' test suite, which validates that each
-implementation correctly implements the cloudbridge specification.
-
-3. Make the test suite comprehensive enough that a provider which passes all the
-tests can be used safely by an application with no additional testing. In other
-words, the cloudbridge specification and accompanying test suite must be
-comprehensive enough that no provider specific workarounds, code or testing is
-required.
-
-4. For development, mock providers may be used to speed up the feedback cycle,
-but providers must also pass the full suite of tests when run against actual
-cloud infrastructure to ensure that we are not testing against an idealised or
-imagined environment.
-
-5. Aim for 100% code coverage.
-
-.. _`tox`: https://tox.readthedocs.org/en/latest/
+
+.. _`get started`: http://cloudbridge.readthedocs.org/en/latest/
+    getting_started.html
 .. _`PEP8 style guide`: https://www.python.org/dev/peps/pep-0008/
 .. _`provider development page`: http://cloudbridge.readthedocs.org/en/latest/
     topics/provider_development.html

docs/topics/overview.rst

@@ -11,3 +11,4 @@ Introductions to all the key parts of Cloudbridge you'll need to know:
     Object states and lifecycles <object_lifecycles.rst>
     Paging and iteration <paging_and_iteration.rst>
     Using block storage <block_storage.rst>
+    Testing <test.rst>

docs/topics/test.rst

@@ -0,0 +1,68 @@
+Running tests
+=============
+In the spirit of the set library `design goals`_, the aim is to have through
+tests for the entire library. This page explains the testing philosopy and
+shows how to run the tests locally.
+
+Testing philosophy
+------------------
+Our testing goals are to:
+
+ 1. Write one set of tests that all provider implementations must pass.
+
+ 2. Make that set of tests a 'conformance' test suite, which validates that each
+    implementation correctly implements the cloudbridge specification.
+
+ 3. Make the test suite comprehensive enough that a provider which passes all
+    the tests can be used safely by an application with no additional testing.
+    In other words, the cloudbridge specification and accompanying test suite
+    must be comprehensive enough that no provider specific workarounds, code or testing is required.
+
+ 4. For development, mock providers may be used to speed up the feedback cycle,
+    but providers must also pass the full suite of tests when run against actual
+    cloud infrastructure to ensure that we are not testing against an idealised
+    or imagined environment.
+
+ 5. Aim for 100% code coverage.
+
+
+Running tests
+-------------
+To run the test suite locally:
+ 1. Install `tox`_ with :code:`pip install tox`
+ 2. Export all environment variables listed in ``tox.ini`` (under ``passenv``)
+ 3. Run ``tox`` command
+
+This will run all the tests for all the environments defined in file
+``tox.ini``.
+
+
+Specific environment
+~~~~~~~~~~~~~~~~~~~~
+If you’d like to run the tests on a specific environment only, say Python 2.7,
+use a command like this: ``tox -e py27``. Alternativley, to use your default
+python, you can also run the test command directly ``python setup.py test``.
+
+Select infrastructure
+~~~~~~~~~~~~~~~~~~~~~
+You can also run the tests on a specific cloud only. To do so, export an
+environment variable ``CB_TEST_PROVIDER`` and specify the desired provider
+name. The available provider names are listed in the `ProviderList`_ class
+(e.g., ``aws`` or ``openstack``). Then, run the ``tox`` command.
+
+Using a mock provider
+~~~~~~~~~~~~~~~~~~~~~
+
+Note that running the tests may create various cloud resources, for which you
+may incur costs. For the AWS cloud, there is also a mock provider (`moto`_) that
+will simulate AWS resources. It is used by default when running the test suite.
+You can toggle the use of mock providers by setting an environment variable:
+``CB_USE_MOCK_PROVIDERS`` to ``Yes`` or ``No``.
+
+
+.. _design goals: https://github.com/galaxyproject/galaxy-cloudman-playbook/
+   blob/master/README.md
+.. _tox: https://tox.readthedocs.org/en/latest/
+.. _ProviderList: https://github.com/gvlproject/cloudbridge/blob/master/
+   cloudbridge/cloud/factory.py#L15
+.. _moto: https://github.com/spulec/moto