@sous-io/sous 0.1.0

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/scripts/debug.mjs

@@ -0,0 +1,383 @@
+/**
+ * ctx.debug — exploration & debugging tools for automation scripts.
+ *
+ * Browser automation fails because authors GUESS about a page (its DOM, its
+ * timing) instead of observing it. These tools make observation cheap, so you
+ * can build condition-based waits and correct selectors from what is actually
+ * on the page. See references/script-conventions.md ("observe the real page").
+ *
+ * Built per-run and bound to the live `page`/`logger`. Artifacts (screenshots,
+ * HTML, snapshots) are written under a per-run debug directory so repeated runs
+ * don't clobber each other.
+ *
+ * Pure formatting helpers (no page I/O) are exported separately so they can be
+ * unit-tested without a browser.
+ */
+
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+/**
+ * Build the debug toolkit for a run.
+ *
+ * @param {import('playwright').Page} page
+ * @param {object} logger - The script's logger (a child is created internally).
+ * @param {object} [opts]
+ * @param {string} [opts.dir] - Directory for artifacts. Defaults to a unique
+ *   subdir of the OS temp dir.
+ * @param {string} [opts.runId] - Identifier mixed into the default dir name.
+ * @returns {object} the ctx.debug surface
+ */
+export function createDebug(page, logger, opts = {}) {
+  const log = logger.child('debug');
+  const dir = opts.dir || join(tmpdir(), 'sous-browser-debug', opts.runId || defaultRunId());
+  let dirReady = false;
+
+  /** Lazily create the artifact dir only when something is actually written. */
+  function ensureDir() {
+    if (!dirReady) {
+      mkdirSync(dir, { recursive: true });
+      dirReady = true;
+    }
+    return dir;
+  }
+
+  /** Resolve an artifact path, creating the dir on demand. */
+  function artifact(name, ext) {
+    return join(ensureDir(), `${slug(name)}.${ext}`);
+  }
+
+  return {
+    /** Absolute path to this run's debug artifact directory. */
+    get dir() {
+      return dir;
+    },
+
+    /**
+     * Save a screenshot. Never throws (a debug aid must not break a run).
+     *
+     * @param {string} [name='screenshot']
+     * @param {object} [o] - { fullPage }
+     * @returns {Promise<string|null>} path written, or null on failure
+     */
+    async screenshot(name = 'screenshot', o = {}) {
+      const { fullPage = true } = o;
+      const path = artifact(name, 'png');
+      try {
+        await page.screenshot({ path, fullPage });
+        log.info(`screenshot → ${path}`);
+        return path;
+      } catch (err) {
+        log.warn(`screenshot failed: ${err.message}`);
+        return null;
+      }
+    },
+
+    /**
+     * Save the page's current HTML. Never throws.
+     *
+     * @param {string} [name='page']
+     * @returns {Promise<string|null>} path written, or null on failure
+     */
+    async html(name = 'page') {
+      const path = artifact(name, 'html');
+      try {
+        writeFileSync(path, await page.content());
+        log.info(`html → ${path}`);
+        return path;
+      } catch (err) {
+        log.warn(`html failed: ${err.message}`);
+        return null;
+      }
+    },
+
+    /**
+     * Capture a full snapshot — URL, title, visible text, screenshot, and HTML —
+     * to the debug dir, and log a concise summary. The go-to "what does this page
+     * look like right now?" tool and the basis of failure auto-capture.
+     *
+     * @param {string} [name='dump']
+     * @returns {Promise<object>} { dir, url, title, files, textPreview }
+     */
+    async dump(name = 'dump') {
+      ensureDir();
+      const url = safeCall(() => page.url(), '(unknown url)');
+      const title = await safeAsync(() => page.title(), '(unknown title)');
+      const text = (await safeAsync(() => page.evaluate(() => document.body?.innerText || ''), '')).trim();
+      const textPath = artifact(`${name}-text`, 'txt');
+      writeFileSync(textPath, `URL: ${url}\nTITLE: ${title}\n\n${text}`);
+      const shot = await this.screenshot(`${name}-screenshot`);
+      const htmlPath = await this.html(`${name}-page`);
+      log.info(`dump "${name}": ${url} — ${title}`);
+      log.info(`  text(${text.length}c) → ${textPath}`);
+      return {
+        dir,
+        url,
+        title,
+        files: { text: textPath, screenshot: shot, html: htmlPath },
+        textPreview: truncate(text, 500),
+      };
+    },
+
+    /**
+     * Describe what a selector matches: how many, and for the first few, their
+     * tag/role/text/visibility/box. The fastest way to learn whether a selector
+     * is right and what it actually targets.
+     *
+     * @param {string} selector - A CSS selector.
+     * @param {object} [o] - { limit }
+     * @returns {Promise<{count:number, elements:object[]}>}
+     */
+    async describe(selector, o = {}) {
+      const { limit = 5 } = o;
+      const data = await safeAsync(
+        () => page.$$eval(selector, (els, lim) => els.slice(0, lim).map((el) => ({
+          tag: el.tagName,
+          role: el.getAttribute('role'),
+          id: el.id || null,
+          classes: (el.className || '').toString().slice(0, 80),
+          text: (el.textContent || '').trim().slice(0, 80),
+          visible: !!(el.offsetWidth || el.offsetHeight || el.getClientRects().length),
+          href: el.getAttribute('href'),
+        })), limit),
+        []
+      );
+      const count = await safeAsync(() => page.$$eval(selector, (els) => els.length), 0);
+      log.info(`describe "${selector}": ${count} match(es)`);
+      for (const el of data) log.info(`  ${formatElement(el)}`);
+      return { count, elements: data };
+    },
+
+    /**
+     * List interactive/clickable elements on the page (anchors, buttons, role
+     * buttons/tabs/links, elements with cursor:pointer). Invaluable when the
+     * obvious selector (e.g. an `<a href>`) doesn't exist and the real control is
+     * a click-handled div.
+     *
+     * @param {object} [o] - { limit }
+     * @returns {Promise<object[]>}
+     */
+    async clickables(o = {}) {
+      const { limit = 40 } = o;
+      const els = await safeAsync(
+        () => page.evaluate((lim) => {
+          const sel = 'a, button, [role="button"], [role="tab"], [role="link"], [role="menuitem"], [onclick]';
+          const out = [];
+          for (const el of document.querySelectorAll(sel)) {
+            const visible = !!(el.offsetWidth || el.offsetHeight || el.getClientRects().length);
+            if (!visible) continue;
+            const text = (el.textContent || '').trim();
+            out.push({
+              tag: el.tagName,
+              role: el.getAttribute('role'),
+              href: el.getAttribute('href'),
+              text: text.slice(0, 60),
+            });
+            if (out.length >= lim) break;
+          }
+          return out;
+        }, limit),
+        []
+      );
+      log.info(`clickables: ${els.length} visible interactive element(s)`);
+      for (const el of els) log.info(`  ${formatElement(el)}`);
+      return els;
+    },
+
+    /**
+     * Find where some text lives. Returns, for each text match, the leaf element
+     * and its clickable ancestor (the thing you probably want to click). Solves
+     * "I can see the text but what do I target?".
+     *
+     * @param {string|RegExp} pattern
+     * @param {object} [o] - { limit }
+     * @returns {Promise<object[]>}
+     */
+    async findText(pattern, o = {}) {
+      const { limit = 10 } = o;
+      const { source, flags } = regexParts(pattern);
+      const hits = await safeAsync(
+        () => page.evaluate((args) => {
+          const re = new RegExp(args.source, args.flags);
+          const clickableSel = 'a,button,[role="button"],[role="tab"],[role="link"],[onclick]';
+          const isClickable = (el) =>
+            el.matches(clickableSel) || getComputedStyle(el).cursor === 'pointer';
+          // Match the element that DIRECTLY owns the text (in its own text nodes),
+          // not childless leaves only — text can sit on an element that also has
+          // element children (e.g. a tab label beside an icon). Matching own-text
+          // also avoids reporting every ancestor up the tree for one string.
+          const ownText = (el) =>
+            [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => n.textContent).join('');
+          const out = [];
+          const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
+          while (walker.nextNode()) {
+            const el = walker.currentNode;
+            if (re.test(ownText(el))) {
+              let anc = el, depth = 0;
+              while (anc && depth < 8 && !isClickable(anc)) { anc = anc.parentElement; depth += 1; }
+              out.push({
+                text: (el.textContent || '').trim().slice(0, 60),
+                leafTag: el.tagName,
+                clickableAncestor: anc
+                  ? { tag: anc.tagName, role: anc.getAttribute('role'), classes: (anc.className || '').toString().slice(0, 60) }
+                  : null,
+              });
+              if (out.length >= args.limit) break;
+            }
+          }
+          return out;
+        }, { source, flags, limit }),
+        []
+      );
+      log.info(`findText ${pattern}: ${hits.length} match(es)`);
+      for (const h of hits) {
+        const anc = h.clickableAncestor ? ` → clickable<${h.clickableAncestor.tag}${h.clickableAncestor.role ? ` role=${h.clickableAncestor.role}` : ''}>` : ' (no clickable ancestor)';
+        log.info(`  "${h.text}" [${h.leafTag}]${anc}`);
+      }
+      return hits;
+    },
+
+    /**
+     * Sample a page metric repeatedly over time and log how it evolves. Built to
+     * answer "WHEN is this actually ready?" — the question that exposes why
+     * `networkidle` lies and where a real readiness signal lives.
+     *
+     * @param {() => any} fn - Runs in the BROWSER; returns a JSON-serializable metric.
+     *   e.g. `() => document.body.innerText.length`
+     * @param {object} [o] - { samples=10, intervalMs=500, label='metric' }
+     * @returns {Promise<Array<{t:number, value:any}>>}
+     */
+    async watch(fn, o = {}) {
+      const { samples = 10, intervalMs = 500, label = 'metric' } = o;
+      const series = [];
+      for (let i = 0; i < samples; i++) {
+        const value = await safeAsync(() => page.evaluate(fn), null);
+        const t = i * intervalMs;
+        series.push({ t, value });
+        log.info(`watch[${label}] +${t}ms: ${formatValue(value)}`);
+        if (i < samples - 1) await page.waitForTimeout(intervalMs);
+      }
+      return series;
+    },
+
+    /**
+     * Quick count of elements matching a selector.
+     *
+     * @param {string} selector
+     * @returns {Promise<number>}
+     */
+    async count(selector) {
+      const n = await safeAsync(() => page.$$eval(selector, (els) => els.length), 0);
+      log.info(`count "${selector}": ${n}`);
+      return n;
+    },
+  };
+}
+
+// --- Pure helpers (no page I/O; unit-tested) -------------------------------
+
+/**
+ * Filesystem-safe slug for artifact filenames.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function slug(name) {
+  return String(name)
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'debug';
+}
+
+/**
+ * Truncate a string, appending an ellipsis + original length when cut.
+ *
+ * @param {string} s
+ * @param {number} max
+ * @returns {string}
+ */
+export function truncate(s, max) {
+  const str = String(s ?? '');
+  if (str.length <= max) return str;
+  return `${str.slice(0, max)}… (${str.length} chars total)`;
+}
+
+/**
+ * Format a single element-summary object into a one-line string.
+ *
+ * @param {object} el - { tag, role, id, classes, text, visible, href }
+ * @returns {string}
+ */
+export function formatElement(el) {
+  const parts = [String(el.tag || '?').toLowerCase()];
+  if (el.role) parts.push(`role=${el.role}`);
+  if (el.id) parts.push(`#${el.id}`);
+  if (el.href) parts.push(`href=${truncate(el.href, 40)}`);
+  if (el.visible === false) parts.push('(hidden)');
+  const tag = parts.join(' ');
+  return el.text ? `${tag} — "${truncate(el.text, 60)}"` : tag;
+}
+
+/**
+ * Format a watch() sample value compactly for logging.
+ *
+ * @param {any} v
+ * @returns {string}
+ */
+export function formatValue(v) {
+  if (v === null || v === undefined) return String(v);
+  if (typeof v === 'object') return truncate(JSON.stringify(v), 120);
+  return String(v);
+}
+
+/**
+ * Decompose a string|RegExp pattern into source + flags for cross-context
+ * (browser) reconstruction.
+ *
+ * @param {string|RegExp} pattern
+ * @returns {{source:string, flags:string}}
+ */
+export function regexParts(pattern) {
+  if (pattern instanceof RegExp) return { source: pattern.source, flags: pattern.flags };
+  return { source: escapeRegExp(String(pattern)), flags: 'i' };
+}
+
+/**
+ * Escape a string for literal use inside a RegExp.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function escapeRegExp(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * A short, sortable-ish run id derived from high-res time (no Date dependency at
+ * module load; called only when a debug dir is actually needed).
+ *
+ * @returns {string}
+ */
+function defaultRunId() {
+  return `run-${process.pid}-${Math.floor(performance.now())}`;
+}
+
+/** Run a sync fn, returning a fallback if it throws. */
+function safeCall(fn, fallback) {
+  try {
+    return fn();
+  } catch {
+    return fallback;
+  }
+}
+
+/** Await an async fn, returning a fallback if it throws. */
+async function safeAsync(fn, fallback) {
+  try {
+    return await fn();
+  } catch {
+    return fallback;
+  }
+}

