doc_test.go

Documentation: go/doc

		 1  // Copyright 2012 The Go Authors. All rights reserved.
		 2  // Use of this source code is governed by a BSD-style
		 3  // license that can be found in the LICENSE file.
		 4  
		 5  package doc
		 6  
		 7  import (
		 8  	"bytes"
		 9  	"flag"
		10  	"fmt"
		11  	"go/ast"
		12  	"go/parser"
		13  	"go/printer"
		14  	"go/token"
		15  	"io/fs"
		16  	"os"
		17  	"path/filepath"
		18  	"regexp"
		19  	"strings"
		20  	"testing"
		21  	"text/template"
		22  )
		23  
		24  var update = flag.Bool("update", false, "update golden (.out) files")
		25  var files = flag.String("files", "", "consider only Go test files matching this regular expression")
		26  
		27  const dataDir = "testdata"
		28  
		29  var templateTxt = readTemplate("template.txt")
		30  
		31  func readTemplate(filename string) *template.Template {
		32  	t := template.New(filename)
		33  	t.Funcs(template.FuncMap{
		34  		"node":		 nodeFmt,
		35  		"synopsis": synopsisFmt,
		36  		"indent":	 indentFmt,
		37  	})
		38  	return template.Must(t.ParseFiles(filepath.Join(dataDir, filename)))
		39  }
		40  
		41  func nodeFmt(node interface{}, fset *token.FileSet) string {
		42  	var buf bytes.Buffer
		43  	printer.Fprint(&buf, fset, node)
		44  	return strings.ReplaceAll(strings.TrimSpace(buf.String()), "\n", "\n\t")
		45  }
		46  
		47  func synopsisFmt(s string) string {
		48  	const n = 64
		49  	if len(s) > n {
		50  		// cut off excess text and go back to a word boundary
		51  		s = s[0:n]
		52  		if i := strings.LastIndexAny(s, "\t\n "); i >= 0 {
		53  			s = s[0:i]
		54  		}
		55  		s = strings.TrimSpace(s) + " ..."
		56  	}
		57  	return "// " + strings.ReplaceAll(s, "\n", " ")
		58  }
		59  
		60  func indentFmt(indent, s string) string {
		61  	end := ""
		62  	if strings.HasSuffix(s, "\n") {
		63  		end = "\n"
		64  		s = s[:len(s)-1]
		65  	}
		66  	return indent + strings.ReplaceAll(s, "\n", "\n"+indent) + end
		67  }
		68  
		69  func isGoFile(fi fs.FileInfo) bool {
		70  	name := fi.Name()
		71  	return !fi.IsDir() &&
		72  		len(name) > 0 && name[0] != '.' && // ignore .files
		73  		filepath.Ext(name) == ".go"
		74  }
		75  
		76  type bundle struct {
		77  	*Package
		78  	FSet *token.FileSet
		79  }
		80  
		81  func test(t *testing.T, mode Mode) {
		82  	// determine file filter
		83  	filter := isGoFile
		84  	if *files != "" {
		85  		rx, err := regexp.Compile(*files)
		86  		if err != nil {
		87  			t.Fatal(err)
		88  		}
		89  		filter = func(fi fs.FileInfo) bool {
		90  			return isGoFile(fi) && rx.MatchString(fi.Name())
		91  		}
		92  	}
		93  
		94  	// get packages
		95  	fset := token.NewFileSet()
		96  	pkgs, err := parser.ParseDir(fset, dataDir, filter, parser.ParseComments)
		97  	if err != nil {
		98  		t.Fatal(err)
		99  	}
	 100  
	 101  	// test packages
	 102  	for _, pkg := range pkgs {
	 103  		importPath := dataDir + "/" + pkg.Name
	 104  		var files []*ast.File
	 105  		for _, f := range pkg.Files {
	 106  			files = append(files, f)
	 107  		}
	 108  		doc, err := NewFromFiles(fset, files, importPath, mode)
	 109  		if err != nil {
	 110  			t.Error(err)
	 111  			continue
	 112  		}
	 113  
	 114  		// golden files always use / in filenames - canonicalize them
	 115  		for i, filename := range doc.Filenames {
	 116  			doc.Filenames[i] = filepath.ToSlash(filename)
	 117  		}
	 118  
	 119  		// print documentation
	 120  		var buf bytes.Buffer
	 121  		if err := templateTxt.Execute(&buf, bundle{doc, fset}); err != nil {
	 122  			t.Error(err)
	 123  			continue
	 124  		}
	 125  		got := buf.Bytes()
	 126  
	 127  		// update golden file if necessary
	 128  		golden := filepath.Join(dataDir, fmt.Sprintf("%s.%d.golden", pkg.Name, mode))
	 129  		if *update {
	 130  			err := os.WriteFile(golden, got, 0644)
	 131  			if err != nil {
	 132  				t.Error(err)
	 133  			}
	 134  			continue
	 135  		}
	 136  
	 137  		// get golden file
	 138  		want, err := os.ReadFile(golden)
	 139  		if err != nil {
	 140  			t.Error(err)
	 141  			continue
	 142  		}
	 143  
	 144  		// compare
	 145  		if !bytes.Equal(got, want) {
	 146  			t.Errorf("package %s\n\tgot:\n%s\n\twant:\n%s", pkg.Name, got, want)
	 147  		}
	 148  	}
	 149  }
	 150  
	 151  func Test(t *testing.T) {
	 152  	test(t, 0)
	 153  	test(t, AllDecls)
	 154  	test(t, AllMethods)
	 155  }
	 156  
	 157  func TestAnchorID(t *testing.T) {
	 158  	const in = "Important Things 2 Know & Stuff"
	 159  	const want = "hdr-Important_Things_2_Know___Stuff"
	 160  	got := anchorID(in)
	 161  	if got != want {
	 162  		t.Errorf("anchorID(%q) = %q; want %q", in, got, want)
	 163  	}
	 164  }
	 165
View as plain text