[testing framework] Add documentation

website/data/cli-nav-data.json

@@ -243,6 +243,13 @@
       }
     ]
   },
+  {
+    "title": "Testing Terraform",
+    "routes": [
+      { "title": "Overview", "path": "test" },
+      { "title":  "<code>test<code>", "href": "/cli/commands/test"}
+    ]
+  },
   {
     "title": "Automating Terraform",
     "routes": [
@@ -320,10 +327,7 @@
         "href": "/cli/commands/state/show"
       },
       { "title": "<code>taint</code>", "href": "/cli/commands/taint" },
-      {
-        "title": "<code>test (deprecated)</code>",
-        "href": "/cli/commands/test"
-      },
+      { "title": "<code>test</code>", "href": "/cli/commands/test" },
       { "title": "<code>untaint</code>", "href": "/cli/commands/untaint" },
       { "title": "<code>validate</code>", "href": "/cli/commands/validate" },
       { "title": "<code>version</code>", "href": "/cli/commands/version" },
@@ -406,7 +410,7 @@
         ]
       },
       { "title": "taint", "path": "commands/taint" },
-      { "title": "test (deprecated)", "path": "commands/test", "hidden": true },
+      { "title": "test", "path": "commands/test" },
       { "title": "untaint", "path": "commands/untaint" },
       { "title": "validate", "path": "commands/validate" },
       { "title": "version", "path": "commands/version" },

website/data/language-nav-data.json

@@ -11,10 +11,8 @@
     "routes": [
       { "title": "Overview", "path": "files" },
       { "title": "Override Files", "path": "files/override" },
-      {
-        "title": "Dependency Lock File",
-        "path": "files/dependency-lock"
-      }
+      { "title": "Dependency Lock File", "path": "files/dependency-lock" },
+      { "title": "Test Files", "path": "files/tests" }
     ]
   },
   {
@@ -213,11 +211,6 @@
             "path": "modules/develop/refactoring"
           }
         ]
-      },
-      {
-        "title": "Module Testing Experiment",
-        "path": "modules/testing-experiment",
-        "hidden": true
       }
     ]
   },
@@ -1059,8 +1052,9 @@
       }
     ]
   },
