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