hashicorp · austinvalle · Jun 16, 2025 · Jun 16, 2025 · Jun 16, 2025 · Jun 16, 2025
@@ -1,6 +1,6 @@
 kind: BREAKING CHANGES
 body: 'generate: The `.ProviderShortName` template function now uses the rendered provider name to derive the provider short name. Users that pass in the 
-`--rendered-provider-name` flag might see a different output for this function'
+    `--rendered-provider-name` flag might see a different output for this function'
 time: 2025-06-13T13:51:04.745115-04:00
 custom:
     Issue: "492"
@@ -0,0 +1,6 @@
+kind: FEATURES
+body: 'generate: Added support for defining import example file (`import-by-identity.tf`) using Terraform configuration
+    and the `identity` attribute (managed resource identity)'
+time: 2025-06-25T17:37:10.853795-04:00
+custom:
+    Issue: "496"
@@ -223,16 +223,17 @@ For examples:
 > **NOTE:** In the following conventional paths for examples, `<data source name>` and `<resource name>` include the provider prefix as well, but the provider prefix is **NOT** included in`<function name>`.
 > For example, the data source [`caller_identity`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) in the `aws` provider would have an "example" conventional path of: `examples/data-sources/aws_caller_identity/data-source.tf`
 
-| Path                                                                      | Description                          |
-|---------------------------------------------------------------------------|--------------------------------------|
-| `examples/`                                                               | Root of examples                     |
-| `examples/provider/provider.tf`                                           | Provider example config              |
-| `examples/data-sources/<data source name>/data-source.tf`                 | Data source example config           |
-| `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource.tf` | Ephemeral resource example config    |
-| `examples/functions/<function name>/function.tf`                          | Function example config              |
-| `examples/resources/<resource name>/resource.tf`                          | Resource example config              |
-| `examples/resources/<resource name>/import.sh`                            | Resource example import command      |
-| `examples/resources/<resource name>/import-by-string-id.tf`               | Resource example import by id config |
+| Path                                                                      | Description                                |
+|---------------------------------------------------------------------------|--------------------------------------------|
+| `examples/`                                                               | Root of examples                           |
+| `examples/provider/provider.tf`                                           | Provider example config                    |
+| `examples/data-sources/<data source name>/data-source.tf`                 | Data source example config                 |
+| `examples/ephemeral-resources/<ephemeral resource>/ephemeral-resource.tf` | Ephemeral resource example config          |
+| `examples/functions/<function name>/function.tf`                          | Function example config                    |
+| `examples/resources/<resource name>/resource.tf`                          | Resource example config                    |
+| `examples/resources/<resource name>/import.sh`                            | Resource example import command            |
+| `examples/resources/<resource name>/import-by-string-id.tf`               | Resource example import by id config       |
+| `examples/resources/<resource name>/import-by-identity.tf`                | Resource example import by identity config |
 
 #### Migration
 
@@ -293,21 +294,24 @@ using the following data fields and functions:
 
 ##### Managed Resource / Ephemeral Resource / Data Source Fields
 
-| Field                   | Type   | Description                                                                               |
-|-------------------------|--------|-------------------------------------------------------------------------------------------|
-| `.Name`                 | string | Name of the resource/data-source (ex. `tls_certificate`)                                  |
-| `.Type`                 | string | Either `Resource` or `Data Source`                                                        |
-| `.Description`          | string | Resource / Data Source description                                                        |
-| `.HasExample`           | bool   | Is there an example file?                                                                 |
-| `.ExampleFile`          | string | Path to the file with the terraform configuration example                                 |
-| `.HasImport`            | bool   | Is there an import shell file? (`terraform import` shell example)                         |
-| `.ImportFile`           | string | Path to the file with the command for importing the resource                              |
-| `.HasImportIDConfig`    | bool   | Is there an import terraform config file? (`import` block example with `id`)              |
-| `.ImportIDConfigFile`   | string | Path to the file with the Terraform configuration for importing the resource by `id`      |
-| `.ProviderName`         | string | Canonical provider name (ex. `terraform-provider-random`)                                 |
-| `.ProviderShortName`    | string | Short version of the rendered provider name (ex. `random`)                                |
-| `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` |
-| `.SchemaMarkdown`       | string | a Markdown formatted Resource / Data Source Schema definition                             |
+| Field                       | Type   | Description                                                                                |
+|-----------------------------|--------|--------------------------------------------------------------------------------------------|
+| `.Name`                     | string | Name of the resource/data-source (ex. `tls_certificate`)                                   |
+| `.Type`                     | string | Either `Resource` or `Data Source`                                                         |
+| `.Description`              | string | Resource / Data Source description                                                         |
+| `.HasExample`               | bool   | Is there an example file?                                                                  |
+| `.ExampleFile`              | string | Path to the file with the terraform configuration example                                  |
+| `.HasImport`                | bool   | Is there an import shell file? (`terraform import` shell example)                          |
+| `.ImportFile`               | string | Path to the file with the command for importing the resource                               |
+| `.HasImportIDConfig`        | bool   | Is there an import terraform config file? (`import` block example with `id`)               |
+| `.ImportIDConfigFile`       | string | Path to the file with the Terraform configuration for importing the resource by `id`       |
+| `.HasImportIdentityConfig`  | bool   | Is there an import terraform config file? (`import` block example with `identity`)         |
+| `.ImportIdentityConfigFile` | string | Path to the file with the Terraform configuration for importing the resource by `identity` |
+| `.IdentitySchemaMarkdown`   | string | a Markdown formatted Resource Identity Schema definition                                   |
+| `.ProviderName`             | string | Canonical provider name (ex. `terraform-provider-random`)                                  |
+| `.ProviderShortName`        | string | Short version of the rendered provider name (ex. `random`)                                 |
+| `.RenderedProviderName`     | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName`  |
+| `.SchemaMarkdown`           | string | a Markdown formatted Resource / Data Source Schema definition                              |
 
 ##### Provider-defined Function Fields
 
@@ -360,16 +364,57 @@ This can be autogenerated by running `make generate` or running `go generate ./.
 ### Acceptance Tests
 
 This repo uses the `testscript` [package](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript) for acceptance testing.
