GitLabgitlab-org
cli
main
1package main
3import (
4 "bytes"
5 "os"
6 "path/filepath"
7 "testing"
9 "github.com/spf13/cobra"
10 "github.com/stretchr/testify/assert"
11 "github.com/stretchr/testify/require"
12)
14func seedRaw(t *testing.T, path, content string) {
15 t.Helper()
16 require.NoError(t, os.MkdirAll(filepath.Dir(path), 0o750))
17 require.NoError(t, os.WriteFile(path, []byte(content), 0o644))
18}
20func seedGenerated(t *testing.T, path string) {
21 t.Helper()
22 seedRaw(t, path, "---\ntitle: stale\n---\n\n<!--\n"+generatedMarker+"\n-->\n\nStale content.\n")
23}
25// TestGenWebDocsPrunesAndDocuments exercises the full generate flow: available
26// commands are documented, deprecated and hidden commands are excluded, orphaned
27// generated pages are pruned (with their empty directories), and non-generated
28// content is preserved.
29func TestGenWebDocsPrunesAndDocuments(t *testing.T) {
30 root := &cobra.Command{Use: "glab"}
31 normal := &cobra.Command{Use: "normal", Short: "Normal command", Run: func(*cobra.Command, []string) {}}
32 parent := &cobra.Command{Use: "parent", Short: "Parent command"}
33 child := &cobra.Command{Use: "child", Short: "Child command", Run: func(*cobra.Command, []string) {}}
34 deprecated := &cobra.Command{
35 Use: "deprecated",
36 Short: "Deprecated command",
37 Deprecated: "use 'glab parent child' instead.",
38 Run: func(*cobra.Command, []string) {},
39 }
40 secret := &cobra.Command{Use: "secret", Short: "Secret command", Hidden: true, Run: func(*cobra.Command, []string) {}}
41 parent.AddCommand(child, deprecated, secret)
42 root.AddCommand(normal, parent)
44 dir := t.TempDir()
45 // Pre-seed: an orphaned generated page, an orphaned page that is the only
46 // file in its directory, a hand-maintained file, and an image.
47 seedGenerated(t, filepath.Join(dir, "parent", "removed.md"))
48 seedGenerated(t, filepath.Join(dir, "gone", "gone.md"))
49 seedRaw(t, filepath.Join(dir, "keepme.md"), "Hand-maintained, no marker.\n")
50 seedRaw(t, filepath.Join(dir, "img", "logo.png"), "PNG")
52 readmePath := filepath.Join(dir, "README.md")
53 seedRaw(t, readmePath,
54 readmeCommandListStart+"\n- [`glab old`](docs/source/old): Old.\n"+readmeCommandListEnd+"\n")
56 configPath := filepath.Join(dir, "configuration.md")
57 seedRaw(t, configPath,
58 "Hand-maintained.\n\n"+envVarTableStart+"\nstale table\n"+envVarTableEnd+"\n")
60 require.NoError(t, genWebDocs(root, dir, readmePath))
62 configContent, err := os.ReadFile(configPath)
63 require.NoError(t, err)
64 assert.Contains(t, string(configContent), "Hand-maintained.")
65 assert.NotContains(t, string(configContent), "stale table")
66 assert.Contains(t, string(configContent), "| `GITLAB_TOKEN` |")
67 assert.Contains(t, string(configContent), "### GitLab access variables")
69 // Documented pages exist.
70 assert.FileExists(t, filepath.Join(dir, "_index.md"))
71 assert.FileExists(t, filepath.Join(dir, "commands.md"))
72 assert.FileExists(t, filepath.Join(dir, "normal", "_index.md"))
73 assert.FileExists(t, filepath.Join(dir, "parent", "_index.md"))
74 assert.FileExists(t, filepath.Join(dir, "parent", "child.md"))
76 // Deprecated command is not documented.
77 assert.NoFileExists(t, filepath.Join(dir, "parent", "deprecated.md"))
79 // Hidden command is not documented.
80 assert.NoFileExists(t, filepath.Join(dir, "parent", "secret.md"))
82 // Orphaned generated page is pruned; its emptied directory is removed.
83 assert.NoFileExists(t, filepath.Join(dir, "parent", "removed.md"))
84 assert.NoDirExists(t, filepath.Join(dir, "gone"))
86 // Non-generated content is preserved.
87 assert.FileExists(t, filepath.Join(dir, "keepme.md"))
88 assert.FileExists(t, filepath.Join(dir, "img", "logo.png"))
89}
91func TestGenMarkdownCustomRendersHelpAnnotations(t *testing.T) {
92 root := &cobra.Command{Use: "glab"}
93 child := &cobra.Command{
94 Use: "child",
95 Short: "Child command",
96 Run: func(*cobra.Command, []string) {},
97 Annotations: map[string]string{
98 "help:arguments": "A child can be supplied by number.\n",
99 "help:environment": "CHILD_VAR: a variable the child reads.\nOTHER_VAR: another one.\n",
100 },
101 }
102 plain := &cobra.Command{Use: "plain", Short: "Plain command", Run: func(*cobra.Command, []string) {}}
103 root.AddCommand(child, plain)
105 var page bytes.Buffer
106 require.NoError(t, GenMarkdownCustom(child, &page))
107 assert.Contains(t, page.String(), "\n## Arguments\n\n```plaintext\nA child can be supplied by number.\n```\n")
108 assert.Contains(t, page.String(), "\n## Environment variables\n\n```plaintext\nCHILD_VAR: a variable the child reads.\nOTHER_VAR: another one.\n```\n")
110 page.Reset()
111 require.NoError(t, GenMarkdownCustom(plain, &page))
112 assert.NotContains(t, page.String(), "## Arguments")
113 assert.NotContains(t, page.String(), "## Environment variables")
114}
116// TestGenCommandsPage checks that the commands landing page lists the available
117// top-level commands, excludes hidden and deprecated ones, and carries the
118// generated marker so it is rewritten on every run.
119func TestGenCommandsPage(t *testing.T) {
120 root := &cobra.Command{Use: "glab"}
121 normal := &cobra.Command{Use: "normal", Short: "Normal command", Run: func(*cobra.Command, []string) {}}
122 deprecated := &cobra.Command{Use: "deprecated", Short: "d", Deprecated: "use 'glab normal' instead.", Run: func(*cobra.Command, []string) {}}
123 secret := &cobra.Command{Use: "secret", Short: "s", Hidden: true, Run: func(*cobra.Command, []string) {}}
124 root.AddCommand(normal, deprecated, secret)
126 dir := t.TempDir()
127 require.NoError(t, genCommandsPage(root, dir))
129 page, err := os.ReadFile(filepath.Join(dir, "commands.md"))
130 require.NoError(t, err)
131 assert.Contains(t, string(page), generatedMarker)
132 assert.Contains(t, string(page), "- [`glab normal`](normal/_index.md)\n")
133 assert.NotContains(t, string(page), "glab deprecated")
134 assert.NotContains(t, string(page), "glab secret")
135}
137// TestGenRootCommandDocsPointsAtCommandsPage checks that the root page links to
138// the commands landing page instead of repeating the list.
139func TestGenRootCommandDocsPointsAtCommandsPage(t *testing.T) {
140 root := &cobra.Command{Use: "glab"}
141 root.AddCommand(&cobra.Command{Use: "normal", Short: "Normal command", Run: func(*cobra.Command, []string) {}})
143 dir := t.TempDir()
144 require.NoError(t, genRootCommandDocs(root, dir))
146 page, err := os.ReadFile(filepath.Join(dir, "_index.md"))
147 require.NoError(t, err)
148 assert.Contains(t, string(page), "For the list of top-level `glab` commands, see [Commands](commands.md).")
149 assert.NotContains(t, string(page), "- [`glab normal`](normal/_index.md)")
150}
152func TestReadmeCommandList(t *testing.T) {
153 root := &cobra.Command{Use: "glab"}
154 root.AddCommand(
155 &cobra.Command{Use: "alias", Short: "Create, list, and delete aliases.", Run: func(*cobra.Command, []string) {}},
156 &cobra.Command{Use: "mr", Short: "Create, view, and manage merge requests.", Run: func(*cobra.Command, []string) {}},
157 &cobra.Command{Use: "secret", Short: "Secret command.", Hidden: true, Run: func(*cobra.Command, []string) {}},
158 &cobra.Command{Use: "deprecated", Short: "Old command.", Deprecated: "use 'glab alias' instead.", Run: func(*cobra.Command, []string) {}},
159 )
161 got := readmeCommandList(root)
163 assert.Equal(t,
164 "- [`glab alias`](docs/source/alias): Create, list, and delete aliases.\n"+
165 "- [`glab mr`](docs/source/mr): Create, view, and manage merge requests.\n",
166 got,
167 )
168 assert.NotContains(t, got, "secret")
169 assert.NotContains(t, got, "deprecated")
170}
172func TestUpdateReadme(t *testing.T) {
173 input := "# GLab\n\nIntro.\n\n" +
174 readmeCommandListStart + "\n" +
175 "- [`glab old`](docs/source/old): Old description.\n" +
176 readmeCommandListEnd + "\n\n" +
177 "More prose.\n"
179 root := &cobra.Command{Use: "glab"}
180 root.AddCommand(
181 &cobra.Command{Use: "alias", Short: "Create, list, and delete aliases.", Run: func(*cobra.Command, []string) {}},
182 )
184 got, err := updateReadme([]byte(input), root)
185 require.NoError(t, err)
187 want := "# GLab\n\nIntro.\n\n" +
188 readmeCommandListStart + "\n" +
189 "- [`glab alias`](docs/source/alias): Create, list, and delete aliases.\n" +
190 readmeCommandListEnd + "\n\n" +
191 "More prose.\n"
193 assert.Equal(t, want, string(got))
194}
196func TestUpdateReadmeMissingMarkers(t *testing.T) {
197 root := &cobra.Command{Use: "glab"}
198 _, err := updateReadme([]byte("# GLab\n\nNo markers here.\n"), root)
199 require.Error(t, err)
200}
202func TestGenNavExcludesHiddenAndDeprecated(t *testing.T) {
203 root := &cobra.Command{Use: "glab"}
204 parent := &cobra.Command{Use: "parent", Short: "Parent command"}
205 normal := &cobra.Command{Use: "normal", Short: "n", Run: func(*cobra.Command, []string) {}}
206 deprecated := &cobra.Command{Use: "deprecated", Short: "d", Deprecated: "use x.", Run: func(*cobra.Command, []string) {}}
207 secret := &cobra.Command{Use: "secret", Short: "s", Hidden: true, Run: func(*cobra.Command, []string) {}}
208 parent.AddCommand(normal, deprecated, secret)
209 root.AddCommand(parent)
211 navPath := filepath.Join(t.TempDir(), "nav.yaml")
212 require.NoError(t, genNav(root, navPath))
214 nav, err := os.ReadFile(navPath)
215 require.NoError(t, err)
216 assert.Contains(t, string(nav), "glab parent normal")
217 assert.NotContains(t, string(nav), "glab parent deprecated")
218 assert.NotContains(t, string(nav), "glab parent secret")
219}
Diagnostics6 git calls · 212 ms
CallStatusSizeTime0212 ms
discover200185 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=185 git.server.agent=git/2.56.g1891de4-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=185 git.pkt.payload.max=35
ls-refs20058 KiB · hit2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=59849 git.response.cache=HIT git.response.duration_ms=2 git.protocol.version=2 git.pkt.frames=731 git.pkt.data=730 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=59849 git.pkt.payload.max=143 git.ls_refs.count=730 git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=4273 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=combine:blob:none+tree:2 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=1 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4273 git.pkt.payload.max=4173 git.sideband.band1.bytes=4173 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=11 git.pack.bytes=4173 git.fetch.wide.objects=11 git.fetch.wide.extra_bytes=3930 git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit4 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=32926 git.response.cache=HIT git.response.duration_ms=4 git.fetch.filter=tree:0 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=22 git.pkt.data=20 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=32926 git.pkt.payload.max=32046 git.sideband.band1.bytes=32046 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=80 git.pack.bytes=32046 git.pack.ofs_delta=36 git.pack.ref_delta=0 git.pack.chain.max=2 git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91 git.pack.full=44Open pack map
fetchtree:0200174 B · hit1 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=1 git.response.bytes=174 git.response.cache=HIT git.response.duration_ms=1 git.fetch.filter=tree:0 git.fetch.wants=9a364b543bd220d89afac6cc877ed8db92abf022 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=174 git.pkt.payload.max=147 git.sideband.band1.bytes=147 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=147 git.pack.trailer=5a3ab82bf6fbb95581196169deb2e857fd8acdf5Open pack map
fetch2002.2 KiB206 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=206 git.response.bytes=2259 git.response.cache=MISS git.response.duration_ms=206 git.fetch.wants=0676aff48ea042b7af5c5b0d5f89abc9d03a2ac8 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=2259 git.pkt.payload.max=2232 git.sideband.band1.bytes=2232 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://gitlab.com/gitlab-org/cli
- Ref
- refs/heads/main
- Commit
- 0dd7574dce9e385c5c30540e6c15657adc6bdce9
- cf-ray
- a5e1450fbf460bf5
- Request
- 91738f43…
- Protocol
- v2 · sha1
- Agent
- git/2.56.g1891de4-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format