@tooluminati/testing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jitterbox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/browser-helpers-RSQLRHHZ.js

@@ -0,0 +1,8 @@
+import {
+  expectWebMcpTool,
+  invokeWebMcpTool
+} from "./chunk-6YAIOYYZ.js";
+export {
+  expectWebMcpTool,
+  invokeWebMcpTool
+};

package/dist/browser-helpers.d.ts

@@ -0,0 +1,6 @@
+export interface WebMcpTestPage {
+    evaluate<T, A>(callback: (arg: A) => T | Promise<T>, arg: A): Promise<T>;
+}
+export declare function expectWebMcpTool(page: WebMcpTestPage, name: string): Promise<void>;
+export declare function invokeWebMcpTool<T>(page: WebMcpTestPage, name: string, args: unknown): Promise<T>;
+//# sourceMappingURL=browser-helpers.d.ts.map

package/dist/browser-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-helpers.d.ts","sourceRoot":"","sources":["../src/browser-helpers.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,CAAC,EAAE,CAAC,EACX,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACpC,GAAG,EAAE,CAAC,GACL,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAef;AAED,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,CAAC,CAAC,CAoBZ"}

package/dist/browser-helpers.js

@@ -0,0 +1,23 @@
+export async function expectWebMcpTool(page, name) {
+    const exists = await page.evaluate(async (toolName) => {
+        const context = document
+            .modelContext;
+        const tools = (await context?.getTools?.()) ?? [];
+        return tools.some((tool) => tool.name === toolName);
+    }, name);
+    if (!exists) {
+        throw new Error(`Expected WebMCP tool "${name}" to be registered.`);
+    }
+}
+export async function invokeWebMcpTool(page, name, args) {
+    return page.evaluate(async ({ toolName, input }) => {
+        const context = document
+            .modelContext;
+        const tools = (await context?.getTools?.()) ?? [];
+        const tool = tools.find((candidate) => candidate.name === toolName);
+        if (!tool || !context?.executeTool) {
+            throw new Error(`WebMCP tool "${toolName}" cannot be invoked.`);
+        }
+        return context.executeTool(tool, JSON.stringify(input));
+    }, { toolName: name, input: args });
+}

package/dist/chunk-6YAIOYYZ.js

@@ -0,0 +1,30 @@
+// src/browser-helpers.ts
+async function expectWebMcpTool(page, name) {
+  const exists = await page.evaluate(async (toolName) => {
+    const context = document.modelContext;
+    const tools = await context?.getTools?.() ?? [];
+    return tools.some((tool) => tool.name === toolName);
+  }, name);
+  if (!exists) {
+    throw new Error(`Expected WebMCP tool "${name}" to be registered.`);
+  }
+}
+async function invokeWebMcpTool(page, name, args) {
+  return page.evaluate(
+    async ({ toolName, input }) => {
+      const context = document.modelContext;
+      const tools = await context?.getTools?.() ?? [];
+      const tool = tools.find((candidate) => candidate.name === toolName);
+      if (!tool || !context?.executeTool) {
+        throw new Error(`WebMCP tool "${toolName}" cannot be invoked.`);
+      }
+      return context.executeTool(tool, JSON.stringify(input));
+    },
+    { toolName: name, input: args }
+  );
+}
+
+export {
+  expectWebMcpTool,
+  invokeWebMcpTool
+};

package/dist/chunk-EG3BG65X.js

