cobra/doc/man_docs_test.go

236 lines
6.6 KiB
Go
Raw Normal View History

2023-03-06 02:28:31 +00:00
// Copyright 2013-2023 The Cobra Authors
2022-09-16 11:55:56 +00:00
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package doc
2015-08-18 22:33:41 +00:00
import (
"bufio"
2015-08-18 22:33:41 +00:00
"bytes"
"fmt"
"io/ioutil"
2015-08-18 22:33:41 +00:00
"os"
"path/filepath"
2015-08-18 22:33:41 +00:00
"strings"
"testing"
"github.com/spf13/cobra"
2015-08-18 22:33:41 +00:00
)
func assertNoErr(t *testing.T, e error) {
if e != nil {
t.Error(e)
}
}
2015-08-18 22:33:41 +00:00
func translate(in string) string {
return strings.ReplaceAll(in, "-", "\\-")
2015-08-18 22:33:41 +00:00
}
func TestGenManDoc(t *testing.T) {
header := &GenManHeader{
Title: "Project",
Section: "2",
}
2017-11-02 15:22:38 +00:00
2015-08-18 22:33:41 +00:00
// We generate on a subcommand so we have both subcommands and parents
2017-11-02 15:22:38 +00:00
buf := new(bytes.Buffer)
if err := GenMan(echoCmd, header, buf); err != nil {
t.Fatal(err)
}
2017-11-02 15:22:38 +00:00
output := buf.String()
2015-08-18 22:33:41 +00:00
// Make sure parent has - in CommandPath() in SEE ALSO:
2017-11-02 15:22:38 +00:00
parentPath := echoCmd.Parent().CommandPath()
dashParentPath := strings.ReplaceAll(parentPath, " ", "-")
expected := translate(dashParentPath)
expected = expected + "(" + header.Section + ")"
2017-11-02 15:22:38 +00:00
checkStringContains(t, output, expected)
checkStringContains(t, output, translate(echoCmd.Name()))
checkStringContains(t, output, translate(echoCmd.Name()))
checkStringContains(t, output, "boolone")
checkStringContains(t, output, "rootflag")
checkStringContains(t, output, translate(rootCmd.Name()))
checkStringContains(t, output, translate(echoSubCmd.Name()))
checkStringOmits(t, output, translate(deprecatedCmd.Name()))
checkStringContains(t, output, translate("Auto generated"))
}
func TestGenManNoHiddenParents(t *testing.T) {
header := &GenManHeader{
Title: "Project",
Section: "2",
}
// We generate on a subcommand so we have both subcommands and parents
for _, name := range []string{"rootflag", "strtwo"} {
f := rootCmd.PersistentFlags().Lookup(name)
f.Hidden = true
defer func() { f.Hidden = false }()
}
buf := new(bytes.Buffer)
if err := GenMan(echoCmd, header, buf); err != nil {
t.Fatal(err)
}
output := buf.String()
// Make sure parent has - in CommandPath() in SEE ALSO:
parentPath := echoCmd.Parent().CommandPath()
dashParentPath := strings.ReplaceAll(parentPath, " ", "-")
expected := translate(dashParentPath)
expected = expected + "(" + header.Section + ")"
checkStringContains(t, output, expected)
checkStringContains(t, output, translate(echoCmd.Name()))
checkStringContains(t, output, translate(echoCmd.Name()))
checkStringContains(t, output, "boolone")
checkStringOmits(t, output, "rootflag")
checkStringContains(t, output, translate(rootCmd.Name()))
checkStringContains(t, output, translate(echoSubCmd.Name()))
checkStringOmits(t, output, translate(deprecatedCmd.Name()))
checkStringContains(t, output, translate("Auto generated"))
checkStringOmits(t, output, "OPTIONS INHERITED FROM PARENT COMMANDS")
}
func TestGenManNoGenTag(t *testing.T) {
2017-11-02 15:22:38 +00:00
echoCmd.DisableAutoGenTag = true
defer func() { echoCmd.DisableAutoGenTag = false }()
header := &GenManHeader{
Title: "Project",
Section: "2",
}
2017-11-02 15:22:38 +00:00
// We generate on a subcommand so we have both subcommands and parents
2017-11-02 15:22:38 +00:00
buf := new(bytes.Buffer)
if err := GenMan(echoCmd, header, buf); err != nil {
t.Fatal(err)
}
2017-11-02 15:22:38 +00:00
output := buf.String()
unexpected := translate("#HISTORY")
2017-11-02 15:22:38 +00:00
checkStringOmits(t, output, unexpected)
unexpected = translate("Auto generated by spf13/cobra")
checkStringOmits(t, output, unexpected)
2015-08-18 22:33:41 +00:00
}
func TestGenManSeeAlso(t *testing.T) {
2017-11-02 15:22:38 +00:00
rootCmd := &cobra.Command{Use: "root", Run: emptyRun}
aCmd := &cobra.Command{Use: "aaa", Run: emptyRun, Hidden: true} // #229
bCmd := &cobra.Command{Use: "bbb", Run: emptyRun}
cCmd := &cobra.Command{Use: "ccc", Run: emptyRun}
rootCmd.AddCommand(aCmd, bCmd, cCmd)
2017-11-02 15:22:38 +00:00
buf := new(bytes.Buffer)
header := &GenManHeader{}
2017-11-02 15:22:38 +00:00
if err := GenMan(rootCmd, header, buf); err != nil {
t.Fatal(err)
}
2017-11-02 15:22:38 +00:00
scanner := bufio.NewScanner(buf)
2017-11-02 15:22:38 +00:00
if err := assertLineFound(scanner, ".SH SEE ALSO"); err != nil {
t.Fatalf("Couldn't find SEE ALSO section header: %v", err)
}
2017-11-02 15:22:38 +00:00
if err := assertNextLineEquals(scanner, ".PP"); err != nil {
t.Fatalf("First line after SEE ALSO wasn't break-indent: %v", err)
}
if err := assertNextLineEquals(scanner, `\fBroot-bbb(1)\fP, \fBroot-ccc(1)\fP`); err != nil {
2017-11-02 15:22:38 +00:00
t.Fatalf("Second line after SEE ALSO wasn't correct: %v", err)
}
}
func TestManPrintFlagsHidesShortDeperecated(t *testing.T) {
2017-11-02 15:22:38 +00:00
c := &cobra.Command{}
c.Flags().StringP("foo", "f", "default", "Foo flag")
assertNoErr(t, c.Flags().MarkShorthandDeprecated("foo", "don't use it no more"))
2017-11-02 15:22:38 +00:00
buf := new(bytes.Buffer)
manPrintFlags(buf, c.Flags())
2017-11-02 15:22:38 +00:00
got := buf.String()
expected := "**--foo**=\"default\"\n\tFoo flag\n\n"
2017-11-02 15:22:38 +00:00
if got != expected {
t.Errorf("Expected %v, got %v", expected, got)
}
}
func TestGenManTree(t *testing.T) {
2017-11-02 15:22:38 +00:00
c := &cobra.Command{Use: "do [OPTIONS] arg1 arg2"}
header := &GenManHeader{Section: "2"}
tmpdir, err := ioutil.TempDir("", "test-gen-man-tree")
if err != nil {
t.Fatalf("Failed to create tmpdir: %s", err.Error())
}
defer os.RemoveAll(tmpdir)
2017-11-02 15:22:38 +00:00
if err := GenManTree(c, header, tmpdir); err != nil {
t.Fatalf("GenManTree failed: %s", err.Error())
}
if _, err := os.Stat(filepath.Join(tmpdir, "do.2")); err != nil {
t.Fatalf("Expected file 'do.2' to exist")
}
if header.Title != "" {
t.Fatalf("Expected header.Title to be unmodified")
}
}
2017-11-02 15:22:38 +00:00
func assertLineFound(scanner *bufio.Scanner, expectedLine string) error {
for scanner.Scan() {
line := scanner.Text()
if line == expectedLine {
return nil
}
}
if err := scanner.Err(); err != nil {
2017-11-02 15:22:38 +00:00
return fmt.Errorf("scan failed: %s", err)
}
2017-11-02 15:22:38 +00:00
return fmt.Errorf("hit EOF before finding %v", expectedLine)
}
2017-11-02 15:22:38 +00:00
func assertNextLineEquals(scanner *bufio.Scanner, expectedLine string) error {
if scanner.Scan() {
line := scanner.Text()
if line == expectedLine {
return nil
}
2017-11-02 15:22:38 +00:00
return fmt.Errorf("got %v, not %v", line, expectedLine)
}
if err := scanner.Err(); err != nil {
2017-11-02 15:22:38 +00:00
return fmt.Errorf("scan failed: %v", err)
}
2017-11-02 15:22:38 +00:00
return fmt.Errorf("hit EOF before finding %v", expectedLine)
}
func BenchmarkGenManToFile(b *testing.B) {
file, err := ioutil.TempFile("", "")
if err != nil {
b.Fatal(err)
}
defer os.Remove(file.Name())
defer file.Close()
b.ResetTimer()
for i := 0; i < b.N; i++ {
2017-11-02 15:22:38 +00:00
if err := GenMan(rootCmd, nil, file); err != nil {
b.Fatal(err)
}
}
}