testaro 78.4.0 → 78.6.0

package/validation/act/capture.js

@@ -23,9 +23,12 @@
       [--rules id,id] [--max N] [--out path.jsonl]
       [--urls path.txt] [--recycle N]
 
-  Each output line: {testcaseId, ruleId, expected, engine, prevented,
-  instanceCount, outcomeTotals: {failed, cantTell}, asserted: {SC: count},
-  review: {SC: count}, ruleIDs: {engineRuleID: count}, ms}
+  First line is a header {header: true, capturedAt, mode, engines,
+  engineVersions, testaro, forkCommit, playwright}; scorers skip rows without
+  a testcaseId. Each further line: {testcaseId, ruleId, expected, engine,
+  prevented, instanceCount, outcomeTotals: {failed, cantTell},
+  asserted: {SC: count}, review: {SC: count}, ruleIDs: {engineRuleID: count},
+  ruleOutcomes: {engineRuleID: {failed, cantTell}}, ms}
   `asserted` counts definite failures (standard-instance outcome `failed`);
   `review` counts engine-flagged uncertainty (outcome `cantTell`). Criteria
   are dotted WCAG SC numbers, extracted per engine from native results;
@@ -49,6 +52,50 @@ const CACHE_DIR = path.join(__dirname, 'cache');
 const RESULTS_DIR = path.join(__dirname, 'results');
 // Per-reporter time limit, matching the production limits in procs/doActs.js.
 const REPORTER_TIMEOUT_MS = 45000;
