Public: anyone can read this; the crew can change it.
A test walks the README tour and fails when a button or heading it names is no longer on the page #263
Check · Review · Land · Live done — Landed and live in production.
mason/deal-clock:mason/258-a-test-walks-the-readme-tour-and-fails-w → main 2 commits fork 3 threads · 3 unresolved
1 file
changed +81
−0
src/tour.test.ts added +81
| @@ -0,0 +1,81 @@ | ||
| 1 | /** The README tour names buttons and headings; each must still be on the page its step sends the reader to. */ | |
| 2 | import { afterAll, expect, test } from "bun:test"; | |
| 3 | import { mkdtempSync, readFileSync } from "node:fs"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { labelOf } from "./outbox.ts"; | |
| 7 | import { forgetRationing } from "./security.ts"; | |
| 8 | import { serve } from "./server.ts"; | |
| 9 | import { sign } from "./who.ts"; | |
| 10 | ||
| 11 | const KEY = "a-key-only-the-forge-holds"; | |
| 12 | const dir = mkdtempSync(join(tmpdir(), "app-tour-")); | |
| 13 | const server = serve({ port: 0, dataDir: dir, identityKey: KEY }); | |
| 14 | const base = `http://${server.hostname}:${server.port}`; | |
| 15 | afterAll(() => server.stop(true)); | |
| 16 | // Admin, because Profile's save is for admins and some names show only to them. | |
| 17 | const identity = `u1|alice|admin|${Date.now() + 600_000}`; | |
| 18 | const admin = { "x-forge-identity": identity, "x-forge-signature": sign(identity, KEY) }; | |
| 19 | const get = async (path: string, headers: Record<string, string> = admin) => { | |
| 20 | forgetRationing(); | |
| 21 | return (await fetch(base + path, { headers })).text(); | |
| 22 | }; | |
| 23 | ||
| 24 | const readme = readFileSync(new URL("../README.md", import.meta.url), "utf8"); | |
| 25 | ||
| 26 | /** Steps 1-10 of the tour, as [number, text]. */ | |
| 27 | function tourSteps(markdown: string): [number, string][] { | |
| 28 | const start = markdown.indexOf("## A five-minute tour"); | |
| 29 | const rest = markdown.slice(start).split("\n## ").at(0)!; | |
| 30 | const out: [number, string][] = []; | |
| 31 | for (const m of rest.matchAll(/^(\d+)\. ([\s\S]*?)(?=^\d+\. |$(?![\s\S]))/gm)) out.push([Number(m[1]), m[2]!.replace(/\s+/g, " ").trim()]); | |
| 32 | return out; | |
| 33 | } | |
| 34 | ||
| 35 | /** Bold UI names in a step, not its leading title ("**Sign in.**"). */ | |
| 36 | function boldNames(text: string): string[] { | |
| 37 | return [...text.replace(/^\*\*[^*]+\*\*/, "").matchAll(/\*\*([^*]+)\*\*/g)].map((m) => m[1]!.replace(/[.,]$/, "")).filter((n, i, a) => a.indexOf(n) === i); | |
| 38 | } | |
| 39 | ||
| 40 | // Where each step sends the reader. A name is checked on every listed page; it must be on at least one. | |
| 41 | const pages: Record<number, { paths: (ids: number[]) => string[]; as?: "anon" }> = { | |
| 42 | 1: { paths: () => ["/"], as: "anon" }, | |
| 43 | 2: { paths: () => ["/"] }, | |
| 44 | 3: { paths: (ids) => [`/deals/${ids[0]}`] }, | |
| 45 | 4: { paths: (ids) => ids.map((i) => `/deals/${i}/sheets`) }, | |
| 46 | 5: { paths: (ids) => ids.map((i) => `/deals/${i}/sheets`) }, | |
| 47 | 6: { paths: (ids) => ["/", ...ids.map((i) => `/deals/${i}`)] }, | |
| 48 | 7: { paths: (ids) => ids.flatMap((i) => [`/deals/${i}`, `/deals/${i}/timeline`]) }, | |
| 49 | 8: { paths: () => ["/", "/week"] }, | |
| 50 | 9: { paths: () => ["/people", "/people?q=priya", "/people?q=zzzz"] }, | |
| 51 | 10: { paths: () => ["/profile"] }, | |
| 52 | }; | |
| 53 | ||
| 54 | test("the tour has steps 1 to 10 and each is checked", () => { | |
| 55 | expect(tourSteps(readme).map(([n]) => n)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); | |
| 56 | expect(tourSteps(readme).flatMap(([, t]) => boldNames(t)).length).toBeGreaterThan(15); | |
| 57 | }); | |
| 58 | ||
| 59 | /** One message per bold name a step names that is not on the pages it sends the reader to. */ | |
| 60 | async function missingNames(markdown: string, ids: number[]): Promise<string[]> { | |
| 61 | const missing: string[] = []; | |
| 62 | for (const [n, text] of tourSteps(markdown)) { | |
| 63 | const where = pages[n]!; | |
| 64 | const got = (await Promise.all(where.paths(ids).map((p) => get(p, where.as === "anon" ? {} : admin)))).join("\n") + (n === 6 ? ` ${labelOf("mailto:")} ${labelOf("sms:")}` : ""); | |
| 65 | for (const name of boldNames(text)) if (!got.includes(name)) missing.push(`step ${n}: "${name}" is not on ${where.paths(ids).slice(0, 3).join(", ")}`); | |
outdated
Extract this check (lines 63-67) into a function that takes the README text and returns the missing-name messages, so the renamed-label test can run the real page comparison. |
||
| 66 | } | |
| 67 | return missing; | |
| 68 | } | |
| 69 | ||
| 70 | const dealIds = async (): Promise<number[]> => | |
| 71 | ((await (await fetch(base + "/api/deals", { headers: admin })).json()) as { id: number }[]).map((d) => d.id); | |
outdated
This only tests the parser. It would still pass if the page check never reported a missing name, or reported the wrong step. Assert on the output of the page check for a renamed README: one entry beginning |
||
| 72 | ||
| 73 | test("every bold name in tour steps 1-10 is on a page that step sends the reader to", async () => { | |
| 74 | expect(await missingNames(readme, await dealIds())).toEqual([]); | |
| 75 | }); | |
| 76 | ||
| 77 | test("a renamed label fails the page check with its step number", async () => { | |
| 78 | const got = await missingNames(readme.replace("**Mark done**", "**Finish**"), await dealIds()); | |
| 79 | expect(got).toHaveLength(1); | |
| 80 | expect(got[0]!.startsWith('step 4: "Finish" is not on')).toBe(true); | |
| 81 | }); |
new above
offline
Nothing imports this or boldNames; drop
export.