1## Running tests 2 3### 1. (Optional) Create repositories for policy sets and registry modules 4 5If you are planning to run the full suite of tests or work on policy sets or registry modules, you'll need to set up repositories for them in GitHub. 6 7Your policy set repository will need the following: 81. A policy set stored in a subdirectory `policy-sets/foo` 91. A branch other than master named `policies` 10 11Your registry module repository will need to be a [valid module](https://www.terraform.io/docs/cloud/registry/publish.html#preparing-a-module-repository). 12It will need the following: 131. To be named `terraform-<PROVIDER>-<NAME>` 141. At least one valid SemVer tag in the format `x.y.z` 15[terraform-random-module](ttps://github.com/caseylang/terraform-random-module) is a good example repo. 16 17### 2. Set up environment variables 18 19##### Required: 20Tests are run against an actual backend so they require a valid backend address and token. 211. `TFE_ADDRESS` - URL of a Terraform Cloud or Terraform Enterprise instance to be used for testing, including scheme. Example: `https://tfe.local` 221. `TFE_TOKEN` - A [user API token](https://www.terraform.io/docs/cloud/users-teams-organizations/users.html#api-tokens) for the Terraform Cloud or Terraform Enterprise instance being used for testing. 23 24##### Optional: 251. `GITHUB_TOKEN` - [GitHub personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). Required for running any tests that use VCS (OAuth clients, policy sets, etc). 261. `GITHUB_POLICY_SET_IDENTIFIER` - GitHub policy set repository identifier in the format `username/repository`. Required for running policy set tests. 271. `GITHUB_REGISTRY_MODULE_IDENTIFIER` - GitHub registry module repository identifier in the format `username/repository`. Required for running registry module tests. 28 29You can set your environment variables up however you prefer. The following are instructions for setting up environment variables using [envchain](https://github.com/sorah/envchain). 30 1. Make sure you have envchain installed. [Instructions for this can be found in the envchain README](https://github.com/sorah/envchain#installation). 31 1. Pick a namespace for storing your environment variables. I suggest `go-tfe` or something similar. 32 1. For each environment variable you need to set, run the following command: 33 ```sh 34 envchain --set YOUR_NAMESPACE_HERE ENVIRONMENT_VARIABLE_HERE 35 ``` 36 **OR** 37 38 Set all of the environment variables at once with the following command: 39 ```sh 40 envchain --set YOUR_NAMESPACE_HERE TFE_ADDRESS TFE_TOKEN GITHUB_TOKEN GITHUB_POLICY_SET_IDENTIFIER 41 ``` 42 43### 3. Make sure run queue settings are correct 44 45In order for the tests relating to queuing and capacity to pass, FRQ (fair run queuing) should be 46enabled with a limit of 2 concurrent runs per organization on the Terraform Cloud or Terraform Enterprise instance you are using for testing. 47 48### 4. Run the tests 49 50#### Running all the tests 51As running the all of the tests takes about ~20 minutes, make sure to add a timeout to your 52command (as the default timeout is 10m). 53 54##### With envchain: 55```sh 56$ envchain YOUR_NAMESPACE_HERE go test ./... -timeout=30m 57``` 58 59##### Without envchain: 60```sh 61$ go test ./... -timeout=30m 62``` 63#### Running specific tests 64 65The commands below use notification configurations as an example. 66 67##### With envchain: 68```sh 69$ envchain YOUR_NAMESPACE_HERE go test -run TestNotificationConfiguration -v ./... 70``` 71 72##### Without envchain: 73```sh 74$ go test -run TestNotificationConfiguration -v ./... 75``` 76 77