Add information on using Test Kitchen for E2E testing.

2 files changed, 57 insertions, 2 deletions

diff --git a/.travis.yml b/.travis.yml
index eb0569ab8c..615a39b21e 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -27,6 +27,7 @@ matrix:
   - rvm: 2.1.1
     gemfile: pedant.gemfile
     script: bundle exec rake pedant
+    ### START TEST KITCHEN ONLY ###
   - rvm: 2.1.1
     gemfile: spec/e2e/Gemfile
     before_install:
@@ -70,6 +71,7 @@ matrix:
     - secure: Ljk6Gp1zFRHqfXFq2SQuU/BJCWcfwffTyOLcO9vQbjQuqzPGMzyGGhN1tXjzkjwEh+xJZ73Hq1j1pCgZ7TNwI1nxu0FDkNjyF9fnMi8lkomvUiABT7W7zhwKO9tTwIaq8A39ddZKyZB86qKtDZqhXUl5Jl3KqUbxCx+L+Vy4q5A=
     - secure: A0myAHUOz4k43oCM+vlsHjT89ueLxXulgNFE3d80s8zBN31Ved84QnEdyYUFOt3ktnrqSo83eviZV99/hmS4T7sk92lTxWScF+N4eoMckjgFqwz4W2z4rLAFcJsPxUj7vKky+Sw7YoBPVXjHi82wKXDXsEUw67fimXG3Ldz7Aq8=
     - secure: ajtyC9PL2ZAnyCxKCGioUMnWgDX/08bJW79tG6FJMShHCxD4viF2UgOpQV/c8kcZ76DAq9Zc89zigUQOeJFN2abFVT+8O43plhwirbLRmuZEjKPOk7XpcLSMgoVsfT6raZn8bvMug4wYVSquoQ8WN8rWqjlN2QPFTN/2Q0vS/ZM=
+    ### END TEST KITCHEN ONLY ###
 
 notifications:
   on_success: change
diff --git a/spec/e2e/README.md b/spec/e2e/README.md
index 9938fccd26..e5b205c1b6 100644
--- a/spec/e2e/README.md
+++ b/spec/e2e/README.md
@@ -1,4 +1,57 @@
-# 
+# End-To-End Testing for Chef Client
 
-TODO: Enter the cookbook description here.
+The goal is to provide end-to-end testing of `chef-client` and tools which ship
+with it. To accomplish this, we use Test Kitchen with the `chef-solo` provisioner
+to download Chef source code from GitHub, locally create and install the chef
+gem from the source code, and run functional tests. Currently, these tests can
+be run locally on your machine, or on Travis when you submit a pull request.
 
+## Testing
+### On your local machine
+By default, Test Kitchen uses the [kitchen-vagrant](https://github.com/test-kitchen/kitchen-vagrant)
+driver plugin to create local kitchen instances and installs Chef based on your
+latest commit to `github.com/opscode/chef`. Currently, for this to work you'll
+need to ensure that your latest commit has been pushed to GitHub. If you want to
+download Chef from a different commit, modify the `branch` line under
+`provisioner` to have that commit's SHA. For example, it may look something like this:
+
+```(yaml)
+# spec/e2e/.kitchen.yml
+---
+provisioner:
+  name: chef_solo
+  branch: c8a54df7ca24f1482a701d5f39879cdc6c836f8a
+  github: "github.com/opscode/chef"
+  require_chef_omnibus: true
+
+platforms:
+  - name: ubuntu-12.04
+    driver_plugin: vagrant
+```
+`branch` accepts any valid git reference.
+
+When you're ready to test, execute the following lines (this assumes your current
+working directory is the head of the chef source code, e.g. mine is`~/oc/chef/`):
+
+```
+$ pwd
+~/oc/chef
+$ cd spec/e2e
+$ bundle install
+$ bundle exec kitchen test
+```
+To change what Test Kitchen runs, modify your `spec/e2e/.kitchen.yml`.
+
+### On Travis
+By default, Test Kitchen uses the [kitchen-ec2](https://github.com/test-kitchen/kitchen-ec2)
+driver plugin to create kitchen instances on EC2 and installs Chef based on the
+latest pushed commit to your pull request on `github.com/opscode/chef`. That is,
+Travis installs Chef from the branch and commit it's testing. Travis runs automatically
+every time you publish your commits to a pull request, so please disable Test Kitchen
+in Travis (by commenting out the appropriate lines in your `.travis.yml`) or push
+new commits to your PR infrequently.
+
+To change what Test Kitchen runs, modify your `spec/e2e/.kitchen.travis.yml`.
+
+**IMPORTANT: Do not modify any of the values in the matrix under `env`!** These are carefully
+configured so that Travis can use EC2 and Test Kitchen.