@decocms/parity 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -9,9 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+* **Configurable `minicartPanel` selector for open-minicart reveal detection (issue #149).** `isCartUiVisible` and the title-scope sweep in `validateCartContainsTitleQuick` used a hardcoded list of name-based patterns (`[role='dialog']`, `[class*='minicart']`, etc.) to detect that the cart drawer was open. Any site built with utility-CSS (Tailwind) and `data-qa-*` testing attributes — a common modern stack — has no class/attribute those patterns can match, so detection always returns `null` and the step reports "failed" even when the drawer is genuinely open. The new `minicartPanel` selector key (`.parityrc.json`) is tried first, ahead of all hardcoded patterns. Built-in defaults cover `[data-qa-minicart]`, `[data-minicart]`, `[data-minicart-drawer]`, `[data-testid='minicart']` and common class patterns — so the `data-qa-*` case is handled out-of-the-box. Override with a single selector that matches the drawer root for your specific site.
+
+## [0.15.0](https://github.com/decocms/parity/compare/v0.14.0...v0.15.0) (2026-07-27)
+
+### Added
+
+* **Structural overlay interception detection + configurable overlay selectors (issues #145, #146).** A "no-signal" add-to-cart failure is often not a broken cart but a newsletter/discount modal intercepting the click — classically one that pops on the very `mousemove` Playwright's `.click()` dispatches, in a cookie-less session (e.g. a `div.fixed bg-black/50 z-9999` backdrop over the buy button). Instead of name-matching every popup shape (whack-a-mole), parity now detects interception **structurally**: before retrying, it checks whether the buy button is still the topmost element at its click point (`document.elementFromPoint`) and, if something covers it, dismisses it least-destructive-first — Escape → a named close button → an icon/geometry close control inside the overlay (catches unnamed `<button><svg/></button>` X's) → a corner backdrop click → and, guarded, hiding the confirmed interceptor as a last resort (never an ancestor of the target, and it can't fake success — the step still needs a real confirmation signal) — then retries once. What was detected/dismissed is recorded in the step's `detail.overlayDismissed` and surfaced in the action text, so a report shows *why* a click was intercepted even when dismissal succeeded. Separately, `.parityrc.json` `overlaySelectors` adds explicit site-specific overlay selectors, merged with the built-in cookie/toast/newsletter defaults (never replacing them), as a fast-path override.
+
+## [0.14.0](https://github.com/decocms/parity/compare/v0.13.0...v0.14.0) (2026-07-27)
+
+### Added
+
+* **Configurable add-to-cart confirmation deadline (issue #143).** The purchase-journey / `e2e` add-to-cart step polled a hardcoded 3000ms for a success signal (URL→cart, minicart count increase, drawer open, success toast). On sites whose success toast is short-lived, or with slow TTFB / popup overlays, that could race the deadline and report a false "no signal" failure on an add-to-cart that actually worked. Now tunable via `.parityrc.json` `addToCartConfirmMs` or `--add-to-cart-timeout <ms>` (on `parity run` and `parity e2e`); a non-positive/NaN override is ignored and falls back to the 3000ms default.
+
+## [0.13.0](https://github.com/decocms/parity/compare/v0.12.0...v0.13.0) (2026-07-27)
+
+### Added
+
 * **`parity e2e` now automates selectors like `parity run` (issue #141).** Single-site runs previously saw only `DEFAULT_SELECTORS` + hand-written `.parityrc.json` — `e2e` never detected the platform, never ran LLM selector discovery, and never learned from its flow runs (so `learned-selectors.json`, keyed by platform, never applied). It now detects the platform, runs the same grounded LLM discovery + live-validation pass, threads the platform into every flow, and promotes selectors learned from real successful interactions. New flags mirror `run`: `--no-auto-selectors`, `--refresh-selectors`, `--no-learn`. The discovery pass is now shared code (`src/engine/selector-discovery-pass.ts`) used by both commands.
 * **Discovery covers the journey variant/quantity keys.** LLM selector discovery now infers `variantRow`, `quantityIncrement`, `quantityInput`, `sizeSwatch`, and `colorSwatch` (grounded on the real PDP and live-validated) — exactly the keys single-site users kept hand-writing in `.parityrc.json`.
-* **Configurable add-to-cart confirmation deadline (issue #143).** The purchase-journey / `e2e` add-to-cart step polled a hardcoded 3000ms for a success signal (URL→cart, minicart count increase, drawer open, success toast). On sites whose success toast is short-lived, or with slow TTFB / popup overlays, that could race the deadline and report a false "no signal" failure on an add-to-cart that actually worked. Now tunable via `.parityrc.json` `addToCartConfirmMs` or `--add-to-cart-timeout <ms>` (on `parity run` and `parity e2e`); a non-positive/NaN override is ignored and falls back to the 3000ms default.
 
 ### Fixed
 

package/dist/cli.js

@@ -41389,6 +41389,7 @@ var ParityRc = z.object({
     quantityInput: z.string().optional(),
     minicartCount: z.string().optional(),
     cartOpenedIndicator: z.string().optional(),
+    minicartPanel: z.string().optional(),
     searchTrigger: z.string().optional(),
     searchInput: z.string().optional(),
     searchSuggestions: z.string().optional(),
@@ -41434,6 +41435,7 @@ var ParityRc = z.object({
   }).optional(),
   serverFnFloodBudget: z.number().optional(),
   serverFnPattern: z.string().optional(),
+  overlaySelectors: z.array(z.string()).optional(),
   addToCartConfirmMs: z.number().optional()
 });
 var ParityIgnore = z.object({
@@ -49544,6 +49546,7 @@ var SelectorKey = z2.enum([
   "quantityInput",
   "minicartCount",
   "cartOpenedIndicator",
+  "minicartPanel",
   "searchTrigger",
   "searchInput",
   "searchSuggestions",
@@ -49948,6 +49951,17 @@ var DEFAULT_SELECTORS = {
     "[role='dialog']:has-text('adicionado')",
     "[role='dialog']:has-text('added')"
   ],
+  minicartPanel: [
+    "[data-qa-minicart]",
+    "[data-minicart]",
+    "[data-minicart-drawer]",
+    "[data-drawer='minicart']",
+    "[data-testid='minicart']",
+    "[data-testid='cart-drawer']",
+    "[class*='minicart' i]",
+    "[class*='cart-drawer' i]",
+    "[class*='drawer-cart' i]"
+  ],
   cartItemRow: [
     "[data-cart-item]",
     "[data-testid='cart-item']",
@@ -50531,41 +50545,206 @@ async function extractProductTitle(page) {
     return docTitle.trim();
   return null;
 }
+var DEFAULT_OVERLAY_SELECTORS = [
+  "[class*='cookie' i][class*='banner' i]",
+  "[class*='cookie' i][class*='consent' i]",
+  "[id*='cookie' i][class*='banner' i]",
+  "[role='alertdialog']:visible",
+  "[class*='toast' i]:visible",
+  "[class*='snackbar' i]:visible",
+  "[class*='added-to-cart' i]:visible",
+  "[class*='product-added' i]:visible",
+  "[id*='newsletter' i]:visible",
+  "[class*='newsletter' i]:visible",
+  "[id*='signup-popup' i]:visible",
+  "[class*='signup' i][class*='popup' i]:visible"
+];
+var CLOSE_BUTTON_SELECTOR = "button[aria-label*='close' i], [aria-label*='close' i], button[aria-label*='fechar' i], [aria-label*='fechar' i], [data-close], [data-dismiss], [data-qa-dismiss], button[class*='close' i], button:has-text('×'), button:has-text('✕')";
+function overlaySelectorsFor(rc) {
+  const extra = rc?.overlaySelectors ?? [];
+  return [...new Set([...DEFAULT_OVERLAY_SELECTORS, ...extra])];
+}
+async function blockerAtTarget(target) {
+  return await withCap(target.evaluate((el) => {
+    const node2 = el;
+    const rect = node2.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0)
+      return null;
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const top = document.elementFromPoint(cx, cy);
+    if (!top || top === node2 || node2.contains(top))
+      return null;
+    let cur = top;
+    let overlay = top;
+    while (cur && cur !== document.body) {
+      const pos = getComputedStyle(cur).position;
+      if (pos === "fixed" || pos === "sticky" || pos === "absolute")
+        overlay = cur;
+      cur = cur.parentElement;
+    }
+    const r = overlay.getBoundingClientRect();
+    const coverage = r.width * r.height / (window.innerWidth * window.innerHeight);
+    const cls = typeof overlay.className === "string" ? overlay.className : "";
+    return {
+      tag: overlay.tagName.toLowerCase(),
+      id: overlay.id || undefined,
+      className: cls ? cls.slice(0, 120) : undefined,
+      fullViewport: coverage > 0.6
+    };
+  }).catch(() => null), 2000, null);
+}
+async function findOverlayCloseControl(target) {
+  return await withCap(target.evaluate((el) => {
+    const node2 = el;
+    const rect = node2.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0)
+      return null;
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const top = document.elementFromPoint(cx, cy);
+    if (!top || top === node2 || node2.contains(top))
+      return null;
+    let cur = top;
+    let overlay = top;
+    while (cur && cur !== document.body) {
+      const pos = getComputedStyle(cur).position;
+      if (pos === "fixed" || pos === "sticky" || pos === "absolute")
+        overlay = cur;
+      cur = cur.parentElement;
+    }
+    const orect = overlay.getBoundingClientRect();
+    const clickables = Array.from(overlay.querySelectorAll("button, a, [role='button']"));
+    let best = null;
+    for (const c of clickables) {
+      const r = c.getBoundingClientRect();
+      if (r.width === 0 || r.height === 0 || r.width > 72 || r.height > 72)
+        continue;
+      const label = `${c.getAttribute("aria-label") ?? ""} ${typeof c.className === "string" ? c.className : ""} ${c.textContent ?? ""}`.toLowerCase();
+      const named = /close|fechar|dismiss|×|✕/.test(label);
+      const distTopRight = Math.hypot(orect.right - r.right, r.top - orect.top);
+      const score = (named ? 0 : 1e5) + distTopRight;
+      if (!best || score < best.score) {
+        best = { x: r.left + r.width / 2, y: r.top + r.height / 2, score };
+      }
+    }
+    return best ? { x: best.x, y: best.y } : null;
+  }).catch(() => null), 2000, null);
+}
+async function neutralizeBlockerAtTarget(target) {
+  return await withCap(target.evaluate((el) => {
+    const node2 = el;
+    const rect = node2.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0)
+      return false;
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    const top = document.elementFromPoint(cx, cy);
+    if (!top || top === node2 || node2.contains(top))
+      return false;
+    let cur = top;
+    let overlay = top;
+    while (cur && cur !== document.body) {
+      const pos = getComputedStyle(cur).position;
+      if (pos === "fixed" || pos === "sticky" || pos === "absolute")
+        overlay = cur;
+      cur = cur.parentElement;
+    }
+    if (overlay.contains(node2))
+      return false;
+    overlay.style.setProperty("display", "none", "important");
+    return true;
+  }).catch(() => false), 2000, false);
+}
+async function dismissBlockingOverlay(page, ctx, target) {
+  const blocker = await blockerAtTarget(target);
+  if (!blocker)
+    return null;
+  const base = {
+    reason: "click-point-intercepted",
+    tag: blocker.tag,
+    id: blocker.id,
+    className: blocker.className,
+    fullViewport: blocker.fullViewport
+  };
+  const cleared = async () => await blockerAtTarget(target) === null;
+  await page.keyboard.press("Escape").catch(() => {
+    return;
+  });
+  await page.waitForTimeout(300);
+  if (await cleared()) {
+    dlog2(ctx, `  overlay: dismissed via Escape (${describe(blocker)})`);
+    return { ...base, method: "escape", dismissed: true };
+  }
+  const closer = page.locator(CLOSE_BUTTON_SELECTOR).first();
+  if (await withCap(closer.isVisible({ timeout: 300 }).catch(() => false), 500, false)) {
+    await closer.click({ timeout: 1500 }).catch(() => {
+      return;
+    });
+    await page.waitForTimeout(300);
+    if (await cleared()) {
+      dlog2(ctx, `  overlay: dismissed via close button (${describe(blocker)})`);
+      return { ...base, method: "close-button", dismissed: true };
+    }
+  }
+  const closeXY = await findOverlayCloseControl(target);
+  if (closeXY) {
+    await page.mouse.click(closeXY.x, closeXY.y).catch(() => {
+      return;
+    });
+    await page.waitForTimeout(300);
+    if (await cleared()) {
+      dlog2(ctx, `  overlay: dismissed via icon close control (${describe(blocker)})`);
+      return { ...base, method: "close-button", dismissed: true };
+    }
+  }
+  await page.mouse.click(5, 5).catch(() => {
+    return;
+  });
+  await page.waitForTimeout(300);
+  if (await cleared()) {
+    dlog2(ctx, `  overlay: dismissed via backdrop click (${describe(blocker)})`);
+    return { ...base, method: "backdrop-click", dismissed: true };
+  }
+  if (await neutralizeBlockerAtTarget(target)) {
+    await page.waitForTimeout(150);
+    if (await cleared()) {
+      dlog2(ctx, `  overlay: neutralized (hidden) as last resort (${describe(blocker)})`);
+      return { ...base, method: "neutralized", dismissed: true };
+    }
+  }
+  dlog2(ctx, `  overlay: detected but NOT dismissed (${describe(blocker)})`);
+  return { ...base, method: "backdrop-click", dismissed: false };
+}
+function describe(b) {
+  return `${b.tag}${b.id ? `#${b.id}` : ""}${b.className ? `.${b.className.split(/\s+/)[0]}` : ""}`;
+}
 async function dismissOverlays(page, ctx) {
-  const overlaySelectors = [
-    "[class*='cookie' i][class*='banner' i]",
-    "[class*='cookie' i][class*='consent' i]",
-    "[id*='cookie' i][class*='banner' i]",
-    "[role='alertdialog']:visible",
-    "[class*='toast' i]:visible",
-    "[class*='snackbar' i]:visible",
-    "[class*='added-to-cart' i]:visible",
-    "[class*='product-added' i]:visible"
-  ];
-  let dismissedAny = false;
-  for (const sel of overlaySelectors) {
+  const dismissals = [];
+  for (const sel of overlaySelectorsFor(ctx.rc)) {
     try {
       const overlay = page.locator(sel).first();
       if (!await withCap(overlay.isVisible({ timeout: 200 }).catch(() => false), 400, false))
         continue;
-      const closer = overlay.locator("button[aria-label*='close' i], button[aria-label*='fechar' i], button[class*='close' i], [data-close], [aria-label='Close']").first();
+      const closer = overlay.locator(CLOSE_BUTTON_SELECTOR).first();
       if (await withCap(closer.isVisible({ timeout: 200 }).catch(() => false), 400, false)) {
         await closer.click({ timeout: 1500 }).catch(() => {
           return;
         });
-        dismissedAny = true;
+        dismissals.push({ reason: "selector-match", tag: sel, method: "close-button", dismissed: true });
         continue;
       }
       await page.keyboard.press("Escape").catch(() => {
         return;
       });
-      dismissedAny = true;
+      dismissals.push({ reason: "selector-match", tag: sel, method: "escape", dismissed: true });
     } catch {}
   }
-  if (dismissedAny) {
-    dlog2(ctx, "  openMinicart: dismissed overlay(s) before interacting");
+  if (dismissals.length > 0) {
+    dlog2(ctx, `  dismissed ${dismissals.length} overlay(s) before interacting`);
     await page.waitForTimeout(500);
   }
+  return dismissals;
 }
 
 // src/engine/flows/cart-helpers.ts
@@ -50584,8 +50763,10 @@ async function readCartCount(page, ctx) {
   }
   return 0;
 }
-async function isCartUiVisible(page) {
+async function isCartUiVisible(page, ctx) {
+  const configured = ctx ? [...selFor(ctx, "minicartPanel"), ...selFor(ctx, "cartOpenedIndicator")] : [];
   return firstVisible(page, [
+    ...configured,
     "[role='dialog']:visible",
     "[aria-modal='true']:visible",
     "[data-minicart][aria-hidden='false']",
@@ -50671,16 +50852,17 @@ async function detectCartRevealMode(page, trigger, drawerAlreadyOpen, viewport)
     return "click-drawer";
   return "unknown";
 }
-async function isCartRevealed(page, expectedProductTitle) {
+async function isCartRevealed(page, expectedProductTitle, ctx) {
   if (expectedProductTitle) {
-    const v = await validateCartContainsTitleQuick(page, expectedProductTitle);
+    const v = await validateCartContainsTitleQuick(page, expectedProductTitle, ctx);
     if (v)
       return `title-found:${v}`;
   }
-  return isCartUiVisible(page);
+  return isCartUiVisible(page, ctx);
 }
-async function validateCartContainsTitleQuick(page, expectedTitle) {
+async function validateCartContainsTitleQuick(page, expectedTitle, ctx) {
   const quickSelectors = [
+    ...ctx ? selFor(ctx, "minicartPanel") : [],
     "[role='dialog']",
     "[class*='minicart' i]",
     "[class*='cart' i]",
@@ -50717,7 +50899,7 @@ async function openMinicart(page, trigger, ctx, expectedProductTitle) {
   const beforeUrl = page.url();
   await dismissOverlays(page, ctx);
   await page.waitForTimeout(800);
-  const alreadyOpen = await isCartRevealed(page, expectedProductTitle);
+  const alreadyOpen = await isCartRevealed(page, expectedProductTitle, ctx);
   if (alreadyOpen) {
     dlog2(ctx, `  openMinicart: already-open (matched ${alreadyOpen})`);
     return { method: "already-open", url: beforeUrl, visibleMarker: alreadyOpen };
@@ -50730,7 +50912,7 @@ async function openMinicart(page, trigger, ctx, expectedProductTitle) {
       return;
     });
     await page.waitForTimeout(1500);
-    const hoverOpened = await isCartRevealed(page, expectedProductTitle);
+    const hoverOpened = await isCartRevealed(page, expectedProductTitle, ctx);
     if (hoverOpened) {
       dlog2(ctx, `  openMinicart: hover opened drawer (${hoverOpened})`);
       return { method: "hover", url: page.url(), visibleMarker: hoverOpened };
@@ -50755,7 +50937,7 @@ async function openMinicart(page, trigger, ctx, expectedProductTitle) {
       return { method: "click-navigate", url: page.url(), visibleMarker: null };
     }
     await page.waitForTimeout(800);
-    const tapOpened = await isCartRevealed(page, expectedProductTitle);
+    const tapOpened = await isCartRevealed(page, expectedProductTitle, ctx);
     if (tapOpened) {
       dlog2(ctx, `  openMinicart: tap opened drawer (${tapOpened})`);
       return { method: "click", url: page.url(), visibleMarker: tapOpened };
@@ -50780,7 +50962,7 @@ async function openMinicart(page, trigger, ctx, expectedProductTitle) {
     return { method: "click-navigate", url: page.url(), visibleMarker: null };
   }
   await page.waitForTimeout(1500);
-  const clickOpened = await isCartRevealed(page, expectedProductTitle);
+  const clickOpened = await isCartRevealed(page, expectedProductTitle, ctx);
   if (clickOpened) {
     dlog2(ctx, `  openMinicart: click opened drawer (${clickOpened})`);
     return { method: "click", url: afterClickUrl, visibleMarker: clickOpened };
@@ -50791,7 +50973,7 @@ async function openMinicart(page, trigger, ctx, expectedProductTitle) {
       return;
     });
     await page.waitForTimeout(1500);
-    const hoverOpened = await isCartRevealed(page, expectedProductTitle);
+    const hoverOpened = await isCartRevealed(page, expectedProductTitle, ctx);
     if (hoverOpened) {
       dlog2(ctx, `  openMinicart: hover opened drawer (${hoverOpened})`);
       return { method: "hover", url: page.url(), visibleMarker: hoverOpened };
@@ -50837,7 +51019,16 @@ function titlesMatch(observed, expected) {
   return false;
 }
 async function validateCartContainsTitle(page, expectedTitle, ctx) {
+  const panelScopedTitleSelectors = selFor(ctx, "minicartPanel").flatMap((p) => [
+    `${p} a[href*='/p']`,
+    `${p} [class*='name' i]`,
+    `${p} [class*='title' i]`,
+    `${p} [class*='product' i]`,
+    `${p} [data-cart-item-name]`,
+    `${p} [data-qa-product-name]`
+  ]);
   const titleSelectors = [
+    ...panelScopedTitleSelectors,
     "[data-cart-item-name]",
     "[data-cart-item] [class*='title' i]",
     "[data-cart-item] [class*='name' i]",
@@ -51631,10 +51822,25 @@ async function flowPurchaseJourney(ctx) {
         validation = await validateAddToCart(page, ctx, cartCountBefore, beforeUrl6);
       }
     }
+    let overlayDismissed;
+    if (validation.status === "failed" && validation.signal === "no-signal") {
+      const od = await dismissBlockingOverlay(page, ctx, buyHit.locator);
+      if (od) {
+        overlayDismissed = od;
+        if (od.dismissed) {
+          await page.waitForTimeout(300);
+          await buyHit.locator.click({ timeout: 5000 }).catch(() => {
+            return;
+          });
+          validation = await validateAddToCart(page, ctx, cartCountBefore, beforeUrl6);
+        }
+      }
+    }
     const sp6 = screenshotPath(ctx, "pj-6-add-cart");
     await screenshotStable(page, { path: sp6, fullPage: false });
     const buyActionDesc = `Clicou no botão${buyText ? ` '${buyText.slice(0, 40).trim()}'` : ""} (\`${buyHit.selector}\`)${buyRecovered ? " — selector veio de recovery LLM" : ""}`;
-    const fullActionDesc = variantRetryNote ? `${buyActionDesc} — ${variantRetryNote} — ${validation.note}` : `${buyActionDesc} — ${validation.note}`;
+    const overlayNote = overlayDismissed ? ` — overlay ${overlayDismissed.tag}${overlayDismissed.id ? `#${overlayDismissed.id}` : ""} ${overlayDismissed.dismissed ? `dismissed (${overlayDismissed.method}), click retried` : "detected but NOT dismissed"}` : "";
+    const fullActionDesc = variantRetryNote ? `${buyActionDesc} — ${variantRetryNote}${overlayNote} — ${validation.note}` : `${buyActionDesc}${overlayNote} — ${validation.note}`;
     steps.push({
       step: 6,
       name: "add-to-cart",
@@ -51654,7 +51860,8 @@ async function flowPurchaseJourney(ctx) {
       detail: {
         signal: validation.signal,
         errorText: validation.errorText,
-        variantRetry: variantRetryNote
+        variantRetry: variantRetryNote,
+        overlayDismissed
       }
     });
     reportEnd(6, "add-to-cart", validation.status, Date.now() - t6, validation.status === "ok" ? undefined : validation.note);
@@ -51679,7 +51886,7 @@ async function flowPurchaseJourney(ctx) {
     let cartOpenMethod = "failed";
     let miniText = "";
     let cartRevealMode = "unknown";
-    const drawerAlreadyOpen = await isCartRevealed(page, expectedProductTitle) !== null;
+    const drawerAlreadyOpen = await isCartRevealed(page, expectedProductTitle, ctx) !== null;
     if (miniHit) {
       miniText = await miniHit.locator.innerText().catch(() => "");
       cartRevealMode = await detectCartRevealMode(page, miniHit.locator, drawerAlreadyOpen, ctx.viewport).catch(() => "unknown");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/parity",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "E2E parity validator for site migrations. Compares prod vs cand and reports UI, functional, SEO, visual, and Web Vitals deltas with an LLM-ranked HTML report.",
   "type": "module",
   "license": "MIT",