Add acceptance tests and ignore no such file or directory errors in cleaning rendered website dir (#296)

* Add acceptance tests for `generate` command

* Ignore file does not exist error when cleaning up rendered website dir.

* Add more template rendering unit tests

* Run `go mod tidy`

* Run tests from makefile

* Add changelog entry

* Add copyright headers

* Add flag to skip tests for non-unix systems

* Add unit test target

* Add Acceptance Testing section to Readme

* Move `build` package and update goreleaser `idflags`

* Add `.SchemaMarkdown` field and `printf` functions to Readme

* Add copyright headers

Author: SBGoods

.changes/unreleased/BUG FIXES-20231108-172558.yaml

@@ -0,0 +1,6 @@
+kind: BUG FIXES
+body: 'generate: fix `no such file or directory` error when running `generate` with
+  no existing rendered website directory.'
+time: 2023-11-08T17:25:58.561956-05:00
+custom:
+  Issue: "296"

.copywrite.hcl

@@ -9,6 +9,9 @@ project {
     ".changes/unreleased/*.yaml",
     ".changie.yaml",
 
+    # examples used within documentation (prose)
+    "internal/provider/testdata/**",
+
     # GitHub issue template configuration
     ".github/ISSUE_TEMPLATE/*.yml",
 

.github/workflows/test.yml

@@ -33,5 +33,5 @@ jobs:
           args: --timeout=3m
       - name: go vet
         run: go vet ./...
-      - name: Run tests
-        run: go test -v -cover -race ./...
+      - name: Run acceptance tests
+        run: make testacc

.goreleaser.yml

@@ -7,7 +7,7 @@ builds:
   flags:
   - -trimpath
   ldflags:
-  - '-s -w -X main.version={{.Version}} -X main.commit={{.Commit}}'
+  - '-s -w -X github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs/build.version={{.Version}} -X github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs/build.commit={{.Commit}}'
   goos:
   - windows
   - linux

GNUmakefile

@@ -2,14 +2,17 @@ TEST?=./...
 
 default: build
 
-.PHONY: build test
+.PHONY: build test testacc
 
 build:
 	go install ./cmd/tfplugindocs
 
 test:
 	go test $(TEST) $(TESTARGS) -timeout=5m
 
+testacc:
+	ACCTEST=1 go test -v -cover -race -timeout 120m ./...
+
 # Generate copywrite headers
 generate:
 	cd tools; go generate ./...

README.md

@@ -146,6 +146,7 @@ using the following data fields and functions:
 |         `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`)                                 |
 |    `.ProviderShortName` | string | Short version of the provider name (ex. `random`)                                         |
 | `.RenderedProviderName` | string | Value provided via argument `--rendered-provider-name`, otherwise same as `.ProviderName` |
+|       `.SchemaMarkdown` | string | a Markdown formatted Provider Schema definition                                           |
 
 ##### Resources / Data Source
 
@@ -161,6 +162,7 @@ using the following data fields and functions:
 |         `.ProviderName` | string | Canonical provider name (ex. `terraform-provider-random`)                                 |
 |    `.ProviderShortName` | string | Short version of the 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                             |
 
 #### Functions
 
@@ -170,6 +172,7 @@ using the following data fields and functions:
 | `lower`         | Equivalent to [`strings.ToLower`](https://pkg.go.dev/strings#ToLower).                            |
 | `plainmarkdown` | Render Markdown content as plaintext.                                                             |
 | `prefixlines`   | Add a prefix to all (newline-separated) lines in a string.                                        |
+| `printf`        | Equivalent to [`fmt.Printf`](https://pkg.go.dev/fmt#Printf).                                      |
 | `split`         | Split string into sub-strings, by a given separator (ex. `split .Name "_"`).                      |
 | `title`         | Equivalent to [`cases.Title`](https://pkg.go.dev/golang.org/x/text/cases#Title).                  |
 | `tffile`        | A special case of the `codefile` function, designed for Terraform files (i.e. `.tf`).             |
@@ -190,3 +193,14 @@ Your help and patience is truly appreciated.
 All source code files in this repository (excluding autogenerated files like `go.mod`, prose, and files excluded in [.copywrite.hcl](.copywrite.hcl)) must have a license header at the top.
 
 This can be autogenerated by running `make generate` or running `go generate ./...` in the [/tools](/tools) directory.
+
+### Acceptance Tests
+
+This repo uses the `testscript` [package](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript) for acceptance testing.
+
+You can run `make testacc` to run the acceptance tests. By default, the 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 test scripts are defined in the `tfplugindocs/testdata/scripts` directory. Each script includes the test, golden files, and the provider source code 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. 
+You can also use `txtar` CLI archive files into the `.txtar` format to create new tests or modify existing ones.

cmd/tfplugindocs/build/version.go

@@ -0,0 +1,18 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package build
+
+var (
+	// These vars will be set by goreleaser.
+	version string = `dev`
+	commit  string = ``
+)
+
+func GetVersion() string {
+	version := "tfplugindocs" + " Version " + version
+	if commit != "" {
+		version += " from commit " + commit
+	}
+	return version
+}

cmd/tfplugindocs/main.go

@@ -6,24 +6,9 @@ package main
 import (
 	"os"
 
-	"github.com/mattn/go-colorable"
-
 	"github.com/hashicorp/terraform-plugin-docs/internal/cmd"
 )
 
 func main() {
-	name := "tfplugindocs"
-	version := name + " Version " + version
-	if commit != "" {
-		version += " from commit " + commit
-	}
-
-	os.Exit(cmd.Run(
-		name,
-		version,
-		os.Args[1:],
-		os.Stdin,
-		colorable.NewColorableStdout(),
-		colorable.NewColorableStderr(),
-	))
+	os.Exit(cmd.Main())
 }

cmd/tfplugindocs/main_test.go

@@ -0,0 +1,40 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package main
+
+import (
+	"os"
+	"testing"
+
+	"github.com/rogpeppe/go-internal/testscript"
+
+	"github.com/hashicorp/terraform-plugin-docs/internal/cmd"
+)
+
+func TestMain(m *testing.M) {
+	os.Exit(testscript.RunMain(m, map[string]func() int{
+		"tfplugindocs": cmd.Main,
+	}))
+}
+
+func Test_GenerateAcceptanceTests(t *testing.T) {
+	t.Parallel()
+	if os.Getenv("ACCTEST") == "" {
+		t.Skip("ACCTEST env var not set; skipping acceptance tests.")
+	}
+	// Setting a custom temp dir instead of relying on os.TempDir()
+	// because Terraform providers fail to start up when $TMPDIR
+	// length is too long: https://github.com/hashicorp/terraform/issues/32787
+	tmpDir := "/tmp/tftmp"
+	err := os.MkdirAll(tmpDir, 0755)
+	if err != nil {
+		t.Errorf("Error creating temp dir for testing: %s", err.Error())
+	}
+	defer os.RemoveAll(tmpDir)
+
+	testscript.Run(t, testscript.Params{
+		Dir:         "testdata/scripts/generate",
+		WorkdirRoot: tmpDir,
+	})
+}