github.com/onsi/ginkgo@v1.16.6-0.20211118180735-4e1925ba4c95/docs/docs_suite_test.go (about)

     1  package docs_test
     2  
     3  import (
     4  	"go/ast"
     5  	"go/doc"
     6  	"go/parser"
     7  	"go/token"
     8  	"os"
     9  	"path/filepath"
    10  	"regexp"
    11  	"strings"
    12  	"testing"
    13  
    14  	. "github.com/onsi/ginkgo"
    15  	"github.com/onsi/ginkgo/internal/test_helpers"
    16  	. "github.com/onsi/gomega"
    17  )
    18  
    19  func TestDocs(t *testing.T) {
    20  	RegisterFailHandler(Fail)
    21  	RunSpecs(t, "Docs Suite")
    22  }
    23  
    24  var anchors test_helpers.Anchors
    25  
    26  var _ = BeforeSuite(func() {
    27  	var err error
    28  	anchors, err = test_helpers.LoadAnchors(test_helpers.DOCS, "../")
    29  	Ω(err).ShouldNot(HaveOccurred())
    30  })
    31  
    32  var _ = Describe("Validating internal links", func() {
    33  	var entries = []TableEntry{
    34  		Entry("Narrative Documentation", "index.md"),
    35  		Entry("V2 Migration Documentation", "MIGRATING_TO_V2.md"),
    36  		Entry("Repo Readme", "README.md"),
    37  	}
    38  
    39  	DescribeTable("Ensuring no headings have any markdown formatting characters in them", func(name string) {
    40  		headings, err := test_helpers.LoadMarkdownHeadings(test_helpers.DOCS.DocWithName(name).Path("../"))
    41  		Ω(err).ShouldNot(HaveOccurred())
    42  		failed := false
    43  		for _, heading := range headings {
    44  			if strings.ContainsAny(heading, "`*_~#") {
    45  				failed = true
    46  				GinkgoWriter.Printf("%s: '%s'\n", name, heading)
    47  			}
    48  		}
    49  		if failed {
    50  			Fail("Identified invalid headings")
    51  		}
    52  	}, entries)
    53  
    54  	DescribeTable("Ensuring all anchors resolve", func(name string) {
    55  		links, err := test_helpers.LoadMarkdownLinks(test_helpers.DOCS.DocWithName(name).Path("../"))
    56  		Ω(err).ShouldNot(HaveOccurred())
    57  		Ω(links).ShouldNot(BeEmpty())
    58  		failed := false
    59  		for _, link := range links {
    60  			if !anchors.IsResolvable(name, link) {
    61  				failed = true
    62  				GinkgoWriter.Printf("%s: '%s'\n", name, link)
    63  			}
    64  		}
    65  		if failed {
    66  			Fail("Identified invalid links")
    67  		}
    68  	}, entries)
    69  })
    70  
    71  var _ = Describe("Validating godoc links", func() {
    72  	It("validates that all links in the core dsl package are good", func() {
    73  		fset := token.NewFileSet()
    74  		entries, err := os.ReadDir("../")
    75  		Ω(err).ShouldNot(HaveOccurred())
    76  		parsedFiles := []*ast.File{}
    77  		for _, entry := range entries {
    78  			name := entry.Name()
    79  			if !strings.HasSuffix(name, ".go") {
    80  				continue
    81  			}
    82  			parsed, err := parser.ParseFile(fset, filepath.Join("../", name), nil, parser.ParseComments)
    83  			Ω(err).ShouldNot(HaveOccurred())
    84  			parsedFiles = append(parsedFiles, parsed)
    85  		}
    86  
    87  		p, err := doc.NewFromFiles(fset, parsedFiles, "github.com/onsi/ginkgo")
    88  		Ω(err).ShouldNot(HaveOccurred())
    89  
    90  		var b strings.Builder
    91  		b.WriteString(p.Doc)
    92  		b.WriteString("\n")
    93  		for _, elem := range p.Consts {
    94  			b.WriteString(elem.Doc)
    95  			b.WriteString("\n")
    96  		}
    97  		for _, elem := range p.Types {
    98  			b.WriteString(elem.Doc)
    99  			b.WriteString("\n")
   100  		}
   101  		for _, elem := range p.Vars {
   102  			b.WriteString(elem.Doc)
   103  			b.WriteString("\n")
   104  		}
   105  		for _, elem := range p.Funcs {
   106  			b.WriteString(elem.Doc)
   107  			b.WriteString("\n")
   108  		}
   109  
   110  		doc := b.String()
   111  		urlRegexp := regexp.MustCompile(`https*[\w:/#\-\.]*`)
   112  		links := urlRegexp.FindAllString(doc, -1)
   113  
   114  		failed := false
   115  		for _, link := range links {
   116  			if !anchors.IsResolvable("", link) {
   117  				failed = true
   118  				GinkgoWriter.Printf("Godoc: '%s'\n", link)
   119  			}
   120  		}
   121  		if failed {
   122  			Fail("Identified invalid links")
   123  		}
   124  	})
   125  })