package/shared-prompts/skills/automated-browser-tasks/about-automated-browser-tasks/scripts/debug.spec.mjs

@@ -0,0 +1,267 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { existsSync, readFileSync, rmSync, mkdtempSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import {
+  createDebug,
+  slug,
+  truncate,
+  formatElement,
+  formatValue,
+  regexParts,
+  escapeRegExp,
+} from './debug.mjs';
+
+// --- Pure helpers ----------------------------------------------------------
+
+describe('slug()', () => {
+  it('replaces unsafe characters with dashes', () => {
+    expect(slug('Foo Bar/baz!!')).toBe('Foo-Bar-baz');
+  });
+  it('trims leading/trailing dashes', () => {
+    expect(slug('  !!hi!!  ')).toBe('hi');
+  });
+  it('falls back to "debug" for empty/blank input', () => {
+    expect(slug('   ')).toBe('debug');
+    expect(slug('')).toBe('debug');
+  });
+  it('caps length at 80 chars', () => {
+    expect(slug('a'.repeat(200)).length).toBe(80);
+  });
+});
+
+describe('truncate()', () => {
+  it('returns the string unchanged when within max', () => {
+    expect(truncate('hello', 10)).toBe('hello');
+  });
+  it('cuts and annotates with total length when over max', () => {
+    expect(truncate('abcdefghij', 5)).toBe('abcde… (10 chars total)');
+  });
+  it('handles null/undefined as empty', () => {
+    expect(truncate(null, 5)).toBe('');
+    expect(truncate(undefined, 5)).toBe('');
+  });
+});
+
+describe('formatElement()', () => {
+  it('formats tag, role, href, and text', () => {
+    expect(formatElement({ tag: 'A', role: 'tab', href: '/x', text: 'Checks', visible: true }))
+      .toBe('a role=tab href=/x — "Checks"');
+  });
+  it('marks hidden elements', () => {
+    expect(formatElement({ tag: 'DIV', visible: false, text: '' })).toBe('div (hidden)');
+  });
+  it('omits text segment when there is no text', () => {
+    expect(formatElement({ tag: 'BUTTON', visible: true })).toBe('button');
+  });
+});
+
+describe('formatValue()', () => {
+  it('stringifies objects compactly', () => {
+    expect(formatValue({ a: 1 })).toBe('{"a":1}');
+  });
+  it('passes through scalars', () => {
+    expect(formatValue(42)).toBe('42');
+    expect(formatValue(null)).toBe('null');
+    expect(formatValue(undefined)).toBe('undefined');
+  });
+});
+
+describe('regexParts() / escapeRegExp()', () => {
+  it('decomposes a RegExp into source + flags', () => {
+    expect(regexParts(/SUCCEEDED|FAILED/i)).toEqual({ source: 'SUCCEEDED|FAILED', flags: 'i' });
+  });
+  it('escapes a string pattern and defaults to case-insensitive', () => {
+    expect(regexParts('a.b')).toEqual({ source: 'a\\.b', flags: 'i' });
+  });
+  it('escapeRegExp escapes regex metacharacters', () => {
+    expect(escapeRegExp('a.b*c')).toBe('a\\.b\\*c');
+  });
+});
+
+// --- Page-driven tools (fake page) -----------------------------------------
+
+/** A logger that records messages instead of printing. */
+function fakeLogger() {
+  const messages = [];
+  const mk = () => ({
+    info: (m) => messages.push(`info:${m}`),
+    warn: (m) => messages.push(`warn:${m}`),
+    error: (m) => messages.push(`error:${m}`),
+    child: () => mk(),
+  });
+  const l = mk();
+  l.messages = messages;
+  return l;
+}
+
+/** A configurable fake Playwright Page recording what the tools ask of it. */
+function fakePage(overrides = {}) {
+  const calls = { screenshot: [], evaluate: 0, waitForTimeout: [] };
+  return {
+    calls,
+    url: () => overrides.url ?? 'https://example.com/page',
+    title: async () => overrides.title ?? 'Example Title',
+    content: async () => overrides.content ?? '<html><body>hi</body></html>',
+    async screenshot(o) {
+      calls.screenshot.push(o);
+      if (overrides.screenshotThrows) throw new Error('boom');
+      // emulate playwright writing the file
+      const { writeFileSync } = await import('fs');
+      writeFileSync(o.path, 'PNG');
+    },
+    async evaluate(fn, arg) {
+      calls.evaluate += 1;
+      if (typeof overrides.evaluate === 'function') return overrides.evaluate(fn, arg);
+      return overrides.evaluateResult ?? null;
+    },
+    async $$eval(sel, fn, arg) {
+      if (typeof overrides.$$eval === 'function') return overrides.$$eval(sel, fn, arg);
+      return overrides.$$evalResult ?? [];
+    },
+    async waitForTimeout(ms) {
+      calls.waitForTimeout.push(ms);
+    },
+  };
+}
+
+describe('createDebug() — artifacts', () => {
+  let dir;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'debug-spec-'));
+  });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('does not create the dir until something is written', () => {
+    const sub = join(dir, 'lazy');
+    createDebug(fakePage(), fakeLogger(), { dir: sub });
+    expect(existsSync(sub)).toBe(false);
+  });
+
+  it('screenshot writes a .png and returns its path', async () => {
+    const debug = createDebug(fakePage(), fakeLogger(), { dir });
+    const path = await debug.screenshot('shot one');
+    expect(path).toBe(join(dir, 'shot-one.png'));
+    expect(existsSync(path)).toBe(true);
+  });
+
+  it('screenshot returns null (never throws) on failure', async () => {
+    const debug = createDebug(fakePage({ screenshotThrows: true }), fakeLogger(), { dir });
+    expect(await debug.screenshot('x')).toBeNull();
+  });
+
+  it('html writes page content to a .html file', async () => {
+    const debug = createDebug(fakePage({ content: '<p>real</p>' }), fakeLogger(), { dir });
+    const path = await debug.html('snap');
+    expect(readFileSync(path, 'utf8')).toBe('<p>real</p>');
+  });
+
+  it('dump captures url/title/text and writes a text artifact', async () => {
+    const page = fakePage({ url: 'https://x/y', title: 'T', evaluateResult: 'BODY TEXT' });
+    const debug = createDebug(page, fakeLogger(), { dir });
+    const snap = await debug.dump('d');
+    expect(snap.url).toBe('https://x/y');
+    expect(snap.title).toBe('T');
+    expect(snap.textPreview).toContain('BODY TEXT');
+    expect(readFileSync(snap.files.text, 'utf8')).toContain('BODY TEXT');
+    expect(existsSync(snap.files.screenshot)).toBe(true);
+  });
+});
+
+describe('createDebug() — inspection tools', () => {
+  let dir;
+  beforeEach(() => { dir = mkdtempSync(join(tmpdir(), 'debug-spec-')); });
+  afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+  it('describe reports count and per-element summaries', async () => {
+    const els = [{ tag: 'A', role: 'tab', text: 'Checks', visible: true }];
+    const page = fakePage({
+      $$eval: (_sel, _fn, arg) => (typeof arg === 'number' ? els : els.length),
+    });
+    const debug = createDebug(page, fakeLogger(), { dir });
+    const out = await debug.describe('a', { limit: 5 });
+    expect(out.count).toBe(1);
+    expect(out.elements[0].text).toBe('Checks');
+  });
+
+  it('count returns the number of matches', async () => {
+    const debug = createDebug(fakePage({ $$evalResult: 7 }), fakeLogger(), { dir });
+    expect(await debug.count('div')).toBe(7);
+  });
+
+  it('clickables returns the evaluated list', async () => {
+    const list = [{ tag: 'BUTTON', text: 'Go' }];
+    const debug = createDebug(fakePage({ evaluateResult: list }), fakeLogger(), { dir });
+    expect(await debug.clickables()).toEqual(list);
+  });
+
+  it('watch samples the metric N times and spaces them by interval', async () => {
+    let n = 0;
+    const page = fakePage({ evaluate: () => ++n });
+    const debug = createDebug(page, fakeLogger(), { dir });
+    const series = await debug.watch(() => 0, { samples: 3, intervalMs: 250, label: 'len' });
+    expect(series.map((s) => s.value)).toEqual([1, 2, 3]);
+    expect(series.map((s) => s.t)).toEqual([0, 250, 500]);
+    // waits between samples only (N-1 times)
+    expect(page.calls.waitForTimeout).toEqual([250, 250]);
+  });
+
+  it('tools degrade gracefully when the page throws', async () => {
+    const page = fakePage({ evaluate: () => { throw new Error('nope'); }, $$eval: () => { throw new Error('nope'); } });
+    const debug = createDebug(page, fakeLogger(), { dir });
+    expect(await debug.count('x')).toBe(0);
+    expect(await debug.clickables()).toEqual([]);
+    expect((await debug.describe('x')).count).toBe(0);
+  });
+
+  it('findText passes the pattern source/flags through to the page', async () => {
+    let received;
+    const page = fakePage({ evaluate: (_fn, arg) => { received = arg; return []; } });
+    const debug = createDebug(page, fakeLogger(), { dir });
+    await debug.findText(/SUCCEEDED|FAILED/i, { limit: 3 });
+    expect(received).toMatchObject({ source: 'SUCCEEDED|FAILED', flags: 'i', limit: 3 });
+  });
+
+  it('findText returns whatever the page evaluation yields', async () => {
+    const hits = [{ text: 'Checks', leafTag: 'DIV', clickableAncestor: { tag: 'DIV', role: 'tab' } }];
+    const debug = createDebug(fakePage({ evaluateResult: hits }), fakeLogger(), { dir });
+    expect(await debug.findText('Checks')).toEqual(hits);
+  });
+});
+
+/**
+ * The own-text matching rule that findText runs in-browser, replicated here as a
+ * pure check. This is the logic that the leaf-only version got wrong: an element
+ * may own a matching text node AND have element children (e.g. a tab label beside
+ * an icon). The in-browser behavior itself is covered by live tests.
+ */
+describe('findText own-text matching rule', () => {
+  // Mirror of the in-browser predicate: match on an element's OWN text nodes.
+  const ownText = (node) => (node.childNodes || [])
+    .filter((n) => n.nodeType === 3)
+    .map((n) => n.textContent)
+    .join('');
+  const matches = (node, re) => re.test(ownText(node));
+
+  it('matches an element whose own text node holds the pattern, even with element children', () => {
+    // <div role=tab>"Checks"<span(icon)/></div>  — a common real-world tab shape.
+    const tab = {
+      childNodes: [
+        { nodeType: 3, textContent: 'Checks' },
+        { nodeType: 1, textContent: '' }, // icon element child
+      ],
+    };
+    expect(matches(tab, /Checks/i)).toBe(true);
+  });
+
+  it('does NOT match an ancestor whose text comes only from descendants', () => {
+    // A wrapper with no own text nodes — only an element child that contains text.
+    const wrapper = { childNodes: [{ nodeType: 1, textContent: 'Checks' }] };
+    expect(matches(wrapper, /Checks/i)).toBe(false);
+  });
+
+  it('matches a plain leaf', () => {
+    const leaf = { childNodes: [{ nodeType: 3, textContent: 'SUCCEEDED' }] };
+    expect(matches(leaf, /SUCCEEDED/)).toBe(true);
+  });
+});