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; Terraform Cloud completes this step automatically when a configuration file is uploaded.
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 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 | Terraform Cloud has queued the test operation to start. | |
running | Terraform Cloud 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. |
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 to create a module 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 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 version is being created. |
:provider | The name of the provider for which the version 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 Terraform Cloud executes the tests. |
data.attributes.filters | array[string] | (empty array) | When specified, Terraform Cloud 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 | Specifies the configuration version that Terraform Cloud 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 to create a module 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 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 version is being created. |
:provider | The name of the provider for which the 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 to create a module 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 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 version is being created. |
:provider | The name of the provider for which the version is being created. |
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 |
---|---|
page[number] | Optional. If omitted, the endpoint returns the first page. |
page[size] | Optional. If omitted, the endpoint returns 20 runs per page. |
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 to create a module 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 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 version is being created. |
:provider | The name of the provider for which the version is being created. |
: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 module 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 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 version is being created. |
:provider | The name of the provider for which the version is being created. |
:test_run_id | The test ID to cancel. |
Use the cancel
action to interrupt a test that is currently running. The running Terraform process is sent an INT
signal, 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 to create a module 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 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 version is being created. |
:provider | The name of the provider for which the version is being created. |
: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 to create a module 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 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 version is being created. |
:provider | The name of the provider for which the version 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 | Must be "vars" . | |
data.attributes.key | string | The name of the variable. | |
data.attributes.value | string | "" | The value of the variable. |
data.attributes.description | string | The description of the variable. | |
data.attributes.category | string | This must be "env" . | |
data.attributes.sensitive | bool | false | Whether the value is sensitive. When set to true , Terraform write 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 to create a module 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 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 version is being created. |
:provider | The name of the provider for which the version is being created. |
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 to create a module 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 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 version is being created. |
:provider | The name of the provider for which the version is being created. |
: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 | 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 to create a module 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 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 version is being created. |
:provider | The name of the provider for which the version is being created. |
:variable_id | The ID of the variable to delete. |
Sample Request