kryptheon 0.1.16 → 0.1.18

package/README.md

@@ -46,6 +46,22 @@ npx kryptheon record https://your-app.example.com
 A browser opens. Use your app the way a customer would. Close the browser when
 you are done, and the recording is saved as a test.
 
+On its own, a recording knows that every button and field is still there and
+that the last page looks the same. To say what must be true — "Reservation
+received" appears after booking — use the toolbar at the top of the page while
+recording:
+
+| Button | Click it, then click… | Kryptheon then checks |
+| --- | --- | --- |
+| Eye | any element | it is on the page |
+| `ab` | some text | that text is there |
+| Box | a filled-in field | the field still holds that value |
+| `{ }` | a part of the page | that part is laid out the same |
+
+The round red button pauses and resumes recording. The arrow only shows how an
+element would be found; it adds nothing to the test. One check at the end of a
+flow — on the success message — is usually all a recording needs.
+
 ## Check
 
 ```
@@ -127,6 +143,24 @@ npx kryptheon accept "Checkout"
 
 `npx kryptheon accept` on its own lists what has been saved.
 
+## Renamed buttons
+
+A button that only changed its words has not broken anything. When a step
+cannot find "Reserve a table" and the page shows exactly one new button in its
+place — "Reserve here" — kryptheon clicks that one, carries on through the rest
+of the flow, and says so:
+
+```
+OK  Reserve a table  (16.0s)
+    Renamed: The button "Reserve a table" is now called "Reserve here" - I used "Reserve here" and carried on.
+    Nothing is broken. To stop seeing this, record the flow again.
+```
+
+It only does this when the page proves it: one name gone, the one the step
+wanted, and one new name of the same kind. A button that is gone with nothing
+in its place, or a rename next to other new buttons, fails as it always did.
+Checks you added with the toolbar are never redirected.
+
 ## Files it creates in your folder
 
 | File | What it is |

package/bin/kryptheon.js

@@ -2057,6 +2057,57 @@ async function finishWith(code) {
   );
 }
 
+// The copy that must run `check` is the one the recordings load. Measured: in
+// a folder `record` set up, `npx kryptheon@latest check` ran npx's copy, whose
+// Playwright loads the config, while the recordings loaded the folder's copy -
+// two Playwrights, and "Requiring @playwright/test second time" before a single
+// recording ran. `npx kryptheon check` worked in the same folder only because
+// npx happened to pick the local copy.
+//
+// So when this is not the folder's copy, the folder's copy does the work.
+// Returns its exit code, or null to carry on here.
+function handToFolderCopy() {
+  if (process.env.KRYPTHEON_HANDED_OVER) return null; // once, never in a loop
+  const theirs = project.kryptheonCopyFor(USER_DIR);
+  if (!theirs) return null;
+  let same = false;
+  try {
+    same = fs.realpathSync(theirs) === fs.realpathSync(PACKAGE_DIR);
+  } catch (err) {
+    same = path.resolve(theirs) === path.resolve(PACKAGE_DIR);
+  }
+  if (same) return null;
+
+  let theirVersion = 'unknown';
+  try {
+    theirVersion = JSON.parse(fs.readFileSync(path.join(theirs, 'package.json'), 'utf8')).version;
+  } catch (err) {
+    /* said as unknown */
+  }
+  const mine = packageVersion();
+  if (theirVersion !== mine) {
+    // Not an error: the folder's copy is the one its recordings are written
+    // against. Said, so an older one is never mistaken for this one.
+    console.log('');
+    console.log('  Running the kryptheon installed in this folder (' + theirVersion + '), because your');
+    console.log('  recordings load that one. ' + (mine !== 'unknown' ? 'To move this folder to ' + mine + ':' : 'To update it:'));
+    console.log('    npm i -D kryptheon@latest');
+  }
+  const result = spawnSync(process.execPath, [path.join(theirs, 'bin', 'kryptheon.js')].concat(process.argv.slice(2)), {
+    cwd: USER_DIR,
+    stdio: 'inherit',
+    env: Object.assign({}, process.env, { KRYPTHEON_HANDED_OVER: '1' }),
+  });
+  if (result.error) {
+    console.error('');
+    console.error('  Could not run the kryptheon installed in this folder: ' + result.error.message);
+    console.error('  Reinstalling it usually fixes this:  npm i -D kryptheon@latest');
+    console.error('');
+    return 1;
+  }
+  return result.status === null ? 1 : result.status;
+}
+
 async function main() {
   if (nodeIsTooOld()) {
     console.error('');
@@ -2073,9 +2124,11 @@ async function main() {
     case 'record':
       return finishWith(await record(rest[0]));
       break;
-    case 'check':
+    case 'check': {
+      const handedOver = handToFolderCopy();
+      if (handedOver !== null) return finishWith(handedOver);
       return finishWith(check({ quiet: rest.indexOf('--quiet') !== -1 || rest.indexOf('-q') !== -1 }));
-      break;
+    }
     case 'remove':
     case 'rm':
       return finishWith(await remove(rest.join(" ").trim()));
@@ -2122,6 +2175,7 @@ module.exports = {
   rulesBlock: rulesBlock,
   record: record,
   prepareFolder: prepareFolder,
+  handToFolderCopy: handToFolderCopy,
   finaliseRecording: finaliseRecording,
   takeOutSecrets: takeOutSecrets,
   reportSecrets: reportSecrets,

package/kryptheon-fixture.js

@@ -22,6 +22,7 @@ const base = require('@playwright/test');
 const { requestPath } = require('./kryptheon-reporter.js');
 const signature = require('./kryptheon-signature.js');
 const replay = require('./kryptheon-replay.js');
+const heal = require('./kryptheon-heal.js');
 
 const MAX_ITEMS = 5; // keep the failure block readable
 
@@ -133,6 +134,9 @@ function normalisedEntry(current) {
   // only to a file name, and a re-recording that lands on the same name
   // inherits a baseline it never created and can never match.
   if (current.recordingId) stored.recordingId = current.recordingId;
+  // The names each step saw, which is what lets a later run tell a renamed
+  // button from a missing one. See kryptheon-heal.js.
+  if (current.steps && Object.keys(current.steps).length) stored.steps = current.steps;
   return stored;
 }
 
@@ -188,14 +192,14 @@ function normaliseTitle(value) {
 
 // The address, the title, and what the page ended up showing decide pass or
 // fail. Browser noise changing is not on its own a regression.
-function compareBaselines(previous, current) {
+function compareBaselines(previous, current, renamed) {
   const urlChanged = normaliseUrl(previous.url) !== normaliseUrl(current.url);
   const titleChanged = normaliseTitle(previous.title) !== normaliseTitle(current.title);
   if (!urlChanged && !titleChanged) {
     // Nothing moved in the address bar. This is the case the address and title
     // alone cannot see: a single-page app with a catch-all route lands on the
     // same URL under the same title whether the flow worked or not.
-    return signature.compareSignatures(previous.signature, current.signature);
+    return signature.compareSignatures(previous.signature, current.signature, renamed);
   }
 
   const what =
@@ -248,6 +252,18 @@ function stampRecording(file, key, recordingId) {
   return saveBaselines(file, all);
 }
 
+// Keeps the names each step saw on this passing run, and nothing else about
+// the entry - its recorded time is what "this was working on" means.
+function rememberSteps(file, key, steps) {
+  if (!steps || !Object.keys(steps).length) return false;
+  const all = readBaselines(file);
+  const entry = all[key];
+  if (!entry || typeof entry !== 'object') return false;
+  if (JSON.stringify(entry.steps || null) === JSON.stringify(steps)) return false;
+  entry.steps = steps;
+  return saveBaselines(file, all);
+}
+
 function upgradeBaseline(file, key, sig) {
   const all = readBaselines(file);
   const entry = all[key];
@@ -257,7 +273,7 @@ function upgradeBaseline(file, key, sig) {
 }
 
 // The whole decision in one call: create on first sight, otherwise compare.
-function applyBaseline(file, key, current) {
+function applyBaseline(file, key, current, renamed) {
   const previous = readBaselines(file)[key];
   if (!previous || typeof previous !== 'object') {
     writeBaseline(file, key, current);
@@ -274,7 +290,7 @@ function applyBaseline(file, key, current) {
     writeBaseline(file, key, current);
     return { status: 'created', message: null };
   }
-  const message = compareBaselines(previous, current);
+  const message = compareBaselines(previous, current, renamed);
   if (message) return { status: 'changed', message: message };
 
   // A baseline from before signatures existed passes on address and title, and
@@ -325,6 +341,17 @@ const test = base.test.extend({
       }
     })();
 
+    // What the last passing run of this same recording saw. A saved result
+    // from a different recording describes steps this one does not have.
+    const previousEntry = readBaselines(BASELINE_FILE)[key];
+    const sameRecording =
+      Boolean(previousEntry) && typeof previousEntry === 'object' &&
+      !(previousEntry.recordingId && recordingId && previousEntry.recordingId !== recordingId);
+    const healer = heal.watch(page, {
+      memory: sameRecording ? previousEntry.steps : null,
+      fallback: sameRecording ? previousEntry.signature : null,
+    });
+
     // Reports only what this run added on top of the last passing run.
     const attachObservations = async () => {
       let url = null;
@@ -354,6 +381,19 @@ const test = base.test.extend({
 
     await use(page);
 
+    // Said whether the test passed or not: on a pass it is the only thing the
+    // person needs to know, and on a failure it explains the steps before it.
+    if (healer.renamed.length) {
+      try {
+        await testInfo.attach('kryptheon-renamed', {
+          body: JSON.stringify(healer.renamed),
+          contentType: 'application/json',
+        });
+      } catch (e) {
+        /* a note, never a second failure */
+      }
+    }
+
     // Read the page before anything else looks at the outcome. A test that
     // failed is exactly the one where knowing what was on screen matters most,
     // so this runs whether it passed or not. It is null when the page could
@@ -394,13 +434,17 @@ const test = base.test.extend({
         failedRequests: failedRequests,
         signature: captured,
         recordingId: recordingId,
+        steps: heal.mergeMemory(sameRecording ? previousEntry.steps : null, healer.learned),
       };
     } catch (e) {
       current = null; // page closed by the test - leave any baseline untouched
     }
     if (!current) return;
 
-    const outcome = applyBaseline(BASELINE_FILE, key, current);
+    const outcome = applyBaseline(BASELINE_FILE, key, current, healer.renamed);
+    if (outcome.status === 'match' || outcome.status === 'learned') {
+      rememberSteps(BASELINE_FILE, key, current.steps);
+    }
     if (outcome.status === 'changed') {
       // Remember what this run saw so `kryptheon accept` can promote it, but
       // leave the accepted baseline exactly as it was.
@@ -428,5 +472,6 @@ module.exports = {
   applyBaseline: applyBaseline,
   upgradeBaseline: upgradeBaseline,
   stampRecording: stampRecording,
+  rememberSteps: rememberSteps,
   BASELINE_FILE: BASELINE_FILE,
 };

package/kryptheon-heal.js

@@ -0,0 +1,215 @@
+// A button that was renamed has not broken the flow.
+//
+// Found on a real Lovable app: "Reserve a table" became "Reserve here", the
+// replay stopped at the first step that clicked it, and the report said the
+// flow was broken. It was not - the same button was in the same place, and
+// everything after it (the form, the email check, the date check, the
+// confirmation) was never looked at. One rename hid the whole flow, and the
+// person had to go and prove that themselves.
+//
+// So when a step cannot find its element by the recorded name, this asks what
+// changed on the page since the flow last passed. The rule is deliberately
+// narrow: exactly one name of that kind is gone, it is the one the step
+// wanted, and exactly one new name of the same role has appeared in its
+// place. Then the step uses the new one and the report says so. Anything
+// looser - two new buttons, the old name still somewhere, a page that has
+// not finished drawing - is not a rename this can prove, and the step fails
+// exactly as it did before, with the same message.
+//
+// What the page looked like before comes from two places. Every step that
+// finds its element by name notes the names of its role on the page at that
+// moment, and the baseline keeps them from the last passing run. A project
+// recorded before this existed has none of those yet, and falls back to the
+// buttons, links and fields the baseline saw on the flow's last page - which
+// only proves a rename when the step's page and the last page are the same.
+//
+// Only page.getByRole with a plain string name is watched: that is what
+// codegen writes for nearly every click and fill. Assertions are never
+// redirected. A check someone added on purpose says what they expect to see,
+// and quietly checking something else instead would make it a lie.
+
+// How long a step waits for its element by the recorded name before asking
+// whether it was renamed. A step whose element is merely slow is not
+// affected: when the page does not prove a rename, the step carries on
+// waiting exactly as it always did.
+const PROBE_MS = 5000;
+
+const ACTIONS = [
+  'click', 'dblclick', 'tap', 'hover', 'focus',
+  'fill', 'clear', 'press', 'pressSequentially', 'type',
+  'check', 'uncheck', 'setChecked', 'selectOption', 'setInputFiles',
+];
+
+// The same groups the baseline signature uses: its "actions" are buttons and
+// links, its "fields" are form controls.
+const ACTION_ROLES = new Set(['button', 'link']);
+const FIELD_ROLES = new Set(['textbox', 'searchbox', 'combobox', 'listbox', 'spinbutton', 'checkbox', 'radio', 'slider', 'switch']);
+
+function norm(text) {
+  return String(text == null ? '' : text).replace(/\s+/g, ' ').trim().toLowerCase();
+}
+
+/**
+ * Names on the page by role, read from Playwright's accessibility snapshot -
+ * the same names getByRole matches against, so nothing is guessed.
+ *
+ *   - button "Reserve here"
+ *   - link "Story":
+ *   - textbox "Email" [disabled]
+ */
+function namesByRole(snapshot) {
+  const out = new Map();
+  for (const line of String(snapshot || '').split('\n')) {
+    const m = line.match(/^\s*- ([a-z]+) "((?:[^"\\]|\\.)*)"/);
+    if (!m) continue;
+    let name;
+    try {
+      name = JSON.parse('"' + m[2] + '"');
+    } catch (e) {
+      continue;
+    }
+    if (!name) continue;
+    if (!out.has(m[1])) out.set(m[1], []);
+    out.get(m[1]).push(name);
+  }
+  return out;
+}
+
+/**
+ * The whole decision, with nothing but names in and out.
+ *
+ * `wanted` is the name the step was recorded with, `before` and `now` the
+ * names of that kind on the page then and now, and `candidates` the names
+ * now on the page with the step's own role. Returns the new name, or null
+ * when the page does not prove a rename.
+ */
+function decideRename(wanted, before, now, candidates) {
+  const target = norm(wanted);
+  if (!target || !Array.isArray(before) || !before.length) return null;
+  const nowSet = new Set((now || []).map(norm));
+  const beforeSet = new Set(before.map(norm));
+
+  const gone = [...beforeSet].filter((n) => !nowSet.has(n));
+  const added = [...nowSet].filter((n) => !beforeSet.has(n));
+  if (gone.length !== 1 || added.length !== 1) return null;
+  // getByRole matches a name that contains the recorded one, so the name
+  // that went is the step's own only if it contains what was recorded.
+  if (!gone[0].includes(target)) return null;
+
+  // Of the step's own role. A button renamed while the recorded link went
+  // missing is two changes, not one rename.
+  return (candidates || []).find((c) => norm(c) === added[0]) || null;
+}
+
+/**
+ * Watches one test's page. `memory` is what the last passing run noted per
+ * step, `fallback` the last page's signature; either may be missing.
+ */
+function watch(page, options) {
+  const opts = options || {};
+  const memory = opts.memory && typeof opts.memory === 'object' ? opts.memory : null;
+  const fallback = opts.fallback && typeof opts.fallback === 'object' ? opts.fallback : null;
+  const probeMs = opts.probeMs || PROBE_MS;
+
+  const learned = {};
+  const renamed = [];
+  let counter = 0;
+
+  const byRole = page.getByRole.bind(page);
+
+  async function readRoles() {
+    try {
+      return namesByRole(await page.locator('body').ariaSnapshot({ timeout: 3000 }));
+    } catch (e) {
+      return null; // a page that cannot be read proves nothing
+    }
+  }
+
+  async function findRename(key, role, name) {
+    const roles = await readRoles();
+    if (!roles) return null;
+    const ofRole = roles.get(role) || [];
+    if (memory && Array.isArray(memory[key])) {
+      return decideRename(name, memory[key], ofRole, ofRole);
+    }
+    if (!fallback) return null;
+    const kind = ACTION_ROLES.has(role) ? 'actions' : FIELD_ROLES.has(role) ? 'fields' : null;
+    if (!kind || !Array.isArray(fallback[kind])) return null;
+    const group = kind === 'actions' ? ACTION_ROLES : FIELD_ROLES;
+    const now = [];
+    for (const [r, names] of roles) if (group.has(r)) now.push(...names);
+    return decideRename(name, fallback[kind], now, ofRole);
+  }
+
+  async function act(locator, real, method, args, role, name) {
+    const key = counter++ + ' ' + role + ' ' + name;
+    const there = await locator
+      .first()
+      .waitFor({ state: 'attached', timeout: probeMs })
+      .then(() => true, () => false);
+    if (there) {
+      const roles = await readRoles();
+      if (roles) learned[key] = roles.get(role) || [];
+      return real.apply(locator, args);
+    }
+
+    const newName = await findRename(key, role, name);
+    if (newName) {
+      const replacement = byRole(role, { name: newName, exact: true });
+      const count = await replacement.count().catch(() => 0);
+      if (count === 1) {
+        renamed.push({ role: role, was: name, now: newName });
+        return replacement[method].apply(replacement, args);
+      }
+    }
+    // Not a rename this can prove: the step fails the way it always did.
+    return real.apply(locator, args);
+  }
+
+  page.getByRole = function (role, roleOptions) {
+    const locator = byRole(role, roleOptions);
+    const name = roleOptions && typeof roleOptions.name === 'string' ? roleOptions.name : null;
+    if (!name) return locator;
+    for (const method of ACTIONS) {
+      const real = locator[method];
+      if (typeof real !== 'function') continue;
+      locator[method] = function () {
+        return act(locator, real, method, Array.prototype.slice.call(arguments), role, name);
+      };
+    }
+    return locator;
+  };
+
+  return {
+    learned: learned,
+    renamed: renamed,
+  };
+}
+
+/**
+ * What to keep for next time: the steps this run found by their recorded
+ * name, over whatever was kept before. A step that had to follow a rename
+ * keeps its old note - that note is what lets the next run prove the same
+ * rename again.
+ */
+function mergeMemory(previous, learned) {
+  const out = {};
+  if (previous && typeof previous === 'object') Object.assign(out, previous);
+  if (learned && typeof learned === 'object') Object.assign(out, learned);
+  return out;
+}
+
+/** The report line, shared by the terminal and the history. */
+function describeRename(entry) {
+  const what = entry.role === 'link' ? 'link' : entry.role === 'button' ? 'button' : entry.role;
+  return 'The ' + what + ' "' + entry.was + '" is now called "' + entry.now + '" - I used "' + entry.now + '" and carried on.';
+}
+
+module.exports = {
+  PROBE_MS: PROBE_MS,
+  namesByRole: namesByRole,
+  decideRename: decideRename,
+  watch: watch,
+  mergeMemory: mergeMemory,
+  describeRename: describeRename,
+};

package/kryptheon-project.js

@@ -238,6 +238,31 @@ function noRecordingsLines() {
 // missing before the browser, which is a 200MB download on a new machine, and
 // offers to add it.
 
+/**
+ * The installed kryptheon a recording saved in this folder will load - the
+ * nearest node_modules/kryptheon going up - or null if there is none.
+ *
+ * `check` must be run by this same copy. Found through the MCP server, then
+ * measured by hand in a folder `record` had set up: `npx kryptheon@latest
+ * check` runs npx's own copy, whose Playwright loads the config, while the
+ * recordings load this one's - and Playwright stops with "Requiring
+ * @playwright/test second time" before a single recording runs.
+ */
+function kryptheonCopyFor(dir) {
+  let current = path.resolve(String(dir || ''));
+  for (;;) {
+    const candidate = path.join(current, 'node_modules', 'kryptheon');
+    // Whole copies only. A half-finished install - the fixture there, the rest
+    // not - was handed the run and answered with Node's own stack trace.
+    const whole = ['kryptheon-fixture.js', 'package.json', path.join('bin', 'kryptheon.js')]
+      .every((f) => fs.existsSync(path.join(candidate, f)));
+    if (whole) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
 /**
  * Whether kryptheon can be loaded by a recording saved in this folder.
  *
@@ -505,6 +530,7 @@ module.exports = {
   ESCAPE_HATCH: ESCAPE_HATCH,
   HOME_RECORDINGS: HOME_RECORDINGS,
   kryptheonReachableFrom: kryptheonReachableFrom,
+  kryptheonCopyFor: kryptheonCopyFor,
   kryptheonInstalledIn: kryptheonInstalledIn,
   projectAbove: projectAbove,
   setupPlan: setupPlan,

package/kryptheon-reporter.js

@@ -5,6 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const recordings = require('./kryptheon-recordings.js');
+const heal = require('./kryptheon-heal.js');
 
 // An assistant runs this after every change, so it needs a mode that says
 // nothing at all when the news is good.
@@ -57,6 +58,13 @@ const ROLE_NOUNS = {
   option: 'option',
   img: 'image',
   dialog: 'dialog',
+  // What the recorder's "assert text" button picks when the text is in the
+  // body of the page: "a check on the main" meant nothing to anyone.
+  main: 'main part of the page',
+  navigation: 'menu',
+  banner: 'top of the page',
+  contentinfo: 'footer',
+  status: 'status message',
 };
 
 // Returns a lower-case noun phrase such as: the button "Request my demo".
@@ -69,7 +77,9 @@ function describeLocator(locator) {
   m = raw.match(/getByRole\(\s*['"]([^'"]+)['"]\s*,\s*\{[^}]*name:\s*['"]([^'"]*)['"]/);
   if (m) return 'the ' + (ROLE_NOUNS[m[1]] || m[1]) + ' "' + m[2] + '"';
 
-  m = raw.match(/getByRole\(\s*['"]([^'"]+)['"]\s*\)/);
+  // With no name, or with options that are not a name - { level: 1 } is
+  // what a check on a page's main heading gets.
+  m = raw.match(/getByRole\(\s*['"]([^'"]+)['"]\s*(?:,\s*\{[^}]*\}\s*)?\)/);
   if (m) return 'the ' + (ROLE_NOUNS[m[1]] || m[1]);
 
   m = raw.match(/getByText\(\s*['"]([^'"]*)['"]/);
@@ -361,21 +371,50 @@ function translate(message) {
     };
   }
 
+  // What the recorder's snapshot button writes. Its diff is a page of YAML,
+  // which says nothing to someone who has never seen one.
+  if (/expect\([^)]*\)(?:\.not)?\.toMatchAriaSnapshot\(/.test(msg)) {
+    return {
+      reason: capitalise(subject || 'part of the page') + ' is laid out differently than when this check was recorded.',
+      advice: 'something in it was added, removed or renamed - the screenshot shows how it looks now.',
+    };
+  }
+
   // Value comparisons: toHaveTitle / toHaveText / toHaveValue / toHaveCount.
-  m = msg.match(/expect\([^)]*\)(?:\.not)?\.(toHave\w+|toContainText)\([^)]*\)\s*failed/);
+  m = msg.match(/expect\([^)]*\)(\.not)?\.(toHave\w+|toContainText)\([^)]*\)\s*failed/);
   if (m) {
-    const expected = (msg.match(/^\s*Expected:\s*(.+)$/m) || [])[1];
-    const received = (msg.match(/^\s*Received:\s*(.+)$/m) || [])[1];
-    const matcher = m[1];
+    // Playwright names the lines after what it compared: "Expected substring"
+    // for toContainText, "Expected string" for toHaveText and toHaveValue,
+    // "Expected pattern" for a regex. Reading only "Expected:" missed every
+    // check the recorder's own buttons write.
+    const expected = (msg.match(/^\s*Expected(?: substring| string| pattern)?:\s*(.+)$/m) || [])[1];
+    const received = (msg.match(/^\s*Received(?: string)?:\s*(.+)$/m) || [])[1];
+    const negated = Boolean(m[1]);
+    const matcher = m[2];
     const what =
       matcher === 'toHaveTitle' ? 'the page title'
       : matcher === 'toHaveURL' ? 'the page address'
       : matcher === 'toHaveCount' ? 'the number of matching items'
       : subject ? subject.charAt(0).toLowerCase() + subject.slice(1)
       : 'the element';
+    // A whole page of text is not an answer anyone can read. Say what was
+    // looked for, and show what was there only when it is short enough to be
+    // the thing someone meant.
+    const shown = received && received.trim().length <= 82 ? received.trim() : null;
+    if (expected && matcher === 'toContainText') {
+      return {
+        reason: negated
+          ? 'The test expected ' + what + ' not to say ' + expected.trim() + ', but it does.'
+          : 'The test expected ' + what + ' to say ' + expected.trim() + ', but ' +
+            (shown ? 'it says ' + shown + '.' : 'that text is not there.'),
+        advice: 'the wording on the page may have changed, or the step before it did not do what it should.',
+      };
+    }
     if (expected && received) {
       return {
-        reason: 'The test expected ' + what + ' to be ' + expected.trim() + ', but found ' + received.trim() + '.',
+        reason: negated
+          ? 'The test expected ' + what + ' not to be ' + expected.trim() + ', but it is.'
+          : 'The test expected ' + what + ' to be ' + expected.trim() + ', but found ' + (shown || 'something else') + '.',
         advice: 'the wording on the page may have changed, or the page shown was not the one expected.',
       };
     }
@@ -480,6 +519,21 @@ function readObservations(attachments) {
   }
 }
 
+// Renamed buttons and fields the replay followed (kryptheon-heal.js), each
+// already one sentence. Empty when there were none or the note is unreadable.
+function readRenamed(attachments) {
+  const found = (attachments || []).find(function (a) {
+    return a.name === 'kryptheon-renamed' && a.body;
+  });
+  if (!found) return [];
+  try {
+    const list = JSON.parse(found.body.toString('utf8'));
+    return Array.isArray(list) ? list.filter(function (e) { return e && e.was && e.now; }) : [];
+  } catch (e) {
+    return [];
+  }
+}
+
 function uniq(list) {
   const seen = Object.create(null);
   const out = [];
@@ -755,11 +809,24 @@ class KryptheonReporter {
       return;
     }
 
+    const renamed = readRenamed(result.attachments);
+    if (renamed.length) record.renamed = renamed;
+    const renamedLines = renamed.map(function (entry) {
+      return '    Renamed: ' + heal.describeRename(entry);
+    });
+
     if (status === 'passed') {
       this.records.push(record);
       if (!QUIET) {
         process.stdout.write('OK  ' + test.title + '  (' + formatDuration(result.duration) + ')\n');
       }
+      // Said even when quiet: a pass that followed a rename is still a pass,
+      // but the person should hear that their button has a new name.
+      if (renamedLines.length) {
+        if (QUIET) process.stdout.write('OK  ' + test.title + '\n');
+        process.stdout.write(renamedLines.join('\n') + '\n');
+        process.stdout.write('    Nothing is broken. To stop seeing this, record the flow again.\n');
+      }
       return;
     }
 
@@ -833,6 +900,9 @@ class KryptheonReporter {
     for (const detail of details) out.push('   ' + detail);
 
     out.push(lastPass ? '   This was working on ' + formatWhen(lastPass) + '.' : '   This has not passed before.');
+    // On the way to the failure. It explains why the steps before it worked
+    // even though a name in the recording no longer matches.
+    for (const entry of renamed) out.push('   Renamed on the way: ' + heal.describeRename(entry));
 
     // A first run that fails is a different situation from a regression:
     // nothing has broken, because nothing ever worked. Far more often the

package/kryptheon-signature.js

@@ -183,6 +183,23 @@ function setDifference(before, after) {
   };
 }
 
+// A rename the replay already followed is not also a difference in how the
+// page ended up. Takes the pair out of the lists - both halves, or neither.
+function withoutRenames(diff, renamed) {
+  const norm = (text) => String(text == null ? '' : text).replace(/\s+/g, ' ').trim().toLowerCase();
+  let gone = diff.gone;
+  let added = diff.added;
+  for (const entry of renamed || []) {
+    if (!entry || !entry.was || !entry.now) continue;
+    const was = gone.filter((item) => norm(item).includes(norm(entry.was)));
+    const now = added.filter((item) => norm(item) === norm(entry.now));
+    if (was.length !== 1 || now.length !== 1) continue;
+    gone = gone.filter((item) => item !== was[0]);
+    added = added.filter((item) => item !== now[0]);
+  }
+  return { gone: gone, added: added };
+}
+
 function requestLabel(req) {
   return (req.method || 'GET') + ' ' + req.path + ' ' + req.status;
 }
@@ -200,14 +217,17 @@ function quoteList(items) {
  * 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.
+ *
+ * `renamed` is what the replay followed on the way (kryptheon-heal.js): the
+ * same rename showing up again on the last page is not a second problem.
  */
-function compareSignatures(previous, current) {
+function compareSignatures(previous, current, renamed) {
   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);
+  const actions = withoutRenames(setDifference(previous.actions, current.actions), renamed);
+  const fields = withoutRenames(setDifference(previous.fields, current.fields), renamed);
 
   // 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.

package/package.json

@@ -1,76 +1,78 @@
-{
-  "name": "kryptheon",
-  "version": "0.1.16",
-  "description": "Record what you do in your app and get plain-language reports when it breaks.",
-  "license": "MIT",
-  "type": "commonjs",
-  "bin": {
-    "kryptheon": "bin/kryptheon.js"
-  },
-  "exports": {
-    ".": "./kryptheon-fixture.js",
-    "./kryptheon-fixture": "./kryptheon-fixture.js",
-    "./kryptheon-reporter": "./kryptheon-reporter.js",
-    "./package.json": "./package.json",
-    "./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",
-    "kryptheon-selectors.js",
-    "kryptheon-recordings.js",
-    "kryptheon-cleanup.js",
-    "kryptheon-baselines.js",
-    "kryptheon-project.js"
-  ],
-  "engines": {
-    "node": ">=20.6.0"
-  },
-  "dependencies": {
-    "@playwright/test": "^1.62.1"
-  },
-  "scripts": {
-    "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-signature.number.check.js && node kryptheon-env.check.js && node kryptheon-watchdog.check.js && node kryptheon-record.check.js && node kryptheon-selectors.check.js && node kryptheon-recordings.check.js && node kryptheon-cleanup.check.js && node kryptheon-orphan.check.js && node kryptheon-project.check.js && node kryptheon-setup.check.js && node kryptheon-browser.check.js && node kryptheon-load.check.js && node kryptheon-package.check.js",
-    "check:reporter": "node kryptheon-reporter.check.js",
-    "check:signature": "node kryptheon-signature.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:number": "node kryptheon-signature.number.check.js",
-    "check:env": "node kryptheon-env.check.js",
-    "check:watchdog": "node kryptheon-watchdog.check.js",
-    "check:record": "node kryptheon-record.check.js",
-    "check:selectors": "node kryptheon-selectors.check.js",
-    "check:recordings": "node kryptheon-recordings.check.js",
-    "check:cleanup": "node kryptheon-cleanup.check.js",
-    "check:orphan": "node kryptheon-orphan.check.js",
-    "check:project": "node kryptheon-project.check.js",
-    "check:setup": "node kryptheon-setup.check.js",
-    "check:browser": "node kryptheon-browser.check.js",
-    "check:load": "node kryptheon-load.check.js",
-    "check:package": "node kryptheon-package.check.js",
-    "prepublishOnly": "node kryptheon-package.check.js"
-  },
-  "keywords": [
-    "playwright",
-    "testing",
-    "end-to-end",
-    "cli"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jhashantanu987-beep/kryptheon-cli.git"
-  },
-  "bugs": {
-    "url": "https://github.com/jhashantanu987-beep/kryptheon-cli/issues"
-  },
-  "homepage": "https://github.com/jhashantanu987-beep/kryptheon-cli#readme"
-}
+{
+  "name": "kryptheon",
+  "version": "0.1.18",
+  "description": "Record what you do in your app and get plain-language reports when it breaks.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "kryptheon": "bin/kryptheon.js"
+  },
+  "exports": {
+    ".": "./kryptheon-fixture.js",
+    "./kryptheon-fixture": "./kryptheon-fixture.js",
+    "./kryptheon-reporter": "./kryptheon-reporter.js",
+    "./package.json": "./package.json",
+    "./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",
+    "kryptheon-heal.js",
+    "kryptheon-selectors.js",
+    "kryptheon-recordings.js",
+    "kryptheon-cleanup.js",
+    "kryptheon-baselines.js",
+    "kryptheon-project.js"
+  ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "dependencies": {
+    "@playwright/test": "^1.62.1"
+  },
+  "scripts": {
+    "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-signature.number.check.js && node kryptheon-env.check.js && node kryptheon-watchdog.check.js && node kryptheon-record.check.js && node kryptheon-selectors.check.js && node kryptheon-recordings.check.js && node kryptheon-cleanup.check.js && node kryptheon-orphan.check.js && node kryptheon-project.check.js && node kryptheon-setup.check.js && node kryptheon-browser.check.js && node kryptheon-heal.check.js && node kryptheon-load.check.js && node kryptheon-package.check.js",
+    "check:reporter": "node kryptheon-reporter.check.js",
+    "check:signature": "node kryptheon-signature.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:number": "node kryptheon-signature.number.check.js",
+    "check:env": "node kryptheon-env.check.js",
+    "check:watchdog": "node kryptheon-watchdog.check.js",
+    "check:record": "node kryptheon-record.check.js",
+    "check:selectors": "node kryptheon-selectors.check.js",
+    "check:recordings": "node kryptheon-recordings.check.js",
+    "check:cleanup": "node kryptheon-cleanup.check.js",
+    "check:orphan": "node kryptheon-orphan.check.js",
+    "check:project": "node kryptheon-project.check.js",
+    "check:setup": "node kryptheon-setup.check.js",
+    "check:browser": "node kryptheon-browser.check.js",
+    "check:heal": "node kryptheon-heal.check.js",
+    "check:load": "node kryptheon-load.check.js",
+    "check:package": "node kryptheon-package.check.js",
+    "prepublishOnly": "node kryptheon-package.check.js"
+  },
+  "keywords": [
+    "playwright",
+    "testing",
+    "end-to-end",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jhashantanu987-beep/kryptheon-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jhashantanu987-beep/kryptheon-cli/issues"
+  },
+  "homepage": "https://github.com/jhashantanu987-beep/kryptheon-cli#readme"
+}