package main import ( "bytes" "os" "path/filepath" "testing" "github.com/spf13/cobra" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) func seedRaw(t *testing.T, path, content string) { t.Helper() require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o750)) require.NoError(t, os.WriteFile(path, []byte(content), 0o644)) } func seedGenerated(t *testing.T, path string) { t.Helper() seedRaw(t, path, "---\ntitle: stale\n---\n\n\n\nStale content.\n") } // TestGenWebDocsPrunesAndDocuments exercises the full generate flow: available // commands are documented, deprecated and hidden commands are excluded, orphaned // generated pages are pruned (with their empty directories), and non-generated // content is preserved. func TestGenWebDocsPrunesAndDocuments(t *testing.T) { root := &cobra.Command{Use: "glab"} normal := &cobra.Command{Use: "normal", Short: "Normal command", Run: func(*cobra.Command, []string) {}} parent := &cobra.Command{Use: "parent", Short: "Parent command"} child := &cobra.Command{Use: "child", Short: "Child command", Run: func(*cobra.Command, []string) {}} deprecated := &cobra.Command{ Use: "deprecated", Short: "Deprecated command", Deprecated: "use 'glab parent child' instead.", Run: func(*cobra.Command, []string) {}, } secret := &cobra.Command{Use: "secret", Short: "Secret command", Hidden: true, Run: func(*cobra.Command, []string) {}} parent.AddCommand(child, deprecated, secret) root.AddCommand(normal, parent) dir := t.TempDir() // Pre-seed: an orphaned generated page, an orphaned page that is the only // file in its directory, a hand-maintained file, and an image. seedGenerated(t, filepath.Join(dir, "parent", "removed.md")) seedGenerated(t, filepath.Join(dir, "gone", "gone.md")) seedRaw(t, filepath.Join(dir, "keepme.md"), "Hand-maintained, no marker.\n") seedRaw(t, filepath.Join(dir, "img", "logo.png"), "PNG") readmePath := filepath.Join(dir, "README.md") seedRaw(t, readmePath, readmeCommandListStart+"\n- [`glab old`](docs/source/old): Old.\n"+readmeCommandListEnd+"\n") configPath := filepath.Join(dir, "configuration.md") seedRaw(t, configPath, "Hand-maintained.\n\n"+envVarTableStart+"\nstale table\n"+envVarTableEnd+"\n") require.NoError(t, genWebDocs(root, dir, readmePath)) configContent, err := os.ReadFile(configPath) require.NoError(t, err) assert.Contains(t, string(configContent), "Hand-maintained.") assert.NotContains(t, string(configContent), "stale table") assert.Contains(t, string(configContent), "| `GITLAB_TOKEN` |") assert.Contains(t, string(configContent), "### GitLab access variables") // Documented pages exist. assert.FileExists(t, filepath.Join(dir, "_index.md")) assert.FileExists(t, filepath.Join(dir, "commands.md")) assert.FileExists(t, filepath.Join(dir, "normal", "_index.md")) assert.FileExists(t, filepath.Join(dir, "parent", "_index.md")) assert.FileExists(t, filepath.Join(dir, "parent", "child.md")) // Deprecated command is not documented. assert.NoFileExists(t, filepath.Join(dir, "parent", "deprecated.md")) // Hidden command is not documented. assert.NoFileExists(t, filepath.Join(dir, "parent", "secret.md")) // Orphaned generated page is pruned; its emptied directory is removed. assert.NoFileExists(t, filepath.Join(dir, "parent", "removed.md")) assert.NoDirExists(t, filepath.Join(dir, "gone")) // Non-generated content is preserved. assert.FileExists(t, filepath.Join(dir, "keepme.md")) assert.FileExists(t, filepath.Join(dir, "img", "logo.png")) } func TestGenMarkdownCustomRendersHelpAnnotations(t *testing.T) { root := &cobra.Command{Use: "glab"} child := &cobra.Command{ Use: "child", Short: "Child command", Run: func(*cobra.Command, []string) {}, Annotations: map[string]string{ "help:arguments": "A child can be supplied by number.\n", "help:environment": "CHILD_VAR: a variable the child reads.\nOTHER_VAR: another one.\n", }, } plain := &cobra.Command{Use: "plain", Short: "Plain command", Run: func(*cobra.Command, []string) {}} root.AddCommand(child, plain) var page bytes.Buffer require.NoError(t, GenMarkdownCustom(child, &page)) assert.Contains(t, page.String(), "\n## Arguments\n\n```plaintext\nA child can be supplied by number.\n```\n") assert.Contains(t, page.String(), "\n## Environment variables\n\n```plaintext\nCHILD_VAR: a variable the child reads.\nOTHER_VAR: another one.\n```\n") page.Reset() require.NoError(t, GenMarkdownCustom(plain, &page)) assert.NotContains(t, page.String(), "## Arguments") assert.NotContains(t, page.String(), "## Environment variables") } // TestGenCommandsPage checks that the commands landing page lists the available // top-level commands, excludes hidden and deprecated ones, and carries the // generated marker so it is rewritten on every run. func TestGenCommandsPage(t *testing.T) { root := &cobra.Command{Use: "glab"} normal := &cobra.Command{Use: "normal", Short: "Normal command", Run: func(*cobra.Command, []string) {}} deprecated := &cobra.Command{Use: "deprecated", Short: "d", Deprecated: "use 'glab normal' instead.", Run: func(*cobra.Command, []string) {}} secret := &cobra.Command{Use: "secret", Short: "s", Hidden: true, Run: func(*cobra.Command, []string) {}} root.AddCommand(normal, deprecated, secret) dir := t.TempDir() require.NoError(t, genCommandsPage(root, dir)) page, err := os.ReadFile(filepath.Join(dir, "commands.md")) require.NoError(t, err) assert.Contains(t, string(page), generatedMarker) assert.Contains(t, string(page), "- [`glab normal`](normal/_index.md)\n") assert.NotContains(t, string(page), "glab deprecated") assert.NotContains(t, string(page), "glab secret") } // TestGenRootCommandDocsPointsAtCommandsPage checks that the root page links to // the commands landing page instead of repeating the list. func TestGenRootCommandDocsPointsAtCommandsPage(t *testing.T) { root := &cobra.Command{Use: "glab"} root.AddCommand(&cobra.Command{Use: "normal", Short: "Normal command", Run: func(*cobra.Command, []string) {}}) dir := t.TempDir() require.NoError(t, genRootCommandDocs(root, dir)) page, err := os.ReadFile(filepath.Join(dir, "_index.md")) require.NoError(t, err) assert.Contains(t, string(page), "For the list of top-level `glab` commands, see [Commands](commands.md).") assert.NotContains(t, string(page), "- [`glab normal`](normal/_index.md)") } func TestReadmeCommandList(t *testing.T) { root := &cobra.Command{Use: "glab"} root.AddCommand( &cobra.Command{Use: "alias", Short: "Create, list, and delete aliases.", Run: func(*cobra.Command, []string) {}}, &cobra.Command{Use: "mr", Short: "Create, view, and manage merge requests.", Run: func(*cobra.Command, []string) {}}, &cobra.Command{Use: "secret", Short: "Secret command.", Hidden: true, Run: func(*cobra.Command, []string) {}}, &cobra.Command{Use: "deprecated", Short: "Old command.", Deprecated: "use 'glab alias' instead.", Run: func(*cobra.Command, []string) {}}, ) got := readmeCommandList(root) assert.Equal(t, "- [`glab alias`](docs/source/alias): Create, list, and delete aliases.\n"+ "- [`glab mr`](docs/source/mr): Create, view, and manage merge requests.\n", got, ) assert.NotContains(t, got, "secret") assert.NotContains(t, got, "deprecated") } func TestUpdateReadme(t *testing.T) { input := "# GLab\n\nIntro.\n\n" + readmeCommandListStart + "\n" + "- [`glab old`](docs/source/old): Old description.\n" + readmeCommandListEnd + "\n\n" + "More prose.\n" root := &cobra.Command{Use: "glab"} root.AddCommand( &cobra.Command{Use: "alias", Short: "Create, list, and delete aliases.", Run: func(*cobra.Command, []string) {}}, ) got, err := updateReadme([]byte(input), root) require.NoError(t, err) want := "# GLab\n\nIntro.\n\n" + readmeCommandListStart + "\n" + "- [`glab alias`](docs/source/alias): Create, list, and delete aliases.\n" + readmeCommandListEnd + "\n\n" + "More prose.\n" assert.Equal(t, want, string(got)) } func TestUpdateReadmeMissingMarkers(t *testing.T) { root := &cobra.Command{Use: "glab"} _, err := updateReadme([]byte("# GLab\n\nNo markers here.\n"), root) require.Error(t, err) } func TestGenNavExcludesHiddenAndDeprecated(t *testing.T) { root := &cobra.Command{Use: "glab"} parent := &cobra.Command{Use: "parent", Short: "Parent command"} normal := &cobra.Command{Use: "normal", Short: "n", Run: func(*cobra.Command, []string) {}} deprecated := &cobra.Command{Use: "deprecated", Short: "d", Deprecated: "use x.", Run: func(*cobra.Command, []string) {}} secret := &cobra.Command{Use: "secret", Short: "s", Hidden: true, Run: func(*cobra.Command, []string) {}} parent.AddCommand(normal, deprecated, secret) root.AddCommand(parent) navPath := filepath.Join(t.TempDir(), "nav.yaml") require.NoError(t, genNav(root, navPath)) nav, err := os.ReadFile(navPath) require.NoError(t, err) assert.Contains(t, string(nav), "glab parent normal") assert.NotContains(t, string(nav), "glab parent deprecated") assert.NotContains(t, string(nav), "glab parent secret") }