+/*
+  Failures that say nothing about the engine: the fixture host was
+  unreachable, or the browser wedged. Such a row is retried in place a few
+  times (fixtures are fetched live from w3.org, and a flaky uplink drops for
+  seconds at a time) and, if still failing, is recaptured by a later resumed
+  run instead of being treated as captured.
+*/
+const RETRYABLE_ERROR = /ERR_INTERNET_DISCONNECTED|ERR_NAME_NOT_RESOLVED|ERR_CONNECTION|ERR_NETWORK_CHANGED|ERR_TIMED_OUT|Timeout \d+ms exceeded|newPage deadline|reporter timeout|has been closed|Protocol error/;
+const NETWORK_RETRIES = 3;
+const NETWORK_RETRY_DELAY_MS = 15000;
+// The testaro tool runs ~45 rules (screenshots, hover, motion) in its own
+// browser: seconds on a fixture, minutes on a heavy real page.
+const TESTARO_TIMEOUT_MS = 180000;
+const TESTARO_URL_TIMEOUT_MS = 600000;
+
+/*
+  The testaro tool is not a page-injected reporter: its rules launch and
+  navigate their own browser through procs/launch.js and validate the job
+  they are given. So it is run through doJob() with a minimal valid job, as
+  validation/validateTest.js does, and its test act is read back.
+*/
+let testaroJobCount = 0;
+const testaroJob = (url, timeLimit = 120) => {
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/^\d\d(\d{6})T(\d{4}).*$/, '$1T$2');
+  // The id names doJob's temporary directory, so it must be unique across
+  // fixtures and across concurrent capture processes.
+  testaroJobCount++;
+  return {
+    id: `${stamp}-act-${process.pid}-${testaroJobCount}`,
+    what: 'ACT fixture capture (testaro)',
+    strict: false,
+    standard: 'also',
+    observe: false,
+    device: {id: 'default', windowOptions: {reducedMotion: 'no-preference'}},
+    browserID: 'chromium',
+    timeLimit,
+    creationTimeStamp: stamp,
+    executionTimeStamp: stamp,
+    sendReportTo: '',
+    target: {what: 'ACT fixture', url},
+    sources: {script: 'act', batch: 'act', mergeID: 'act', requester: ''},
+    acts: [{type: 'test', which: 'testaro', withItems: true, stopOnFail: false}]
+  };
+};
 
 // Mirrors procs/doTestAct.js xPathNeeds for the engines this harness supports.
 const XPATH_NEEDS = {
@@ -153,6 +200,216 @@ const ruleIDCounts = standardResult => {
   return counts;
 };
 
+// Per-rule certainty bands: {ruleID: {failed, cantTell}} from instance outcomes.
+// Lets a scorer join rules to ACT rule ids without a criterion extractor.
+const ruleOutcomeCounts = standardResult => {
+  const bands = {};
+  ((standardResult && standardResult.instances) || []).forEach(instance => {
+    const band = bands[instance.ruleID] ??= {failed: 0, cantTell: 0};
+    if (instance.outcome === 'failed' || instance.outcome === 'cantTell') {
+      band[instance.outcome] += instance.count || 1;
+    }
+  });
+  return bands;
+};
+
+/*
+  URL mode: one snapshot row per page, taken after every engine has run,
+  holding the DOM context of each element any engine flagged. Element
+  identity is the normalized XPath the engines already share, so one
+  snapshot serves every engine's instances (including the testaro tool,
+  whose own browser is gone by then). Bounded per page and per element.
+*/
+const SNAPSHOT_MAX_ELEMENTS = 400;
+const SNAPSHOT_MAX_HTML = 4000;
+// Elements per page for which the (slower) accessibility-tree snapshot is taken.
+const SNAPSHOT_MAX_ARIA = 200;
+/*
+  Snapshot profile version. v1: DOM context (outerHTML, two ancestor shells,
+  computed style subset, box, text) plus the accessibility invariant a
+  reducer must preserve, captured at source rather than reconstructed: the
+  element's own accessibility-tree snapshot (`aria`), the elements its IDREF
+  attributes point at (`refs`), and the structural context outside the
+  element itself (`context`: ancestor roles, table/list position).
+*/
+const SNAPSHOT_PROFILE_VERSION = 1;
+const IDREF_ATTRIBUTES = [
+  'aria-labelledby', 'aria-describedby', 'aria-controls', 'aria-owns', 'aria-activedescendant',
+  'aria-flowto', 'aria-details', 'aria-errormessage', 'headers', 'for', 'list', 'form'
+];
+const snapshotScript = ([xPaths, maxHTML, idrefAttributes]) => {
+  const shell = element => {
+    const attrs = Array.from(element.attributes)
+    .map(attribute => `${attribute.name}="${attribute.value.slice(0, 120)}"`)
+    .join(' ');
+    return `<${element.tagName.toLowerCase()}${attrs ? ` ${attrs}` : ''}>`;
+  };
+  const styleKeys = [
+    'display', 'visibility', 'opacity', 'position', 'color', 'background-color',
+    'font-size', 'font-weight', 'line-height', 'letter-spacing', 'word-spacing', 'outline-style'
+  ];
+  const snapshots = {};
+  for (const xPath of xPaths) {
+    try {
+      const element = document.evaluate(
+        xPath, document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null
+      ).singleNodeValue;
+      if (! element || element.nodeType !== Node.ELEMENT_NODE) {
+        snapshots[xPath] = {missing: true};
+        continue;
+      }
+      const ancestors = [];
+      const ancestorRoles = [];
+      let parent = element.parentElement;
+      while (parent && parent !== document.documentElement) {
+        if (ancestors.length < 2) {
+          ancestors.unshift(shell(parent));
+        }
+        const role = parent.getAttribute('role');
+        const tag = parent.tagName.toLowerCase();
+        if (role || /^(main|nav|header|footer|aside|section|article|form|table|thead|tbody|tr|ul|ol|dl|fieldset|dialog|menu|figure|details)$/.test(tag)) {
+          ancestorRoles.unshift(role ? `${tag}[role=${role}]` : tag);
+        }
+        parent = parent.parentElement;
+      }
+      // Elements this element points at by IDREF: the part of the invariant that lives outside it.
+      const refs = {};
+      idrefAttributes.forEach(attribute => {
+        const value = element.getAttribute(attribute);
+        if (! value) {
+          return;
+        }
+        refs[attribute] = value.trim().split(/\s+/).slice(0, 8).map(id => {
+          const target = document.getElementById(id);
+          return target
+            ? {id, html: target.outerHTML.slice(0, 400), text: (target.textContent || '').trim().slice(0, 120)}
+            : {id, missing: true};
+        });
+      });
+      // Structural context: table and list position, and whether the element labels something.
+      const context = {ancestorRoles};
+      const cell = element.closest('td, th');
+      if (cell) {
+        const row = cell.parentElement;
+        const table = cell.closest('table');
+        context.table = {
+          row: row ? Array.from(row.parentElement.children).indexOf(row) : -1,
+          col: Array.from(row ? row.children : []).indexOf(cell),
+          rows: table ? table.rows.length : 0,
+          scope: cell.getAttribute('scope') || '',
+          headers: cell.getAttribute('headers') || ''
+        };
+      }
+      const item = element.closest('li, option, [role=listitem], [role=option], [role=menuitem], [role=tab], [role=treeitem]');
+      if (item && item.parentElement) {
+        context.set = {
+          index: Array.from(item.parentElement.children).indexOf(item),
+          size: item.parentElement.children.length,
+          container: shell(item.parentElement)
+        };
+      }
+      if (element.id) {
+        const referrers = Array.from(document.querySelectorAll(
+          `[aria-labelledby~="${element.id}"], [aria-describedby~="${element.id}"], [headers~="${element.id}"], label[for="${element.id}"]`
+        )).slice(0, 8).map(shell);
+        if (referrers.length) {
+          context.referencedBy = referrers;
+        }
+      }
+      const computed = getComputedStyle(element);
+      const style = {};
+      styleKeys.forEach(key => {
+        style[key] = computed.getPropertyValue(key);
+      });
+      const rect = element.getBoundingClientRect();
+      const outerHTML = element.outerHTML;
+      snapshots[xPath] = {
+        outerHTML: outerHTML.length > maxHTML ? `${outerHTML.slice(0, maxHTML)} …` : outerHTML,
+        truncated: outerHTML.length > maxHTML,
+        ancestors,
+        style,
+        box: [rect.x, rect.y, rect.width, rect.height].map(Math.round),
+        text: (element.textContent || '').trim().slice(0, 200),
+        refs,
+        context
+      };
+    }
+    catch(error) {
+      snapshots[xPath] = {error: String(error && error.message || error).slice(0, 120)};
+    }
+  }
+  return snapshots;
+};
+// Adds each element's accessibility-tree snapshot (role, name, states, children) to its snapshot.
+const addAriaSnapshots = async (page, snapshots, xPaths) => {
+  for (const xPath of xPaths.slice(0, SNAPSHOT_MAX_ARIA)) {
+    const snapshot = snapshots[xPath];
+    if (! snapshot || snapshot.missing || snapshot.error) {
+      continue;
+    }
+    try {
+      snapshot.aria = await page.locator(`xpath=${xPath}`).first().ariaSnapshot({timeout: 2000});
+    }
+    catch(error) {
+      snapshot.ariaError = String(error && error.message || error).split('\n')[0].slice(0, 120);
+    }
+  }
+};
+
+// Versions of the engines in play, for the capture header row.
+const engineVersions = engines => {
+  const packages = {
+    alfa: '@siteimprove/alfa-rules',
+    aslint: 'aslint',
+    axe: 'axe-core',
+    ed11y: 'editoria11y',
+    htmlcs: 'html_codesniffer',
+    ibm: 'accessibility-checker',
+    qualWeb: '@qualweb/act-rules'
+  };
+  const versions = {};
+  const root = path.join(__dirname, '..', '..');
+  engines.forEach(engine => {
+    try {
+      if (packages[engine]) {
+        // Read from disk: some packages' `exports` maps block require() of package.json.
+        const packageJSON = path.join(root, 'node_modules', packages[engine], 'package.json');
+        versions[engine] = JSON.parse(fs.readFileSync(packageJSON, 'utf8')).version;
+      }
+      else if (['pour', 'surea11y'].includes(engine)) {
+        const readme = fs.readFileSync(path.join(root, engine, 'README.md'), 'utf8');
+        const match = readme.match(/\b(\d+\.\d+\.\d+)\b/);
+        versions[engine] = match ? match[1] : 'unknown';
+      }
+      else if (engine === 'testaro') {
+        versions[engine] = require('../../package.json').version;
+      }
+    }
+    catch(error) {
+      versions[engine] = 'unknown';
+    }
+  });
+  return versions;
+};
+
+/*
+  The ibm engine version is the one that actually runs: by default IBM's deployed rule archive
+  ("latest"), whose engine can be older than the package's own (4.0.27 under accessibility-checker
+  4.0.33 on 2026-09-23), or with IBM_ENGINE=package the engine released with the checker
+  (tests/ibm.ts, ibmEngine).
+*/
+const ibmRuleArchive = async () => {
+  try {
+    // Applies IBM_ENGINE first, so the header records the engine that will run.
+    const {mode, version} = await require('../../tests/ibm').ibmEngine();
+    const {ruleArchive} = await require('accessibility-checker').getConfig();
+    return {id: mode === 'package' ? 'package' : ruleArchive, version, mode};
+  }
+  catch(error) {
+    return null;
+  }
+};
+
 // FUNCTIONS
 
 // Parses CLI arguments of the form --name value.
@@ -207,6 +464,55 @@ const getXPathScript = () => {
 
 // OPERATION
 
+/*
+  Races a promise against a deadline and clears the timer once either settles.
+  An uncleared timer keeps the event loop alive: each Testaro job and engine
+  reporter used to leave one behind, so a finished capture lingered until the
+  last fired (up to 3 minutes for fixtures, 10 in URL mode). `message` keeps
+  the error text the resume logic matches (RETRYABLE_ERROR).
+*/
+const withDeadline = (promise, ms, label, message = `${label} deadline ${ms}ms`) => {
+  let timer;
+  const deadline = new Promise((resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(message)), ms);
+  });
+  return Promise.race([promise, deadline]).finally(() => clearTimeout(timer));
+};
+
+/*
+  Stop on SIGTERM or SIGINT. Playwright's browser launcher registers listeners
+  for both that close its browsers but don't end the process, so a plain kill
+  used to be ignored. Now the capture stops once the (testcase, engine) run in
+  progress has been recorded (as a retryable prevention, if its browser was
+  just closed under it), writes out, and exits; rerunning the same command
+  resumes. A second signal exits at once.
+*/
+let stopSignal = null;
+for (const signal of ['SIGTERM', 'SIGINT']) {
+  process.on(signal, () => {
+    if (stopSignal) {
+      console.log(`${signal} again: exiting now`);
+      process.exit(signal === 'SIGINT' ? 130 : 143);
+    }
+    stopSignal = signal;
+    console.log(`${signal}: stopping after the current engine run`);
+  });
+}
+
+// A tool's stray promise (e.g. a playwright-extra CDP session settling after
+// the page is closed) must not abort a multi-hour capture; the row's own
+// try/catch and the browser-replacement heuristics handle the page.
+process.on('unhandledRejection', reason => {
+  const message = reason && reason.message ? reason.message : String(reason);
+  if (/cdpSession|Target page, context or browser has been closed/.test(message)) {
+    console.log(`WARNING: unhandled rejection (${message})`);
+    return;
+  }
+  // Anything else is a bug in the harness: fail loudly rather than hang.
+  console.error(`ERROR: unhandled rejection (${message})`);
+  process.exit(1);
+});
+
 (async () => {
   const args = parseArgs(process.argv);
   const engines = (args.engines || 'pour').split(',');
@@ -236,13 +542,38 @@ const getXPathScript = () => {
   if (args.max) {
     testcases = testcases.slice(0, Number(args.max));
   }
-  // Resume support: skip (testcase, engine) pairs already in the out file.
+  // Resume support: skip (testcase, engine) pairs already in the out file,
+  // except rows prevented for a retryable reason — those are recaptured, and
+  // a scorer keeps the last row per pair.
   const alreadyCaptured = new Set();
+  // URL mode: flagged XPaths from rows captured by earlier runs, so a resumed
+  // page still gets its snapshot row (its engine rows are skipped).
+  const priorFlagged = new Map();
   if (fs.existsSync(outPath)) {
     fs.readFileSync(outPath, 'utf8').split('\n').filter(Boolean).forEach(line => {
       try {
         const row = JSON.parse(line);
-        alreadyCaptured.add(`${row.testcaseId}:${row.engine}`);
+        if (! row.testcaseId) {
+          return;
+        }
+        // Fixture ids are content hashes shared across rules (e.g. the AA and
+        // AAA contrast rules), so the rule is part of the identity.
+        const key = `${row.ruleId || ''}/${row.testcaseId}:${row.engine}`;
+        if (row.prevented && RETRYABLE_ERROR.test(row.error || '')) {
+          alreadyCaptured.delete(key);
+        }
+        else {
+          alreadyCaptured.add(key);
+        }
+        if (Array.isArray(row.instances)) {
+          const flagged = priorFlagged.get(row.testcaseId) || new Set();
+          row.instances.forEach(instance => {
+            if (instance.xPath && instance.outcome === 'failed') {
+              flagged.add(instance.xPath);
+            }
+          });
+          priorFlagged.set(row.testcaseId, flagged);
+        }
       }
       catch(error) {}
     });
@@ -252,6 +583,34 @@ const getXPathScript = () => {
     + (alreadyCaptured.size ? ` (resuming; ${alreadyCaptured.size} rows already captured)` : '')
   );
   const out = fs.createWriteStream(outPath, {flags: 'a'});
+  // Header row (no testcaseId) pinning what produced a fresh capture; scorers
+  // skip it, and a resumed capture keeps the original header.
+  if (! alreadyCaptured.size) {
+    let forkCommit = 'unknown';
+    try {
+      forkCommit = require('child_process')
+      .execFileSync('git', ['rev-parse', 'HEAD'], {cwd: path.join(__dirname, '..', '..'), encoding: 'utf8'})
+      .trim();
+    }
+    catch(error) {}
+    const versions = engineVersions(engines);
+    const ibmArchive = engines.includes('ibm') ? await ibmRuleArchive() : null;
+    if (ibmArchive) {
+      ibmArchive.checker = versions.ibm;
+      versions.ibm = ibmArchive.version;
+    }
+    out.write(`${JSON.stringify({
+      header: true,
+      capturedAt: new Date().toISOString(),
+      mode: args.urls ? 'urls' : 'act-fixtures',
+      engines,
+      engineVersions: versions,
+      ...(ibmArchive ? {ibmRuleArchive: ibmArchive} : {}),
+      testaro: require('../../package.json').version,
+      forkCommit,
+      playwright: require('playwright/package.json').version
+    })}\n`);
+  }
   /*
     The browser is recycled every RECYCLE_EVERY testcases: a 2026-08-22 full
     run showed script-tag injection silently failing (tool global never
@@ -272,12 +631,6 @@ const getXPathScript = () => {
     replaced (the old one is closed with its own deadline and abandoned if
     that hangs too).
   */
-  const withDeadline = (promise, ms, label) => Promise.race([
-    promise,
-    new Promise((resolve, reject) => setTimeout(
-      () => reject(new Error(`${label} deadline ${ms}ms`)), ms
-    ))
-  ]);
   const replaceBrowser = async () => {
     const oldBrowser = browser;
     withDeadline(oldBrowser.close(), 10000, 'browser.close').catch(() => {});
@@ -285,11 +638,19 @@ const getXPathScript = () => {
     context = await browser.newContext();
   };
   for (const testcase of testcases) {
+    if (stopSignal) {
+      break;
+    }
     if (done > 0 && RECYCLE_EVERY && done % RECYCLE_EVERY === 0) {
       await replaceBrowser();
     }
+    // XPaths flagged on this page by any engine, for the URL-mode snapshot row.
+    const flaggedXPaths = new Set(priorFlagged.get(testcase.testcaseId) || []);
     for (const engine of engines) {
-      if (alreadyCaptured.has(`${testcase.testcaseId}:${engine}`)) {
+      if (stopSignal) {
+        break;
+      }
+      if (alreadyCaptured.has(`${testcase.ruleId || ''}/${testcase.testcaseId}:${engine}`)) {
         continue;
       }
       const row = {
@@ -308,7 +669,32 @@ const getXPathScript = () => {
         if (xPathNeed === 'script' || xPathNeed === 'attribute') {
           await page.addInitScript(getXPathScript);
         }
-        await page.goto(testcase.url, {waitUntil: 'load', timeout: args.urls ? 30000 : 20000});
+        // Navigate, waiting out a dropped uplink rather than recording it as a result.
+        for (let attempt = 0; ; attempt++) {
+          try {
+            await page.goto(testcase.url, {waitUntil: 'load', timeout: args.urls ? 60000 : 20000});
+            break;
+          }
+          catch(error) {
+            if (attempt < NETWORK_RETRIES && /ERR_INTERNET_DISCONNECTED|ERR_NAME_NOT_RESOLVED|ERR_CONNECTION|ERR_NETWORK_CHANGED/.test(error.message)) {
+              console.log(`WARNING: network error on ${testcase.testcaseId}; retrying in ${NETWORK_RETRY_DELAY_MS / 1000}s`);
+              await new Promise(resolve => setTimeout(resolve, NETWORK_RETRY_DELAY_MS));
+              continue;
+            }
+            throw error;
+          }
+        }
+        /*
+          Chromium shows an XML file it cannot render as a document (e.g. a <math> root with no
+          namespace) in its XML tree viewer, an HTML page of its own; the engines would test that
+          page instead of the fixture.
+        */
+        const inXMLViewer = await page.evaluate(
+          () => !! document.getElementById('webkit-xml-viewer-source-xml')
+        ).catch(() => false);
+        if (inXMLViewer) {
+          throw new Error('fixture not renderable as a document in Chromium (XML viewer)');
+        }
         if (xPathNeed === 'attribute') {
           // Stamp data-xpath attributes, as procs/launch.js does.
           await withDeadline(page.evaluate(() => {
@@ -326,19 +712,36 @@ const getXPathScript = () => {
           const nonced = document.querySelector('script[nonce]');
           return (nonced && nonced.nonce) || '';
         }).catch(() => '');
-        const report = {
-          standard: 'also',
-          jobData: scriptNonce ? {lastScriptNonce: scriptNonce} : {},
-          catalog: {},
-          target: {url: testcase.url},
-          acts: [{type: 'test', which: engine, withItems: true}]
-        };
-        const actReport = await Promise.race([
-          require(`../../tests/${engine}`).reporter(page, report, 0, 40),
-          new Promise((resolve, reject) => setTimeout(
-            () => reject(new Error('reporter timeout')), REPORTER_TIMEOUT_MS
-          ))
-        ]);
+        let report;
+        let actReport;
+        if (engine === 'testaro') {
+          const {doJob} = require('../../run');
+          report = await withDeadline(
+            doJob(testaroJob(testcase.url, args.urls ? 540 : 120)),
+            args.urls ? TESTARO_URL_TIMEOUT_MS : TESTARO_TIMEOUT_MS,
+            'testaro',
+            'reporter timeout'
+          );
+          actReport = report.jobData && report.jobData.aborted
+            ? {data: {prevented: true, error: report.jobData.abortMessage || 'job aborted'}}
+            : report.acts.find(jobAct => jobAct.type === 'test')
+              || {data: {prevented: true, error: 'no test act in job report'}};
+        }
+        else {
+          report = {
+            standard: 'also',
+            jobData: scriptNonce ? {lastScriptNonce: scriptNonce} : {},
+            catalog: {},
+            target: {url: testcase.url},
+            acts: [{type: 'test', which: engine, withItems: true}]
+          };
+          actReport = await withDeadline(
+            require(`../../tests/${engine}`).reporter(page, report, 0, 40),
+            REPORTER_TIMEOUT_MS,
+            engine,
+            'reporter timeout'
+          );
+        }
         const {data, result} = actReport;
         row.prevented = !! (data && data.prevented);
         if (row.prevented) {
@@ -348,6 +751,7 @@ const getXPathScript = () => {
           row.instanceCount = result.standardResult.instances.length;
           row.outcomeTotals = result.standardResult.outcomeTotals;
           row.ruleIDs = ruleIDCounts(result.standardResult);
+          row.ruleOutcomes = ruleOutcomeCounts(result.standardResult);
           const unoutcomed = result.standardResult.instances
           .filter(instance => ! OUTCOMES.includes(instance.outcome)).length;
           if (unoutcomed) {
@@ -368,8 +772,13 @@ const getXPathScript = () => {
               severity: instance.ordinalSeverity,
               outcome: instance.outcome,
               uncertainty: instance.uncertainty,
-              xPath: (report.catalog[instance.catalogIndex] || {}).pathID || ''
+              xPath: ((report.catalog || {})[instance.catalogIndex] || {}).pathID || ''
             }));
+            row.instances.forEach(instance => {
+              if (instance.xPath && instance.outcome === 'failed') {
+                flaggedXPaths.add(instance.xPath);
+              }
+            });
           }
         }
       }
@@ -395,7 +804,7 @@ const getXPathScript = () => {
         rows fail before the next scheduled recycle).
       */
       if (
-        closeHung
+        ! stopSignal && (closeHung
         || (row.error && /deadline|has been closed|Protocol error/.test(row.error))
         /*
           Canary: a script-tag-injecting tool reporting its global undefined
@@ -405,7 +814,7 @@ const getXPathScript = () => {
           consecutive rows in a browser only ~36 pages old). XML pages are
           excluded: script elements legitimately never execute there.
         */
-        || (row.error && /global not defined \(contentType text\/html/.test(row.error))
+        || (row.error && /global not defined \(contentType text\/html/.test(row.error)))
       ) {
         row.browserReplaced = true;
         await replaceBrowser();
@@ -413,12 +822,56 @@ const getXPathScript = () => {
       row.ms = Date.now() - started;
       out.write(`${JSON.stringify(row)}\n`);
     }
+    // A stop mid-testcase leaves its remaining engines (and snapshot) to a resumed run.
+    if (stopSignal) {
+      break;
+    }
+    // URL mode: snapshot the flagged elements once per page.
+    if (args.urls && flaggedXPaths.size && ! alreadyCaptured.has(`${testcase.ruleId || ''}/${testcase.testcaseId}:_snapshot`)) {
+      const snapshotRow = {testcaseId: testcase.testcaseId, engine: '_snapshot', prevented: false};
+      const started = Date.now();
+      let page;
+      try {
+        page = await withDeadline(context.newPage(), 20000, 'newPage');
+        await page.goto(testcase.url, {waitUntil: 'load', timeout: 30000});
+        const xPaths = [...flaggedXPaths].slice(0, SNAPSHOT_MAX_ELEMENTS);
+        snapshotRow.snapshots = await withDeadline(
+          page.evaluate(snapshotScript, [xPaths, SNAPSHOT_MAX_HTML, IDREF_ATTRIBUTES]), 30000, 'snapshot'
+        );
+        await withDeadline(addAriaSnapshots(page, snapshotRow.snapshots, xPaths), 120000, 'ariaSnapshot');
+        snapshotRow.profileVersion = SNAPSHOT_PROFILE_VERSION;
+        snapshotRow.flaggedCount = flaggedXPaths.size;
+        snapshotRow.capped = flaggedXPaths.size > SNAPSHOT_MAX_ELEMENTS;
+      }
+      catch(error) {
+        snapshotRow.prevented = true;
+        snapshotRow.error = error.message.slice(0, 200);
+      }
+      finally {
+        if (page) {
+          await withDeadline(page.close(), 5000, 'page.close').catch(() => {});
+        }
+      }
+      snapshotRow.ms = Date.now() - started;
+      out.write(`${JSON.stringify(snapshotRow)}\n`);
+    }
     done++;
     if (done % 25 === 0) {
       console.log(`${done}/${testcases.length}`);
     }
   }
-  await browser.close();
-  out.end();
-  console.log(`Done: ${done} testcases → ${outPath}`);
+  await withDeadline(browser.close(), 10000, 'browser.close').catch(() => {});
+  await new Promise(resolve => out.end(resolve));
+  if (stopSignal) {
+    console.log(`Stopped (${stopSignal}) after ${done} testcases → ${outPath}; rerun the same command to resume`);
+  }
+  else {
+    console.log(`Done: ${done} testcases → ${outPath}`);
+  }
+  /*
+    Exit explicitly: code under test (Testaro's own jobs, engine adapters) can
+    leave handles that would otherwise hold the process open after the output
+    is complete.
+  */
+  process.exit(stopSignal ? (stopSignal === 'SIGINT' ? 130 : 143) : 0);
 })();