@@ -0,0 +1,146 @@
+import {
+  invokeWebMcpTool
+} from "./chunk-6YAIOYYZ.js";
+
+// src/dom-only-inspection.ts
+function pushUnique(target, value) {
+  const trimmed = value?.trim();
+  if (!trimmed || target.includes(trimmed)) {
+    return;
+  }
+  target.push(trimmed);
+}
+function collectDisabledActionReasonsFromDom(root, buttonLabel) {
+  const buttons = [...root.querySelectorAll("button")];
+  const button = buttons.find(
+    (candidate) => candidate.textContent?.includes(buttonLabel)
+  );
+  if (!button) {
+    return {
+      label: buttonLabel,
+      disabled: false,
+      visibleBlockerReasons: []
+    };
+  }
+  const visibleBlockerReasons = [];
+  pushUnique(visibleBlockerReasons, button.getAttribute("title"));
+  pushUnique(
+    visibleBlockerReasons,
+    button.getAttribute("aria-label")?.includes("because") ? button.getAttribute("aria-label") : null
+  );
+  const describedBy = button.getAttribute("aria-describedby");
+  if (describedBy) {
+    for (const id of describedBy.split(/\s+/)) {
+      pushUnique(
+        visibleBlockerReasons,
+        root.getElementById(id)?.textContent
+      );
+    }
+  }
+  const fieldset = button.closest("fieldset");
+  if (fieldset) {
+    pushUnique(
+      visibleBlockerReasons,
+      fieldset.querySelector("legend")?.textContent
+    );
+  }
+  const row = button.closest('[data-testid="checkout-row"]');
+  if (row) {
+    pushUnique(
+      visibleBlockerReasons,
+      row.querySelector("[data-dom-blocker-hint]")?.textContent
+    );
+  }
+  return {
+    label: buttonLabel,
+    disabled: button.disabled,
+    visibleBlockerReasons
+  };
+}
+async function inspectDisabledActionFromDom(page, buttonLabel) {
+  return page.evaluate((label) => {
+    const buttons = [...document.querySelectorAll("button")];
+    const button = buttons.find(
+      (candidate) => candidate.textContent?.includes(label)
+    );
+    if (!button) {
+      return {
+        label,
+        disabled: false,
+        visibleBlockerReasons: []
+      };
+    }
+    const visibleBlockerReasons = [];
+    const push = (value) => {
+      const trimmed = value?.trim();
+      if (trimmed && !visibleBlockerReasons.includes(trimmed)) {
+        visibleBlockerReasons.push(trimmed);
+      }
+    };
+    push(button.getAttribute("title"));
+    const ariaLabel = button.getAttribute("aria-label");
+    if (ariaLabel?.includes("because")) {
+      push(ariaLabel);
+    }
+    const describedBy = button.getAttribute("aria-describedby");
+    if (describedBy) {
+      for (const id of describedBy.split(/\s+/)) {
+        push(document.getElementById(id)?.textContent);
+      }
+    }
+    const fieldset = button.closest("fieldset");
+    if (fieldset) {
+      push(fieldset.querySelector("legend")?.textContent);
+    }
+    const row = button.closest('[data-testid="checkout-row"]');
+    if (row) {
+      push(row.querySelector("[data-dom-blocker-hint]")?.textContent);
+    }
+    return {
+      label,
+      disabled: button.disabled,
+      visibleBlockerReasons
+    };
+  }, buttonLabel);
+}
+
+// src/comparative-proof.ts
+async function diagnoseCheckoutBlockerFromDomOnly(page, buttonLabel) {
+  return inspectDisabledActionFromDom(page, buttonLabel);
+}
+async function diagnoseCheckoutBlockerFromWebMcp(page, actionId, toolName = "why_is_action_unavailable") {
+  const result = await invokeWebMcpTool(page, toolName, { actionId });
+  return {
+    actionId: result.actionId,
+    available: result.available,
+    reasons: result.reasons ?? []
+  };
+}
+async function runComparativeProof(page, options) {
+  const domOnly = await diagnoseCheckoutBlockerFromDomOnly(
+    page,
+    options.buttonLabel
+  );
+  const webMcp = await diagnoseCheckoutBlockerFromWebMcp(
+    page,
+    options.actionId,
+    options.toolName
+  );
+  const domBlockerCount = domOnly.visibleBlockerReasons.length;
+  const webMcpBlockerCount = webMcp.reasons.length;
+  return {
+    domOnly,
+    webMcp,
+    domBlockerCount,
+    webMcpBlockerCount,
+    webMcpIsStrictlyMoreInformative: domOnly.disabled && domBlockerCount === 0 && webMcpBlockerCount > 0 && !webMcp.available
+  };
+}
+
+export {
+  collectDisabledActionReasonsFromDom,
+  inspectDisabledActionFromDom,
+  diagnoseCheckoutBlockerFromDomOnly,
+  diagnoseCheckoutBlockerFromWebMcp,
+  runComparativeProof
+};

