From 0f94e1e7ab75d0f5164d05aea23d6222f4f97c57 Mon Sep 17 00:00:00 2001
From: Liam Cervante <liam.cervante@hashicorp.com>
Date: Thu, 30 Nov 2023 16:53:57 +0100
Subject: [PATCH] docs: update terraform test docs with provider to run block
 reference examples (#34332)

* docs: update terraform test docs with examples on provider to run block references

* undo weird formatting
---
 website/docs/language/tests/index.mdx | 34 +++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/website/docs/language/tests/index.mdx b/website/docs/language/tests/index.mdx
index a5443ab0ca..7aea0c705d 100644
--- a/website/docs/language/tests/index.mdx
+++ b/website/docs/language/tests/index.mdx
@@ -412,6 +412,40 @@ run "customised_providers" {
 
 > **Note:** When running tests with `command = apply`, switching providers between `run` blocks can result in failed operations and tests because resources created by one provider definition will be unusable when modified by a second.
 
+From Terraform v1.7.0, `provider` blocks can also reference test file variables and run block outputs. This means the testing framework can retrieve credentials and other setup information from one provider and use this when initializing a second.
+
+In the following example, the `vault` provider is initialized first, and then used within a setup module to extract credentials for the `aws` provider. For more information on setup modules, see [Modules](#modules).
+
+```hcl
+
+provider "vault" {
+  # ... vault configuration ...
+}
+
+provider "aws" {
+  region     = "us-east-1"
+
+  # The `aws` provider can reference the outputs of the "vault_setup" run block.
+  access_key = run.vault_setup.aws_access_key
+  secret_key = run.vault_setup.aws_secret_key
+}
+
+run "vault_setup" {
+  module {
+    # This module should only include reference to the Vault provider. Terraform
+    # will automatically work out which providers to supply based on the module
+    # configuration. The tests will error if a run block requires access to a
+    # provider that references outputs from a run block that has not executed.
+    source = "./testing/vault-setup"
+  }
+}
+
+run "use_aws_provider" {
+  # This run block can then use both the `aws` and `vault` providers, as the
+  # previous run block provided all the data required for the `aws` provider.
+}
+```
+
 ## Modules
 
 You can modify the module that a given `run` block executes.