diff --git a/README.md b/README.md index 1efc5ba3cb..031b4bb050 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ * Mailing list: [Google Groups](http://groups.google.com/group/terraform) Terraform is a tool for building and changing infrastructure -safetly and efficiently. +safely and efficiently. ## Developing Terraform @@ -45,3 +45,36 @@ package by specifying the `TEST` variable. For example below, only $ make test TEST=./terraform ... + +### Acceptance Tests + +Terraform also has a comprehensive +[acceptance test](http://en.wikipedia.org/wiki/Acceptance_testing) +suite covering most of the major features of the built-in providers. + +If you're working on a feature of a provider and want to verify it +is functioning (and hasn't broken anything else), we recommend running +the acceptance tests. Note that we _do not require_ that you run or +write acceptance tests to have a PR accepted. The acceptance tests +are just here for your convenience. + +**Warning:** The acceptance tests create/destroy/modify _real resources_, +which may incur real costs. In the presence of a bug, it is technically +possible that broken providers could corrupt existing infrastructure +as well. Therefore, please run the acceptance providers at your own +risk. At the very least, we recommend running them in their own private +account for whatever provider you're testing. + +To run the acceptance tests, invoke `make testacc`: + + $ make testacc TEST=./builtin/providers/aws TESTARGS='-run=VPC' + ... + +The `TEST` variable is required, and you should specify the folder where +the provider is. The `TESTARGS` variable is recommended to filter down +to a specific resource to test, since testing all of them at once can +take a very long time. + +Acceptance tests typically require other environment variables to be +set for things such as access keys. The provider itself should error +early and tell you what to set, so it is not documented here.