kryptheon 0.1.9 → 0.1.10

package/bin/kryptheon.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 // The kryptheon CLI. A thin wrapper so nobody has to remember Playwright's
 // command line or edit a config file. Everything here shells out to the
 // Playwright binary that ships with this package.
@@ -14,6 +14,9 @@ const { spawn, spawnSync } = require('child_process');
 const os = require('os');
 const secrets = require(require('path').join(__dirname, '..', 'kryptheon-secrets.js'));
 const replay = require('../kryptheon-replay.js');
+const selectors = require('../kryptheon-selectors.js');
+const recordings = require('../kryptheon-recordings.js');
+const cleanup = require('../kryptheon-cleanup.js');
 
 const PACKAGE_DIR = path.join(__dirname, '..');
 const USER_DIR = process.cwd();
@@ -66,6 +69,7 @@ function usage() {
   console.log('  kryptheon record <url>   open your app and record what you do as a test');
   console.log('  kryptheon check          run every recorded test and report in plain language');
   console.log('  kryptheon accept <name>  agree that one test\'s new result is the correct one');
+  console.log('  kryptheon remove [name]  list the recordings, or remove one you no longer want');
   console.log('  kryptheon setup-ai       tell your AI assistant to check its work');
   console.log('');
   console.log('  add --quiet to check for one line when everything passes');
@@ -853,6 +857,89 @@ function reportSecrets(replacements) {
   console.log('');
 }
 
+// One keypress, no Enter, because the safe answer is the default and getting
+// out of the way should cost nothing.
+//
+// Falls back to the default where there is no terminal to read keys from - a
+// CI job, a pipe, an assistant running the command - rather than waiting for
+// an answer that will never arrive.
+function askKey(question, keys, fallback) {
+  return new Promise((resolve) => {
+    const allowed = keys.map((k) => k.toLowerCase());
+    if (!process.stdin.isTTY || !process.stdin.setRawMode) return resolve(fallback);
+    process.stdout.write(question);
+
+    const finish = (answer) => {
+      process.stdin.removeListener("data", onKey);
+      try {
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+      } catch (err) {
+        /* nothing more to do */
+      }
+      process.stdout.write(answer + String.fromCharCode(10));
+      resolve(answer);
+    };
+
+    const onKey = (chunk) => {
+      const key = String(chunk);
+      // In raw mode Ctrl-C arrives as a keystroke rather than a signal, so it
+      // has to be turned back into one. Sent as a signal rather than exiting
+      // here, because exiting would cut off whatever is still buffered - and
+      // it must not be read as an answer either: stopping is not "keep going".
+      if (key === String.fromCharCode(3)) {
+        process.stdin.removeListener('data', onKey);
+        try {
+          process.stdin.setRawMode(false);
+          process.stdin.pause();
+        } catch (err) {
+          /* nothing more to do */
+        }
+        process.stdout.write(String.fromCharCode(10));
+        process.kill(process.pid, 'SIGINT');
+        return;
+      }
+      if (key === String.fromCharCode(13) || key === String.fromCharCode(10)) return finish(fallback);
+      const pressed = key.toLowerCase();
+      if (allowed.indexOf(pressed) === -1) return; // an unknown key: keep waiting
+      finish(pressed);
+    };
+
+    try {
+      process.stdin.setRawMode(true);
+    } catch (err) {
+      return resolve(fallback);
+    }
+    process.stdin.resume();
+    process.stdin.on("data", onKey);
+  });
+}
+
+// Removing a recording means removing what was remembered about it too, or
+// the saved results of a file that no longer exists stay behind for ever.
+function deleteRecording(name) {
+  const relative = path.join("tests", name).split(path.sep).join("/");
+  try {
+    fs.unlinkSync(path.join(TESTS_DIR, name));
+  } catch (err) {
+    return { ok: false, name: name, why: err.message };
+  }
+
+  try {
+    const api = require(path.join(PACKAGE_DIR, "kryptheon-fixture.js"));
+    const all = api.readBaselines(api.BASELINE_FILE);
+    const keys = recordings.baselineKeysForSpec(all, relative);
+    if (keys.length) {
+      for (const key of keys) delete all[key];
+      fs.writeFileSync(api.BASELINE_FILE, JSON.stringify(all, null, 2) + String.fromCharCode(10), "utf8");
+    }
+  } catch (err) {
+    // The recording is gone either way, and a leftover baseline is not worth
+    // failing the command over.
+  }
+  return { ok: true, name: name, file: relative };
+}
+
 function askYesNo(question) {
   return new Promise((resolve) => {
     if (!process.stdin.isTTY) return resolve(false);
@@ -871,6 +958,24 @@ function askYesNo(question) {
   });
 }
 
+// A typed answer, for questions whose answers are not single letters.
+function askLine(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) return resolve("");
+    const readline = require("readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      try {
+        process.stdin.pause();
+      } catch (err) {
+        /* nothing to do */
+      }
+      resolve(String(answer));
+    });
+  });
+}
+
 // Ending on a logout means the next run starts somewhere else. Almost nobody
 // wants that, so ask.
 async function offerToDropLogout(relativeFile) {
@@ -897,6 +1002,37 @@ async function offerToDropLogout(relativeFile) {
   return true;
 }
 
+// Codegen writes whatever identified the element at the moment it was clicked,
+// which on a page of live figures means the figures end up in the selector. Say
+// so, and say nothing when there is nothing to say.
+// Codegen records the wrong keystrokes along with the right ones, so a typo
+// corrected on the second attempt becomes a wrong login performed on every
+// run. This takes those out and says what it took, because a tool that edits
+// your recording without telling you is worse than one that leaves the mess.
+function tidyRecording(relativeFile) {
+  const source = readSpec(relativeFile);
+  if (source === null) return [];
+  const result = cleanup.cleanRecording(source);
+  if (!result.removed.length) return [];
+  if (!writeSpec(relativeFile, result.source)) return [];
+  return result.removed;
+}
+
+// Said after the file has its name, with the other closing notes, so the
+// order on screen matches the order things happened in.
+function reportTidying(removed) {
+  for (const line of cleanup.describeCleanup(removed)) console.log(line);
+  return removed || [];
+}
+
+function reportFragileSelectors(relativeFile) {
+  const source = readSpec(relativeFile);
+  if (source === null) return [];
+  const findings = selectors.findFragileSelectors(source);
+  for (const line of selectors.describeFragileSelectors(findings)) console.log(line);
+  return findings;
+}
+
 function reportReplayRisks(relativeFile) {
   const source = readSpec(relativeFile);
   if (source === null) return [];
@@ -937,16 +1073,23 @@ async function finaliseRecording(outFile, context) {
     // this point. Take it out before doing anything else with the file.
     const secrets = takeOutSecrets(outFile);
 
+    // After the secrets, deliberately. By this point a password is an
+    // environment variable rather than a literal, so nothing that is said
+    // about a field that was typed twice can put the value back on screen.
+    const tidied = tidyRecording(outFile);
+
     const named = await nameRecording(outFile);
     console.log('');
     console.log('  Saved to ' + named);
     console.log('  Run it any time with:  kryptheon check');
     console.log('');
 
+    reportTidying(tidied);
     reportSecrets(secrets);
     keepArtefactsOutOfGit();
     await offerToDropLogout(named);
     reportReplayRisks(named);
+    reportFragileSelectors(named);
 
     return { code: 0, savedAs: named };
   }
@@ -1003,6 +1146,125 @@ async function finaliseRecording(outFile, context) {
   return { code: 1, savedAs: null };
 }
 
+// Every record writes another file and check runs all of them, so a first day
+// spent learning the tool leaves a pile of recordings that never worked and a
+// check that reads like a wall of failures. This is the moment asking costs
+// nothing.
+//
+// Keeping is the default because it is the answer that cannot lose work, and
+// the other one is a single keypress away. Where there is no terminal to
+// answer with - a CI job, an assistant running the command - nothing is asked
+// and nothing is deleted: a question nobody can see is not a question.
+async function askAboutExisting(names) {
+  if (!names.length || !process.stdin.isTTY) return false;
+
+  for (const line of recordings.existingRecordingsQuestion(names.length)) console.log(line);
+  const answer = await askKey("  Keep or replace? [K/r] ", ["k", "r"], "k");
+  if (answer !== "r") return false;
+
+  console.log("");
+  console.log("  They will be deleted once this new recording is saved.");
+  return true;
+}
+
+// The old recordings, once the new one is safely on disk. The new file is
+// never in this list, but it is checked by name anyway - deleting the thing
+// just recorded is the one mistake here that cannot be undone.
+function dropOldRecordings(names, savedAs) {
+  const keep = path.basename(String(savedAs || ""));
+  const gone = [];
+  for (const name of names) {
+    if (path.basename(name) === keep) continue;
+    const result = deleteRecording(name);
+    if (result.ok) gone.push(name);
+  }
+  if (!gone.length) return gone;
+  console.log("  Removed " + recordings.plural(gone.length, "older recording") + ":");
+  for (const name of gone) console.log("    " + path.join("tests", name));
+  console.log("");
+  return gone;
+}
+
+// --- remove -----------------------------------------------------------------
+//
+// Recordings pile up. Without a way to take one out, the only way to stop a
+// half-finished experiment being run for ever is to know where the files live
+// and delete one by hand.
+
+function listRecordings(names) {
+  console.log("");
+  console.log("  " + recordings.plural(names.length, "recording") + " in this project:");
+  console.log("");
+  names.forEach((name, i) => {
+    console.log("    " + String(i + 1).padStart(2) + "  " + path.join("tests", name));
+  });
+  console.log("");
+}
+
+async function remove(name) {
+  const names = listSpecFiles();
+  if (!names.length) {
+    console.log("");
+    console.log("  There are no recordings to remove.");
+    console.log("");
+    return 0;
+  }
+
+  let choice;
+  if (name) {
+    choice = recordings.chooseFromList(names, name);
+  } else {
+    listRecordings(names);
+    if (!process.stdin.isTTY) {
+      console.log("  To remove one, run:  kryptheon remove <name>");
+      console.log("");
+      return 0;
+    }
+    const answer = await askLine("  Which one? [number, a for all, Enter to cancel] ");
+    choice = recordings.chooseFromList(names, answer);
+  }
+
+  if (choice.action === "cancel") {
+    console.log("");
+    console.log("  Nothing was removed.");
+    console.log("");
+    return 0;
+  }
+  if (choice.action === "unclear") {
+    console.error("");
+    console.error("  " + choice.why + ": " + JSON.stringify(choice.said));
+    console.error("  Run \"kryptheon remove\" on its own to see the list.");
+    console.error("");
+    return 1;
+  }
+
+  const gone = [];
+  const failed = [];
+  for (const target of choice.names) {
+    const result = deleteRecording(target);
+    if (result.ok) gone.push(target);
+    else failed.push(result);
+  }
+
+  console.log("");
+  if (gone.length) {
+    console.log("  Removed " + recordings.plural(gone.length, "recording") + ":");
+    for (const g of gone) console.log("    " + path.join("tests", g));
+    console.log("");
+    console.log(
+      gone.length === 1
+        ? "  Its saved result was removed too, so nothing is left behind."
+        : "  Their saved results were removed too, so nothing is left behind.",
+    );
+    console.log("");
+  }
+  for (const f of failed) {
+    console.error("  Could not remove " + path.join("tests", f.name) + ": " + f.why);
+    console.error("");
+  }
+  return failed.length ? 1 : 0;
+}
+
 async function record(url) {
   if (!url) {
     console.error('');
@@ -1025,6 +1287,9 @@ async function record(url) {
 
   if (!ensureBrowser()) return 1;
 
+  const existingBefore = listSpecFiles();
+  const replaceExisting = await askAboutExisting(existingBefore);
+
   const hadTestsDir = fs.existsSync(TESTS_DIR);
   try {
     fs.mkdirSync(TESTS_DIR, { recursive: true });
@@ -1064,6 +1329,9 @@ async function record(url) {
       stderr: stderr,
       reason: reason,
     });
+    // Only now, and only if something was actually saved. Deleting first
+    // would mean a recording that went wrong takes the old ones with it.
+    if (replaceExisting && outcome.savedAs) dropOldRecordings(existingBefore, outcome.savedAs);
     return outcome.code;
   };
 
@@ -1606,6 +1874,9 @@ async function main() {
     case 'check':
       return finishWith(check({ quiet: rest.indexOf('--quiet') !== -1 || rest.indexOf('-q') !== -1 }));
       break;
+    case 'remove':
+    case 'rm':
+      return finishWith(await remove(rest.join(" ").trim()));
     case 'setup-ai':
       return finishWith(setupAi());
     case 'accept':
@@ -1660,6 +1931,14 @@ module.exports = {
   inspectBrowserWindows: inspectBrowserWindows,
   parseWindowProbe: parseWindowProbe,
   codegenComplaints: codegenComplaints,
+  reportFragileSelectors: reportFragileSelectors,
+  tidyRecording: tidyRecording,
+  reportTidying: reportTidying,
+  remove: remove,
+  deleteRecording: deleteRecording,
+  dropOldRecordings: dropOldRecordings,
+  askAboutExisting: askAboutExisting,
+  askKey: askKey,
   WINDOW_TIMEOUT_MS: WINDOW_TIMEOUT_MS,
   WINDOW_HARD_LIMIT_MS: WINDOW_HARD_LIMIT_MS,
   WINDOW_POLL_MS: WINDOW_POLL_MS,

package/kryptheon-cleanup.js

@@ -0,0 +1,245 @@
+// Taking the fumbling out of a recording before it becomes a baseline.
+//
+// Codegen records every keystroke, including the wrong ones. A username typed
+// once with a typo and again correctly comes out as two fills of the same box:
+//
+//   await page.getByRole('textbox', { name: 'Username' }).fill('shantanu892');
+//   await page.getByRole('textbox', { name: 'Username' }).fill('shantanu89');
+//
+// Kept as-is, that is not a tidiness problem. The first fill is a whole wrong
+// login attempt performed on every run from then on, and the mistake is baked
+// into the baseline as if it were the intended flow.
+//
+// The same happens with a stray click on nothing - getByRole('img') with no
+// name and no text identifies nothing, and clicking it does nothing - and with
+// the same button clicked twice because the first one seemed not to take.
+//
+// Everything here follows one rule: when in doubt, keep it. Leaving a pointless
+// step in a recording costs a moment. Removing a real one silently changes what
+// the test does, and nobody finds out until the thing it was covering breaks
+// unnoticed. So every removal below needs the steps to be adjacent, to be the
+// same action on the same element, and to have nothing between them - anything
+// less certain is left alone.
+//
+// Pure string work: no Playwright, no filesystem.
+
+const selectors = require('./kryptheon-selectors.js');
+
+/* --------------------------------------------------------------------------
+   Reading the recording as steps.
+-------------------------------------------------------------------------- */
+
+// Only the things a person does to the page.
+//
+// Assertions end in toBeVisible, toHaveText and the like, none of which are
+// here, so an assertion is never read as a step in the first place. There was
+// an explicit guard against them as well; mutation testing showed removing it
+// changed nothing, and a line that reads like the reason something is safe -
+// while not being the reason - is worse than no line at all. This list is the
+// reason. Anything added to it has to be a thing a person actually did.
+const ACTION = /\.\s*(click|dblclick|fill|type|press|check|uncheck|selectOption|hover|tap|setInputFiles|clear|goto)\s*\(/;
+
+/**
+ * Every line that does something to the page, with the parts that matter.
+ *
+ * `chain` is how the element was found, which is what makes two steps "the
+ * same element". It comes from the same reader the fragile-selector report
+ * uses, so the two can never disagree about what a step points at.
+ */
+function readSteps(source) {
+  const steps = [];
+  String(source || '')
+    .split('\n')
+    .forEach((raw, i) => {
+      const line = raw.trim();
+      if (!/\bpage\s*\./.test(line)) return;
+      const match = line.match(ACTION);
+      if (!match) return;
+      steps.push({
+        line: i + 1,
+        text: line,
+        action: match[1],
+        chain: selectors.selectorChain(line),
+      });
+    });
+  return steps;
+}
+
+/** The readable name of the thing a step acts on, for saying what went. */
+function labelFor(chain) {
+  const text = String(chain || '');
+  let m = text.match(/name:\s*(['"])(.*?)\1/);
+  if (m) return m[2];
+  m = text.match(/getBy(?:Label|Placeholder|Text|TestId|Title|AltText)\(\s*(['"])(.*?)\1/);
+  if (m) return m[2];
+  m = text.match(/getByRole\(\s*(['"])(.*?)\1/);
+  if (m) return 'the ' + m[2];
+  m = text.match(/locator\(\s*(['"])(.*?)\1/);
+  if (m) return m[2];
+  return 'it';
+}
+
+/* --------------------------------------------------------------------------
+   A step that points at nothing.
+-------------------------------------------------------------------------- */
+
+// Anything that says which element is meant. One of these present is enough
+// for a step to be left alone.
+const IDENTIFYING = /name\s*:|getByLabel|getByPlaceholder|getByTestId|getByTitle|getByAltText|getByText/;
+
+// What a .filter({ hasText: ... }) is matching on, if anything.
+const HAS_TEXT = /has(?:Not)?Text\s*:\s*(\/(?:\\.|[^/\\])*\/[a-z]*|(['"])(?:\\.|(?!\2).)*\2)/;
+
+/**
+ * Whether a text filter actually narrows anything down.
+ *
+ * `hasText: /^$/` is the one codegen writes when there was no text to match
+ * on - it says "an element with empty text", which is every empty element on
+ * the page. Written out as a test rather than folded into the pattern above,
+ * because a lookahead there can slide along and match at the space instead,
+ * which quietly reads an empty filter as identifying.
+ */
+function narrowsAnything(chain) {
+  const m = String(chain || '').match(HAS_TEXT);
+  if (!m) return false;
+  const value = m[1];
+  if (value[0] !== '/') return value.length > 2; // a non-empty string
+  const body = value.slice(1, value.lastIndexOf('/'));
+  return body !== '' && body !== '^$';
+}
+
+// A CSS selector that picks something out: an id, a class, an attribute.
+const ANCHORED = /locator\(\s*(['"])[^'"]*[#.\[][^'"]*\1/;
+
+// Roles that are not there to be used. A click on one of these does nothing,
+// which is why codegen only ever writes them by accident. Interactive roles -
+// button, link, textbox - are deliberately absent even when unnamed: an
+// unnamed button is still a button, and removing a click on one would change
+// what the recording does.
+const INERT_ROLE = /getByRole\(\s*(['"])(img|image|generic|presentation|none|paragraph|separator|figure)\1/;
+
+/**
+ * A click on something with nothing to identify it.
+ *
+ * Both halves are required: the step must name nothing at all, and the element
+ * must be of a kind that does nothing when clicked. Either one on its own is
+ * not enough to be sure.
+ */
+function pointsAtNothing(step) {
+  if (!step || step.action !== 'click') return false;
+  const chain = step.chain;
+  if (IDENTIFYING.test(chain)) return false;
+  if (narrowsAnything(chain)) return false;
+  if (ANCHORED.test(chain)) return false;
+  return INERT_ROLE.test(chain);
+}
+
+/* --------------------------------------------------------------------------
+   The clean-up.
+-------------------------------------------------------------------------- */
+
+/**
+ * The steps to take out, and why, in the words they will be reported in.
+ *
+ * Nothing here looks at the values that were typed. They are not needed to
+ * decide anything, and by this point a password may already have been moved
+ * into an environment variable - printing "typed X then Y" would put the very
+ * thing that was just hidden back on the screen.
+ */
+function findRedundantSteps(source) {
+  const steps = readSteps(source);
+  const removals = [];
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const next = steps[i + 1];
+
+    if (pointsAtNothing(step)) {
+      removals.push({
+        line: step.line,
+        text: step.text,
+        kind: 'points-at-nothing',
+        why: 'a click on something with nothing to identify it',
+      });
+      continue;
+    }
+
+    if (!next || next.chain !== step.chain || step.action === 'goto') continue;
+
+    // Adjacent in the list, so nothing happened in between. A fill with
+    // another action between it and the next one is somebody going back to a
+    // field on purpose, and both are kept.
+    if (step.action === 'fill' && next.action === 'fill') {
+      removals.push({
+        line: step.line,
+        text: step.text,
+        kind: 'typed-twice',
+        why: labelFor(step.chain) + ' was typed twice in a row, and only the last one counts',
+      });
+      continue;
+    }
+
+    if (step.action === 'click' && next.action === 'click') {
+      // The second click is the one dropped: the first is what the person
+      // meant to do, and it is the one whose effect the rest of the recording
+      // was made against.
+      removals.push({
+        line: next.line,
+        text: next.text,
+        kind: 'clicked-twice',
+        why: labelFor(step.chain) + ' was clicked twice in a row, and once is enough',
+      });
+      i++;
+    }
+  }
+
+  return removals;
+}
+
+/**
+ * The recording with the fumbling taken out.
+ *
+ * Lines are removed by number and nothing else is touched, so what comes back
+ * is the file as it was minus whole lines - never reformatted, never rewritten.
+ */
+function cleanRecording(source) {
+  const text = String(source || '');
+  const removed = findRedundantSteps(text);
+  if (!removed.length) return { source: text, removed: [] };
+
+  const drop = new Set(removed.map((r) => r.line));
+  const kept = text.split('\n').filter((line, i) => !drop.has(i + 1));
+  return { source: kept.join('\n'), removed: removed };
+}
+
+/**
+ * What was taken out, said plainly.
+ *
+ * Never silent about it. A tool that edits what you recorded and does not say
+ * so is worse than one that leaves the mess in - the next time the recording
+ * does something unexpected, you have no way of knowing it was changed.
+ */
+function describeCleanup(removed) {
+  const list = removed || [];
+  if (!list.length) return [];
+
+  const lines = [];
+  lines.push('');
+  lines.push(
+    '  ' + list.length + (list.length === 1 ? ' step was' : ' steps were') + ' taken out of the recording:',
+  );
+  for (const item of list) lines.push('    - ' + item.why);
+  lines.push('');
+  lines.push('  Everything else was left exactly as you did it.');
+  lines.push('');
+  return lines;
+}
+
+module.exports = {
+  readSteps: readSteps,
+  findRedundantSteps: findRedundantSteps,
+  cleanRecording: cleanRecording,
+  describeCleanup: describeCleanup,
+  pointsAtNothing: pointsAtNothing,
+  labelFor: labelFor,
+};