Add test instructions and contributing information.

1 files changed, 78 insertions, 46 deletions

diff --git a/kitchen-tests/README.md b/kitchen-tests/README.md
index e5b205c1b6..2d03b19b62 100644
--- a/kitchen-tests/README.md
+++ b/kitchen-tests/README.md
@@ -1,57 +1,89 @@
 # End-To-End Testing for Chef Client
+Here we seek to provide end-to-end testing of Chef Client through cookbooks which
+exercise many of the available resources, providers, and common patterns. The cookbooks
+here are designed to ensure certain capabilities remain functional with updates
+to the client code base.
 
-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.
+## Getting started
+All the gems needed to run these tests can be installed with Bundler.
 
-## 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
+```shell
+chef/kitchen-tests$ bundle install
 ```
-`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/`):
+To ensure everything is working properly, and to see which platforms can have tests
+executed on them, run
 
+```shell
+chef/kitchen-tests$ bundle exec kitchen list
 ```
-$ pwd
-~/oc/chef
-$ cd spec/e2e
-$ bundle install
-$ bundle exec kitchen test
+
+You should see output similar to
+
+```shell
+Instance            Driver    Provisioner  Last Action
+webapp-ubuntu-1204  Vagrant   ChefSolo     <Not Created>
 ```
-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.
+## Testing
+We use Test Kitchen to build instances, test client code, and destroy instances. If
+you are unfamiliar with Test Kitchen we recommend checking out the [tutorial](http://kitchen.ci/)
+along with the `kitchen-vagrant` [driver documentation](https://github.com/test-kitchen/kitchen-vagrant).
+Test Kitchen is configured to manipulate instances using [Vagrant](http://www.vagrantup.com/)
+when testing locally, and [Amazon EC2](http://aws.amazon.com/ec2/) when testing
+pull requests on [Travis CI](https://travis-ci.com).
+
+### Commands
+Kitchen instances are led through a series of states. The instance states, and the actions
+taken to transition into each state, are in order:
+* `destroy`: Delete all information for and terminate one or more instances.
+  * This is equivalent to running `vagrant destroy` to stop and delete a Vagrant machine.
+* `create`: Start one or more instances.
+  * This is equivalent to running `vagrant up --no-provision` to start a Vagrant instance.
+* `converge`: Use a provisioner to configure one or more instances.
+  * By default, Test Kitchen is configured to use the `ChefSolo` provisioner which:
+    * Prepares local files for transfer,
+    * Installs the latest release of Chef Omnibus,
+    * Downloads Chef Client source code from the prescribed GitHub repository and reference,
+    * Builds and installs a `chef` gem from the downloaded source,
+    * Runs `chef-client`.
+* `setup`: Prepare to run automated tests. Installs `busser` and related gems on one or more instances.
+* `verify`: Run automated tests on one or more instances.
+
+When transitioning between states, actions for any and all intermediate states will performed.
+Executing the `create` then the `verify` commands is equivalent to executing `create`, `converge`,
+`setup`, and `verify` one-by-one and in order. The only exception is `destroy`, which will
+immediately transfer that machine's state to destroyed.
+
+The `test` command takes one or more instances through all the states, in order: `destroy`, `create`,
+`converge`, `setup`, `verify`, `destroy`.
+
+To see a list of available commands, type `bundle exec kitchen help`. To see more information
+about a particular command, type `bundle exec kitchen help <command>`.
+
+### Configuring your tests
+Test Kitchen is configured for local testing in the `.kitchen.yml` file which resides in this directory.
+You will need to configure the provisioner before running the tests.
+
+The provisioner can be configured to pull client source code from a GitHub repository using any
+valid Git reference. You are encouraged to modify any of these settings, but please return them
+to their original values before submitting a pull request for review (unless, of course, your
+changes are enhancements to the default provisioner settings).
+
+By default, the provisioner is configured to pull your most recent commit to `opscode/chef`. You
+can change this by modifying the `github` and `branch` provisioner options:
+* `github`: Set this to `"<your_username>/<your_chef_repo>"`. The default is `"opscode/chef"`.
+* `branch`: This can be any valid git reference (e.g., branch name, tag, or commit SHA). If omitted, it defaults to `master`.
+
+The branch you choose must be accessible on GitHub. You cannot use a local commit at this time.
 
-To change what Test Kitchen runs, modify your `spec/e2e/.kitchen.travis.yml`.
+### Testing pull requests
+These end-to-end tests are also configured to run with Travis on EC2 instances when you submit a pull request
+to `opscode/chef`. Kitchen is configured to pull chef client source code from the branch it is testing. There
+is no need to modify `.kitchen.travis.yml` unless you are contributing tests.
 
-**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.
+## Contributing
+We would love to fill out our end-to-end testing coverage! If you have cookbooks and tests that you would
+like to see become a part of client testing, we encourage you to submit a pull request with your additions.
+We request that you do not add platforms to `.kitchen.travis.yml`. Please file a request to add a
+platform under [Issues](https://github.com/opscode/chef/issues).