Document regression tests, make run_regression fail if environ not set.

CONTRIBUTING.rst

@@ -3,7 +3,7 @@ Contributing
 
 #. **Please sign one of the contributor license agreements below.**
 #. Fork the repo, develop and test your code changes, add docs.
-#. Make sure that your commit messages clearly describe the changes. 
+#. Make sure that your commit messages clearly describe the changes.
 #. Send a pull request.
 
 Here are some guidelines for hacking on gcloud-python.
@@ -16,7 +16,7 @@ using a Git checkout:
 
 - While logged into your GitHub account, navigate to the gcloud-python repo on
   GitHub.
-  
+
   https://github.com/GoogleCloudPlatform/gcloud-python
 
 - Fork and clone the gcloud-python repository to your GitHub account by
@@ -130,6 +130,35 @@ Running Tests
    $ cd ~/hack-on-gcloud/
    $ /usr/bin/tox
 
+Running Regression Tests
+------------------------
+
+- To run regression tests you can execute::
+
+   $ tox -e regression
+
+  or run only regression tests for a particular package via::
+
+   $ python regression/run_regression.py --package {package}
+
+- Regression tests will be run against an actual project and
+  so you'll need to provide some environment variables to facilitate
+  authentication to your project:
+
+  - ``GCLOUD_TESTS_DATASET_ID``: The name of the dataset your tests connect to.
+  - ``GCLOUD_TESTS_CLIENT_EMAIL``: The email for the service account you're
+    authenticating with
+  - ``GCLOUD_TESTS_KEY_FILE``: The path to an encrypted key file.
+
+- Examples of these can be found in ``regression/local_test_setup.sample``. We
+  recommend copying this to ``regression/local_test_setup``, editing the values
+  and sourcing them into your environment::
+
+   $ source regression/local_test_setup
+
+- The ``GCLOUD_TESTS_KEY_FILE`` value should point to a valid path (relative or
+  absolute) on your system where the key file for your service account can
+  be found.
 
 Test Coverage
 -------------
@@ -184,4 +213,4 @@ Before we can accept your pull requests you'll need to sign a Contributor Licens
 - **If you are an individual writing original source code** and **you own the intellectual property**, then you'll need to sign an `individual CLA <https://developers.google.com/open-source/cla/individual>`__.
 - **If you work for a company that wants to allow you to contribute your work**, then you'll need to sign a `corporate CLA <https://developers.google.com/open-source/cla/corporate>`__.
 
-You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests.
+You can sign these electronically (just scroll to the bottom). After that, we'll be able to accept your pull requests.

regression/run_regression.py

@@ -1,6 +1,10 @@
 import argparse
 import unittest2
 
+# This assumes the command is being run via tox hence the
+# repository root is the current directory.
+from regression import regression_utils
+
 
 def get_parser():
     parser = argparse.ArgumentParser(
@@ -21,6 +25,8 @@ def run_module_tests(module_name):
 def main():
     parser = get_parser()
     args = parser.parse_args()
+    # Make sure environ is set before running test.
+    regression_utils.get_environ()
     run_module_tests(args.package)