test(web): exercise command directory behavior

Author: SarthakWade

apps/web/package.json

@@ -6,7 +6,7 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "node scripts/validate-harness-onboarding.mjs && node scripts/validate-content-provenance.mjs && node scripts/validate-command-directory.mjs && node scripts/validate-bundle-policy.mjs && node scripts/validate-deployment-config.mjs && eslint .",
+    "lint": "node scripts/validate-harness-onboarding.mjs && node scripts/validate-content-provenance.mjs && node scripts/validate-command-directory.mjs && node --test scripts/command-directory.test.mjs && node scripts/validate-bundle-policy.mjs && node scripts/validate-deployment-config.mjs && eslint .",
     "brand": "node scripts/render-brand.mjs"
   },
   "dependencies": {
@@ -24,6 +24,7 @@
     "@types/react-dom": "^19.2.7",
     "eslint": "^9.36.0",
     "eslint-config-next": "^16.3.3",
+    "jsdom": "30.0.1",
     "tailwindcss": "^4.1.11",
     "typescript": "^6.0.3"
   }

apps/web/scripts/command-directory.test.mjs

@@ -0,0 +1,219 @@
+import assert from "node:assert/strict";
+import * as nodeModule from "node:module";
+import test from "node:test";
+import { JSDOM } from "jsdom";
+import * as componentTestLoader from "./component-test-loader.mjs";
+import { loadProductDocsContent } from "../lib/repository-content.mjs";
+
+if (typeof nodeModule.registerHooks === "function") {
+  nodeModule.registerHooks(componentTestLoader);
+} else {
+  nodeModule.register("./component-test-loader.mjs", import.meta.url);
+}
+
+const { groups } = loadProductDocsContent().commands;
+
+async function renderDirectory({ width = 1280 } = {}) {
+  const dom = new JSDOM('<div id="root"></div>', {
+    pretendToBeVisual: true,
+    url: "https://headless.test/docs/commands",
+  });
+  Object.defineProperty(dom.window, "innerWidth", {
+    configurable: true,
+    value: width,
+  });
+
+  const previousGlobals = new Map();
+  for (const name of [
+    "document",
+    "Event",
+    "HTMLElement",
+    "HTMLInputElement",
+    "InputEvent",
+    "KeyboardEvent",
+    "Node",
+    "navigator",
+    "window",
+  ]) {
+    previousGlobals.set(name, Object.getOwnPropertyDescriptor(globalThis, name));
+    Object.defineProperty(globalThis, name, {
+      configurable: true,
+      value: dom.window[name],
+      writable: true,
+    });
+  }
+  previousGlobals.set(
+    "IS_REACT_ACT_ENVIRONMENT",
+    Object.getOwnPropertyDescriptor(globalThis, "IS_REACT_ACT_ENVIRONMENT"),
+  );
+  Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
+    configurable: true,
+    value: true,
+    writable: true,
+  });
+
+  const [{ act, createElement }, { createRoot }, { CommandDirectory }] =
+    await Promise.all([
+      import("react"),
+      import("react-dom/client"),
+      import("@/components/command-directory"),
+    ]);
+  const container = dom.window.document.querySelector("#root");
+  const root = createRoot(container);
+  await act(() => root.render(createElement(CommandDirectory, { groups })));
+
+  return {
+    act,
+    document: dom.window.document,
+    input: dom.window.document.querySelector("input[type=search]"),
+    async cleanup() {
+      await act(() => root.unmount());
+      dom.window.close();
+      for (const [name, descriptor] of previousGlobals) {
+        if (descriptor === undefined) delete globalThis[name];
+        else Object.defineProperty(globalThis, name, descriptor);
+      }
+    },
+  };
+}
+
+async function typeWithKeyboard(view, value) {
+  const valueSetter = Object.getOwnPropertyDescriptor(
+    view.input.ownerDocument.defaultView.HTMLInputElement.prototype,
+    "value",
+  ).set;
+
+  view.input.focus();
+  await view.act(() => {
+    for (let index = 0; index < value.length; index += 1) {
+      const key = value[index];
+      view.input.dispatchEvent(
+        new KeyboardEvent("keydown", { bubbles: true, key }),
+      );
+      valueSetter.call(view.input, value.slice(0, index + 1));
+      view.input.dispatchEvent(
+        new InputEvent("input", {
+          bubbles: true,
+          data: key,
+          inputType: "insertText",
+        }),
+      );
+      view.input.dispatchEvent(
+        new KeyboardEvent("keyup", { bubbles: true, key }),
+      );
+    }
+  });
+}
+
+async function replaceSearch(view, value) {
+  const valueSetter = Object.getOwnPropertyDescriptor(
+    view.input.ownerDocument.defaultView.HTMLInputElement.prototype,
+    "value",
+  ).set;
+  await view.act(() => {
+    valueSetter.call(view.input, value);
+    view.input.dispatchEvent(
+      new InputEvent("input", {
+        bubbles: true,
+        data: value,
+        inputType: "insertReplacementText",
+      }),
+    );
+  });
+}
+
+function assertTocTargetsExist(document) {
+  for (const link of document.querySelectorAll("nav[aria-label='On this page'] a")) {
+    assert.ok(
+      document.querySelector(link.hash),
+      `table-of-contents target ${link.hash} must exist`,
+    );
+  }
+}
+
+test("filters real command groups from keyboard input and updates accessible status", async () => {
+  const view = await renderDirectory();
+  try {
+    const label = view.document.querySelector("label[for=command-filter]");
+    const status = view.document.querySelector("[role=status]");
+
+    assert.equal(label.control, view.input);
+    assert.equal(view.input.tabIndex, 0);
+    assert.equal(status.getAttribute("aria-live"), "polite");
+    assert.equal(status.textContent, `${groups.length} of ${groups.length} groups`);
+    assertTocTargetsExist(view.document);
+
+    await typeWithKeyboard(view, "auth login");
+
+    assert.equal(view.document.activeElement, view.input);
+    assert.equal(status.textContent, `1 of ${groups.length} groups`);
+    assert.deepEqual(
+      [...view.document.querySelectorAll("section h2")].map(
+        (heading) => heading.textContent,
+      ),
+      ["Credential vault"],
+    );
+    assert.deepEqual(
+      [...view.document.querySelectorAll("nav[aria-label='On this page'] a")].map(
+        (link) => link.textContent,
+      ),
+      ["Credential vault"],
+    );
+    assertTocTargetsExist(view.document);
+  } finally {
+    await view.cleanup();
+  }
+});
+
+test("handles normalized queries, no matches, and clearing without stale links", async () => {
+  const view = await renderDirectory();
+  try {
+    const status = view.document.querySelector("[role=status]");
+
+    await replaceSearch(view, "  SCREENSHOT  ");
+    assert.equal(status.textContent, `1 of ${groups.length} groups`);
+    assert.equal(
+      view.document.querySelector("section")?.id,
+      "capture-and-evidence",
+    );
+    assertTocTargetsExist(view.document);
+
+    await replaceSearch(view, "not-a-command");
+    assert.equal(status.textContent, "No commands match “not-a-command”.");
+    assert.equal(view.document.querySelector("section"), null);
+    assert.equal(view.document.querySelector("nav[aria-label='On this page']"), null);
+
+    await replaceSearch(view, "");
+    assert.equal(status.textContent, `${groups.length} of ${groups.length} groups`);
+    assert.equal(view.document.querySelectorAll("section").length, groups.length);
+    assertTocTargetsExist(view.document);
+  } finally {
+    await view.cleanup();
+  }
+});
+
+test("keeps command discovery functional in a mobile viewport", async () => {
+  const view = await renderDirectory({ width: 375 });
+  try {
+    assert.equal(view.document.defaultView.innerWidth, 375);
+    assert.ok(view.input);
+    assert.equal(view.document.querySelectorAll("section").length, groups.length);
+    assertTocTargetsExist(view.document);
+
+    await typeWithKeyboard(view, "visit");
+    assert.equal(
+      view.document.querySelector("[role=status]").textContent,
+      `1 of ${groups.length} groups`,
+    );
+    assert.equal(
+      view.document.querySelector("nav[aria-label='On this page'] a").hash,
+      "#navigation-and-interaction",
+    );
+    assert.equal(
+      view.document.querySelector("section")?.id,
+      "navigation-and-interaction",
+    );
+  } finally {
+    await view.cleanup();
+  }
+});

