Tests - API Docs - Terraform Enterprise | Terraform

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 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.

test run 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(/terraform/enterprise/users-teams-organizations/permissions) for additional 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:

"attributes": {  "variables": [    { "key": "replicas", "value": "2" },    { "key": "access_key", "value": "\"ABCDE12345\"" }  ]}

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 executes the tests.
`data.attributes.filters`	array[string]	(empty array)	When specified, 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		Specifies the configuration version that Terraform executes the test against.

Sample Payload

{  "data": {    "attributes": {      "verbose": true,      "filters": ["tests/test.tftest.hcl"],      "test-directory": "tests",      "variables": [        { "key" : "number", "value": 4}      ]    },    "type":"test-runs"  }}

Sample Request

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  --data @payload.json \  https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/private/registry-provider/test-runs

Sample Response

{  "data": {    "id": "trun-KFg8DSiRz4E37mdJ",    "type": "test-runs",    "attributes": {      "status": "queued",      "status-timestamps": {          "queued-at": "2023-10-03T18:27:39+00:00"      },      "created-at": "2023-10-03T18:27:39.239Z",      "updated-at": "2023-10-03T18:27:39.264Z",      "test-configurable-type": "RegistryModule",      "test-configurable-id": "mod-9rjVHLCUE9QD3k6L",      "variables": [          {              "key": "number",              "value": "4"          }      ],      "filters": [          "tests/test.tftest.hcl"      ],      "test-directory": "tests",      "verbose": true,      "test-status": null,      "tests-passed": null,      "tests-failed": null,      "tests-errored": null,      "tests-skipped": null,      "source": "tfe-api",      "message": "Queued manually via the Terraform Enterprise API"    },    "relationships": {        "configuration-version": {            "data": {                "id": "cv-d3zBGFf5DfWY4GY9",                "type": "configuration-versions"            },            "links": {                "related": "/api/v2/configuration-versions/cv-d3zBGFf5DfWY4GY9"            }        },        "created-by": {            "data": {                "id": "user-zsRFs3AGaAHzbEfs",                "type": "users"            },            "links": {                "related": "/api/v2/users/user-zsRFs3AGaAHzbEfs"            }        }    }  }}

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

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  --data @payload.json \  https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs

Sample Response

{  "data": {    "id": "cv-aaady7niJMY1wAvx",    "type": "configuration-versions",    "attributes": {        "auto-queue-runs": true,        "error": null,        "error-message": null,        "source": "tfe-api",        "speculative": false,        "status": "pending",        "status-timestamps": {},        "changed-files": [],        "provisional": false,        "upload-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djM6eFliQ0l1ZEhNUDRMZmdWeExoYWZ1WnFwaCtYQUFSQjFaWVcySkEyT0tyZTZXQ0hjN3ZYQkFvbkJHWkg2Y0U2MDRHRXFvQVl6cUJqQzJ0VkppVHBXTlJNWmpVc1ZTekg5Q1hMZ0hNaUpNdUhib1hGS1RpT3czRGdRaWtPZFZ3VWpDQ1U0S2dhK2xLTUQ2ZFZDaUZ3SktiNytrMlpoVHd0cXdGVHIway8zRkFmejdzMSt0Rm9TNFBTV3dWYjZUTzJVNE1jaW9UZ2VKVFJNRnUvbjBudUp4U0l6VzFDYkNzVVFsb2VFbC9DRFlCTWFsbXBMNzZLUGQxeTJHb09ZTkxHL1d2K1NtcmlEQXptZTh1Q1BwR1dhbVBXQTRiREdlTkI3Qyt1YTRRamFkRzBWYUg3NE52TGpqT1NKbzFrZ3J3QmxnMGhHT3VaTHNhSmo0eXpv"    },    "relationships": {        "ingress-attributes": {            "data": null,            "links": {              "related": "/api/v2/configuration-versions/cv-aaady7niJMY1wAvx/ingress-attributes"            }        }    },    "links": {        "self": "/api/v2/configuration-versions/cv-aaady7niJMY1wAvx"    }  }}

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.

curl \  --header "Content-Type: application/octet-stream" \  --request PUT \  --data-binary @filename \  https://archivist.terraform.io/v1/object/4c44d964-eba7-4dd5-ad29-1ece7b99e8da

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

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs

Sample Response

