fix(tests): add docs for local testing with s3cmd

Author: carmstrong

docs/contributing/testing.rst

@@ -69,6 +69,14 @@ individual pieces of Deis, then bring up a Vagrant cluster and test all of them
 as a system. They call ``tests/bin/test-setup.sh`` to test for important
 environment variables and will exit with a helpful message if any are missing.
 
+The ``test-setup.sh`` script also prepares the testing environment, as well as
+tears it down after testing is complete. If there is a test failure, the script
+collects verbose component logs, compresses them, and places them in ``$HOME``.
+If `s3cmd`_ is installed and configured on the test machine, the script will
+instead upload the logs to Amazon S3. This is how the Jenkins CI infrastructure
+is configured, so that contributors have access to the logs to see how their
+PR failed.
+
 test-integration.sh
 ^^^^^^^^^^^^^^^^^^^
 
@@ -155,3 +163,4 @@ variables that can affect the tests' behavior. Here are some important ones:
 .. _`source code`: https://github.com/deis/deis
 .. _`Docker registry`: https://github.com/docker/docker-registry
 .. _`Deis example app`: https://github.com/deis?query=example-
+.. _`s3cmd`: http://s3tools.org/s3cmd

tests/bin/test-setup.sh

@@ -96,7 +96,7 @@ function cleanup {
 function dump_logs {
   log_phase "Error detected, dumping logs"
   TIMESTAMP=`date +%Y-%m-%d-%H%M%S`
-  FAILED_LOGS_DIR=$HOME/jenkins-$TIMESTAMP
+  FAILED_LOGS_DIR=$HOME/deis-test-failure-$TIMESTAMP
   mkdir -p $FAILED_LOGS_DIR
   set +e
   export FLEETCTL_TUNNEL=$DEISCTL_TUNNEL
@@ -138,14 +138,16 @@ function dump_logs {
 
   # tarball logs
   BUCKET=jenkins-failure-logs
-  FILENAME=$BUCKET-$TIMESTAMP.tar.gz
+  FILENAME=deis-test-failure-$TIMESTAMP.tar.gz
   cd $FAILED_LOGS_DIR && tar -czf $FILENAME *.log && mv $FILENAME .. && cd ..
   rm -rf $FAILED_LOGS_DIR
   if [ `which s3cmd` ] && [ -f $HOME/.s3cfg ]; then
     echo "configured s3cmd found in path. Attempting to upload logs to S3"
     s3cmd put $HOME/$FILENAME s3://$BUCKET
     rm $HOME/$FILENAME
-    echo "Logs can be viewed here: https://s3.amazonaws.com/$BUCKET/$FILENAME"
+    echo "Logs are accessible at https://s3.amazonaws.com/$BUCKET/$FILENAME"
+  else
+    echo "Logs are accessible at $HOME/$FILENAME"
   fi
   exit 1
 }