Tests API
Performing a test on a new configuration is a multi-step process.
- Create a configuration version on the registry module.
- Upload configuration files to the configuration version.
- Create a test on the module; HCP Terraform completes this step automatically when you upload a configuration file.
Alternatively, you can create a test with a pre-existing configuration version, even one from another module. This is useful for promoting known good code from one module to another.
Attributes
The tests
API endpoint has the following attributes.
Test run states
The state of the test operation is found in data.attributes.status
, and you can reference the following list of possible states.
State | Description |
---|---|
pending | The initial status of a run after creation. |
queued | HCP Terraform has queued the test operation to start. |
running | HCP Terraform is executing the test. |
errored | The test has errored. This is a final state. |
canceled | The test has been canceled. This is a final state. |
finished | The test has completed. This is a final state. |
Test run status
The final test status is found in data.attributes.test-status
, and you can reference the following list of possible states.
Status | Description |
---|---|
pass | The given tests have passed. |
fail | The given tests have failed. |
Detailed test status
The test results can be found via the following attributes
Status | Description | |
---|---|---|
data.attributes.tests-passed | The number of tests that have passed. | |
data.attributes.tests-failed | The number of tests that have failed. | |
data.attributes.tests-errored | The number of tests that have errored out. | |
data.attributes.tests-skipped | The number of tests that have been skipped. |
Test Sources
List tests for a module. You can use the following sources as tests list query parameters.
Source | Description |
---|---|
terraform | Indicates a test was queued from HCP Terraform CLI. |
tfe-api | Indicates a test was queued from HCP Terraform API. |
tfe-configuration-version | Indicates a test was queued from a Configuration Version, triggered from a VCS provider. |
Create a test Run
POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs
Parameter | Description |
---|---|
:organization_name | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. |
:namespace | The namespace of the module for which the test is being created. For private modules this is the same as the :organization_name parameter. |
:name | The name of the module for which the test is being created. |
:provider | The name of the provider for which the test is being created. |
A test run executes tests against a registry module, using a configuration version and the modules’s current environment variables.
Creating a test run requires permission to access the specified module. Refer to Permissions for more information.
When creating a test run, you may optionally provide a list of variable objects containing key and value attributes. These values apply to that test run specifically and take precedence over variables with the same key that are created within the module. All values must be expressed as an HCL literal in the same syntax you would use when writing Terraform code.
Sample Test Variables:
Request Body
This POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data.attributes.verbose | bool | false | Specifies whether Terraform should print the plan or state for each test run block as it executes. |
data.attributes.test-directory | string | "tests" | Sets the directory where HCP Terraform executes the tests. |
data.attributes.filters | array[string] | (empty array) | When specified, HCP Terraform only executes the test files contained within this array. |
data.attributes.variables | array[{key, value}] | (empty array) | Specifies an optional list of test-specific environment variable values. |
data.relationships.configuration-version.data.id | string | none | Specifies the configuration version that HCP Terraform executes the test against. |
Sample Payload
Sample Request
Sample Response
Create a Configuration Version for a test
POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/configuration-versions
Parameter | Description |
---|---|
:organization_name | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. |
:namespace | The namespace of the module for which the configuration version is being created. For private modules this is the same as the :organization_name parameter. |
:name | The name of the module for which the configuration version is being created. |
:provider | The name of the provider for which the configuration version is being created. |
Sample Request
Sample Response
Upload Configuration Files for a Test
PUT https://archivist.terraform.io/v1/object/<UNIQUE OBJECT ID>
The URL is provided in the upload-url
attribute when creating a configuration-versions
resource. After creation, the URL is hidden on the resource and no longer available.
Sample Request
@filename is the name of the configuration file you wish to upload.
List tests for a module
GET /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/
Parameter | Description |
---|---|
:organization_name | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. |
:namespace | The namespace of the module which the tests have executed against. For private modules this is the same as the :organization_name parameter. |
:name | The name of the module which the tests have executed against. |
:provider | The name of the provider which the tests have executed against. |
Query Parameters
This endpoint supports pagination with standard URL query parameters; remember to percent-encode [
as %5B
and ]
as %5D
if your tooling does not automatically encode URLs.
Parameter | Description | Required |
---|---|---|
page[number] | If omitted, the endpoint returns the first page. | Optional |
page[size] | If omitted, the endpoint returns 20 runs per page. | Optional |
filter[source] | Optional. A comma-separated list of test sources; the result will only include tests that came from one of these sources. Options are listed in Test Sources. |
Sample Request
Sample Response
Get Test Details
GET /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/:test_run_id
Parameter | Description |
---|---|
:organization_name | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. |
:namespace | The namespace of the module which the test was executed against. For private modules this is the same as the :organization_name parameter. |
:name | The name of the module which the test was executed against. |
:provider | The name of the provider which the test was executed against. |
:test_run_id | The test ID to get. |
Sample Request
Sample Response
Cancel a Test
POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/:test_run_id/cancel
Parameter | Description |
---|---|
:organization_name | The name of the organization to create a test in. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. |
:namespace | The namespace of the module for which the test is being canceled. For private modules this is the same as the :organization_name parameter. |
:name | The name of the module for which the test is being canceled. |
:provider | The name of the provider for which the test is being canceled. |
:test_run_id | The test ID to cancel. |
Use the cancel
action to interrupt a test that is currently running. The action sends an INT
signal to the running Terraform process, which instructs Terraform to safely end the tests and attempt to teardown any infrastructure that your tests create.
Status | Response | Reason(s) |
---|---|---|
202 | none | Successfully queued a cancel request. |
409 | JSON API error object | Test was not running; cancel not allowed. |
404 | JSON API error object | Test was not found or user not authorized. |
Sample Request
Forcefully cancel a Test
POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/test-runs/:test_run_id/force-cancel
Parameter | Description |
---|---|
:organization_name | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the owners team or a member of the owners team. |
:namespace | The namespace of the module for which the test is being force-canceled. For private modules this is the same as the :organization_name parameter. |
:name | The name of the module for which the test is being force-canceled. |
:provider | The name of the provider for which the test is being force-canceled. |
:test_run_id | The test ID to cancel. |
The force-cancel
action ends the test immediately. Once invoked, Terraform places the test into a canceled
state and terminates the running Terraform process.
Warning: This endpoint has potentially dangerous side-effects, including loss of any in-flight state in the running Terraform process. Use this operation with extreme caution.
Status | Response | Reason(s) |
---|---|---|
202 | none | Successfully queued a cancel request. |
409 | JSON API error object | Test was not running, or has not been canceled non-forcefully. |
404 | JSON API error object | Test was not found or user not authorized. |
Sample Request
Create an Environment Variable for module tests
POST /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars
Parameter | Description |
---|---|
:organization_name | The name of the organization of the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. |
:namespace | The namespace of the module for which the testing environment variable is being created. For private modules this is the same as the :organization_name parameter. |
:name | The name of the module for which the testing environment variable is being created. |
:provider | The name of the provider for which the testing environment variable is being created. |
Request Body
This POST endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data.type | string | none | Must be "vars" . |
data.attributes.key | string | none | The name of the variable. |
data.attributes.value | string | "" | The value of the variable. |
data.attributes.description | string | none | The description of the variable. |
data.attributes.category | string | none | This must be "env" . |
data.attributes.sensitive | bool | false | Whether the value is sensitive. When set to true , Terraform writes the variable once and is not visible thereafter. |
Sample Payload
Sample Request
Sample Response
List Test Variables for a Module
GET /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars
Parameter | Description |
---|---|
:organization_name | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the owners team or a member of the owners team. |
:namespace | The namespace of the module which the test environment variables were created for. For private modules this is the same as the :organization_name parameter. |
:name | The name of the module which the test environment variables were created for. |
:provider | The name of the provider which the test environment variables were created for. |
Sample Request
Sample Response
Update Test Variables for a Module
PATCH /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars/variable_id
Parameter | Description |
---|---|
:organization_name | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the "owners" team or a member of the "owners" team. |
:namespace | The namespace of the module for which the test environment variable is being updated. For private modules this is the same as the :organization_name parameter. |
:name | The name of the module for which the test environment variable is being updated. |
:provider | The name of the provider for which the test environment variable is being updated. |
:variable_id | The ID of the variable to update. |
Request Body
This PATCH endpoint requires a JSON object with the following properties as a request payload.
Properties without a default value are required.
Key path | Type | Default | Description |
---|---|---|---|
data.type | string | Must be "vars" . | |
data.attributes | object | none | New attributes for the variable. This object can include key , value , description , category , and sensitive properties. Refer to Create an Environment Variable for Module Tests for additional information. All properties are optional. |
Sample Payload
Sample Request
Sample Response
Delete Test Variable for a Module
DELETE /organizations/:organization_name/tests/registry-modules/private/:namespace/:name/:provider/vars/variable_id
Parameter | Description |
---|---|
:organization_name | The name of the organization for the module. The organization must already exist, and the token authenticating the API request must belong to the owners team or a member of the owners team. |
:namespace | The namespace of the module for which the test environment variable is being deleted. For private modules this is the same as the :organization_name parameter. |
:name | The name of the module for which the test environment variable is being deleted. |
:provider | The name of the provider for which the test environment variable is being deleted. |
:variable_id | The ID of the variable to delete. |
Sample Request