-
 There are two types of acceptance tests: full provider build tests in `tfplugindocs/testdata/scripts/provider-build` and provider schema json tests in `tfplugindocs/testdata/scripts/schema-json`.
 
-Provider build tests run the default `tfplugindocs` command which builds the provider source code and runs Terraform to retrieve the schema. These tests require the full provider source code to build a valid provider binary.
-
-Schema json tests run the `tfplugindocs` command with the `--providers-schema=<arg>` flag to specify a provider schemas json file. This allows the test to skip the provider build and Terraform CLI call, instead using the specified file to generate docs.
+Provider [build tests](./cmd/tfplugindocs/testdata/scripts/provider-build/) run the default `tfplugindocs` command which builds the provider source code and runs Terraform to retrieve the schema. These tests require the full provider source code to build a valid provider binary.
+[Schema json](./cmd/tfplugindocs/testdata/scripts/schema-json/) tests run the `tfplugindocs` command with the `--providers-schema=<arg>` flag to specify a provider schemas json file. This allows the test to skip the provider build and Terraform CLI call, instead using the specified file to generate docs.
 
 You can run `make testacc` to run the full suite of acceptance tests. By default, the provider build acceptance tests will create a temporary directory in `/tmp/tftmp` for testing, but you can change this location in `cmd/tfplugindocs/main_test.go`. The schema json tests uses the `testscript` package's [default work directory](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript#Params.WorkdirRoot).
 
 The test scripts are defined in the `tfplugindocs/testdata/scripts` directory. Each script includes the test, golden files, and the provider source code or schema JSON file needed to run the test.
+Each script is a [text archive](https://pkg.go.dev/golang.org/x/tools/txtar). You can install the `txtar` CLI locally by running `go install golang.org/x/exp/cmd/txtar@latest` to extract the files in the test script for debugging or to help with updating.
+
+For example, to unarchive all of the files from a test script:
+```bash
+# Assuming that your working directory is the root of the terraform-plugin-docs repo
+
+# Create a fresh directory to extract to
+mkdir tmp && cd tmp
+
+# Extract this specific test script to the current working directory
+txtar -x <../cmd/tfplugindocs/testdata/scripts/provider-build/generate/framework_provider_success_no_templates.txtar
+```
+
+#### New test scripts
+
+Updates to existing tests are typically just made manually, but the `txtar` CLI can be used to create a new test quickly.
+
+A new text archive can be created from a folder with:
+```bash
+# Assuming that your working directory is the root of the terraform-plugin-docs repo
+
+# Create a fresh directory to make changes to
+mkdir tmp && cd tmp
+
+# Update files in ./tmp that you want in the new .txtar
+
+# Archives all of the files in the current directory with a placeholder comment
+echo "placeholder comment" | txtar . >../cmd/tfplugindocs/testdata/scripts/provider-build/generate/new.txtar
+```
 
-Each script is a [text archive](https://pkg.go.dev/golang.org/x/tools/txtar). You can install the `txtar` CLI locally by running `go install golang.org/x/exp/cmd/txtar@latest` to extract the files in the test script for debugging.
-You can also use `txtar` CLI archive files into the `.txtar` format to create new tests or modify existing ones.
+Once a new text archive is created, the comment header can be replaced with [test script commands](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript)
+like `env`, `cmp`, `exec`, etc. These commands control what actually is run during the test along with the assertions, for example:
+```bash
+# Copyright (c) HashiCorp, Inc.
+# SPDX-License-Identifier: MPL-2.0
+
+# Successful run of tfplugindocs on a Framework provider with examples but no templates or pre-existing docs.
+[!unix] skip
+env GOCACHE=$WORK/gocache  # sets an environment variable
+env GOMODCACHE=$WORK/gomodcache  # sets an environment variable
+exec tfplugindocs --provider-name=terraform-provider-scaffolding  # executes the Go binary for generating documentation
+cmp stdout expected-output.txt  # compares stdout from binary with the golden file in the text archive below
+cmp docs/index.md expected-index.md  # compares the generated docs with the golden file in the text archive below
+cmp docs/data-sources/example.md expected-datasource.md  # compares the generated docs with the golden file in the text archive below
+cmp docs/resources/example.md expected-resource.md  # compares the generated docs with the golden file in the text archive below
+```