fix: build docs command for files with multiple tests (#1087)

Signed-off-by: Charles-Edouard Brétéché <[email protected]>

.release-notes/main.md

@@ -33,7 +33,8 @@ Release notes for `TODO`.
 - Fixed resource templating always enabled in `patch` operation, regardless of the configured `template` field
 - Added missing operations to the `build docs` command template
 - Added test-level catch statements to the `build docs` command template
-- Added binding name validation markers
+- Added binding `name` validation markers
+- Fixed `build docs` command for files with multiple tests
 
 ## ⭐ Examples ⭐
 

pkg/commands/build/docs/command.go

@@ -44,8 +44,12 @@ func Command() *cobra.Command {
 			if err != nil {
 				return err
 			}
+			testsSet := map[string][]discovery.Test{}
+			for _, test := range tests {
+				testsSet[test.BasePath] = append(testsSet[test.BasePath], test)
+			}
 			out := cmd.OutOrStdout()
-			if err := generateDocs(out, options.readmeFile, tests...); err != nil {
+			if err := generateDocs(out, options.readmeFile, testsSet); err != nil {
 				return err
 			}
 			if options.catalog != "" {
@@ -63,20 +67,30 @@ func Command() *cobra.Command {
 	return cmd
 }
 
-func generateDocs(out io.Writer, fileName string, tests ...discovery.Test) error {
-	for _, test := range tests {
-		if test.Err == nil {
-			file, err := os.Create(filepath.Join(test.BasePath, fileName))
+func generateDocs(out io.Writer, fileName string, tests map[string][]discovery.Test) error {
+	for path, tests := range tests {
+		err := func() error {
+			var validTests []discovery.Test
+			for _, test := range tests {
+				if test.Err != nil {
+					fmt.Fprintf(out, "ERROR: failed to load test %s (%s)", test.BasePath, test.Err)
+				} else {
+					validTests = append(validTests, test)
+				}
+			}
+			file, err := os.Create(filepath.Join(path, fileName))
 			if err != nil {
 				return err
 			}
 			defer file.Close()
 			output := file
-			if err := docsTmpl.Execute(output, test); err != nil {
+			if err := docsTmpl.Execute(output, validTests); err != nil {
 				return err
 			}
-		} else {
-			fmt.Fprintf(out, "ERROR: failed to load test %s (%s)", test.BasePath, test.Err)
+			return nil
+		}()
+		if err != nil {
+			return err
 		}
 	}
 	return nil

pkg/commands/build/docs/docs.tmpl

@@ -20,7 +20,7 @@ sleep
 {{- else if .Wait -}}
 wait
 {{- else -}}
-{{ fail (print "unknown operation " (toJson .)) }}
+{{- fail (print "unknown operation " (toJson .)) -}}
 {{- end -}}
 {{- end -}}
 
@@ -44,7 +44,7 @@ sleep
 {{- else if .Wait -}}
 wait
 {{- else -}}
-{{ fail (print "unknown catch " (toJson .)) }}
+{{- fail (print "unknown catch " (toJson .)) -}}
 {{- end -}}
 {{- end -}}
 
@@ -68,10 +68,13 @@ sleep
 {{- else if .Wait -}}
 wait
 {{- else -}}
-{{ fail (print "unknown finally " (toJson .)) }}
+{{- fail (print "unknown finally " (toJson .)) -}}
 {{- end -}}
 {{- end -}}
 
+{{- range . }}
+{{- $test := . -}}
+
 # Test: `{{ .Name }}`
 
 {{ default "*No description*" .Spec.Description }}
@@ -84,7 +87,7 @@ wait
 |:-:|---|:-:|:-:|:-:|
 {{- range $i, $step := . }}
 {{- $name := default (print "step-" (add $i 1)) $step.Name }}
-| {{ add $i 1 }} | [{{ $name }}](#step-{{ $name }}) | {{ len $step.Try }} | {{ add (len $step.Catch) (len $.Spec.Catch) }} | {{ len $step.Finally }} |
+| {{ add $i 1 }} | [{{ $name }}](#step-{{ $name }}) | {{ len $step.Try }} | {{ add (len $step.Catch) (len $test.Spec.Catch) }} | {{ len $step.Finally }} |
 {{- end }}
 {{- end }}
 
@@ -112,11 +115,11 @@ wait
 
 | # | Operation | Description |
 |:-:|---|---|
-{{- range $i, $op := $.Spec.Catch }}
+{{- range $i, $op := $test.Spec.Catch }}
 | {{ add $i 1 }} | `{{ template "CatchType" $op }}` | {{ default "*No description*" $op.Description }} |
 {{- end }}
 {{- range $i, $op := . }}
-| {{ add (len $.Spec.Catch) $i 1 }} | `{{ template "CatchType" $op }}` | {{ default "*No description*" $op.Description }} |
+| {{ add (len $test.Spec.Catch) $i 1 }} | `{{ template "CatchType" $op }}` | {{ default "*No description*" $op.Description }} |
 {{- end }}
 {{- end }}
 
@@ -132,3 +135,7 @@ wait
 {{- end }}
 
 {{- end }}
+
+---
+
+{{ end -}}

testdata/e2e/examples/apply-outputs/README.md

@@ -4,6 +4,30 @@
 
 ### Steps
 
+| # | Name | Try | Catch | Finally |
+|:-:|---|:-:|:-:|:-:|
+| 1 | [step-1](#step-step-1) | 3 | 0 | 0 |
+
+## Step: `step-1`
+
+*No description*
+
+### Try
+
+| # | Operation | Description |
+|:-:|---|---|
+| 1 | `apply` | *No description* |
+| 2 | `script` | *No description* |
+| 3 | `assert` | *No description* |
+
+---
+
+# Test: `apply-outputs`
+
+*No description*
+
+### Steps
+
 | # | Name | Try | Catch | Finally |
 |:-:|---|:-:|:-:|:-:|
 | 1 | [step-1](#step-step-1) | 6 | 0 | 0 |
@@ -22,3 +46,6 @@
 | 4 | `script` | *No description* |
 | 5 | `assert` | *No description* |
 | 6 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/array-assertion/README.md

@@ -18,3 +18,6 @@
 |:-:|---|---|
 | 1 | `apply` | *No description* |
 | 2 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/assertion-tree/README.md

@@ -17,3 +17,6 @@
 | # | Operation | Description |
 |:-:|---|---|
 | 1 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/basic/README.md

@@ -19,3 +19,6 @@ This steps applies the configmap in the cluster and checks the configmap content
 | 1 | `apply` | Create the configmap. |
 | 2 | `assert` | Check the configmap content. |
 | 3 | `script` | *No description* |
+
+---
+

testdata/e2e/examples/bindings/README.md

@@ -28,3 +28,6 @@
 | # | Operation | Description |
 |:-:|---|---|
 | 1 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/catch/README.md

@@ -25,3 +25,6 @@
 |:-:|---|---|
 | 1 | `events` | *No description* |
 | 2 | `describe` | *No description* |
+
+---
+

testdata/e2e/examples/command-output/README.md

@@ -17,3 +17,6 @@
 | # | Operation | Description |
 |:-:|---|---|
 | 1 | `script` | *No description* |
+
+---
+

testdata/e2e/examples/delete/README.md

@@ -18,3 +18,6 @@
 |:-:|---|---|
 | 1 | `apply` | *No description* |
 | 2 | `delete` | *No description* |
+
+---
+

testdata/e2e/examples/deployment/README.md

@@ -18,3 +18,6 @@
 |:-:|---|---|
 | 1 | `apply` | *No description* |
 | 2 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/finally/README.md

@@ -25,3 +25,6 @@
 |:-:|---|---|
 | 1 | `events` | *No description* |
 | 2 | `script` | *No description* |
+
+---
+

testdata/e2e/examples/inline/README.md

@@ -18,3 +18,6 @@
 |:-:|---|---|
 | 1 | `apply` | *No description* |
 | 2 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/k8s-server-version/README.md

@@ -17,3 +17,6 @@
 | # | Operation | Description |
 |:-:|---|---|
 | 1 | `script` | *No description* |
+
+---
+

testdata/e2e/examples/list/README.md

@@ -19,3 +19,6 @@
 | 1 | `apply` | *No description* |
 | 2 | `assert` | *No description* |
 | 3 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/namespace-template/README.md

@@ -17,3 +17,6 @@
 | # | Operation | Description |
 |:-:|---|---|
 | 1 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/non-resource-assertion/README.md

@@ -30,3 +30,6 @@
 |:-:|---|---|
 | 1 | `assert` | *No description* |
 | 2 | `error` | *No description* |
+
+---
+

testdata/e2e/examples/outputs/README.md

@@ -41,3 +41,6 @@
 |:-:|---|---|
 | 1 | `command` | *No description* |
 | 2 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/patch/README.md

@@ -19,3 +19,6 @@
 | 1 | `apply` | *No description* |
 | 2 | `patch` | *No description* |
 | 3 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/script-env/README.md

@@ -18,3 +18,6 @@
 |:-:|---|---|
 | 1 | `script` | *No description* |
 | 2 | `command` | *No description* |
+
+---
+

testdata/e2e/examples/sleep/README.md

@@ -29,3 +29,6 @@
 | # | Operation | Description |
 |:-:|---|---|
 | 1 | `sleep` | *No description* |
+
+---
+

testdata/e2e/examples/template/README.md

@@ -19,3 +19,6 @@
 | 1 | `apply` | *No description* |
 | 2 | `assert` | *No description* |
 | 3 | `delete` | *No description* |
+
+---
+

testdata/e2e/examples/timeout/README.md

@@ -17,3 +17,6 @@
 | # | Operation | Description |
 |:-:|---|---|
 | 1 | `script` | *No description* |
+
+---
+

testdata/e2e/examples/values/README.md

@@ -17,3 +17,6 @@
 | # | Operation | Description |
 |:-:|---|---|
 | 1 | `assert` | *No description* |
+
+---
+

testdata/e2e/examples/wait/README.md

@@ -36,3 +36,6 @@
 |:-:|---|---|
 | 1 | `delete` | *No description* |
 | 2 | `wait` | *No description* |
+
+---
+