test(docgen): Structure the generation tests as given/when/then

Each assertion now says in one line what would break without it, and the file
uses testify rather than four hand-rolled assertion helpers.

One assertion was decorative: it looked for the page's own flat filename, which
never appears on it — only a link to its parent does. It now looks for the
prefix cobra uses, and fails when links are left unrewritten.

Author: khvn26

cmd/docgen/main_test.go

@@ -7,61 +7,76 @@ import (
 	"testing"
 
 	"github.com/spf13/cobra"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 
 	"github.com/Flagsmith/flagsmith-cli/v2/internal/cmd"
 )
 
-// Links between pages are recovered from the underscore-joined filenames cobra
-// writes, so a command name containing one would produce a broken link.
 func TestCommandNamesAreURLSafe(t *testing.T) {
-	var check func(*cobra.Command)
-	check = func(c *cobra.Command) {
-		if strings.ContainsAny(c.Name(), "_ ") {
-			t.Errorf("command %q: name must not contain an underscore or space", c.CommandPath())
-		}
+	// Given
+	root := cmd.Root()
+
+	// When / Then
+	var visit func(*cobra.Command)
+	visit = func(c *cobra.Command) {
+		assert.NotContains(t, c.Name(), "_", "an underscore breaks the links between pages")
+		assert.NotContains(t, c.Name(), " ", "a space breaks the page's path")
+		assert.NotContains(t, c.Name(), "/", "a slash breaks the page's path")
+
 		for _, sub := range c.Commands() {
-			check(sub)
+			visit(sub)
 		}
 	}
-	check(cmd.Root())
+	visit(root)
 }
 
 func TestWriteMirrorsCommandTree(t *testing.T) {
+	// Given
 	dir := t.TempDir()
-	if err := write(cmd.Root(), dir); err != nil {
-		t.Fatal(err)
-	}
 
-	for _, want := range []string{"_index.md", "flag/_index.md", "flag/update.md"} {
-		if _, err := os.Stat(filepath.Join(dir, want)); err != nil {
-			t.Errorf("%s: %v", want, err)
-		}
-	}
-	// A hidden command must not be published.
-	if _, err := os.Stat(filepath.Join(dir, "flag/create.md")); err == nil {
-		t.Error("flag/create.md: hidden command should not have a page")
-	}
+	// When
+	require.NoError(t, write(cmd.Root(), dir))
+
+	// Then
+	// the root command's own page is the site's home page
+	assert.FileExists(t, filepath.Join(dir, "_index.md"))
+	// a command with subcommands has a directory
+	assert.FileExists(t, filepath.Join(dir, "flag/_index.md"))
+	// a leaf command is a page inside its parent's directory
+	assert.FileExists(t, filepath.Join(dir, "flag/update.md"))
+	// a hidden command is not published
+	assert.NoFileExists(t, filepath.Join(dir, "flag/create.md"))
+}
 
+func TestWritePage(t *testing.T) {
+	// Given
+	dir := t.TempDir()
+	require.NoError(t, write(cmd.Root(), dir))
+
+	// When
 	page, err := os.ReadFile(filepath.Join(dir, "flag/update.md"))
-	if err != nil {
-		t.Fatal(err)
-	}
+	require.NoError(t, err)
 	got := string(page)
-	for _, want := range []string{
-		`title: "flagsmith flag update"`, // Hextra renders the page heading from it
-		"](../)",                         // link to the parent page, not a flat filename
-	} {
-		if !strings.Contains(got, want) {
-			t.Errorf("page is missing %q:\n%s", want, got)
-		}
-	}
-	for _, unwanted := range []string{
-		"Auto generated",           // non-reproducible build
-		"## flagsmith flag update", // duplicates the front matter title
-		"flagsmith_flag_update.md", // cobra's flat filenames
-	} {
-		if strings.Contains(got, unwanted) {
-			t.Errorf("page should not contain %q:\n%s", unwanted, got)
-		}
-	}
+
+	// Then
+	// the front matter titles the page with the full command path
+	assert.Contains(t, got, `title: "flagsmith flag update"`)
+	// the sidebar entry is the command's own name, unambiguous once nested.
+	assert.Contains(t, got, `linkTitle: "update"`)
+	// the description is the command's Short
+	assert.Contains(t, got, `description: "Change a flag's state in the current environment"`)
+	// the body is cobra's, taken from the command
+	assert.Contains(t, got, "flagsmith flag update <feature> [flags]")
+	// the link to the parent page is relative,
+	assert.Contains(t, got, "](../)")
+	// no link is left as cobra's flat filename
+	assert.NotContains(t, got, "flagsmith_")
+	// cobra's own heading is gone
+	assert.NotContains(t, got, "## flagsmith flag update")
+	// no generation date is stamped into the page
+	assert.NotContains(t, got, "Auto generated")
+
+	// Guard against the assertions above passing on an empty file.
+	require.NotEmpty(t, strings.TrimSpace(got))
 }

go.mod

@@ -11,6 +11,7 @@ require (
 	github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/pflag v1.0.9
+	github.com/stretchr/testify v1.11.1
 	github.com/zalando/go-keyring v0.2.8
 	golang.org/x/sync v0.21.0
 	golang.org/x/term v0.45.0
@@ -32,6 +33,7 @@ require (
 	github.com/clipperhouse/uax29/v2 v2.3.0 // indirect
 	github.com/cpuguy83/go-md2man/v2 v2.0.6 // indirect
 	github.com/danieljoos/wincred v1.2.3 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/go-resty/resty/v2 v2.17.2 // indirect
@@ -49,11 +51,13 @@ require (
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/ohler55/ojg v1.28.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	golang.org/x/net v0.56.0 // indirect
 	golang.org/x/sys v0.47.0 // indirect
 	golang.org/x/text v0.39.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
 )