package/dist/comparative-proof-QUN7C3KM.js

@@ -0,0 +1,11 @@
+import {
+  diagnoseCheckoutBlockerFromDomOnly,
+  diagnoseCheckoutBlockerFromWebMcp,
+  runComparativeProof
+} from "./chunk-EG3BG65X.js";
+import "./chunk-6YAIOYYZ.js";
+export {
+  diagnoseCheckoutBlockerFromDomOnly,
+  diagnoseCheckoutBlockerFromWebMcp,
+  runComparativeProof
+};

package/dist/comparative-proof.d.ts

@@ -0,0 +1,22 @@
+import { invokeWebMcpTool } from './browser-helpers';
+import { inspectDisabledActionFromDom, type DisabledActionDomFinding } from './dom-only-inspection';
+export interface WebMcpActionDiagnosis {
+    actionId: string;
+    available: boolean;
+    reasons: string[];
+}
+export interface ComparativeProofResult {
+    domOnly: DisabledActionDomFinding;
+    webMcp: WebMcpActionDiagnosis;
+    domBlockerCount: number;
+    webMcpBlockerCount: number;
+    webMcpIsStrictlyMoreInformative: boolean;
+}
+export declare function diagnoseCheckoutBlockerFromDomOnly(page: Parameters<typeof inspectDisabledActionFromDom>[0], buttonLabel: string): Promise<DisabledActionDomFinding>;
+export declare function diagnoseCheckoutBlockerFromWebMcp(page: Parameters<typeof invokeWebMcpTool>[0], actionId: string, toolName?: string): Promise<WebMcpActionDiagnosis>;
+export declare function runComparativeProof(page: Parameters<typeof inspectDisabledActionFromDom>[0], options: {
+    buttonLabel: string;
+    actionId: string;
+    toolName?: string;
+}): Promise<ComparativeProofResult>;
+//# sourceMappingURL=comparative-proof.d.ts.map

package/dist/comparative-proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparative-proof.d.ts","sourceRoot":"","sources":["../src/comparative-proof.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,4BAA4B,EAC5B,KAAK,wBAAwB,EAC9B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,wBAAwB,CAAC;IAClC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,+BAA+B,EAAE,OAAO,CAAC;CAC1C;AAED,wBAAsB,kCAAkC,CACtD,IAAI,EAAE,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,CAAC,EACxD,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,wBAAwB,CAAC,CAEnC;AAED,wBAAsB,iCAAiC,CACrD,IAAI,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAA8B,GACrC,OAAO,CAAC,qBAAqB,CAAC,CAYhC;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,CAAC,EACxD,OAAO,EAAE;IACP,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,sBAAsB,CAAC,CAyBjC"}

package/dist/comparative-proof.js

@@ -0,0 +1,29 @@
+import { invokeWebMcpTool } from './browser-helpers';
+import { inspectDisabledActionFromDom, } from './dom-only-inspection';
+export async function diagnoseCheckoutBlockerFromDomOnly(page, buttonLabel) {
+    return inspectDisabledActionFromDom(page, buttonLabel);
+}
+export async function diagnoseCheckoutBlockerFromWebMcp(page, actionId, toolName = 'why_is_action_unavailable') {
+    const result = await invokeWebMcpTool(page, toolName, { actionId });
+    return {
+        actionId: result.actionId,
+        available: result.available,
+        reasons: result.reasons ?? [],
+    };
+}
+export async function runComparativeProof(page, options) {
+    const domOnly = await diagnoseCheckoutBlockerFromDomOnly(page, options.buttonLabel);
+    const webMcp = await diagnoseCheckoutBlockerFromWebMcp(page, options.actionId, options.toolName);
+    const domBlockerCount = domOnly.visibleBlockerReasons.length;
+    const webMcpBlockerCount = webMcp.reasons.length;
+    return {
+        domOnly,
+        webMcp,
+        domBlockerCount,
+        webMcpBlockerCount,
+        webMcpIsStrictlyMoreInformative: domOnly.disabled &&
+            domBlockerCount === 0 &&
+            webMcpBlockerCount > 0 &&
+            !webMcp.available,
+    };
+}