apps/web/scripts/component-test-loader.mjs

@@ -0,0 +1,67 @@
+import { accessSync, readFileSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { transformSync } from "next/dist/build/swc/index.js";
+
+const webRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const sourceExtensions = ["", ".tsx", ".ts", ".jsx", ".js", ".mjs"];
+
+export function resolve(specifier, context, nextResolve) {
+  if (!specifier.startsWith("@/")) return nextResolve(specifier, context);
+
+  const sourcePath = join(webRoot, specifier.slice(2));
+  for (const extension of sourceExtensions) {
+    const candidate = `${sourcePath}${extension}`;
+    try {
+      accessSync(candidate);
+      return { shortCircuit: true, url: pathToFileURL(candidate).href };
+    } catch {
+      // Try the next supported source extension.
+    }
+  }
+
+  throw new Error(`Cannot resolve web source import: ${specifier}`);
+}
+
+export function load(url, context, nextLoad) {
+  const extension = extname(new URL(url).pathname);
+  if (extension === ".json") {
+    const source = readFileSync(fileURLToPath(url), "utf8");
+    return {
+      format: "module",
+      shortCircuit: true,
+      source: `export default ${source};`,
+    };
+  }
+  if (extension !== ".tsx" && extension !== ".ts") {
+    return nextLoad(url, context);
+  }
+
+  const filename = fileURLToPath(url);
+  const source = readFileSync(filename, "utf8");
+  const output = transformSync(source, {
+    filename,
+    sourceMaps: false,
+    jsc: {
+      parser: {
+        syntax: "typescript",
+        tsx: extension === ".tsx",
+      },
+      target: "es2022",
+      transform: {
+        react: {
+          runtime: "automatic",
+        },
+      },
+    },
+    module: {
+      type: "es6",
+    },
+  });
+
+  return {
+    format: "module",
+    shortCircuit: true,
+    source: output.code,
+  };
+}

apps/web/scripts/validate-command-directory.mjs

@@ -12,11 +12,6 @@ const commands = await readFile(
   join(root, "apps/headless/docs/COMMANDS.md"),
   "utf8",
 );
-const directory = await readFile(
-  join(root, "apps/web/components/command-directory.tsx"),
-  "utf8",
-);
-
 const sessionModel = sessionModelFromCommands(commands);
 assert.match(sessionModel, /one browser profile/i);
 assert.doesNotMatch(sessionModel, /stays isolated until you close it/i);
@@ -30,12 +25,9 @@ assert.ok(
   surface.groups.some((group) => /auth login/.test(group.usage)),
   "command directory must include auth login",
 );
-assert.match(directory, /role="status"/);
-assert.match(directory, /aria-live="polite"/);
-assert.match(directory, /docs-toc-inline/);
 assert.doesNotMatch(
   await readFile(join(root, "apps/web/app/docs/commands/page.tsx"), "utf8"),
   /sections=\{commands\.groups/,
 );
 
-console.log("command directory search and accessibility checks passed");
+console.log("command directory content checks passed");