| 1 | import { describe, it, expect } from "vitest"; |
| 2 | import { readFileSync } from "node:fs"; |
| 3 | import { |
| 4 | docTopicHaystack, |
| 5 | filterDocTopics, |
| 6 | highlightSpan, |
| 7 | normalizeQuery, |
| 8 | matches, |
| 9 | } from "./search-utils"; |
| 10 | import { DOC_TOPICS } from "./docs-map"; |
| 11 | |
| 12 | describe("normalizeQuery", () => { |
| 13 | it("trims and lowercases", () => { |
| 14 | expect(normalizeQuery(" Hello World ")).toBe("hello world"); |
| 15 | }); |
| 16 | |
| 17 | it("returns empty string for whitespace-only input", () => { |
| 18 | expect(normalizeQuery(" ")).toBe(""); |
| 19 | }); |
| 20 | }); |
| 21 | |
| 22 | describe("matches", () => { |
| 23 | it("returns true for empty query (shows everything)", () => { |
| 24 | expect(matches("anything", "")).toBe(true); |
| 25 | expect(matches("anything", " ")).toBe(true); |
| 26 | }); |
| 27 | |
| 28 | it("does case-insensitive substring matching", () => { |
| 29 | expect(matches("Install Guide", "install")).toBe(true); |
| 30 | expect(matches("install guide", "INSTALL")).toBe(true); |
| 31 | expect(matches("Configuration", "config")).toBe(true); |
| 32 | }); |
| 33 | |
| 34 | it("returns false when no match", () => { |
| 35 | expect(matches("Install", "docker")).toBe(false); |
| 36 | }); |
| 37 | }); |
| 38 | |
| 39 | describe("docTopicHaystack", () => { |
| 40 | it("includes the topic id and slug", () => { |
| 41 | const install = DOC_TOPICS.find((t) => t.id === "install")!; |
| 42 | const hay = docTopicHaystack(install); |
| 43 | expect(hay).toContain("install"); |
| 44 | }); |
| 45 | |
| 46 | it("includes both EN and ZH labels", () => { |
| 47 | const mcp = DOC_TOPICS.find((t) => t.id === "mcp")!; |
| 48 | const hay = docTopicHaystack(mcp); |
| 49 | expect(hay).toContain("mcp"); |
| 50 | // ZH label is also "MCP" but description has Chinese |
| 51 | expect(hay).toContain("stdio"); |
| 52 | expect(hay).toContain("工具"); // tools in Chinese description |
| 53 | }); |
| 54 | |
| 55 | it("includes source file paths", () => { |
| 56 | const config = DOC_TOPICS.find((t) => t.id === "configuration")!; |
| 57 | const hay = docTopicHaystack(config); |
| 58 | expect(hay).toContain("docs/configuration.md"); |
| 59 | expect(hay).toContain("docs/legacy_paths.md"); |
| 60 | }); |
| 61 | |
| 62 | it("includes category name in both locales", () => { |
| 63 | const install = DOC_TOPICS.find((t) => t.id === "install")!; |
| 64 | const hay = docTopicHaystack(install); |
| 65 | expect(hay).toContain("getting-started"); |
| 66 | expect(hay).toContain("入门"); // ZH for getting-started |
| 67 | }); |
| 68 | }); |
| 69 | |
| 70 | describe("filterDocTopics", () => { |
| 71 | it("returns all indices when query is empty", () => { |
| 72 | const result = filterDocTopics(DOC_TOPICS, ""); |
| 73 | expect(result.length).toBe(DOC_TOPICS.length); |
| 74 | }); |
| 75 | |
| 76 | it("returns all indices when query is whitespace", () => { |
| 77 | const result = filterDocTopics(DOC_TOPICS, " "); |
| 78 | expect(result.length).toBe(DOC_TOPICS.length); |
| 79 | }); |
| 80 | |
| 81 | it("filters by English keyword", () => { |
| 82 | const result = filterDocTopics(DOC_TOPICS, "install"); |
| 83 | const ids = result.map((i) => DOC_TOPICS[i].id); |
| 84 | expect(ids).toContain("install"); |
| 85 | expect(ids.length).toBeGreaterThanOrEqual(1); |
| 86 | }); |
| 87 | |
| 88 | it("filters by Chinese keyword", () => { |
| 89 | const result = filterDocTopics(DOC_TOPICS, "沙箱"); // sandbox |
| 90 | const ids = result.map((i) => DOC_TOPICS[i].id); |
| 91 | expect(ids).toContain("sandbox"); |
| 92 | }); |
| 93 | |
| 94 | it("filters by source file name", () => { |
| 95 | const result = filterDocTopics(DOC_TOPICS, "configuration.md"); |
| 96 | const ids = result.map((i) => DOC_TOPICS[i].id); |
| 97 | expect(ids).toContain("configuration"); |
| 98 | }); |
| 99 | |
| 100 | it("filters by category", () => { |
| 101 | const result = filterDocTopics(DOC_TOPICS, "extending"); |
| 102 | const ids = result.map((i) => DOC_TOPICS[i].id); |
| 103 | // extending category includes mcp, hooks, runtime-api |
| 104 | expect(ids).toContain("mcp"); |
| 105 | expect(ids).toContain("hooks"); |
| 106 | expect(ids).toContain("runtime-api"); |
| 107 | }); |
| 108 | |
| 109 | it("is case-insensitive", () => { |
| 110 | const lower = filterDocTopics(DOC_TOPICS, "mcp"); |
| 111 | const upper = filterDocTopics(DOC_TOPICS, "MCP"); |
| 112 | expect(lower).toEqual(upper); |
| 113 | }); |
| 114 | |
| 115 | it("returns empty array for gibberish query", () => { |
| 116 | const result = filterDocTopics(DOC_TOPICS, "zzzzzzz_nonexistent"); |
| 117 | expect(result).toEqual([]); |
| 118 | }); |
| 119 | |
| 120 | it("matches partial keywords", () => { |
| 121 | const result = filterDocTopics(DOC_TOPICS, "tool"); |
| 122 | const ids = result.map((i) => DOC_TOPICS[i].id); |
| 123 | // "tool" should match "tools" topic (id contains "tool") |
| 124 | expect(ids).toContain("tools"); |
| 125 | }); |
| 126 | |
| 127 | it("matches across locales (EN query matches ZH content)", () => { |
| 128 | // "安装" is the ZH label for "install" |
| 129 | const result = filterDocTopics(DOC_TOPICS, "安装"); |
| 130 | const ids = result.map((i) => DOC_TOPICS[i].id); |
| 131 | expect(ids).toContain("install"); |
| 132 | }); |
| 133 | }); |
| 134 | |
| 135 | describe("highlightSpan", () => { |
| 136 | const webRoot = new URL("../", import.meta.url); |
| 137 | const read = (p: string) => readFileSync(new URL(p, webRoot), "utf8"); |
| 138 | |
| 139 | it("splits a plain match into three reassembling pieces", () => { |
| 140 | const span = highlightSpan("Install Guide", "install")!; |
| 141 | expect(span).toEqual({ before: "", match: "Install", after: " Guide" }); |
| 142 | expect(span.before + span.match + span.after).toBe("Install Guide"); |
| 143 | }); |
| 144 | |
| 145 | it("returns null for an empty query or no match", () => { |
| 146 | expect(highlightSpan("Install", "")).toBeNull(); |
| 147 | expect(highlightSpan("Install", " ")).toBeNull(); |
| 148 | expect(highlightSpan("Install", "docker")).toBeNull(); |
| 149 | expect(highlightSpan("", "install")).toBeNull(); |
| 150 | }); |
| 151 | |
| 152 | it("keeps indices in the source string when lowercasing changes length", () => { |
| 153 | // "İ".toLowerCase() is two code units, so a lowercased copy of this |
| 154 | // string is one longer than the string itself. Index arithmetic done on |
| 155 | // the copy highlighted "tanbul " instead of "stanbul". |
| 156 | const text = "İstanbul kurulumu"; |
| 157 | expect(text.toLowerCase().length).toBe(text.length + 1); |
| 158 | const span = highlightSpan(text, "stanbul")!; |
| 159 | expect(span.match).toBe("stanbul"); |
| 160 | expect(span.before).toBe("İ"); |
| 161 | expect(span.after).toBe(" kurulumu"); |
| 162 | expect(span.before + span.match + span.after).toBe(text); |
| 163 | }); |
| 164 | |
| 165 | it("never claims half of a source character", () => { |
| 166 | const span = highlightSpan("İstanbul", "i")!; |
| 167 | expect(span.match).toBe("İ"); |
| 168 | expect(span.before + span.match + span.after).toBe("İstanbul"); |
| 169 | }); |
| 170 | |
| 171 | it("is the one match rule both search surfaces use", () => { |
| 172 | for (const file of ["components/docs-search.tsx", "components/faq-search.tsx"]) { |
| 173 | const source = read(file); |
| 174 | expect(source, file).toContain("highlightSpan(text, query)"); |
| 175 | expect(source, file).not.toContain("text.toLowerCase()"); |
| 176 | expect(source, file).not.toContain("text.slice("); |
| 177 | } |
| 178 | }); |
| 179 | }); |
| 180 |