{  "data": [    {      "id": "trun-KFg8DSiRz4E37mdJ",      "type": "test-runs",      "attributes": {        "status": "finished",        "status-timestamps": {          "queued-at": "2023-10-03T18:27:39+00:00",          "started-at": "2023-10-03T18:27:41+00:00",          "finished-at": "2023-10-03T18:27:53+00:00"        },        "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djM6eFliQ0l1ZEhNUDRMZmdWeExoYWZ1WnFwaCtYQUFSQjFaWVcySkEyT0tyZTZXQ0hjN3ZYQkFvbkJHWkg2Y0U2MDRHRXFvQVl6cUJqQzJ0VkppVHBXTlJNWmpVc1ZTekg5Q1hMZ0hNaUpNdUhib1hGS1RpT3czRGdRaWtPZFZ3VWpDQ1U0S2dhK2xLTUQ2ZFZDaUZ3SktiNytrMlpoVHd0cXdGVHIway8zRkFmejdzMSt0Rm9TNFBTV3dWYjZUTzJVNE1jaW9UZ2VKVFJNRnUvbjBudUp4U0l6VzFDYkNzVVFsb2VFbC9DRFlCTWFsbXBMNzZLUGQxeTJHb09ZTkxHL1d2K1NtcmlEQXptZTh1Q1BwR1dhbVBXQTRiREdlTkI3Qyt1YTRRamFkRzBWYUg3NE52TGpqT1NKbzFrZ3J3QmxnMGhHT3VaTHNhSmo0eXpv",        "created-at": "2023-10-03T18:27:39.239Z",        "updated-at": "2023-10-03T18:27:53.574Z",        "test-configurable-type": "RegistryModule",        "test-configurable-id": "mod-9rjVHLCUE9QD3k6L",        "variables": [          {            "key": "number",            "value": "4"          }        ],        "filters": [          "tests/test.tftest.hcl"        ],        "test-directory": "tests",        "verbose": true,        "test-status": "pass",        "tests-passed": 1,        "tests-failed": 0,        "tests-errored": 0,        "tests-skipped": 0,        "source": "tfe-api",        "message": "Queued manually via the Terraform Enterprise API"      },      "relationships": {        "configuration-version": {            "data": {              "id": "cv-d3zBGFf5DfWY4GY9",              "type": "configuration-versions"            },            "links": {              "related": "/api/v2/configuration-versions/cv-d3zBGFf5DfWY4GY9"            }        },        "created-by": {          "data": {            "id": "user-zsRFs3AGaAHzbEfs",            "type": "users"          },          "links": {            "related": "/api/v2/users/user-zsRFs3AGaAHzbEfs"          }        }      }    },    {...}  ]}

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

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/trun-xFMAHM3FhkFBL6Z7

Sample Response

{  "data": {    "id": "trun-KFg8DSiRz4E37mdJ",    "type": "test-runs",    "attributes": {      "status": "finished",      "status-timestamps": {        "queued-at": "2023-10-03T18:27:39+00:00",        "started-at": "2023-10-03T18:27:41+00:00",        "finished-at": "2023-10-03T18:27:53+00:00"      },      "log-read-url": "https://archivist.terraform.io/v1/object/dmF1bHQ6djM6eFliQ0l1ZEhNUDRMZmdWeExoYWZ1WnFwaCtYQUFSQjFaWVcySkEyT0tyZTZXQ0hjN3ZYQkFvbkJHWkg2Y0U2MDRHRXFvQVl6cUJqQzJ0VkppVHBXTlJNWmpVc1ZTekg5Q1hMZ0hNaUpNdUhib1hGS1RpT3czRGdRaWtPZFZ3VWpDQ1U0S2dhK2xLTUQ2ZFZDaUZ3SktiNytrMlpoVHd0cXdGVHIway8zRkFmejdzMSt0Rm9TNFBTV3dWYjZUTzJVNE1jaW9UZ2VKVFJNRnUvbjBudUp4U0l6VzFDYkNzVVFsb2VFbC9DRFlCTWFsbXBMNzZLUGQxeTJHb09ZTkxHL1d2K1NtcmlEQXptZTh1Q1BwR1dhbVBXQTRiREdlTkI3Qyt1YTRRamFkRzBWYUg3NE52TGpqT1NKbzFrZ3J3QmxnMGhHT3VaTHNhSmo0eXpv",      "created-at": "2023-10-03T18:27:39.239Z",      "updated-at": "2023-10-03T18:27:53.574Z",      "test-configurable-type": "RegistryModule",      "test-configurable-id": "mod-9rjVHLCUE9QD3k6L",      "variables": [        {          "key": "number",          "value": "4"        }      ],      "filters": [        "tests/test.tftest.hcl"      ],      "test-directory": "tests",      "verbose": true,      "test-status": "pass",      "tests-passed": 1,      "tests-failed": 0,      "tests-errored": 0,      "tests-skipped": 0,      "source": "tfe-api",      "message": "Queued manually via the Terraform Enterprise API"    },    "relationships": {      "configuration-version": {          "data": {            "id": "cv-d3zBGFf5DfWY4GY9",            "type": "configuration-versions"          },          "links": {            "related": "/api/v2/configuration-versions/cv-d3zBGFf5DfWY4GY9"          }      },      "created-by": {        "data": {          "id": "user-zsRFs3AGaAHzbEfs",          "type": "users"        },        "links": {          "related": "/api/v2/users/user-zsRFs3AGaAHzbEfs"        }      }    }  }}

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

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/trun-xFMAHM3FhkFBL6Z7/cancel

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

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/test-runs/trun-xFMAHM3FhkFBL6Z7/force-cancel

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