package/dist/devtools-mcp-helper.d.ts

@@ -0,0 +1,17 @@
+export interface WebMcpToolListing {
+    name: string;
+    description?: string | undefined;
+}
+type ModelContextHost = Document | Navigator;
+/**
+ * Lists registered WebMCP tools from the browser model context.
+ * Returns an empty array when WebMCP is unavailable (e.g. CI without Chrome 149).
+ */
+export declare function listWebMcpTools(host?: ModelContextHost): Promise<WebMcpToolListing[]>;
+/**
+ * Executes a registered WebMCP tool by name.
+ * Throws when WebMCP is unavailable or the tool cannot be resolved.
+ */
+export declare function executeWebMcpTool(name: string, args?: unknown, host?: ModelContextHost): Promise<unknown>;
+export {};
+//# sourceMappingURL=devtools-mcp-helper.d.ts.map

package/dist/devtools-mcp-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devtools-mcp-helper.d.ts","sourceRoot":"","sources":["../src/devtools-mcp-helper.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,KAAK,gBAAgB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAsB7C;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,GAAE,gBAA2B,GAChC,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAW9B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,OAAY,EAClB,IAAI,GAAE,gBAA2B,GAChC,OAAO,CAAC,OAAO,CAAC,CAelB"}

package/dist/devtools-mcp-helper.js

@@ -0,0 +1,34 @@
+function getModelContext(host = document) {
+    return host.modelContext;
+}
+/**
+ * Lists registered WebMCP tools from the browser model context.
+ * Returns an empty array when WebMCP is unavailable (e.g. CI without Chrome 149).
+ */
+export async function listWebMcpTools(host = document) {
+    const context = getModelContext(host);
+    if (!context?.getTools) {
+        return [];
+    }
+    const tools = await context.getTools();
+    return tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+    }));
+}
+/**
+ * Executes a registered WebMCP tool by name.
+ * Throws when WebMCP is unavailable or the tool cannot be resolved.
+ */
+export async function executeWebMcpTool(name, args = {}, host = document) {
+    const context = getModelContext(host);
+    if (!context?.getTools || !context.executeTool) {
+        throw new Error('WebMCP model context is unavailable. Use installModelContextMock() in tests.');
+    }
+    const tools = await context.getTools();
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (!tool) {
+        throw new Error(`WebMCP tool not found: ${name}`);
+    }
+    return context.executeTool(tool, JSON.stringify(args));
+}

package/dist/dom-only-inspection.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Simulates what a DOM-only agent can infer about disabled actions.
+ * Mirrors accessibility-tree inspection: labels, aria-* , title, nearby text.
+ */
+import type { WebMcpTestPage } from './browser-helpers';
+export interface DisabledActionDomFinding {
+    label: string;
+    disabled: boolean;
+    visibleBlockerReasons: string[];
+}
+export declare function collectDisabledActionReasonsFromDom(root: Pick<Document, 'querySelectorAll' | 'getElementById'>, buttonLabel: string): DisabledActionDomFinding;
+export declare function inspectDisabledActionFromDom(page: WebMcpTestPage, buttonLabel: string): Promise<DisabledActionDomFinding>;
+//# sourceMappingURL=dom-only-inspection.d.ts.map

package/dist/dom-only-inspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-only-inspection.d.ts","sourceRoot":"","sources":["../src/dom-only-inspection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC;AAWD,wBAAgB,mCAAmC,CACjD,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,kBAAkB,GAAG,gBAAgB,CAAC,EAC3D,WAAW,EAAE,MAAM,GAClB,wBAAwB,CAsD1B;AAED,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,wBAAwB,CAAC,CAoDnC"}

package/dist/dom-only-inspection.js

