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.
281. `ENABLE_TFE` - Some tests are only applicable to Terraform Enterprise or Terraform Cloud. By setting `ENABLE_TFE=1` you will enable enterprise only tests and disable cloud only tests. In CI `ENABLE_TFE` is not set so if you are writing enterprise only features you should manually test with `ENABLE_TFE=1` against a Terraform Enterprise instance.
291. `SKIP_PAID` - Some tests depend on paid only features. By setting `SKIP_PAID=1`, you will skip tests that access paid features.
30
31You 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).
32   1. Make sure you have envchain installed. [Instructions for this can be found in the envchain README](https://github.com/sorah/envchain#installation).
33   1. Pick a namespace for storing your environment variables. I suggest `go-tfe` or something similar.
34   1. For each environment variable you need to set, run the following command:
35      ```sh
36      envchain --set YOUR_NAMESPACE_HERE ENVIRONMENT_VARIABLE_HERE
37      ```
38      **OR**
39
40      Set all of the environment variables at once with the following command:
41      ```sh
42      envchain --set YOUR_NAMESPACE_HERE TFE_ADDRESS TFE_TOKEN GITHUB_TOKEN GITHUB_POLICY_SET_IDENTIFIER
43      ```
44
45### 3. Make sure run queue settings are correct
46
47In order for the tests relating to queuing and capacity to pass, FRQ (fair run queuing) should be
48enabled with a limit of 2 concurrent runs per organization on the Terraform Cloud or Terraform Enterprise instance you are using for testing.
49
50### 4. Run the tests
51
52#### Running all the tests
53As running the all of the tests takes about ~20 minutes, make sure to add a timeout to your
54command (as the default timeout is 10m).
55
56##### With envchain:
57```sh
58$ envchain YOUR_NAMESPACE_HERE go test ./... -timeout=30m
59```
60
61##### Without envchain:
62```sh
63$ go test ./... -timeout=30m
64```
65#### Running specific tests
66
67The commands below use notification configurations as an example.
68
69##### With envchain:
70```sh
71$ envchain YOUR_NAMESPACE_HERE go test -run TestNotificationConfiguration -v ./...
72```
73
74##### Without envchain:
75```sh
76$ go test -run TestNotificationConfiguration -v ./...
77```
78
79