+  { "title": "Tests", "path": "tests" },
   {
-    "title": "Upgrading to Terraform v1.5",
+    "title": "Upgrading to Terraform v1.6",
     "path": "upgrade-guides"
   },
   {

website/docs/cli/commands/test.mdx

@@ -1,13 +1,45 @@
 ---
 page_title: 'Command: test'
-description: Part of the ongoing design research for module integration testing.
+description: >-
+  The `terraform test` command loads and executes Terraform testing files.
 ---
 
 # Command: test
 
-The `terraform test` command is currently serving as part of
-[the module integration testing experiment](/terraform/language/modules/testing-experiment).
+The `terraform test` command reads in Terraform testing files and executes the tests detailed within.
 
-It's not ready for routine use, but if you'd be interested in trying the
-prototype functionality then we'd love to hear your feedback. See the
-experiment details page linked above for more information.
+The `test` command, and the test file syntax, are targeted at module authors wishing to validate and test their shared modules. It is also possible to use the `test` command to validate root modules.
+
+## Usage
+
+Usage: `terraform test [options]`
+
+This command searches the current directory and the specified testing directory (`tests`, by default) for any Terraform testing files, and executes the tests as specified. Test files and their syntax are discussed in detail within the [Tests](/terraform/language/tests) language page.
+
+Terraform will then execute a series of Terraform plan or apply commands, according to the specifications within the test files, and validate the relevant plan and state files, again, according to the specifications within the test files.
+
+> **Warning:** The Terraform test command can create real infrastructure than can cost you money. Read the [Terraform Test Cleanup](#terraform-test-cleanup) section for best practices on ensuring created infrastructure is destroyed.
+
+## General Options
+
+The following options apply to the Terraform `test` command:
+
+* `-filter=testfile` Limits the `terraform test` operation only to the specified test files.
+
+* `-json` Displays machine-readable JSON output for the testing results.
+
+* `-test-directory=<relative directory>` Override the directory that Terraform will look into for testing files. Note, Terraform always loads testing files within the main configuration directory. The default testing directory is `tests`.
+
+* `-verbose` Prints out the state for each `command=apply` `run` block after execution, or the plan for each `command=plan` `run` block.
+
+## State Management
+
+Each Terraform test file will maintain all Terraform state it requires within memory as it executes, starting empty. This state is entirely separate from any state that exists for the configuration under test, so you can safely execute Terraform test commands without affecting any live infrastructure.
+
+### Terraform Test Cleanup
+
+The Terraform `test` command creates real infrastructure. Once each test file has fully executed, Terraform will attempt to destroy any remaining infrastructure. If it cannot do this, Terraform will report a list of resources that were created and not destroyed.
+
+You should monitor the output of the test command closely to ensure any created infrastructure has been successfully removed and perform manual cleanup if not. Where possible, dedicated testing accounts should be created within the target providers that can be routinely and safely purged to ensure any accidental and costly resources aren't left behind.
+
+Terraform will also provide diagnostics explaining why the cleanup could not be completed automatically. You should resolve these diagnostics to ensure future clean up operations are successful.

website/docs/cli/test/index.mdx

@@ -0,0 +1,60 @@
+---
+page_title: Testing Terraform - Terraform CLI
+description: >-
+  Write structured tests and validations for your configuration to ensure
+  correctness in your infrastructure.
+---
+
+# Testing Terraform
+
+Terraform provides numerous testing capabilities to validate your infrastructure.
+
+The testing capabilities fit into two categories:
+
+1. Configuration and infrastructure validation as part of regular Terraform operations.
+2. More traditional unit and integration testing of your configuration.
+
+The first capability is discussed in detail within the [Custom Conditions](/terraform/language/expressions/custom-conditions) and [Checks](/terraform/language/checks) language documentation.
+
+The second capability is provided by the Terraform [`test`](/terraform/cli/commands/test) command.
+
+## A brief history
+
+- Terraform v0.13.0 introduced [Input Variable Validation](/terraform/language/expressions/custom-conditions#input-variable-validation).
+- Terraform v0.15.0 introduced an experimental Terraform [`test`](/terraform/language/v1.5.x/modules/testing-experiment) command.
+- Terraform v1.2.0 introduced [Pre- and Post-conditions](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions).
+- Terraform v1.5.0 introduced [Checks](/terraform/language/checks).
+- Terraform v1.6.0 deprecated the experimental Terraform `test` command and released the updated and finalized Terraform [`test`](/terraform/cli/commands/test) command.
+
+Note the introduction and deprecation of the experimental `test` command, followed by the introduction of the finalized `test` command. Read the [v1.6.x Upgrade Guide](/terraform/language/v1.6.x/upgrade-guides) for a summary of the changes between the experimental and finalized command.
+
+## The Terraform `test` command
+
+The Terraform `test` command:
+
+- Locates Terraform testing files within your configuration directory.
+- Provisions the infrastructure within your configuration as specified by each testing file.
+- Runs the assertions from the test file against the provisioned infrastructure.
+- Destroys the provisioned infrastructure at the end of the test.
+
+The `test` command, along with command-line flags and options, is discussed in detail within the [Command: test](/terraform/cli/commands/test) page.
+
+### Writing configuration for your tests
+
+Terraform test files have their own configuration syntax. This is discussed in detail within the language [Test Files](/terraform/language/tests) page.
+
+The test file syntax is focused on customizing Terraform executions for the current configuration, and overriding variables and providers to test different behaviours.
+
+## Validations
+
+Validations allow you to verify aspects of your configuration and infrastructure as it is applied and created. Terraform Cloud also supports automated [Continuous Validation](/terraform/cloud-docs/workspaces/health#continuous-validation).
+
+The Terraform `test` command will also execute all validations within your configuration as part of any tests it executes. For more information on the available validations read the [Checks](/terraform/language/checks) and [Custom Condition](/terraform/language/expressions/custom-conditions) language pages.
+
+## Tests or Validations
+
+You can write many validations as test assertions, but there are specific use cases for both.
+
+Validations are executed during usual Terraform plan and apply operations, and are also checked as part of any executed tests. Therefore, validations should be used to validate aspects of your configuration that should always be true and can impact the valid execution of your infrastructure. Module authors should also note that validations are executed and exposed to module users should they fail, and should be understandable to the user and actionable.
+
+In contrast, tests are only executed when requested and can be used to simulate specific behaviours within the configuration. Therefore, tests should be used to assert the correctness of any logical operations or behaviour within your configuration. For example, any conditional resources created based on an input can be verified as part of a test by setting the input that controls the conditional resource to true.