Files
coder/scripts/docshtmlcheck/main_test.go
T
Sas Swart bcb981b839 chore: bump github.com/coder/boundary to v0.11.0 (#30083)
Bumps `github.com/coder/boundary` from v0.10.0 to
[v0.11.0](https://github.com/coder/boundary/releases/tag/v0.11.0). No
transitive dependency changes.

boundary v0.11.0 wraps the `--session-id-inject-target` format and
example in backticks, so:

- The `coder agent-firewall` help golden and
`docs/reference/cli/agent-firewall.md` are regenerated.
- The temporary `<host>`/`<glob>` entry for that page in
`scripts/docshtmlcheck`'s `allowedUnknownTags` is now stale (the
linter's self-clearing guard fails on it), so it is removed. The
allowlist is now passed into `filterAllowed`/`reportFindings` so the
tests use their own fixture instead of depending on the real, now-empty
map.

> Generated by Coder Agents on behalf of @SasSwart.
2026-09-29 17:00:27 +02:00

503 lines
16 KiB
Go

package main
import (
"io"
"os"
"path/filepath"
"slices"
"strings"
"testing"
)
func TestCheckSource(t *testing.T) {
t.Parallel()
cases := []struct {
name string
src string
// want maps each expected finding kind to the tag it concerns. Order
// independent; the test asserts the multiset of (kind, tag) pairs.
want []finding
}{
{
name: "swallowed placeholder in prose",
src: "Use `--region` set to <region> for the endpoint.\n",
want: []finding{{kind: kindUnknownElement, tag: "region"}},
},
{
name: "placeholder inside inline code is ignored",
src: "Constructs `https://bedrock-runtime.<region>.amazonaws.com`.\n",
want: nil,
},
{
name: "placeholder inside fenced code block is ignored",
src: "```\nendpoint: https://host.<region>.example.com\n```\n",
want: nil,
},
{
name: "placeholder inside indented code block is ignored",
src: " literal <region> here\n",
want: nil,
},
{
name: "double-underscore placeholder in prose",
src: "The tool name has the <server>__ prefix stripped.\n",
want: []finding{{kind: kindUnknownElement, tag: "server"}},
},
{
name: "void element end tag",
src: "First line.</br>\nSecond line.\n",
want: []finding{{kind: kindVoidEndTag, tag: "br"}},
},
{
name: "void element self and start tags are fine",
src: "A<br>B<br/>C <img src=\"x.png\"> D\n",
want: nil,
},
{
name: "capitalized component tag",
src: "<Image src=\"x.png\">\n",
want: []finding{{kind: kindUnknownElement, tag: "image"}},
},
{
name: "balanced kbd inline",
src: "Press <kbd>Ctrl</kbd> to continue.\n",
want: nil,
},
{
name: "balanced children component",
src: "<children></children>\n",
want: nil,
},
{
name: "unbalanced children component",
src: "<children>\n\nsome text\n",
want: []finding{{kind: kindUnclosedTag, tag: "children"}},
},
{
name: "unclosed div leaks wrapper",
src: "<div class=\"tabs\">\n\n## Heading\n\ncontent\n",
want: []finding{{kind: kindUnclosedTag, tag: "div"}},
},
{
name: "balanced div block",
src: "<div class=\"tabs\">\n\n## Heading\n\n</div>\n",
want: nil,
},
{
name: "stray end tag",
src: "text</div>\n",
want: []finding{{kind: kindStrayEndTag, tag: "div"}},
},
{
// Regression guard: a start tag whose attributes wrap across lines
// must be tokenized whole, not torn in half. A per-line tokenizer
// silently dropped this unclosed <div> (exit 0), the exact leaked
// wrapper the linter exists to catch.
name: "unclosed div with attributes wrapped across lines",
src: "<div\n class=\"tabs\">\n\n## Heading\n\ncontent\n",
want: []finding{{kind: kindUnclosedTag, tag: "div"}},
},
{
name: "unknown element with attributes wrapped across lines",
src: "See <Image\n src=\"x.png\"> here.\n",
want: []finding{{kind: kindUnknownElement, tag: "image"}},
},
{
// A valid inline tag wrapped across lines must NOT produce a
// spurious stray-end-tag on the closing tag.
name: "balanced kbd wrapped across lines",
src: "Press <kbd\n class=\"key\">Ctrl</kbd> now.\n",
want: nil,
},
{
// Interleaved nesting: the inner tag is left dangling when the outer
// tag closes, exercising matchEndTag's unclosed-reporting loop.
name: "inner tag unclosed when outer closes",
src: "<div>\n\n<span>\n\n</div>\n",
want: []finding{{kind: kindUnclosedTag, tag: "span"}},
},
{
name: "autolink is not raw html",
src: "See <https://coder.com/docs> for details.\n",
want: nil,
},
{
name: "autolink inside a children raw-html block is ignored",
src: "<children>\n This page is rendered on <https://coder.com/docs/tutorials>.\n</children>\n",
want: nil,
},
{
name: "email autolink is not raw html",
src: "Contact <support@coder.com> for help.\n",
want: nil,
},
{
name: "placeholder inside html comment is ignored",
src: "<!-- TODO: document <region> here -->\n",
want: nil,
},
{
name: "optional end tag li is not flagged as unclosed",
src: "<ul>\n<li>one\n<li>two\n</ul>\n",
want: nil,
},
{
name: "table cells with optional end tags are fine",
src: "<table><tr><td>a<td>b</tr></table>\n",
want: nil,
},
{
name: "clean prose with angle-bracket math is not html",
src: "If a < b and b > c then done.\n",
want: nil,
},
{
// A self-closing flag on a non-void HTML container is ignored by
// the HTML5 parser, so <div class="tabs"/> leaks its wrapper
// exactly like the open spelling and must still be caught.
name: "self-closing div still leaks wrapper",
src: "<div class=\"tabs\"/>\n\n## Heading\n\ncontent\n",
want: []finding{{kind: kindUnclosedTag, tag: "div"}},
},
{
// A renderer component is not an HTML element: MDX honors the
// self-closing form, so <children/> is complete and must not be
// flagged as unclosed, even though <div/> above is.
name: "self-closing children component is balanced",
src: "<children/>\n",
want: nil,
},
{
name: "self-closing children component with space is balanced",
src: "<children />\n",
want: nil,
},
{
// A capitalized tag whose lowercase name is a real element
// (<Table>, <Section>) is a component reference, not that element,
// and is reported rather than passing on the accidental lookup.
name: "capitalized real-element name is a component",
src: "<Table>\n",
want: []finding{{kind: kindUnknownElement, tag: "table"}},
},
{
name: "another capitalized real-element name is a component",
src: "<Section>\n\ncontent\n",
want: []finding{{kind: kindUnknownElement, tag: "section"}},
},
{
// The capitalized closing tag must not add a spurious stray-end-tag;
// the opening tag already produced the finding.
name: "capitalized component with close tag reports once",
src: "<Table>\n\ncontent\n\n</Table>\n",
want: []finding{{kind: kindUnknownElement, tag: "table"}},
},
{
// A colon-shaped placeholder is not a real autolink, so it is
// checked (and reported) inside a raw-HTML block.
name: "colon-shaped placeholder in raw block is caught",
src: "<div>\n<region:id>\n</div>\n",
want: []finding{{kind: kindUnknownElement, tag: "region:id"}},
},
{
name: "at-shaped placeholder without a domain dot is caught",
src: "<div>\n<user@host>\n</div>\n",
want: []finding{{kind: kindUnknownElement, tag: "user@host"}},
},
{
// A real dotted email is a genuine autolink and stays ignored, even
// inside a raw-HTML block.
name: "email autolink inside raw block is ignored",
src: "<div>\n<ops@coder.com>\n</div>\n",
want: nil,
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
got := checkSource([]byte(tc.src))
assertFindings(t, tc.want, got)
})
}
}
// TestFindingLine pins the reported line number so the line-tracking machinery
// (lineStarts, lineAt, offset mapping) cannot silently regress to a constant.
func TestFindingLine(t *testing.T) {
t.Parallel()
// 1: "intro", 2: blank, 3: the unclosed <div>.
src := "intro\n\n<div class=\"tabs\">\n\n## Heading\n\ncontent\n"
got := checkSource([]byte(src))
if len(got) != 1 {
t.Fatalf("want exactly 1 finding, got %d: %+v", len(got), got)
}
if got[0].kind != kindUnclosedTag || got[0].tag != "div" {
t.Fatalf("want unclosed <div>, got %+v", got[0])
}
if got[0].line != 3 {
t.Errorf("want unclosed <div> reported on line 3, got line %d", got[0].line)
}
}
// TestFindingLineWrapped pins the source line of a finding that is not the
// first token in its raw-HTML block, so the buffer-offset -> source-line
// mapping (srcOffset/spans) is actually exercised. A mapping that collapsed
// every token to the block start would report line 1 here instead of line 2.
func TestFindingLineWrapped(t *testing.T) {
t.Parallel()
// 1: <section> opens, 2: <Foo> is the finding, 3: </section> closes.
src := "<section>\n<Foo>\n</section>\n"
got := checkSource([]byte(src))
if len(got) != 1 {
t.Fatalf("want exactly 1 finding, got %d: %+v", len(got), got)
}
if got[0].kind != kindUnknownElement || got[0].tag != "foo" {
t.Fatalf("want unknown-element <Foo>, got %+v", got[0])
}
if got[0].line != 2 {
t.Errorf("want <Foo> reported on line 2, got line %d", got[0].line)
}
}
// TestIsGeneratedDoc covers the generated-doc routing branch, which no current
// docs page triggers (every placeholder was fixed at its source), so only a
// test exercises it.
func TestIsGeneratedDoc(t *testing.T) {
t.Parallel()
if !isGeneratedDoc("docs/reference/cli/server.md") {
t.Error("want docs/reference/** treated as generated")
}
if isGeneratedDoc("docs/admin/security/audit-logs.md") {
t.Error("want a hand-written docs path treated as not generated")
}
}
// testAllowlist stands in for allowedUnknownTags so these tests do not depend
// on which pages the real allowlist currently holds.
var testAllowlist = map[string]map[string]bool{
"docs/reference/cli/external.md": {"host": true, "glob": true},
}
func TestFilterAllowed(t *testing.T) {
t.Parallel()
// Allowlisted tags are suppressed on that specific path only.
src := "Format: \"domain=<host> [path=<glob>]\".\n"
raw := checkSource([]byte(src))
if len(raw) != 2 {
t.Fatalf("expected 2 raw findings, got %d: %+v", len(raw), raw)
}
filtered := filterAllowed("docs/reference/cli/external.md", checkSource([]byte(src)), testAllowlist)
if len(filtered) != 0 {
t.Fatalf("expected allowlisted host/glob to be suppressed, got %+v", filtered)
}
// The same tokens are NOT suppressed on any other path.
other := filterAllowed("docs/reference/cli/other.md", checkSource([]byte(src)), testAllowlist)
if len(other) != 2 {
t.Fatalf("expected 2 findings on non-allowlisted path, got %d: %+v", len(other), other)
}
}
// TestFilterAllowedStaleEntry verifies the self-clearing guard: when an
// allowlisted tag no longer appears in its file, the unused entry surfaces as a
// stale-allowlist-entry finding so the dead escape hatch fails the build.
func TestFilterAllowedStaleEntry(t *testing.T) {
t.Parallel()
// Only <host> remains; the <glob> allowlist entry now suppresses nothing.
src := "Format: \"domain=<host>\".\n"
got := filterAllowed("docs/reference/cli/external.md", checkSource([]byte(src)), testAllowlist)
if len(got) != 1 {
t.Fatalf("want exactly 1 stale finding, got %d: %+v", len(got), got)
}
if got[0].kind != kindStaleAllowlist || got[0].tag != "glob" {
t.Fatalf("want stale-allowlist-entry for <glob>, got %+v", got[0])
}
// The fix lives in the linter's allowlist, not at any doc line, so the
// finding carries no line (main reports it against the linter source).
if got[0].line != 0 {
t.Errorf("want stale finding to carry no doc line, got line %d", got[0].line)
}
if !strings.Contains(got[0].msg, "allowedUnknownTags") {
t.Errorf("want stale message to name allowedUnknownTags, got %q", got[0].msg)
}
}
func TestCollectMarkdown(t *testing.T) {
t.Parallel()
dir := t.TempDir()
writeTestFile(t, filepath.Join(dir, "b.md"))
writeTestFile(t, filepath.Join(dir, "a.md"))
writeTestFile(t, filepath.Join(dir, "sub", "c.md"))
writeTestFile(t, filepath.Join(dir, "ignore.txt"))
got, err := collectMarkdown([]string{dir})
if err != nil {
t.Fatalf("collectMarkdown: %v", err)
}
// Expected keys go through canonicalPath just like collectMarkdown's, so
// the assertion holds regardless of the temp dir's absolute location.
want := []string{
canonicalPath(filepath.Join(dir, "a.md")),
canonicalPath(filepath.Join(dir, "b.md")),
canonicalPath(filepath.Join(dir, "sub", "c.md")),
}
slices.Sort(want)
if !slices.Equal(got, want) {
t.Fatalf("want %v (sorted, deduped, .md only), got %v", want, got)
}
}
// TestReportFindings covers the per-file reporting in run: the reported
// location (linter source vs. scanned doc), the generator-source note routing
// per file class, and the returned counts. No current docs page triggers these
// branches, so only a test exercises them.
func TestReportFindings(t *testing.T) {
t.Parallel()
cases := []struct {
name string
path string
findings []finding
wantContains []string
wantAbsent []string
wantHTML int
wantStale int
}{
{
name: "generated page routes to the generator source",
path: "docs/reference/cli/server.md",
findings: []finding{{line: 3, kind: kindUnknownElement, tag: "region", msg: "swallowed"}},
wantContains: []string{"docs/reference/cli/server.md:3: unknown-element: swallowed", "generated by `make gen`"},
wantHTML: 1,
},
{
// An allowlisted external page is generated, but its placeholders
// come from an external CLI, so the generator-source note is skipped.
name: "allowlisted external page omits the generator note",
path: "docs/reference/cli/external.md",
findings: []finding{{line: 5, kind: kindUnknownElement, tag: "foo", msg: "swallowed"}},
wantContains: []string{"docs/reference/cli/external.md:5: unknown-element: swallowed"},
wantAbsent: []string{"generated by `make gen`"},
wantHTML: 1,
},
{
name: "hand-written page omits the generator note",
path: "docs/admin/security/audit-logs.md",
findings: []finding{{line: 2, kind: kindUnknownElement, tag: "foo", msg: "swallowed"}},
wantAbsent: []string{"generated by `make gen`"},
wantHTML: 1,
},
{
// A stale-allowlist finding is reported against the linter source
// with no line, counts as stale (not HTML), and never draws the note.
name: "stale entry reports against the linter source",
path: "docs/reference/cli/external.md",
findings: []finding{{kind: kindStaleAllowlist, tag: "glob", msg: "remove it from allowedUnknownTags"}},
wantContains: []string{docshtmlcheckSource + ": stale-allowlist-entry: remove it from allowedUnknownTags"},
wantAbsent: []string{"generated by `make gen`", "external.md:"},
wantStale: 1,
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
t.Parallel()
var out strings.Builder
html, stale := reportFindings(tc.path, tc.findings, testAllowlist, &out)
got := out.String()
for _, want := range tc.wantContains {
if !strings.Contains(got, want) {
t.Errorf("output missing %q\ngot:\n%s", want, got)
}
}
for _, absent := range tc.wantAbsent {
if strings.Contains(got, absent) {
t.Errorf("output should not contain %q\ngot:\n%s", absent, got)
}
}
if html != tc.wantHTML || stale != tc.wantStale {
t.Errorf("want (html=%d stale=%d), got (html=%d stale=%d)", tc.wantHTML, tc.wantStale, html, stale)
}
})
}
}
// TestRun drives run end to end through temp files and asserts the exit-code
// contract: 0 clean, 1 findings, 2 unreadable root.
func TestRun(t *testing.T) {
t.Parallel()
dir := t.TempDir()
clean := filepath.Join(dir, "clean.md")
if err := os.WriteFile(clean, []byte("# ok\n\nPress <kbd>Ctrl</kbd>.\n"), 0o600); err != nil {
t.Fatal(err)
}
if code := run([]string{clean}, io.Discard, io.Discard); code != 0 {
t.Errorf("clean file: want exit 0, got %d", code)
}
bad := filepath.Join(dir, "bad.md")
if err := os.WriteFile(bad, []byte("A <region> placeholder.\n"), 0o600); err != nil {
t.Fatal(err)
}
var stdout, stderr strings.Builder
if code := run([]string{bad}, &stdout, &stderr); code != 1 {
t.Errorf("file with a finding: want exit 1, got %d", code)
}
if !strings.Contains(stdout.String(), "unknown-element") {
t.Errorf("want an unknown-element line, got:\n%s", stdout.String())
}
if !strings.Contains(stderr.String(), "invalid inline HTML issue(s)") {
t.Errorf("want the summary footer, got:\n%s", stderr.String())
}
if code := run([]string{filepath.Join(dir, "does-not-exist")}, io.Discard, io.Discard); code != 2 {
t.Errorf("missing root: want exit 2, got %d", code)
}
}
func writeTestFile(t *testing.T, path string) {
t.Helper()
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(path, []byte("# doc\n"), 0o600); err != nil {
t.Fatal(err)
}
}
func assertFindings(t *testing.T, want, got []finding) {
t.Helper()
type key struct {
kind findingKind
tag string
}
counts := map[key]int{}
for _, f := range got {
counts[key{f.kind, f.tag}]++
}
wantCounts := map[key]int{}
for _, f := range want {
wantCounts[key{f.kind, f.tag}]++
}
for k, n := range wantCounts {
if counts[k] != n {
t.Errorf("want %d finding(s) of {%s %s}, got %d\nall findings: %+v", n, k.kind, k.tag, counts[k], got)
}
}
for k, n := range counts {
if wantCounts[k] == 0 {
t.Errorf("unexpected %d finding(s) of {%s %s}\nall findings: %+v", n, k.kind, k.tag, got)
}
}
}