kryptheon 0.1.6 → 0.1.8

package/kryptheon-signature.js

@@ -0,0 +1,530 @@
+// A "DOM signature": a small, plain description of what a page ended up
+// showing. Not a screenshot and not a pixel comparison - just the words a
+// person would use to say what is on screen.
+//
+// Why it exists. Automatic baselines currently remember the final address and
+// the page title. In a single-page app with a catch-all route those both stay
+// the same when a flow breaks: a login that no longer logs anyone in still
+// lands on the same URL with the same title, so the baseline sees no
+// difference and the run is reported as fine. The signature is the thing that
+// would have noticed - the headings, buttons, links and fields on the page
+// change even when the address does not.
+//
+// STEP ONE ONLY. This module captures and prints. Nothing here is written to a
+// baseline, compared against anything, or allowed to affect whether a test
+// passes. Collection does not even run unless KRYPTHEON_DEBUG_SIGNATURE=1.
+
+const fs = require('fs');
+
+const MAX_TEXT = 80;
+const MAX_ACTIONS = 40;
+
+// ---------------------------------------------------------------------------
+// Pure helpers. No browser, no filesystem - so the unit checks can exercise
+// them directly.
+// ---------------------------------------------------------------------------
+
+/**
+ * One line, no digits, capped.
+ *
+ * The digits are the important part. "Savings rate 0%" and "Savings rate 12%"
+ * are the same page as far as this is concerned, and a signature that treated
+ * them as different would report a regression every time a number moved.
+ */
+function normaliseText(value) {
+  const line = String(value == null ? '' : value)
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\d+/g, '#');
+  return line.length > MAX_TEXT ? line.slice(0, MAX_TEXT) : line;
+}
+
+function uniqueSorted(list) {
+  const seen = Object.create(null);
+  const out = [];
+  for (const item of list || []) {
+    const text = normaliseText(item);
+    if (!text || seen[text]) continue;
+    seen[text] = true;
+    out.push(text);
+  }
+  return out.sort();
+}
+
+function uniqueInOrder(list) {
+  const seen = Object.create(null);
+  const out = [];
+  for (const item of list || []) {
+    const text = normaliseText(item);
+    if (!text || seen[text]) continue;
+    seen[text] = true;
+    out.push(text);
+  }
+  return out;
+}
+
+/**
+ * Path only: no host, no query string, no fragment.
+ *
+ * Deliberately not the reporter's requestPath, which keeps the query string so
+ * a person reading a failure can see it. A signature is stored and compared,
+ * and query strings routinely carry tokens, ids and search terms.
+ */
+function signaturePath(requestUrl) {
+  let s = String(requestUrl == null ? '' : requestUrl);
+  try {
+    s = new URL(s).pathname || '/';
+  } catch (e) {
+    // Not absolute: strip any scheme://host by hand, then the query and hash.
+    s = s.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/[^/]*/, '');
+    const hash = s.indexOf('#');
+    if (hash !== -1) s = s.slice(0, hash);
+    const query = s.indexOf('?');
+    if (query !== -1) s = s.slice(0, query);
+  }
+  return s || '/';
+}
+
+/** Method, path and status. Never a query string, never a body. */
+function toSignatureRequests(list) {
+  const seen = Object.create(null);
+  const out = [];
+  for (const req of list || []) {
+    const status = Number(req && req.status);
+    if (!(status >= 400 && status <= 599)) continue;
+    const entry = {
+      method: (req && req.method) || 'GET',
+      path: signaturePath((req && req.url) != null ? req.url : req && req.path),
+      status: status,
+    };
+    const key = entry.method + ' ' + entry.path + ' ' + entry.status;
+    if (seen[key]) continue;
+    seen[key] = true;
+    out.push(entry);
+  }
+  return out;
+}
+
+/** Assembles the signature from raw, page-shaped input. */
+function buildSignature(raw) {
+  const input = raw || {};
+  return {
+    headings: uniqueInOrder(input.headings),
+    actions: uniqueSorted(input.actions).slice(0, MAX_ACTIONS),
+    fields: uniqueSorted(input.fields),
+    failedRequests: toSignatureRequests(input.failedRequests),
+  };
+}
+
+/**
+ * One plain line saying what was on screen, for a failure report.
+ *
+ * Deliberately not the JSON. Somebody reading a failure wants "it was still on
+ * the sign-in page", not a structure to parse; the whole object stays behind
+ * the debug flag for when the detail is actually wanted.
+ */
+function describeSignature(signature) {
+  if (!signature || typeof signature !== 'object') return null;
+  const headings = (signature.headings || []).slice(0, 2);
+  const actions = (signature.actions || []).slice(0, 3);
+  const fields = (signature.fields || []).slice(0, 3);
+
+  let what;
+  if (headings.length) what = quoteList(headings);
+  else if (fields.length) what = 'a form';
+  else if (actions.length) what = 'no headings';
+  else return null; // nothing readable was on the page
+
+  const parts = [];
+  if (actions.length) parts.push(actions.join(', '));
+  if (!headings.length && fields.length) parts.push(fields.join(', '));
+  return parts.length ? what + ' with ' + parts.join('; ') : what;
+}
+
+// ---------------------------------------------------------------------------
+// Comparing two signatures.
+// ---------------------------------------------------------------------------
+
+/**
+ * What left and what arrived, as sets.
+ *
+ * Sets, not sequences: a page that moves its buttons around is the same page.
+ * Only something appearing or disappearing is worth stopping a run over.
+ */
+function setDifference(before, after) {
+  const had = new Set(before || []);
+  const has = new Set(after || []);
+  return {
+    gone: [...had].filter((item) => !has.has(item)),
+    added: [...has].filter((item) => !had.has(item)),
+  };
+}
+
+function requestLabel(req) {
+  return (req.method || 'GET') + ' ' + req.path + ' ' + req.status;
+}
+
+function quoteList(items) {
+  return items.map((item) => '"' + item + '"').join(', ');
+}
+
+/**
+ * Compares a stored signature with what this run saw. Returns a message
+ * describing the change, or null when nothing worth failing over moved.
+ *
+ * Returns null when either side is missing. A baseline recorded before this
+ * feature existed has no signature and must keep working on address and title
+ * alone, and a run whose capture failed knows nothing - neither is evidence of
+ * a regression, and treating them as one would fail every old project on
+ * upgrade.
+ */
+function compareSignatures(previous, current) {
+  if (!previous || typeof previous !== 'object') return null;
+  if (!current || typeof current !== 'object') return null;
+
+  const headings = setDifference(previous.headings, current.headings);
+  const actions = setDifference(previous.actions, current.actions);
+  const fields = setDifference(previous.fields, current.fields);
+
+  // Only new failures matter. A 500 that has been fixed since the baseline was
+  // taken is an improvement, and failing the run for it would be perverse.
+  const knownRequests = new Set((previous.failedRequests || []).map(requestLabel));
+  const newRequests = (current.failedRequests || [])
+    .map(requestLabel)
+    .filter((label) => !knownRequests.has(label));
+
+  const moved =
+    headings.gone.length ||
+    headings.added.length ||
+    actions.gone.length ||
+    actions.added.length ||
+    fields.gone.length ||
+    fields.added.length ||
+    newRequests.length;
+  if (!moved) return null;
+
+  const lines = ['Baseline changed: the page ended up somewhere different than before.'];
+  if (headings.gone.length) lines.push('Headings that are gone: ' + quoteList(headings.gone));
+  if (headings.added.length) lines.push('Headings that are new: ' + quoteList(headings.added));
+  if (actions.gone.length) lines.push('Buttons and links that are gone: ' + quoteList(actions.gone));
+  if (actions.added.length) lines.push('Buttons and links that are new: ' + quoteList(actions.added));
+  if (fields.gone.length) lines.push('Form fields that are gone: ' + quoteList(fields.gone));
+  if (fields.added.length) lines.push('Form fields that are new: ' + quoteList(fields.added));
+  if (newRequests.length) lines.push('Requests that failed this time: ' + newRequests.join(', '));
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// The browser side.
+// ---------------------------------------------------------------------------
+
+// Runs inside the page. Written as a single self-contained function because
+// page.evaluate serialises it across the wire - it cannot close over anything
+// in this file.
+function readPage() {
+  const isVisible = (el) => {
+    if (!el) return false;
+    // checkVisibility covers display:none, visibility:hidden, content-visibility
+    // and the hidden attribute in one call where it exists.
+    if (typeof el.checkVisibility === 'function') {
+      if (!el.checkVisibility({ checkOpacity: false, checkVisibilityCSS: true })) return false;
+    } else {
+      const style = window.getComputedStyle(el);
+      if (style.display === 'none' || style.visibility === 'hidden') return false;
+    }
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 || rect.height > 0;
+  };
+
+  const text = (el) => (el && el.innerText ? el.innerText : (el && el.textContent) || '');
+
+  const headings = [];
+  for (const el of document.querySelectorAll('h1, h2, h3')) {
+    if (isVisible(el)) headings.push(text(el));
+  }
+
+  const actions = [];
+  const actionSelector =
+    'button, a[href], [role="button"], [role="link"], input[type="submit"], input[type="button"]';
+  for (const el of document.querySelectorAll(actionSelector)) {
+    if (!isVisible(el)) continue;
+    const label =
+      el.getAttribute('aria-label') ||
+      (el.tagName === 'INPUT' ? el.value : '') ||
+      text(el) ||
+      el.getAttribute('title') ||
+      '';
+    if (label) actions.push(label);
+  }
+
+  const fields = [];
+  for (const el of document.querySelectorAll('input, select, textarea')) {
+    const type = (el.getAttribute('type') || '').toLowerCase();
+    if (type === 'hidden' || type === 'submit' || type === 'button') continue;
+    if (!isVisible(el)) continue;
+    // What a person would call this field, in the order they would find it.
+    let label = '';
+    if (el.id) {
+      const tag = document.querySelector('label[for="' + CSS.escape(el.id) + '"]');
+      if (tag) label = text(tag);
+    }
+    if (!label && el.closest('label')) label = text(el.closest('label'));
+    if (!label) label = el.getAttribute('aria-label') || '';
+    if (!label) label = el.getAttribute('placeholder') || '';
+    if (!label) label = el.getAttribute('name') || '';
+    if (!label) label = el.id || '';
+    if (label) fields.push(label);
+  }
+
+  // A page that never declares its encoding is decoded by guesswork, and the
+  // text really does come out as mojibake - on screen and therefore in here.
+  // That is the app's bug, not this tool's, but it is worth saying once.
+  const declared = !!document.querySelector('meta[charset], meta[http-equiv="Content-Type" i]');
+  const guessedEncoding = !declared && String(document.characterSet || '').toUpperCase() !== 'UTF-8';
+
+  return { headings: headings, actions: actions, fields: fields, guessedEncoding: guessedEncoding };
+}
+
+/** True only for an explicit opt-in. */
+function signatureEnabled(env) {
+  const source = env || process.env;
+  return String(source.KRYPTHEON_DEBUG_SIGNATURE || '') === '1';
+}
+
+// How often the page is read while waiting for it to hold still.
+const SETTLE_GAP = 200;
+// How long it has to hold still before the reading is believed. Measured, not
+// guessed: against a page that renders 1.5s after its request answers, 700ms
+// still read the screen from before the click and 1200ms read the right one.
+const SETTLE_QUIET = 1200;
+// Never spend longer than this on one signature, however restless the page.
+const SETTLE_BUDGET = 4000;
+// A pending request is worth waiting out first, but not for the whole budget.
+const NETWORK_BUDGET = 1500;
+
+/** Two readings of the same page, exactly. */
+function sameSignature(a, b) {
+  if (!a || !b) return false;
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+async function pause(page, ms) {
+  try {
+    await page.waitForTimeout(ms);
+  } catch (e) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+async function readSignature(page, failedRequests) {
+  const raw = await page.evaluate(readPage);
+  const signature = buildSignature({
+    headings: raw.headings,
+    actions: raw.actions,
+    fields: raw.fields,
+    failedRequests: failedRequests,
+  });
+  // Not part of the signature itself - it describes the page's markup, not
+  // what the page showed, and it must never count as a difference.
+  Object.defineProperty(signature, 'guessedEncoding', {
+    value: !!raw.guessedEncoding,
+    enumerable: false,
+  });
+  return signature;
+}
+
+/**
+ * Reads the page once it has stopped changing, and returns a signature - or
+ * null if it could not be read at all. Never throws: this is a diagnostic and
+ * must not become a second failure.
+ *
+ * Why it is not just networkidle. In a single-page app a click causes no
+ * navigation: the request answers and the framework swaps the DOM a moment
+ * later. Playwright's networkidle means "no requests for 500ms", which is a
+ * fact about the network, not about the page - so a render that lands even
+ * 300ms after the response is missed entirely and the reading describes the
+ * screen the user was on *before* the click. That is exactly how a working
+ * login came back as the login form.
+ *
+ * Why it is not a fixed sleep either: whatever number is picked is too short
+ * for a slow machine and wasted on a fast one.
+ *
+ * So: wait out any pending request, then read the page repeatedly until it has
+ * held still for a while. The quiet window matters more than the gap between
+ * reads - two identical readings 200ms apart prove nothing on a page that is
+ * simply waiting, which is why stability is measured from the last change seen
+ * rather than from the first pair that happened to agree. A page that never
+ * settles is capped, and whatever it looked like at the cap is used; running
+ * out of patience is not a reason to fail somebody's test.
+ */
+function positiveNumber(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+/**
+ * The quiet window and the cap, either of which a slow app may need more of.
+ *
+ * No amount of waiting can predict a render that has not happened yet, so
+ * these are a judgement about how long a page is given to prove it has
+ * finished. An app that renders later than the window still reads early, and
+ * raising this is the way out of that.
+ */
+function settleSettings(env) {
+  const source = env || process.env;
+  return {
+    quiet: positiveNumber(source.KRYPTHEON_SIGNATURE_QUIET_MS, SETTLE_QUIET),
+    budget: positiveNumber(source.KRYPTHEON_SIGNATURE_BUDGET_MS, SETTLE_BUDGET),
+  };
+}
+
+async function collectSignature(page, failedRequests, options) {
+  const opts = options || {};
+  const fromEnv = settleSettings(opts.env);
+  const gap = opts.settleGap == null ? SETTLE_GAP : opts.settleGap;
+  const quiet = opts.settleQuiet == null ? fromEnv.quiet : opts.settleQuiet;
+  const budget = opts.settleBudget == null ? fromEnv.budget : opts.settleBudget;
+
+  try {
+    const started = Date.now();
+
+    // An answer still in flight will change the page the moment it lands, so
+    // it is worth waiting out before deciding the page has stopped moving.
+    try {
+      await page.waitForLoadState('networkidle', {
+        timeout: Math.min(NETWORK_BUDGET, Math.max(0, budget - (Date.now() - started))),
+      });
+    } catch (e) {
+      /* still talking, or the state is unavailable - the loop below copes */
+    }
+
+    let current = await readSignature(page, failedRequests);
+    let lastChange = Date.now();
+
+    for (;;) {
+      const now = Date.now();
+      if (now - lastChange >= quiet) return current;
+      if (now - started >= budget) return current;
+      await pause(page, gap);
+      const next = await readSignature(page, failedRequests);
+      if (!sameSignature(current, next)) lastChange = Date.now();
+      current = next;
+    }
+  } catch (e) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Getting the signature out of the worker and onto the terminal.
+//
+// Nothing written from inside a Playwright worker reaches the terminal here.
+// Playwright pipes the worker's real file descriptors and hands whatever comes
+// out to reporter.onStdOut / onStdErr; kryptheon's reporter implements neither
+// hook and the config runs no other reporter, so it is collected and dropped.
+// Measured, not assumed: console.log, process.stdout.write, process.stderr.write
+// and fs.writeSync to both fd 1 and fd 2 all vanish.
+//
+// So the worker hands the signature over through a file, and the CLI - whose
+// stderr really is the terminal - prints it once the run is over. The reporter
+// and its output format are untouched.
+// ---------------------------------------------------------------------------
+
+const SINK_ENV = 'KRYPTHEON_SIGNATURE_FILE';
+
+/** Where the worker should leave signatures, or null if nobody asked for them. */
+function sinkPath(env) {
+  const source = env || process.env;
+  const file = source[SINK_ENV];
+  return file ? String(file) : null;
+}
+
+/** One JSON line per test. Append-only, so parallel workers cannot interleave. */
+function recordSignature(label, signature, env) {
+  const file = sinkPath(env);
+  if (!file) return false;
+  try {
+    fs.appendFileSync(file, JSON.stringify({ test: label, signature: signature }) + '\n', 'utf8');
+    return true;
+  } catch (e) {
+    return false; // a diagnostic must never become a second failure
+  }
+}
+
+/** Reads what the workers left, newest run last. Missing file means nothing ran. */
+function readRecorded(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch (e) {
+      /* a torn line is not worth failing over */
+    }
+  }
+  return out;
+}
+
+/**
+ * Prints the signature. Step one does nothing else with it.
+ *
+ * Goes to stderr so the reporter's own output, which is stdout, stays exactly
+ * as it was - a person or a script reading the report sees no difference.
+ */
+function printSignature(signature, label, out) {
+  const write = out || ((line) => process.stderr.write(line + '\n'));
+  if (!signature) {
+    write('[kryptheon signature] ' + label + ': could not read the page');
+    return;
+  }
+  write('[kryptheon signature] ' + label);
+  write(JSON.stringify(signature, null, 2));
+}
+
+/** Prints everything the workers recorded, then clears the file. */
+function drainSignatures(file, out) {
+  const records = readRecorded(file);
+  for (const record of records) {
+    printSignature(record.signature, record.test, out);
+  }
+  try {
+    fs.rmSync(file, { force: true });
+  } catch (e) {
+    /* leftover temp file is not worth failing over */
+  }
+  return records.length;
+}
+
+module.exports = {
+  SINK_ENV: SINK_ENV,
+  sinkPath: sinkPath,
+  recordSignature: recordSignature,
+  readRecorded: readRecorded,
+  drainSignatures: drainSignatures,
+  normaliseText: normaliseText,
+  uniqueSorted: uniqueSorted,
+  uniqueInOrder: uniqueInOrder,
+  signaturePath: signaturePath,
+  toSignatureRequests: toSignatureRequests,
+  buildSignature: buildSignature,
+  compareSignatures: compareSignatures,
+  describeSignature: describeSignature,
+  setDifference: setDifference,
+  signatureEnabled: signatureEnabled,
+  collectSignature: collectSignature,
+  printSignature: printSignature,
+  readPage: readPage,
+  sameSignature: sameSignature,
+  settleSettings: settleSettings,
+  MAX_TEXT: MAX_TEXT,
+  SETTLE_GAP: SETTLE_GAP,
+  SETTLE_QUIET: SETTLE_QUIET,
+  SETTLE_BUDGET: SETTLE_BUDGET,
+  MAX_ACTIONS: MAX_ACTIONS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kryptheon",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Record what you do in your app and get plain-language reports when it breaks.",
   "license": "MIT",
   "type": "commonjs",
@@ -12,12 +12,16 @@
     "./kryptheon-fixture": "./kryptheon-fixture.js",
     "./kryptheon-reporter": "./kryptheon-reporter.js",
     "./package.json": "./package.json",
-    "./kryptheon-replay": "./kryptheon-replay.js"
+    "./kryptheon-replay": "./kryptheon-replay.js",
+    "./kryptheon-signature": "./kryptheon-signature.js",
+    "./kryptheon-secrets": "./kryptheon-secrets.js"
   },
   "files": [
     "bin/",
     "kryptheon-fixture.js",
     "kryptheon-reporter.js",
+    "kryptheon-signature.js",
+    "kryptheon-secrets.js",
     "playwright.config.js",
     "README.md",
     "kryptheon-replay.js"
@@ -29,7 +33,11 @@
     "@playwright/test": "^1.62.1"
   },
   "scripts": {
-    "check": "node kryptheon-reporter.check.js"
+    "check": "node kryptheon-reporter.check.js && node kryptheon-signature.check.js && node kryptheon-signature.stream.check.js && node kryptheon-signature.baseline.check.js && node kryptheon-signature.settle.check.js && node kryptheon-step3.check.js",
+    "check:stream": "node kryptheon-signature.stream.check.js",
+    "check:baseline": "node kryptheon-signature.baseline.check.js",
+    "check:settle": "node kryptheon-signature.settle.check.js",
+    "check:step3": "node kryptheon-step3.check.js"
   },
   "keywords": [
     "playwright",

package/playwright.config.js

@@ -12,27 +12,27 @@ const USER_DIR = process.cwd();
 // .env is not fatal: CI can supply the same variables as real env vars.
 // loadEnvFile only exists from Node 20.12, and the package supports 20.6, so
 // fall back to a small parser rather than silently skipping the file.
+// Deliberately not process.loadEnvFile, and this is the whole reason:
+//
+// On Windows, PowerShell's `Out-File -Encoding utf8` and Notepad's "Save as
+// UTF-8" both write a byte order mark. loadEnvFile keeps it, so the first line
+// of the file defines "KRYPTHEON_PASSWORD" rather than
+// "KRYPTHEON_PASSWORD" - measured, not assumed. The variable then reads as
+// undefined, the recording signs in with an empty password, and the login
+// fails for a reason nothing in the report mentions. The file is right there,
+// so nothing warns either.
+//
+// One parser, shared with the CLI, is also what stops the command that decides
+// whether a password is present from disagreeing with the test that uses it.
 function loadEnv(file) {
-  if (typeof process.loadEnvFile === 'function') {
-    try {
-      process.loadEnvFile(file);
-      return;
-    } catch (err) {
-      if (err && err.code !== 'ENOENT') throw err;
-      return;
-    }
-  }
-  let raw;
-  try {
-    raw = require('fs').readFileSync(file, 'utf8');
-  } catch (err) {
-    return; // no .env is fine
-  }
-  for (const line of raw.split('\n')) {
-    const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
-    if (!match) continue;
-    const value = match[2].replace(/^(['"])(.*)\1$/, '$2');
-    if (process.env[match[1]] === undefined) process.env[match[1]] = value;
+  const secrets = require(path.join(PACKAGE_DIR, 'kryptheon-secrets.js'));
+  const values = secrets.readEnvFile(file);
+  for (const name of Object.keys(values)) {
+    // A real environment variable wins over the file - but only a real one.
+    // A variable that exists and is empty is how "unset" arrives from a shell
+    // or a CI job, and letting that beat the file would leave the password
+    // blank with the answer sitting right there on disk.
+    if (!secrets.isSet(process.env[name])) process.env[name] = values[name];
   }
 }