// Tests for the documentation under /docs (Syndria98/dragonroll#79): the markdown pages are the // documentation, so what has to stay right is (1) the pages are well formed — a title, a slug, a // numbered group, translations for the group's label, and no link pointing at a page that does not // exist, (2) the page about an integration really documents what that integration offers, which is // checked against the sources that define it: the slash commands of discord-bot/src/commands.js and // the commands the Obsidian plugin registers, and (3) the routes: /docs and /docs/ render the // documentation and every other address still opens the window app. // // `frontend/app/services/DocsMarkdown.js` is the pure part of the docs (headings, slugs, titles) and // is loaded straight from source, the way the other tests load the frontend services; it imports // nothing, so the repository root's no-dependencies rule holds. `Docs.js` itself is not loaded: it // reads the markdown through `import.meta.glob`, which only Vite can answer. // // Run with `npm test` from the repository root, or `node --test tests/`. const { test } = require("node:test"); const assert = require("node:assert/strict"); const fs = require("node:fs"); const path = require("node:path"); const vm = require("node:vm"); function readRepoFile(...parts) { return fs.readFileSync(path.join(__dirname, "..", ...parts), "utf8"); } function loadDocsMarkdown() { const source = readRepoFile("frontend", "app", "services", "DocsMarkdown.js"); return vm.compileFunction(source.replace("export {", "return {") , [], { parsingContext: vm.createContext({}), })(); } const docs = loadDocsMarkdown(); // The documentation pages, as the folder layout defines them. const docsRoot = path.join(__dirname, "..", "frontend", "app", "content", "docs"); const docPages = fs.readdirSync(docsRoot, { withFileTypes: true }) .filter((entry) => entry.isDirectory()) .sort((left, right) => left.name.localeCompare(right.name)) .flatMap((group) => fs.readdirSync(path.join(docsRoot, group.name)) .filter((file) => file.endsWith(".md")) .sort() .map((file) => ({ group: group.name.replace(/^\d+-/, ""), slug: file.replace(/^\d+-/, "").replace(/\.md$/, ""), markdown: fs.readFileSync(path.join(docsRoot, group.name, file), "utf8"), })) ); const slugs = new Set(docPages.map((page) => page.slug)); const groups = [...new Set(docPages.map((page) => page.group))]; const pageAbout = (slug) => docPages.find((page) => page.slug === slug); // --- The heading helpers the sidebar and the anchors are built from --- test("a heading's slug comes out of its words, whatever form they arrive in", () => { assert.equal(docs.Slugify("Link a world"), "link-a-world"); assert.equal(docs.Slugify(" Auto-sync, and one actor "), "auto-sync-and-one-actor"); assert.equal(docs.Slugify("Dragonroll: Force Sync!"), "dragonroll-force-sync"); }); test("the anchor built from a heading's markdown is the one built from its HTML", () => { // The sidebar slugs the markdown source and the renderer slugs what marked produced, so the two // have to land on the same anchor for a sidebar link to land on its section. const pairs = [ ["**Link** a `world`", "Link a world"], ["Commands & characters", "Commands & characters"], ["[Foundry](/docs/foundry) worlds", 'Foundry worlds'], ["It's here", "It's here"], ]; for (const [markdown, html] of pairs) { assert.equal(docs.Slugify(markdown), docs.Slugify(html), `slug of ${markdown}`); } }); test("repeated headings get distinct anchors, in the order they are written", () => { const slug = docs.CreateHeadingSlugger(); assert.equal(slug("Setup"), "setup"); assert.equal(slug("setup"), "setup-1"); assert.equal(slug("Setup"), "setup-2"); }); test("the headings of a page are listed in order, with their anchors", () => { const headings = docs.HeadingsFromMarkdown([ "# Connecting a service", "", "## How a connection works", "text", "### What it allows", "```sh", "# not a heading", "```", "## Next", ].join("\n")); // The service is loaded from another realm, so the values are copied out before being compared. assert.deepEqual( JSON.parse(JSON.stringify(headings.map(({ depth, text, slug }) => ({ depth, text, slug })))), [ { depth: 1, text: "Connecting a service", slug: "connecting-a-service" }, { depth: 2, text: "How a connection works", slug: "how-a-connection-works" }, { depth: 3, text: "What it allows", slug: "what-it-allows" }, { depth: 2, text: "Next", slug: "next" }, ] ); }); test("a page takes its title from its first heading", () => { assert.equal(docs.TitleFromMarkdown("# Your first campaign\n\n## Signing in"), "Your first campaign"); assert.equal(docs.TitleFromMarkdown("no heading here"), ""); }); // --- The pages themselves --- test("the documentation has pages, in numbered groups", () => { assert.ok(docPages.length >= 5, `expected several documentation pages, found ${docPages.length}`); for (const page of docPages) { const folder = `${page.group}`; assert.ok(folder.length > 0, `${page.slug} sits in an oddly named folder`); assert.match(page.slug, /^[a-z0-9]+(-[a-z0-9]+)*$/, `${page.slug} is not a url-friendly slug`); } }); test("every page has a title, and no two pages share a slug", () => { const seen = new Set(); for (const page of docPages) { const title = docs.TitleFromMarkdown(page.markdown); assert.ok(title, `${page.slug} has no heading to title it`); assert.ok(!seen.has(page.slug), `${page.slug} is published twice`); seen.add(page.slug); } assert.equal(seen.size, docPages.length); }); test("every page has sections, which is what the sidebar lists beside it", () => { for (const page of docPages) { const sections = docs.HeadingsFromMarkdown(page.markdown).filter((heading) => heading.depth > 1); assert.ok(sections.length, `${page.slug} has no section headings to list`); } }); test("every group has a sidebar label in every locale", () => { const labels = ["en", "es", "ca"].map((locale) => JSON.parse(readRepoFile("frontend", "i18n", "locales", locale, "docs.json")) ); assert.ok(labels.every((label) => label.groups), "each docs.json namespace needs a `groups` object"); for (const group of groups) { for (const label of labels) { const text = label.groups[group]; assert.ok(text, `the "${group}" group has no label in its docs.json`); assert.notEqual(text, group, `the "${group}" label is untranslated`); } } }); test("the pages only link to pages that are published", () => { for (const page of docPages) { for (const link of page.markdown.matchAll(/\]\((\/docs\/?[a-z0-9-]*)\)/g)) { const target = link[1].replace("/docs/", ""); if (!target) continue; // /docs itself assert.ok(slugs.has(target), `${page.slug} links to ${link[1]}, which is not published`); } } }); test("the three integrations each have their own page", () => { for (const slug of ["discord", "foundry", "obsidian"]) { assert.ok(pageAbout(slug), `${slug} has no documentation page`); } assert.ok(pageAbout("connecting-a-service"), "the shared way of connecting a service is undocumented"); }); // --- The integrations pages describe what the integrations actually offer --- // discord-bot/src/commands.js builds the slash commands with discord.js, which the repository root // does not install: the builder is stubbed by one that records the names it is given. function loadSlashCommands() { const registered = []; class Builder { constructor() { this.name = ""; this.parent = null; this.children = []; this.optionNames = []; } setName(name) { this.name = name; return this; } setDescription() { return this; } setContexts() { return this; } setRequired() { return this; } setMaxLength() { return this; } setAutocomplete() { return this; } addChoices() { return this; } addStringOption(configure) { configure(new Builder()); return this; } addBooleanOption(configure) { configure(new Builder()); return this; } addSubcommand(configure) { const sub = new Builder(); sub.parent = this; configure(sub); this.children.push(sub); return this; } } class SlashCommandBuilder extends Builder { constructor() { super(); registered.push(this); } } const moduleStub = { exports: {} }; vm.compileFunction(readRepoFile("discord-bot", "src", "commands.js"), ["require", "module", "exports"])( (id) => { if (id === "discord.js") return { InteractionContextType: { Guild: 0 }, SlashCommandBuilder }; throw new Error(`require("${id}") is not stubbed`); }, moduleStub, moduleStub.exports ); const names = []; for (const command of registered) { names.push(command.name); for (const sub of command.children) names.push(`${command.name} ${sub.name}`); } return names; } test("the Discord page lists every command the bot declares", () => { const about = pageAbout("discord"); const commands = loadSlashCommands(); // Sanity check on the stub before it is trusted to list anything. assert.ok(commands.includes("characters"), `expected the bot's commands, got ${commands.join(", ")}`); assert.ok(commands.includes("dragonroll connect")); for (const command of commands) { assert.ok( about.markdown.includes("`/" + command), `the Discord page does not document /${command}` ); } }); // The Obsidian plugin registers each command palette entry with `this.addCommand({ id, name, … })`. function loadObsidianCommands() { const source = readRepoFile("obsidian-plugin", "main.js"); const commands = [...source.matchAll( /this\.addCommand\(\{\s*id:\s*["']([^"']+)["'],\s*name:\s*["']([^"']+)["']/g )].map((match) => ({ id: match[1], name: match[2] })); // Sanity check on the extraction before it is trusted to list anything. assert.ok(commands.length >= 2, `expected the plugin's commands, got ${commands.length}`); return commands; } test("the Obsidian page lists the commands the plugin registers", () => { const about = pageAbout("obsidian"); for (const command of loadObsidianCommands()) { assert.ok( about.markdown.includes(`**${command.name}**`), `the Obsidian page does not document "${command.name}" (${command.id})` ); } }); test("the Foundry page covers what the world and the campaign do with each other", () => { const about = pageAbout("foundry").markdown; for (const topic of ["Auto-sync", "Force Sync", "item directory", "Pairing Status"]) { assert.ok(about.includes(topic), `the Foundry page never mentions ${topic}`); } }); // --- The routes --- test("the app renders whichever page the address asks for", () => { const root = readRepoFile("frontend", "app", "app.vue"); assert.match(root, //, "app.vue has to render the matched page"); assert.doesNotMatch(root, /CreateWindow/, "the window app boots from AppShell, not from app.vue"); }); test("the documentation has a route of its own, and the app keeps the rest", () => { const pages = path.join("frontend", "app", "pages"); const docsRoutes = ["docs/index.vue", "docs/[slug].vue"]; for (const route of docsRoutes) { assert.match( readRepoFile(pages, route), //, `${route} has to render the documentation` ); } for (const route of ["index.vue", "[...all].vue"]) { assert.match( readRepoFile(pages, route), //, `${route} has to open the window app` ); } // The catch-all is what keeps /link/authorize, and every path a service already links to, alive. const shell = readRepoFile("frontend", "app", "components", "views", "AppShell.vue"); assert.ok(shell.includes("/link/authorize"), "the service link screen has to stay reachable"); assert.ok(shell.includes("/discord/authorize"), "the legacy Discord link has to stay reachable"); }); test("the main menu points at the documentation", () => { const menu = readRepoFile("frontend", "app", "components", "windows", "MainMenuWindow.vue"); assert.match(menu, /href="\/docs"/, "the main menu has to link to /docs"); assert.match(menu, /main-menu\.documentation/); for (const locale of ["en", "es", "ca"]) { const strings = JSON.parse(readRepoFile("frontend", "i18n", "locales", locale, "main-menu.json")); assert.ok(strings.documentation, `${locale} has no label for the documentation link`); } });