@nextcommerce/campaigns-os 1.33.0

package/src/qa-order-bump.mjs

@@ -0,0 +1,381 @@
+// Order-bump state evidence for browser QA (campaigns-os#323).
+//
+// The `browser-order-bump-state` assertion asks one question: does what the
+// buyer can see on a bump toggle agree with what the SDK thinks is in the cart?
+// It reads three things off each toggle — the SDK's own active/in-cart state,
+// the toggle's checkbox input if it has one, and the rendered state marker —
+// and fails when they disagree.
+//
+// The marker half used to be a single `querySelector` over a selector list that
+// ended in a bare `[aria-hidden]`. Two things went wrong with that:
+//
+//   1. `aria-hidden` is decoration vocabulary, not state vocabulary. A bump
+//      toggle that carries its own visually-hidden `<input type="checkbox"
+//      aria-hidden="true">` has that input match the list, and `querySelector`
+//      returns document order, not selector order — so on every toggle whose
+//      input precedes its tick, the "marker" resolved to the input. An input is
+//      not a rendered marker: it has no `::after`, no glyph, no fill, so
+//      `markerChecked` could never read true and an accepted bump reported
+//      misaligned on every single run. That is the whole of #323.
+//   2. The same clause matched purely decorative nodes — an arrow icon, a
+//      switch slider — whose rendering says nothing about the toggle's state,
+//      so the check would fail a correctly rendered toggle for the same reason.
+//
+// So the marker vocabulary here is only the four families that mean "this is
+// the tick", the families are tried in order (rather than being collapsed into
+// one document-order query), and form controls and `[hidden]` subtrees can
+// never be a marker.
+//
+// A rendered marker is then read for a positive state signal, and the signals
+// are alternatives rather than one replacing another, because the families
+// express state in genuinely different ways:
+//
+//   - `pseudo` — the marker is a persistent box and its `::after` carries the
+//     tick. The box renders in both states, so its visibility says nothing;
+//     the state is whether the pseudo-element is rendered. A marker whose
+//     `::after` has non-empty content belongs to this family by definition,
+//     and its checked reading comes from that pseudo-element alone.
+//   - `glyph` — the tick is literal text in the marker.
+//   - `fill` — the marker is filled with the accepted colour.
+//   - `display_toggled` — the marker *is* the tick and the CSS shows and hides
+//     it: `[data-next-toggle-card] [os-component="check"] { display: none }`
+//     with the active or in-cart card restoring `display: flex`. Only here is
+//     the marker's own rendering the state affordance.
+//
+// The last one is a claim about the page's CSS, so it is tested against the
+// page's CSS (`hiddenByAMatchingRule`) rather than assumed from the family
+// name. That is what keeps a persistent box out of it: a box nothing hides is
+// not display-toggled, and reading its visibility as "checked" would fail a
+// correctly declined bump. For the same reason that walk counts only rules
+// that hide outright: a rule dimming a marker to `opacity: 0.4` leaves it on
+// screen, so it is a style and not a state affordance. The rendered read still
+// treats a faded marker as too faint to read a tick off; the two questions
+// differ, and only the rule walk demands an exact `opacity: 0`.
+//
+// A rendered marker carrying no positive signal is reported as unresolved, not
+// as checked and not as unchecked. The harness cannot read that page's state
+// vocabulary, and saying so is honest; claiming a disagreement is not.
+
+// Bump toggle roots. Matches the SDK's toggle card and the older bump root.
+export const ORDER_BUMP_TOGGLE_SELECTOR = "[data-next-toggle-card], [data-next-bump]";
+
+// State-marker families, most specific first. Tried in order, so a generic
+// match can never outrank a dedicated one just by appearing earlier in the
+// document. Deliberately does NOT include a bare `[aria-hidden]`.
+export const ORDER_BUMP_MARKER_FAMILIES = Object.freeze([
+  ".bump-check",
+  "[data-next-toggle-check]",
+  "[os-component='check']",
+  ".checkbox__icon",
+]);
+
+// Containers a marker may be nested in; the container must render too, so a tick
+// inside a collapsed wrapper is not read as shown. A marker's wrapper is drawn
+// from the same vocabulary as the marker itself — a `.checkbox__icon` box
+// holding an `[os-component="check"]` tick is the shape this exists for — so
+// this is the family list, not a second copy of it: two copies drifted apart
+// once already, and a family added to one but not the other would resolve a
+// nested tick and then judge it by the wrong box. Order is immaterial here,
+// unlike in the family list: the selectors are joined into one `closest()`
+// query, which resolves by tree position rather than by selector order.
+export const ORDER_BUMP_MARKER_CONTAINERS = ORDER_BUMP_MARKER_FAMILIES;
+
+// Elements that can never be a state marker, whatever they match: the toggle's
+// own form control (read separately as `inputChecked`) and anything the author
+// removed from rendering outright.
+export const ORDER_BUMP_MARKER_EXCLUDED = "input, select, textarea, option";
+
+// The accepted-state fill used by the shared checkout CSS, as a computed
+// `background-color` string — `getComputedStyle` always reports an opaque
+// colour in this `rgb(r, g, b)` form, so the comparison is a string equality
+// and the constant has to be written the way the browser serialises it. It is
+// the `fill` family's whole vocabulary: a marker painted this colour is a
+// ticked marker. Deliberately a constant of this module rather than a value
+// read from a brand contract — the check is asking what the checkout CSS in
+// front of the buyer actually paints, and sourcing it from a theme would make
+// the answer move whenever the theme does.
+export const ORDER_BUMP_ACCEPTED_FILL_COLOR = "rgb(45, 148, 127)";
+
+export const ORDER_BUMP_PROBE_INPUT = Object.freeze({
+  toggleSelector: ORDER_BUMP_TOGGLE_SELECTOR,
+  markerFamilies: ORDER_BUMP_MARKER_FAMILIES,
+  markerContainers: ORDER_BUMP_MARKER_CONTAINERS,
+  markerExcluded: ORDER_BUMP_MARKER_EXCLUDED,
+  acceptedFillColor: ORDER_BUMP_ACCEPTED_FILL_COLOR,
+});
+
+// Returns the `page.evaluate` body. Exported as a factory so the browser proof
+// can drive the same function the QA runner does, instead of a copy of it.
+export function orderBumpEvidenceScript() {
+  return ({ toggleSelector, markerFamilies, markerContainers, markerExcluded, acceptedFillColor }) => {
+    // The evaluate body is serialised into the page, so it cannot read the
+    // module constant; the colour arrives through the probe input. A caller
+    // that omits it would compare every fill against undefined and read each
+    // fill-family marker as unresolved with no signal, so refuse instead.
+    if (typeof acceptedFillColor !== "string" || !acceptedFillColor) {
+      throw new Error("order-bump evidence script needs acceptedFillColor in its input (use ORDER_BUMP_PROBE_INPUT)");
+    }
+    const hasContent = (value) => Boolean(value) && !["none", "normal", '""', "''"].includes(value);
+
+    // The one list of declarations that remove an element from view. Both the
+    // computed-style test and the stylesheet-rule walk ask through this, so a
+    // way of hiding a tick can never be understood by one and missed by the
+    // other — `visibility: collapse` was rejected by the computed-style test
+    // and invisible to the rule walk, which left a tick hidden that way
+    // unreadable instead of state-toggled. Reads through getPropertyValue
+    // because a rule's own style leaves unset properties empty, which every
+    // test below treats as "not hidden".
+    //
+    // `opacity` is the one declaration the two callers must weigh differently,
+    // so it is passed in rather than fixed here. `display` and `visibility`
+    // have no middle ground; opacity does, and the two callers are asking
+    // different questions about it (see the two wrappers below).
+    const hiddenBy = (style, opacityHides) => style.getPropertyValue("display") === "none"
+      || ["hidden", "collapse"].includes(style.getPropertyValue("visibility"))
+      || opacityHides(Number.parseFloat(style.getPropertyValue("opacity") || "1"));
+
+    // What the buyer can see. An element faded to half its colour or less is
+    // not something a buyer reads a tick off, so the rendered test treats
+    // anything at or below half opacity as hidden. The threshold is a judgement about
+    // legibility, which is why it belongs only here.
+    const FADED_OUT_AT_OR_BELOW = 0.5;
+    const hiddenFromView = (style) => hiddenBy(style, (value) => value <= FADED_OUT_AT_OR_BELOW);
+
+    // What a stylesheet rule *declares*. The rule walk is not asking whether
+    // the buyer can see the element; it is asking whether a rule removes the
+    // element from rendering, because that is the display-toggled family's
+    // signature. `opacity: 0.4` is a dimmed style, not a hiding one — a
+    // greyed-out but perfectly visible marker would otherwise be read as a
+    // state-toggled tick and report a correctly declined bump as misaligned.
+    // Only `opacity: 0` removes a tick the way `display: none` does, so only
+    // an exact zero counts here.
+    const hiddenByDeclaration = (style) => hiddenBy(style, (value) => value === 0);
+
+    // The marker's `::after`, read once for both jobs it does here. A tick that
+    // is absolutely positioned can render while its host box measures zero, so
+    // a zero-sized host is not on its own proof that the tick is hidden — the
+    // pseudo-element has to be looked at before the size test disqualifies the
+    // marker. Returns null when the element has no generated content at all.
+    const pseudoTick = (element) => {
+      const after = getComputedStyle(element, "::after");
+      if (!hasContent(after.content)) return null;
+      // An unstyled tick is sized by its own content, and its computed width
+      // and height come back as `auto` rather than a length. Only an explicit
+      // zero means the tick occupies nothing; `auto` means the content decides,
+      // and the content is non-empty or we would not be here.
+      const boxed = (value) => {
+        const raw = String(value ?? "").trim();
+        if (raw === "" || raw === "auto") return true;
+        const parsed = Number.parseFloat(raw);
+        return Number.isFinite(parsed) ? parsed > 0 : true;
+      };
+      return {
+        shown: !hiddenFromView(after),
+        boxed: boxed(after.width) && boxed(after.height),
+      };
+    };
+
+    // The one visibility test, in two halves that every call site shares: is the
+    // element styled to be seen, and does it occupy a box. Both the toggle
+    // filter and the marker read go through these, so a toggle and its own
+    // marker can never be judged by different rules — `visibility: collapse`
+    // was rejected for a marker and accepted for the toggle containing it.
+    // Returns the computed style so a caller that needs it does not read twice.
+    const visibleStyle = (element) => {
+      if (!(element instanceof Element) || element.hidden) return null;
+      if (element.closest("[hidden]")) return null;
+      const style = getComputedStyle(element);
+      return hiddenFromView(style) ? null : style;
+    };
+
+    const hasBox = (element) => {
+      const rect = element.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0 && element.getClientRects().length > 0;
+    };
+
+    const displayed = (element) => Boolean(visibleStyle(element)) && hasBox(element);
+
+    // A marker is held to the same visibility rules, with one addition: a
+    // zero-sized host still renders when its own tick does.
+    const rendered = (element) => {
+      if (!visibleStyle(element)) return false;
+      if (hasBox(element)) return true;
+      const tick = pseudoTick(element);
+      return Boolean(tick && tick.shown && tick.boxed);
+    };
+
+    // A candidate must be a plausible marker at all: not the toggle's own form
+    // control, not inside a subtree the author removed from rendering.
+    const eligible = (element) => !element.matches(markerExcluded) && !element.closest("[hidden]");
+
+    // Does any stylesheet rule that *currently applies* and matches this element
+    // remove it from rendering? That is the display-toggled family's signature:
+    // a base rule hides the tick and a state-scoped rule restores it, so the
+    // element matches the hiding rule in both states. A persistent box that
+    // nothing hides matches nothing here, which is exactly why its visibility
+    // must not be read as its state.
+    //
+    // "Currently applies" is load-bearing. A rule inside `@media print`, or
+    // inside an `@supports` block for a feature this browser lacks, says
+    // nothing about what the buyer sees on screen; counting it would read a
+    // visible, unchecked box as a hidden tick and fail a correctly declined
+    // bump. So a conditional group is descended into only while its condition
+    // holds, a stylesheet whose own media attribute does not match is skipped,
+    // and so is a disabled one. A stylesheet the page cannot read
+    // (cross-origin, no CORS) is not evidence either way and is skipped too.
+    const hiddenByAMatchingRule = (element) => {
+      const mediaApplies = (query) => {
+        if (!query || query === "all") return true;
+        try {
+          return window.matchMedia(query).matches;
+        } catch {
+          return false;
+        }
+      };
+      const groupApplies = (rule) => {
+        // A container query is evaluated against a specific element's nearest
+        // container, and there is no API that answers that question for an
+        // arbitrary element — `CSS.supports` rejects a container condition
+        // outright. So an `@container` block is skipped deliberately rather
+        // than by accident: a tick hidden only inside one reads as unresolved,
+        // which is quiet, instead of being guessed at. Recorded as a known
+        // limit in fixtures/qa-order-bump/README.md.
+        if (typeof CSSContainerRule !== "undefined" && rule instanceof CSSContainerRule) return false;
+        // CSSMediaRule carries `.media`; CSSSupportsRule carries only a
+        // condition. Anything else grouping (a layer, a nested style rule) has
+        // no condition to fail and applies.
+        if (rule.media && typeof rule.media.mediaText === "string") {
+          return mediaApplies(rule.conditionText || rule.media.mediaText);
+        }
+        if (typeof rule.conditionText === "string") {
+          try {
+            return CSS.supports(rule.conditionText);
+          } catch {
+            return false;
+          }
+        }
+        return true;
+      };
+      const walk = (rules) => {
+        for (const rule of rules) {
+          if (rule.cssRules) {
+            if (!groupApplies(rule)) continue;
+            if (walk(Array.from(rule.cssRules))) return true;
+          }
+          if (!rule.selectorText || !rule.style || !hiddenByDeclaration(rule.style)) continue;
+          try {
+            // Pseudo-element selectors throw here; they are not this family.
+            if (element.matches(rule.selectorText)) return true;
+          } catch {
+            // unsupported selector: no evidence
+          }
+        }
+        return false;
+      };
+      for (const sheet of Array.from(document.styleSheets)) {
+        if (sheet.disabled) continue;
+        if (!mediaApplies(sheet.media?.mediaText)) continue;
+        let rules;
+        try {
+          rules = Array.from(sheet.cssRules || []);
+        } catch {
+          continue;
+        }
+        if (walk(rules)) return true;
+      }
+      return false;
+    };
+
+
+    // The positive signals, in the order that settles which vocabulary the
+    // marker speaks. Returns null when a rendered marker carries none.
+    const checkedSignal = (marker) => {
+      const style = getComputedStyle(marker);
+      // A marker with pseudo-element content belongs to the pseudo family
+      // whatever else is true of it, and its state is that pseudo-element's
+      // rendering — never the box's.
+      const tick = pseudoTick(marker);
+      if (tick) return { signal: "pseudo", checked: tick.shown };
+      if (/check|\u2713/.test(marker.textContent || "")) return { signal: "glyph", checked: true };
+      if (style.backgroundColor === acceptedFillColor) return { signal: "fill", checked: true };
+      if (hiddenByAMatchingRule(marker)) return { signal: "display_toggled", checked: true };
+      return null;
+    };
+
+    // Families in order. A rendered candidate wins outright; otherwise the
+    // first eligible candidate is kept so an off toggle still reports a marker
+    // (which then correctly reads unchecked) rather than reporting none.
+    const resolveMarker = (toggle) => {
+      let fallback = null;
+      for (const family of markerFamilies) {
+        const candidates = Array.from(toggle.querySelectorAll(family)).filter(eligible);
+        if (!candidates.length) continue;
+        const shown = candidates.find(rendered);
+        if (shown) return { element: shown, family };
+        if (!fallback) fallback = { element: candidates[0], family };
+      }
+      return fallback;
+    };
+
+    const toggles = Array.from(document.querySelectorAll(toggleSelector)).filter(displayed).map((toggle, index) => {
+      const input = toggle.querySelector('input[type="checkbox"]');
+      const resolved = resolveMarker(toggle);
+      const marker = resolved?.element || null;
+      const markerContainer = marker?.closest(markerContainers.join(", ")) || marker;
+      const markerVisible = Boolean(marker)
+        && rendered(marker)
+        && Boolean(markerContainer)
+        && rendered(markerContainer);
+      // A hidden marker is unchecked in every family, so it needs no signal.
+      // A rendered one is read for a positive signal, and a rendered marker
+      // with none is `unresolved`: it exists and renders, but nothing on it
+      // says which state it is in. That is distinct from finding no marker at
+      // all, which is a null signal, so the two are never conflated by a reader
+      // of the evidence.
+      const signal = marker && markerVisible ? checkedSignal(marker) : null;
+      const markerSignal = !marker
+        ? null
+        : (markerVisible ? signal?.signal || "unresolved" : "not_rendered");
+      const markerChecked = Boolean(markerVisible && signal?.checked);
+      // Readable: a marker was found AND its state can be read. An unreadable
+      // marker is read like an absent one, never as a disagreement.
+      const markerReadable = markerSignal !== null && markerSignal !== "unresolved";
+      const active = toggle.classList.contains("next-active")
+        || toggle.classList.contains("next-in-cart")
+        || toggle.classList.contains("next-selected")
+        || toggle.getAttribute("aria-pressed") === "true";
+      const inputChecked = input ? input.checked : null;
+      const inputAgrees = inputChecked === null || inputChecked === active;
+      const markerAgrees = !markerReadable || markerChecked === active;
+      return {
+        index,
+        packageId: toggle.getAttribute("data-next-package-id") || null,
+        active,
+        inputChecked,
+        // Was a marker element found at all. Unchanged in meaning: whether the
+        // harness located something to read.
+        markerResolved: Boolean(marker),
+        // Whether that marker's state could actually be read. A found-but-
+        // unreadable marker is resolved and not readable, and only `markerAgrees`
+        // depends on this one.
+        markerReadable,
+        // Which family matched and what it resolved to, so an operator reading
+        // a misaligned verdict can see whether the harness found the right
+        // element before concluding the page is wrong.
+        markerFamily: resolved?.family || null,
+        markerTag: marker ? marker.tagName.toLowerCase() : null,
+        // How the marker was read: "pseudo", "glyph", "fill" or
+        // "display_toggled" when a state vocabulary was recognised,
+        // "not_rendered" when the marker is on the page but hidden,
+        // "unresolved" when it renders but carries no state signal, and null
+        // when no marker was found at all.
+        markerSignal,
+        markerChecked,
+        inputAgrees,
+        markerAgrees,
+        statesAgree: inputAgrees && markerAgrees,
+      };
+    });
+    return { toggles };
+  };
+}