@@ -0,0 +1,86 @@
+function pushUnique(target, value) {
+    const trimmed = value?.trim();
+    if (!trimmed || target.includes(trimmed)) {
+        return;
+    }
+    target.push(trimmed);
+}
+export function collectDisabledActionReasonsFromDom(root, buttonLabel) {
+    const buttons = [...root.querySelectorAll('button')];
+    const button = buttons.find((candidate) => candidate.textContent?.includes(buttonLabel));
+    if (!button) {
+        return {
+            label: buttonLabel,
+            disabled: false,
+            visibleBlockerReasons: [],
+        };
+    }
+    const visibleBlockerReasons = [];
+    pushUnique(visibleBlockerReasons, button.getAttribute('title'));
+    pushUnique(visibleBlockerReasons, button.getAttribute('aria-label')?.includes('because')
+        ? button.getAttribute('aria-label')
+        : null);
+    const describedBy = button.getAttribute('aria-describedby');
+    if (describedBy) {
+        for (const id of describedBy.split(/\s+/)) {
+            pushUnique(visibleBlockerReasons, root.getElementById(id)?.textContent);
+        }
+    }
+    const fieldset = button.closest('fieldset');
+    if (fieldset) {
+        pushUnique(visibleBlockerReasons, fieldset.querySelector('legend')?.textContent);
+    }
+    const row = button.closest('[data-testid="checkout-row"]');
+    if (row) {
+        pushUnique(visibleBlockerReasons, row.querySelector('[data-dom-blocker-hint]')?.textContent);
+    }
+    return {
+        label: buttonLabel,
+        disabled: button.disabled,
+        visibleBlockerReasons,
+    };
+}
+export async function inspectDisabledActionFromDom(page, buttonLabel) {
+    return page.evaluate((label) => {
+        const buttons = [...document.querySelectorAll('button')];
+        const button = buttons.find((candidate) => candidate.textContent?.includes(label));
+        if (!button) {
+            return {
+                label,
+                disabled: false,
+                visibleBlockerReasons: [],
+            };
+        }
+        const visibleBlockerReasons = [];
+        const push = (value) => {
+            const trimmed = value?.trim();
+            if (trimmed && !visibleBlockerReasons.includes(trimmed)) {
+                visibleBlockerReasons.push(trimmed);
+            }
+        };
+        push(button.getAttribute('title'));
+        const ariaLabel = button.getAttribute('aria-label');
+        if (ariaLabel?.includes('because')) {
+            push(ariaLabel);
+        }
+        const describedBy = button.getAttribute('aria-describedby');
+        if (describedBy) {
+            for (const id of describedBy.split(/\s+/)) {
+                push(document.getElementById(id)?.textContent);
+            }
+        }
+        const fieldset = button.closest('fieldset');
+        if (fieldset) {
+            push(fieldset.querySelector('legend')?.textContent);
+        }
+        const row = button.closest('[data-testid="checkout-row"]');
+        if (row) {
+            push(row.querySelector('[data-dom-blocker-hint]')?.textContent);
+        }
+        return {
+            label,
+            disabled: button.disabled,
+            visibleBlockerReasons,
+        };
+    }, buttonLabel);
+}

package/dist/dom-only-inspection.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dom-only-inspection.test.d.ts.map

package/dist/dom-only-inspection.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-only-inspection.test.d.ts","sourceRoot":"","sources":["../src/dom-only-inspection.test.ts"],"names":[],"mappings":""}

package/dist/dom-only-inspection.test.js

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { collectDisabledActionReasonsFromDom } from './dom-only-inspection';
+describe('collectDisabledActionReasonsFromDom', () => {
+    it('finds no checkout blockers when none are exposed in the DOM', () => {
+        document.body.innerHTML = `
+      <section data-testid="checkout-row">
+        <p>Status: waiting for customer action.</p>
+        <button disabled type="button">Complete checkout</button>
+      </section>
+    `;
+        const finding = collectDisabledActionReasonsFromDom(document, 'Complete checkout');
+        expect(finding.disabled).toBe(true);
+        expect(finding.visibleBlockerReasons).toEqual([]);
+    });
+    it('finds visible hints when the DOM exposes them', () => {
+        document.body.innerHTML = `
+      <section data-testid="checkout-row">
+        <p data-dom-blocker-hint>Terms must be accepted first.</p>
+        <button disabled type="button">Complete checkout</button>
+      </section>
+    `;
+        const finding = collectDisabledActionReasonsFromDom(document, 'Complete checkout');
+        expect(finding.visibleBlockerReasons).toContain('Terms must be accepted first.');
+    });
+});