From fca1531c8b0c94536e9d5c91eb22de1b3fc2d592 Mon Sep 17 00:00:00 2001 From: Jonathan Amsterdam Date: Wed, 21 Aug 2024 15:49:24 -0400 Subject: [PATCH] internal/godoc/dochtml/internal/render: move tests to txtar Move most of the cases of the formatDocHTML test to txtar files. They were too hard to read. The remaining cases have to do with passing an ast.Decl. We may move them later or we may try a different approach to generating unique heading IDs, which is the purpose of passing in the decl. Change-Id: I99c71ed1f04b469cb540ff72a31a39eb6cbb1050 Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/607616 kokoro-CI: kokoro Reviewed-by: Hyang-Ah Hana Kim Reviewed-by: Robert Findley LUCI-TryBot-Result: Go LUCI --- .../dochtml/internal/render/linkify_test.go | 275 +++++------------- .../render/testdata/formatDocHTML/README.md | 17 ++ .../testdata/formatDocHTML/escaping.txt | 12 + .../testdata/formatDocHTML/headinglink.txt | 25 ++ .../render/testdata/formatDocHTML/linking.txt | 29 ++ .../render/testdata/formatDocHTML/links.txt | 58 ++++ .../render/testdata/formatDocHTML/lists.txt | 21 ++ .../render/testdata/formatDocHTML/regdoc.txt | 14 + .../testdata/formatDocHTML/shortdoc.txt | 7 + .../formatDocHTML/unique_overview.txt | 27 ++ 10 files changed, 276 insertions(+), 209 deletions(-) create mode 100644 internal/godoc/dochtml/internal/render/testdata/formatDocHTML/README.md create mode 100644 internal/godoc/dochtml/internal/render/testdata/formatDocHTML/escaping.txt create mode 100644 internal/godoc/dochtml/internal/render/testdata/formatDocHTML/headinglink.txt create mode 100644 internal/godoc/dochtml/internal/render/testdata/formatDocHTML/linking.txt create mode 100644 internal/godoc/dochtml/internal/render/testdata/formatDocHTML/links.txt create mode 100644 internal/godoc/dochtml/internal/render/testdata/formatDocHTML/lists.txt create mode 100644 internal/godoc/dochtml/internal/render/testdata/formatDocHTML/regdoc.txt create mode 100644 internal/godoc/dochtml/internal/render/testdata/formatDocHTML/shortdoc.txt create mode 100644 internal/godoc/dochtml/internal/render/testdata/formatDocHTML/unique_overview.txt diff --git a/internal/godoc/dochtml/internal/render/linkify_test.go b/internal/godoc/dochtml/internal/render/linkify_test.go index 51b78591..20e78841 100644 --- a/internal/godoc/dochtml/internal/render/linkify_test.go +++ b/internal/godoc/dochtml/internal/render/linkify_test.go @@ -11,15 +11,81 @@ import ( "go/doc" "go/parser" "go/token" + "path/filepath" "strings" "testing" "github.com/google/go-cmp/cmp" "github.com/google/safehtml" "github.com/google/safehtml/testconversions" + "golang.org/x/tools/txtar" ) func TestFormatDocHTML(t *testing.T) { + files, err := filepath.Glob(filepath.FromSlash("testdata/formatDocHTML/*.txt")) + if err != nil { + t.Fatal(err) + } + if len(files) == 0 { + t.Fatal("no files") + } + for _, file := range files { + t.Run(strings.TrimSuffix(filepath.Base(file), ".txt"), func(t *testing.T) { + // See testdata/formatDocHTML/README.md for how these txtar files represent + // test cases. + ar, err := txtar.ParseFile(file) + if err != nil { + t.Fatal(err) + } + content := map[string][]byte{} + for _, f := range ar.Files { + content[f.Name] = f.Data + } + + getContent := func(name string) string { + return strings.TrimSpace(string(content[name])) + } + + mustContent := func(t *testing.T, name string) string { + if c := getContent(name); c != "" { + return c + } + t.Fatalf("txtar file %s missing section %q", file, name) + return "" + } + + doc := string(mustContent(t, "doc")) + wantNoExtract := mustContent(t, "want") + for _, extractLinks := range []bool{false, true} { + t.Run(fmt.Sprintf("extractLinks=%t", extractLinks), func(t *testing.T) { + r := New(context.Background(), nil, pkgTime, nil) + got := r.formatDocHTML(doc, nil, extractLinks).String() + want := wantNoExtract + wantLinks := "" + if extractLinks { + // Use "want:links" if present. + if w := getContent("want:links"); w != "" { + want = w + } + wantLinks = getContent("links") + } + if diff := cmp.Diff(want, got); diff != "" { + t.Errorf("doc mismatch (-want +got)\n%s", diff) + } + var b strings.Builder + for _, l := range r.Links() { + b.WriteString(l.Text + " " + l.Href + "\n") + } + if diff := cmp.Diff(wantLinks, strings.TrimSpace(b.String())); diff != "" { + t.Errorf("links mismatch (-want +got)\n%s", diff) + } + }) + } + }) + } +} + +func TestFormatDocHTMLDecl(t *testing.T) { duplicateHeadersDoc := `Documentation. Information @@ -29,25 +95,6 @@ This is some information. Information This is some other information. -` - - linksDoc := `Documentation. - -The Go Project - -Go is an open source project. - - -Links - -- title1, url1 - - - title2 , url2 - - -Header - -More doc. ` // typeWithFieldsDecl is declared as: // type I2 interface { @@ -79,69 +126,6 @@ More doc. want string wantLinks []Link }{ - { - name: "short documentation is rendered", - doc: "The Go Project", - want: "

The Go Project\n

", - }, - { - name: "regular documentation is rendered", - doc: `The Go programming language is an open source project to make programmers more productive. - -Go is expressive, concise, clean, and efficient. Its concurrency mechanisms make it easy to write programs that -get the most out of multicore and networked machines, while its novel type system enables flexible and modular -program construction.`, - want: `

The Go programming language is an open source project to make programmers more productive. -

Go is expressive, concise, clean, and efficient. Its concurrency mechanisms make it easy to write programs that -get the most out of multicore and networked machines, while its novel type system enables flexible and modular -program construction. -

`, - }, - { - name: "header gets linked", - doc: `The Go Project - -Go is an open source project.`, - want: `

The Go Project -

Go is an open source project. -

`, - }, - { - name: "header gets linked 2", - doc: `Documentation. - -The Go Project - -Go is an open source project.`, - want: `
- -
-

Documentation. -

The Go Project

Go is an open source project. -

`, - }, - { - name: "unique header ids in overview section", - doc: duplicateHeadersDoc, - want: `
- -
-

Documentation. -

Information

This is some information. -

Information

This is some other information. -

`, - }, { name: "unique header ids in constants section for grouped constants", doc: duplicateHeadersDoc, @@ -310,133 +294,6 @@ Go is an open source project.`,

Documentation.

Information

This is some information.

Information

This is some other information. -

`, - }, - { - name: "urls become links", - doc: `Go is an open source project developed by a team at https://google.com and many -https://www.golang.org/CONTRIBUTORS from the open source community. - -Go is distributed under a https://golang.org/LICENSE.`, - want: `

Go is an open source project developed by a team at https://google.com and many -https://www.golang.org/CONTRIBUTORS from the open source community. -

Go is distributed under a https://golang.org/LICENSE. -

`, - }, - { - name: "RFCs get linked", - doc: `Package tls partially implements TLS 1.2, as specified in RFC 5246, and TLS 1.3, as specified in RFC 8446. - -In TLS 1.3, this type is called NamedGroup, but at this time this library only supports Elliptic Curve based groups. See RFC 8446, Section 4.2.7. - -TLSUnique contains the tls-unique channel binding value (see RFC -5929, section 3). The newline-separated RFC should be linked, but the words RFC and RFCs should not be. -`, - want: `

Package tls partially implements TLS 1.2, as specified in RFC 5246, and TLS 1.3, as specified in RFC 8446. -

In TLS 1.3, this type is called NamedGroup, but at this time this library only supports Elliptic Curve based groups. See RFC 8446, Section 4.2.7. -

TLSUnique contains the tls-unique channel binding value (see RFC -5929, section 3). The newline-separated RFC should be linked, but the words RFC and RFCs should not be. -

`, - }, - { - name: "quoted strings", - doc: `Bar returns the string "bar".`, - want: `

Bar returns the string "bar". -

`, - }, - { - name: "text is escaped", - doc: `link http://foo">`, - want: `

link http://foo"><script>evil</script> -

`, - }, - { - name: "ulist", - doc: ` - Here is a list: - - a - - b`, - want: `

Here is a list: -

    -
  • a
    • -
  • b
    • -
`, - }, - { - name: "olist", - doc: ` - Here is a list: - 1. a - 2. b`, - want: `

Here is a list: -

    -
  1. a
    2. -
  2. b
    3. -
`, - }, - { - name: "Links section is not extracted", - extractLinks: []bool{false}, - doc: linksDoc, - want: `
- -
-

Documentation. -

The Go Project

Go is an open source project. -

- title1, url1 -

    -
  • title2 , url2
    • -

Header

More doc. -

`, - }, - { - name: "Links section is extracted", - extractLinks: []bool{true}, - doc: linksDoc, - want: `
- -
-

Documentation. -

The Go Project

Go is an open source project. -

Header

More doc. -

`, - wantLinks: []Link{ - {Text: "title1", Href: "url1"}, - {Text: "title2", Href: "url2"}, - }, - }, - { - name: "escape back ticks in quotes", - doc: "For more detail, run ``go help test'' and ``go help testflag''", - want: `

For more detail, run “go help test” and “go help testflag”` + "\n" + "

", - }, - { - name: "symbol links", - doc: "Links to [Month] and [Time.After].", - want: `

Links to Month and Time.After. -

`, - }, - { - name: "package links", - doc: "Links to [time] and [github.com/a/b].", - want: `

Links to time and github.com/a/b.

`, }, } { diff --git a/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/README.md b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/README.md new file mode 100644 index 00000000..12792c96 --- /dev/null +++ b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/README.md @@ -0,0 +1,17 @@ +# Test files for formatDocHTML. + +The files are in txtar format. + +Each file must have the following sections: + +- doc: the comment doc, an input +- want: the HTML, the return value + +By default, "want" is tested with extractLinks set to both true and false. + +The following sections are optional: + +- want:links: the output when extractLinks = true +- links: must be present if want:links is present; the extracted + links, one per line, each line has text and href separated by a single space. + diff --git a/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/escaping.txt b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/escaping.txt new file mode 100644 index 00000000..d5fd18b1 --- /dev/null +++ b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/escaping.txt @@ -0,0 +1,12 @@ +HTML escaping, including quoted strings, angle brackets and backticks. +-- doc -- +Bar returns the string "bar". + +link http://foo"> + +For more detail, run ``go help test'' and ``go help testflag'' +-- want -- +

Bar returns the string "bar". +

link http://foo"><script>evil</script> +

For more detail, run “go help test” and “go help testflag” +

diff --git a/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/headinglink.txt b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/headinglink.txt new file mode 100644 index 00000000..ef62eb31 --- /dev/null +++ b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/headinglink.txt @@ -0,0 +1,25 @@ +Headings get linked, if they are written properly. +The first apparent heading does not get linked because +it does not have a blank line before it. +-- doc -- +The Go Project1 + +Go is an open source project. + +The Go Project2 + +Go is an open source project. +-- want -- +
+ +
+

The Go Project1 +

Go is an open source project. +

The Go Project2

Go is an open source project. +

+ + diff --git a/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/linking.txt b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/linking.txt new file mode 100644 index 00000000..d160c48a --- /dev/null +++ b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/linking.txt @@ -0,0 +1,29 @@ +Linking of URLs, RFCs, symbols and packages. +The symbol and package links work because the function is called on the stdlib time package. +-- doc -- +Go is an open source project developed by a team at https://google.com and many +https://www.golang.org/CONTRIBUTORS from the open source community. + +Go is distributed under a https://golang.org/LICENSE. + +Package tls partially implements TLS 1.2, as specified in RFC 5246, and TLS 1.3, as specified in RFC 8446. + +In TLS 1.3, this type is called NamedGroup, but at this time this library only supports Elliptic Curve based groups. See RFC 8446, Section 4.2.7. + +TLSUnique contains the tls-unique channel binding value (see RFC +5929, section 3). The newline-separated RFC should be linked, but the words RFC and RFCs should not be. + +Links to [Month] and [Time.After]. + +Links to [time] and [github.com/a/b]. +-- want -- +

Go is an open source project developed by a team at https://google.com and many +https://www.golang.org/CONTRIBUTORS from the open source community. +

Go is distributed under a https://golang.org/LICENSE. +

Package tls partially implements TLS 1.2, as specified in RFC 5246, and TLS 1.3, as specified in RFC 8446. +

In TLS 1.3, this type is called NamedGroup, but at this time this library only supports Elliptic Curve based groups. See RFC 8446, Section 4.2.7. +

TLSUnique contains the tls-unique channel binding value (see RFC +5929, section 3). The newline-separated RFC should be linked, but the words RFC and RFCs should not be. +

Links to Month and Time.After. +

Links to time and github.com/a/b. +

diff --git a/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/links.txt b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/links.txt new file mode 100644 index 00000000..e2561834 --- /dev/null +++ b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/links.txt @@ -0,0 +1,58 @@ +Extracting links. +-- doc -- +Documentation. + +The Go Project + +Go is an open source project. + + +Links + +- title1, url1 + + - title2 , url2 + + +Header + +More doc. +-- want -- +
+ +
+

Documentation. +

The Go Project

Go is an open source project. +

- title1, url1 +

    +
  • title2 , url2
    • +

Header

More doc. +

+-- want:links -- +
+ +
+

Documentation. +

The Go Project

Go is an open source project. +

Header

More doc. +

+-- links -- +title1 url1 +title2 url2 diff --git a/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/lists.txt b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/lists.txt new file mode 100644 index 00000000..7dbd5d25 --- /dev/null +++ b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/lists.txt @@ -0,0 +1,21 @@ +Lists. +-- doc -- +Here is a bulleted list: + - a + - b + +Here is a numbered list: + 1. a + 2. b +-- want -- +

Here is a bulleted list: +

    +
  • a
    • +
  • b
    • +

Here is a numbered list: +

    +
  1. a
    2. +
  2. b
    3. +
+ + diff --git a/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/regdoc.txt b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/regdoc.txt new file mode 100644 index 00000000..331a8c20 --- /dev/null +++ b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/regdoc.txt @@ -0,0 +1,14 @@ +Regular documentation is rendered. +-- doc -- +The Go programming language is an open source project to make programmers more productive. + +Go is expressive, concise, clean, and efficient. Its concurrency mechanisms make it easy to write programs that +get the most out of multicore and networked machines, while its novel type system enables flexible and modular +program construction. +-- want -- +

The Go programming language is an open source project to make programmers more productive. +

Go is expressive, concise, clean, and efficient. Its concurrency mechanisms make it easy to write programs that +get the most out of multicore and networked machines, while its novel type system enables flexible and modular +program construction. +

+ diff --git a/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/shortdoc.txt b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/shortdoc.txt new file mode 100644 index 00000000..949481d4 --- /dev/null +++ b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/shortdoc.txt @@ -0,0 +1,7 @@ +Short documentation is rendered. +-- doc -- +The Go Project +-- want -- +

The Go Project +

+ diff --git a/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/unique_overview.txt b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/unique_overview.txt new file mode 100644 index 00000000..d70f8d85 --- /dev/null +++ b/internal/godoc/dochtml/internal/render/testdata/formatDocHTML/unique_overview.txt @@ -0,0 +1,27 @@ +Unique header IDs in overview. +-- doc -- +Documentation. + +Information + +This is some information. + +Information + +This is some other information. +-- want -- +
+ +
+

Documentation. +

Information

This is some information. +

Information

This is some other information. +

+