kaloko 0.4.11 → 0.5.0

package/src/lib/probe.mjs

@@ -268,6 +268,21 @@ export function probe ({ checks = [], highlights = [], scopes = [], maxChars = 9
   // HTTP status of the document (Chrome 109+); null for pages set from stored HTML
   const httpStatus = performance.getEntriesByType('navigation')[0]?.responseStatus || null
   const results = {}
+  // computed values for style_equals / style_matches, decided outside the page (src/lib/assertions.mjs) and kept
+  // with the capture so a recheck can reuse them
+  const values = {}
+  let paint = null
+  // canonical colour through the canvas: names, hsl(), hex and rgb() all come out as #rrggbb or rgba(…)
+  const canvasColor = (v) => {
+    try {
+      paint ||= document.createElement('canvas').getContext('2d')
+      paint.fillStyle = '#010203'; paint.fillStyle = String(v)
+      const out = paint.fillStyle
+      return out === '#010203' && !/^#010203$/i.test(String(v).trim()) ? null : out
+    } catch { return null }
+  }
+  const isColor = (p) => /(^|-)color$|^fill$|^stroke$/.test(String(p || '').trim().toLowerCase())
+  const squash = (s) => String(s ?? '').replace(/\s+/g, ' ').trim()
   for (const { id, check } of checks) {
     try {
       // optional flags (i, m, s); page text is innerText, which follows CSS text-transform (#54)
@@ -303,6 +318,50 @@ export function probe ({ checks = [], highlights = [], scopes = [], maxChars = 9
           evidence = `${check.attr}=${v}`
           break
         }
+        case 'text_equals': {
+          // the element's whole text, whitespace collapsed; flags: i ignores case
+          const els = check.selector ? visibleAll(check.selector) : [document.body]
+          if (!els.length) { evidence = `no visible ${check.selector}`; break }
+          const ci = /i/.test(String(check.flags || ''))
+          const want = squash(check.value)
+          const same = (el) => ci ? squash(el.innerText).toLowerCase() === want.toLowerCase() : squash(el.innerText) === want
+          const hits = els.filter(same)
+          ok = check.all === true ? hits.length === els.length : hits.length > 0
+          const shown = check.all === true ? (els.find((el) => !same(el)) || els[0]) : (hits[0] || els[0])
+          const text = clean(shown.innerText).slice(0, 160)
+          evidence = `${els.length > 1 ? `${hits.length} of ${els.length} × ${check.selector}; ` : ''}"${text}" ${same(shown) ? '=' : '≠'} "${clean(want).slice(0, 160)}"`
+          break
+        }
+        case 'attr_matches': {
+          const els = [...document.querySelectorAll(check.selector)]
+          if (!els.length) { evidence = `no ${check.selector}`; break }
+          const test = (el) => { const v = el.getAttribute(check.attr); return v != null && re.test(v) }
+          const hits = els.filter(test)
+          ok = check.all === true ? hits.length === els.length : hits.length > 0
+          const shown = check.all === true ? (els.find((el) => !test(el)) || els[0]) : (hits[0] || els[0])
+          const v = shown.getAttribute(check.attr)
+          evidence = `${els.length > 1 ? `${hits.length} of ${els.length} × ${check.selector}; ` : ''}${check.attr}${v == null ? ' missing' : `="${clean(v).slice(0, 160)}"`} ${test(shown) ? 'matches' : 'does not match'} /${check.pattern}/`
+          break
+        }
+        case 'style_equals':
+        case 'style_matches': {
+          // visible matches; when none is visible (a check for display: none), every match
+          let els = visibleAll(check.selector)
+          if (!els.length) els = [...document.querySelectorAll(check.selector)]
+          const prop = String(check.property || '').trim().toLowerCase()
+          const color = isColor(prop)
+          const rec = { selector: check.selector, property: check.property, values: els.slice(0, 50).map((el) => { const v = squash(getComputedStyle(el).getPropertyValue(prop)); return { el: describe(el), value: v, ...(color ? { color: canvasColor(v) } : {}) } }), root_px: parseFloat(getComputedStyle(document.documentElement).fontSize) || 16 }
+          if (check.token) {
+            // a token published as a CSS custom property (color.brand.primary → --color-brand-primary)
+            const name = `--${String(check.token).replace(/\./g, '-')}`
+            const v = squash(getComputedStyle(document.documentElement).getPropertyValue(name))
+            rec.token_var = v ? { name, value: v, ...(color ? { color: canvasColor(v) } : {}) } : null
+          }
+          if (check.value != null && color) rec.expected_color = canvasColor(check.value)
+          values[id] = rec
+          ok = null; evidence = 'decided outside the page'
+          break
+        }
         case 'no_overflow': { const list = check.selector ? [...document.querySelectorAll(check.selector)].flatMap(overflowIn) : overflow; ok = list.length === 0; evidence = ok ? 'no horizontal overflow' : list.slice(0, 3).map((o) => `${o.el} right=${o.right}px > ${o.width}px`).join('; '); break }
         case 'title_matches': ok = re.test(document.title); evidence = document.title; break
         case 'meta_matches': { const el = document.querySelector(check.selector); const v = el?.getAttribute('content'); ok = v != null && re.test(v); evidence = v ?? `no ${check.selector}`; break }
@@ -426,6 +485,7 @@ export function probe ({ checks = [], highlights = [], scopes = [], maxChars = 9
     http_status: httpStatus,
     scoped,
     checks: results,
+    ...(Object.keys(values).length ? { values } : {}),
     boxes,
     overflow,
     meta,

package/src/lib/recheck.mjs

@@ -1,7 +1,8 @@
 // `kaloko evaluate --recheck` (#55): after a scenario fix, re-run the deterministic checks against the stored HTML of
 // each capture instead of walking again (some steps cannot be repeated: data created, e-mails sent once, states that
 // moved on). Page scripts stay off, so nothing in the stored page runs; checks that only the live page can answer
-// (console errors, overflow, performance) keep their result from the capture.
+// (console errors, overflow, performance) keep their result from the capture. Computed styles and js_equals
+// expressions are decided again from the values recorded at capture, when the criterion reads the same thing.
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { readJson, writeJson } from './util.mjs'
@@ -13,6 +14,7 @@ import { contextOptions, prepareContext } from './access.mjs'
 import { launchEphemeral } from './browser.mjs'
 import { treeChecks } from './apps/tree.mjs'
 import { KEYBOARD_ASSERTS } from './keyboard.mjs'
+import { VALUE_ASSERTS, storedValueChecks } from './assertions.mjs'
 
 // keyboard walk and accessibility tree (#19) need the live page too
 export const LIVE_ONLY = (assert) => assert === 'no_console_errors' || assert === 'no_overflow' || assert === 'http_status' || assert === 'links_ok' || assert === 'hreflang_pairs' || /^perf_/.test(assert) || KEYBOARD_ASSERTS.has(assert)
@@ -59,8 +61,11 @@ export async function recheckCaptures ({ run, scenario, config, root, env, only
         await page.setContent(withBase(html, cap.url), { waitUntil: 'load', timeout: 20000 }).catch(() => {})
         const result = await page.evaluate(probe, probeArgs(node, config.evaluators?.jev?.max_state_chars))
         const checks = {}
+        // URL from the capture; styles and expressions from the values recorded at capture (src/lib/assertions.mjs)
+        const stored = storedValueChecks(node, cap)
         for (const c of node.criteria || []) {
           if (c.check.type !== 'deterministic') continue
+          if (VALUE_ASSERTS.has(c.check.assert)) { checks[c.id] = stored[c.id]; continue }
           checks[c.id] = LIVE_ONLY(c.check.assert) ? (cap.checks?.[c.id] ?? { ok: null, evidence: 'live-page check; capture the step again to evaluate it' }) : result.checks[c.id]
         }
         await writeJson(file, { ...cap, checks, boxes: result.boxes, criteria_hash: criteriaHash(node), rechecked_at: new Date().toISOString() })

package/src/lib/scenario.mjs

@@ -3,6 +3,7 @@ import yaml from 'js-yaml'
 import { schemaErrors } from './schema.mjs'
 import { UserError } from './util.mjs'
 import { expandPacks } from './packs.mjs'
+import { jsGuard } from './assertions.mjs'
 
 export async function loadScenario (file) {
   const data = yaml.load(await readFile(file, 'utf8'))
@@ -25,6 +26,8 @@ export function validateScenario (data) {
     for (const c of node.criteria || []) {
       if (acIds.has(c.id)) problems.push(`node "${node.id}": criterion ${c.id} is duplicated`)
       acIds.add(c.id)
+      // js_equals reads the page; an expression that could write or act is refused before any walk
+      if (c.check?.assert === 'js_equals') { const why = jsGuard(c.check.expression); if (why) problems.push(`node "${node.id}": ${c.id} js_equals expression: ${why}`) }
     }
     if (!['decision', 'stack'].includes(node.kind) && !node.execution) problems.push(`node "${node.id}": execution is required for ${node.kind} steps`)
     if (node.kind === 'stack' && !node.items) problems.push(`node "${node.id}": stack steps need items (urls, file, sitemap, crawl or script)`)

package/src/lib/stability-core.mjs

@@ -90,10 +90,12 @@ export function mergeRects (rects, slack = 0) {
  * ignore: [{ selector: '.clock' }, { rect: [x, y, w, h], viewport: desktop }, { selector: '#ad', locales: [cs] }]
  */
 export function ignoreFor (node, locale, viewport) {
+  // a viewport name also covers its capture keys in other browsers and schemes (mobile → mobile.webkit.dark)
+  const hit = (v) => v === viewport || v === String(viewport).split('.')[0]
   return (Array.isArray(node?.ignore) ? node.ignore : []).filter((e) => {
     if (!e || typeof e !== 'object') return false
-    if (e.viewport && e.viewport !== viewport) return false
-    if (Array.isArray(e.viewports) && e.viewports.length && !e.viewports.includes(viewport)) return false
+    if (e.viewport && !hit(e.viewport)) return false
+    if (Array.isArray(e.viewports) && e.viewports.length && !e.viewports.some(hit)) return false
     if (Array.isArray(e.locales) && e.locales.length && !e.locales.includes(locale)) return false
     return !!(e.selector || (Array.isArray(e.rect) && e.rect.length === 4))
   })

package/src/lib/walk-dimensions.mjs

@@ -0,0 +1,83 @@
+// CLI side of run dimensions (batch E): the scope `kaloko start` writes, the capture keys a walk pass or a manual
+// capture takes, and the lines the CLI prints. The rules themselves live in dimensions.mjs.
+import { UserError } from './util.mjs'
+import { isApp } from './apps/drivers.mjs'
+import { resolveViewports, expandScope, dimensionsFrom, appDevices, variantOf, pickKeys, DIMENSIONS } from './dimensions.mjs'
+
+const list = (v) => (typeof v === 'string' ? v.split(',').map((s) => s.trim()).filter(Boolean) : Array.isArray(v) ? v : null)
+
+/**
+ * The scope of a new run: viewports (sizes and device presets), app devices and the dimensions from the CLI,
+ * the scenario and the config. Web runs take every dimension; app runs take devices, colour scheme and motion;
+ * Design environments render in Chromium with presets at their whole screen.
+ */
+export function startScope ({ args = {}, scenario, config, env }) {
+  const platform = scenario.platform || 'web'
+  const dims = dimensionsFrom({ args, scenario, config })
+  const design = env?.kind === 'design'
+  if (isApp(platform) || design) {
+    for (const k of ['browsers', 'display_modes']) if (dims[k] && (args[k.replace(/_/g, '-')] || scenario[k])) throw new UserError(`${k.replace(/_/g, ' ')} apply to web runs; ${design ? 'design steps render in Chromium' : `a ${platform} app walks on its devices`}.`)
+    dims.browsers = null; dims.display_modes = null
+    if (isApp(platform)) dims.forced_colors = null
+  }
+  if (isApp(platform)) {
+    const ids = list(args.devices) || scenario.devices
+    if (ids?.length) {
+      const { viewports, devices } = appDevices(ids, platform)
+      return expandScope({ viewports, devices, dims })
+    }
+  }
+  const fullScreen = design
+  const { viewports: all, devices } = resolveViewports(scenario.viewports, { fullScreen })
+  const names = list(args.viewports) || Object.keys(all)
+  const vps = {}; const devs = {}
+  for (const n of names) {
+    if (all[n]) { vps[n] = all[n]; if (devices[n]) devs[n] = devices[n]; continue }
+    // --viewports may name a preset the scenario does not list (kaloko start --viewports iphone-se,fold-open)
+    const r = resolveViewports([n], { fullScreen, fallback: {} })
+    Object.assign(vps, r.viewports); Object.assign(devs, r.devices)
+  }
+  return expandScope({ viewports: vps, devices: devs, dims })
+}
+
+/** Viewport names of a scope without the dimension suffixes, in order. */
+export const baseViewports = (scope) => [...new Set(Object.keys(scope?.viewports || {}).map((k) => variantOf(scope, k).viewport))]
+
+/** "  browsers: chromium, webkit · color schemes: light, dark" for `kaloko start` (empty without dimensions). */
+export function dimensionLine (scope) {
+  const parts = DIMENSIONS.filter((d) => scope?.dimensions?.[d.list]).map((d) => `${d.list.replace(/_/g, ' ')}: ${scope.dimensions[d.list].join(', ')}`)
+  const devices = Object.values(scope?.devices || {}).map((d) => d.title)
+  if (devices.length) parts.push(`devices: ${devices.join(', ')}`)
+  const keys = Object.keys(scope?.viewports || {}).length
+  return parts.length ? `\n  ${parts.join(' · ')}${keys > 1 ? ` (${keys} captures per step and locale)` : ''}` : ''
+}
+
+/**
+ * { key: [w, h] } of the keys a capture takes: `names` (viewport names or full keys, from --viewports or
+ * capture({ viewports })) within `keys` (a walk pass, or every key of an engine). An unknown name is an error.
+ */
+export function scopeKeys (scope, keys, names = null) {
+  const all = scope.viewports
+  if (names) for (const n of names) if (!all[n] && !Object.keys(all).some((k) => variantOf(scope, k).viewport === n)) throw new UserError(`Unknown viewport "${n}".`)
+  return Object.fromEntries(pickKeys(scope, keys, names).map((k) => [k, all[k]]))
+}
+
+/**
+ * Walks of an app run: one per device of `devices:` (its keys: colour scheme and motion variants), or one walk on
+ * the environment's device with the keys of the first viewport. `only` limits the devices (walk --devices).
+ */
+export function appDeviceGroups (scope, only = null) {
+  const keys = Object.keys(scope?.viewports || {})
+  const bases = baseViewports(scope)
+  const devices = bases.filter((b) => scope.devices?.[b]?.app)
+  const keysOf = (base) => keys.filter((k) => variantOf(scope, k).viewport === base)
+  if (devices.length) {
+    const picked = devices.filter((id) => !only || only.includes(id))
+    if (!picked.length) throw new UserError(`This run has no device ${only.join(', ')} (its devices: ${devices.join(', ')}).`)
+    return picked.map((id) => ({ device: id, title: scope.devices[id].title || id, keys: keysOf(id) }))
+  }
+  return [{ device: null, title: null, keys: bases.length ? keysOf(bases[0]) : [] }]
+}
+
+/** Keys of one engine (a capture on the shared Chromium takes the Chromium keys). */
+export const engineKeys = (scope, engine = 'chromium') => Object.keys(scope?.viewports || {}).filter((k) => variantOf(scope, k).browser === engine)