{  "data": {    "type":"vars",    "attributes": {      "key":"some_key",      "value":"some_value",      "description":"some description",      "category":"env",      "sensitive":false    }  }}

Sample Request

curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request POST \  --data @payload.json \  https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars

Sample Response

{  "data": {    "id": "var-xSCUzCxdqMs2ygcg",    "type": "vars",    "attributes": {      "key": "keykey",      "value": "some_value",      "sensitive": false,      "category": "env",      "hcl": false,      "created-at": "2023-10-03T19:47:05.393Z",      "description": "some description",      "version-id": "699b14ea5d5e5c02f6352fac6bfd0a1424c21d32be14d1d9eb79f5e1f28f663a"    },    "links": {      "self": "/api/v2/vars/var-xSCUzCxdqMs2ygcg"    }  }}

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

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars

Sample Response

{  "data": [    {      "id": "var-xSCUzCxdqMs2ygcg",      "type": "vars",      "attributes": {          "key": "keykey",          "value": "some_value",          "sensitive": false,          "category": "env",          "hcl": false,          "created-at": "2023-10-03T19:47:05.393Z",          "description": "some description",          "version-id": "699b14ea5d5e5c02f6352fac6bfd0a1424c21d32be14d1d9eb79f5e1f28f663a"      },      "links": {          "self": "/api/v2/vars/var-xSCUzCxdqMs2ygcg"      }    }  ]}

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

{  "data": {    "attributes": {      "key":"name",      "value":"mars",      "description": "new description",      "category":"env",      "sensitive": false    },    "type":"vars"  }}

Sample Request

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request PATCH \  --data @payload.json \    https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars/var-yRmifb4PJj7cLkMG

Sample Response

{  "data": {    "id":"var-yRmifb4PJj7cLkMG",    "type":"vars",    "attributes": {      "key":"name",      "value":"mars",      "description":"new description",      "sensitive":false,      "category":"env",      "hcl":false    }  }}

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

$ curl \  --header "Authorization: Bearer $TOKEN" \  --header "Content-Type: application/vnd.api+json" \  --request DELETE \    https://app.terraform.io/api/v2/organizations/my-organization/tests/registry-modules/private/my-organization/registry-name/registry-provider/vars/var-yRmifb4PJj7cLkMG

Tests API

Attributes

test run States

test run Status

test run Status

Create a Test Run

Request Body

Sample Payload

Sample Request

Sample Response

Create a Configuration Version for a test

Sample Request

Sample Response

Upload Configuration Files for a Test

Sample Request

List tests for a module

Query Parameters

Sample Request

Sample Response

Get Test Details

Sample Request

Sample Response

Cancel a Test

Sample Request

Forcefully cancel a Test

Sample Request

Create an Environment Variable for module tests

Request Body

Sample Payload

Sample Request

Sample Response

List Test Variables for a Module

Sample Request

Sample Response

Update Test Variables for a Module

Request Body

Sample Payload

Sample Request

Sample Response

Delete Test Variable for a Module

Sample Request