docs(tests): update README.md with integration test setup

Author: mboersma

Makefile

@@ -160,7 +160,7 @@ test-components:
 	)
 
 test-integration:
-	$(MAKE) -C tests/ test
+	$(MAKE) -C tests/ test-full
 
 test-smoke:
 	$(MAKE) -C tests/ test-smoke

tests/Makefile

@@ -1,6 +1,4 @@
-test:
-	GOPATH=$(CURDIR)/_vendor:$(GOPATH) \
-		go test -tags integration -v -run TestSmoke
+test: test-smoke
 
 test-smoke:
 	GOPATH=$(CURDIR)/_vendor:$(GOPATH) \

tests/README.md

@@ -1,20 +1,64 @@
-# Deis integration testing
+# Deis Tests
 
-This directory contains a Go package which will run integration tests on an
-existing Deis cluster.
+This directory contains a [Go](http://golang.org/) package with integration
+tests for the [Deis](http://deis.io/) open source PaaS.
 
-Repo should be properly checked out into your GOPATH
-go get github.com/deis/deis
+[![GoDoc](https://godoc.org/github.com/deis/deis/tests?status.svg)](https://godoc.org/github.com/deis/deis/tests)
 
-To run all tests:
+**NOTE**: These integration tests are targeted for use in Deis'
+[continuous integration system](http://ci.deis.io/). The tests currently assume
+they are targeting a freshly provisioned Deis cluster. **Don't** run the
+integration tests on a Deis installation with existing users; the tests will
+fail and could overwrite data.
+
+## Test Setup
+
+Check out [Deis' source code](https://github.com/deis/deis) into the `$GOPATH`:
+
+```console
+$ go get -u -v github.com/deis/deis
+$ cd $GOPATH/src/github.com/deis/deis/tests
+```
+
+Provision a Deis cluster as usual, and ensure that a matching `deis`
+command-line client is available in your `$PATH`.
+
+Create two SSH keys:
+
+```console
+$ ssh-keygen -q -t rsa -f ~/.ssh/deis -N '' -C deis
+$ ssh-keygen -q -t rsa -f ~/.ssh/deiskey -N '' -C deiskey
+```
+
+The first key `deis` is used for authentication against Deis by the `test` user
+who runs the integration tests. The second `deiskey` is used only for testing
+`deis keys:add`, `deis keys:list`, and related commands.
+
+## Test Execution
+
+Run all the integration tests:
 
 ```console
-$ go test -v -tags integration -timeout 50m ./...
+$ make test-full
 ```
 
-The test environment uses several environment variables, which can be set to customize the run:
-* `DEIS_TEST_AUTH_KEY` - SSH key used to register with the Deis controller -- will be generated if it doesn't exist (default: `~/.ssh/deis`)
-* `DEIS_TEST_KEY` - SSH key used to login to the controller machine (default: `~/.vagrant.d/insecure_private_key`)
-* `DEIS_TEST_HOSTNAME` - hostname which resolves to the controller host (default: `local.deisapp.com`)
-* `DEIS_TEST_HOSTS` - comma-separated list of IPs for nodes in the cluster -- should be internal IPs for cloud providers (default: `172.17.8.100`)
-* `DEIS_TEST_APP` - name of the Deis example app to use, which is cloned from GitHub (default: `example-ruby-sinatra`)
+Or run just the [smoke test](http://www.catb.org/jargon/html/S/smoke-test.html):
+
+```console
+$ make test-smoke
+```
+
+## Customizing Test Runs
+
+These environment variables can be set to customize the test run:
+* `DEIS_TEST_AUTH_KEY` - SSH key used to register with the Deis controller
+  (default: `~/.ssh/deis`)
+* `DEIS_TEST_SSH_KEY` - SSH key used to login to the controller machine
+  (default: `~/.vagrant.d/insecure_private_key`)
+* `DEIS_TEST_DOMAIN` - the domain to use for testing
+  (default: `local.deisapp.com`)
+* `DEIS_TEST_HOSTS` - comma-separated list of IPs for nodes in the cluster,
+  should be internal IPs for cloud providers (default: `172.17.8.100`)
+* `DEIS_TEST_APP` - name of the
+  [Deis example app](https://github.com/deis?query=example-) to use, which is
+  cloned from GitHub (default: random)

tests/_vendor/src/github.com/dotcloud/docker/VERSION

@@ -1 +1 @@
-1.1.1
+1.1.2

tests/dockercliutils/dockercliutils.go

@@ -1,3 +1,5 @@
+// Package dockercliutils provides helper functions for testing with Docker.
+
 package dockercliutils
 
 import (

tests/etcdutils/etcdutils.go

@@ -1,3 +1,5 @@
+// Package etcdutils helps test interactions with etcd.
+
 package etcdutils
 
 import (

tests/integration-utils/itutils.go

@@ -1,3 +1,6 @@
+// Package itutils provides utility functions and configuration for integration
+// testing with the Deis open source PaaS.
+
 package itutils
 
 import (

tests/main.go

@@ -1,2 +1,2 @@
-// Package github.com/deis/deis/tests runs Deis integration tests.
+// Package tests contains integration tests for the Deis open source PaaS.
 package tests

tests/mockserviceutils/mockserviceutils.go

@@ -1,3 +1,5 @@
+// Package mockserviceutils provides mock objects and setup for Deis tests.
+
 package mockserviceutils
 
 import (

tests/utils/utils.go

@@ -1,3 +1,5 @@
+// Package utils contains commonly useful functions from Deis testing.
+
 package utils
 
 import (