kryptheon 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# kryptheon
+
+Record what you do in your app, and get told in plain English when it breaks.
+
+No test code to write, no config to edit.
+
+## Use it
+
+Install it into your project first:
+
+```
+npm i -D kryptheon
+```
+
+This step is not optional. Every recording kryptheon writes starts with
+`import { test, expect } from 'kryptheon/kryptheon-fixture'`, and your tests can
+only find that import if kryptheon lives in your project's `node_modules`.
+Running `npx kryptheon` without installing will record fine but fail to check.
+
+Then record:
+
+```
+npx kryptheon record https://your-app.example.com
+```
+
+A browser opens. Use your app the way a customer would — click, type, sign in.
+Close the browser when you are done, and the recording is saved as a test.
+
+```
+npx kryptheon check
+```
+
+Runs everything you have recorded and reports what happened:
+
+```
+OK  Sign in  (4.1s)
+
+X  Checkout
+   Could not find the button "Place order" on the page.
+   This was working on 12 Mar at 9:14 AM.
+   What to check: your last change may have renamed, hidden, or removed it.
+   Where to look:
+     - Browser was on: https://your-app.example.com/cart
+     - POST /api/orders returned 500
+       the server crashed or is unavailable - the error is in backend code, not the page
+```
+
+Every failure also ends with a short summary you can paste straight into an AI
+coding tool.
+
+## Automatic checks
+
+The first time a test passes, kryptheon remembers where the browser ended up
+and what the page was called. If either changes later, the test fails and tells
+you what changed — so a recording catches regressions without you writing a
+single assertion.
+
+When a change is intentional, accept it for that one test:
+
+```
+npx kryptheon accept "Checkout"
+```
+
+`npx kryptheon accept` on its own lists what has been saved.
+
+## Files it creates in your folder
+
+| File | What it is |
+| --- | --- |
+| `tests/` | your recordings |
+| `kryptheon-baselines.json` | the remembered result for each test |
+| `kryptheon-history.jsonl` | one line per run, used for "this was working on …" |
+
+`.env` in the same folder is loaded automatically, so a recording can sign in
+without the password living in the test file.
+
+Worth adding to `.gitignore`: `.env`, `kryptheon-baselines.json`,
+`kryptheon-history.jsonl`, `test-results/`.
+
+## Requirements
+
+Node 20.6 or later. The first run downloads a browser (about 200MB, once).
+
+## Licence
+
+MIT

package/bin/kryptheon.js

@@ -0,0 +1,554 @@
+#!/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.
+//
+// Two roots matter, and they are not the same once this is installed:
+//   PACKAGE_DIR - the tool's own files (fixture, reporter, config, this file)
+//   USER_DIR    - the folder the command was run in, which owns tests/,
+//                 kryptheon-baselines.json, kryptheon-history.jsonl and .env
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PACKAGE_DIR = path.join(__dirname, '..');
+const USER_DIR = process.cwd();
+const CONFIG = path.join(PACKAGE_DIR, 'playwright.config.js');
+const TESTS_DIR = path.join(USER_DIR, 'tests');
+
+const MIN_NODE = [20, 6, 0];
+
+function nodeIsTooOld(version) {
+  const parts = String(version || process.versions.node).split('.').map(Number);
+  for (let i = 0; i < MIN_NODE.length; i++) {
+    if ((parts[i] || 0) > MIN_NODE[i]) return false;
+    if ((parts[i] || 0) < MIN_NODE[i]) return true;
+  }
+  return false;
+}
+
+function usage() {
+  console.log('');
+  console.log('  kryptheon - record and check your app');
+  console.log('');
+  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('');
+}
+
+// Resolve Playwright's own CLI and run it on this Node binary, rather than
+// relying on a `playwright` executable being on PATH.
+// The package's "exports" map exposes "./cli" (no .js), so that specifier is
+// the one that resolves; the package.json route is the fallback.
+function findPlaywrightCli() {
+  try {
+    return require.resolve('@playwright/test/cli', { paths: [PACKAGE_DIR] });
+  } catch (err) {
+    /* fall through */
+  }
+  try {
+    const pkg = require.resolve('@playwright/test/package.json', { paths: [PACKAGE_DIR] });
+    return path.join(path.dirname(pkg), 'cli.js');
+  } catch (err) {
+    return null;
+  }
+}
+
+// Always runs with the user's folder as the working directory, so tests,
+// baselines and .env are found where they actually live.
+function runPlaywright(args) {
+  const cli = findPlaywrightCli();
+  if (!cli) {
+    console.error('');
+    console.error('  The testing engine is missing from this install.');
+    console.error('  Reinstalling usually fixes it:  npm install -g kryptheon');
+    console.error('');
+    return 1;
+  }
+
+  const result = spawnSync(process.execPath, [cli].concat(args), {
+    cwd: USER_DIR,
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    console.error('');
+    console.error('  Could not start the testing engine: ' + result.error.message);
+    console.error('');
+    return 1;
+  }
+  return result.status === null ? 1 : result.status;
+}
+
+// Chromium is a separate download from the npm package, so the first run on a
+// new machine has to fetch it.
+function ensureBrowser() {
+  let executable = null;
+  try {
+    executable = require('@playwright/test').chromium.executablePath();
+  } catch (err) {
+    return true; // cannot tell - let Playwright speak for itself
+  }
+  if (executable && fs.existsSync(executable)) return true;
+
+  console.log('');
+  console.log('  Downloading a browser to run your app in.');
+  console.log('  This is about 200MB and only happens once.');
+  console.log('');
+  const status = runPlaywright(['install', 'chromium']);
+  if (status !== 0) {
+    console.error('');
+    console.error('  The browser download did not finish.');
+    console.error('  Check your internet connection and try again.');
+    console.error('');
+    return false;
+  }
+  return true;
+}
+
+function listSpecFiles() {
+  if (!fs.existsSync(TESTS_DIR)) return [];
+  let entries = [];
+  try {
+    entries = fs.readdirSync(TESTS_DIR, { recursive: true });
+  } catch (err) {
+    try {
+      entries = fs.readdirSync(TESTS_DIR);
+    } catch (err2) {
+      return [];
+    }
+  }
+  return entries
+    .map(String)
+    .filter((name) => /\.(spec|test)\.(c|m)?[jt]sx?$/.test(name));
+}
+
+function timestampName() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return (
+    'recorded-' +
+    d.getFullYear() + pad(d.getMonth() + 1) + pad(d.getDate()) +
+    '-' + pad(d.getHours()) + pad(d.getMinutes()) + pad(d.getSeconds()) +
+    '.spec.js'
+  );
+}
+
+// Codegen imports from '@playwright/test'. Point the new file at the shared
+// fixture instead, so a recorded test gets the same failure diagnostics
+// (failed requests, console errors) as every other spec. Imported by package
+// name, because the user's tests folder is not next to the installed package.
+function pointAtFixture(relativeFile) {
+  const full = path.join(USER_DIR, relativeFile);
+  let src;
+  try {
+    src = fs.readFileSync(full, 'utf8');
+  } catch (err) {
+    return false;
+  }
+  const updated = src
+    .replace(/from (['"])@playwright\/test\1/, "from 'kryptheon/kryptheon-fixture'")
+    .replace(/require\((['"])@playwright\/test\1\)/, "require('kryptheon/kryptheon-fixture')");
+  if (updated === src) return false;
+  try {
+    fs.writeFileSync(full, updated, 'utf8');
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+// "about-us.html" -> "About Us";  "/" -> null
+function humanisePath(pathname) {
+  const last = String(pathname || '')
+    .split('?')[0]
+    .split('#')[0]
+    .split('/')
+    .filter(Boolean)
+    .pop();
+  if (!last) return null;
+  const words = last
+    .replace(/\.[a-z0-9]+$/i, '')
+    .replace(/[-_+]+/g, ' ')
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .trim();
+  if (!words) return null;
+  return words
+    .split(/\s+/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+// Titles are usually "Site | Page". The page half is the useful one, and a
+// very long tail is prose rather than a name, so it is rejected.
+function nameFromTitle(title) {
+  const parts = String(title || '')
+    .split(/[|–—•:]|\s-\s/)
+    .map((p) => p.replace(/\s+/g, ' ').trim())
+    .filter(Boolean);
+  if (!parts.length) return null;
+  const tail = parts[parts.length - 1];
+  if (tail && tail.split(' ').length <= 4) return tail;
+  return null;
+}
+
+// Reads the title of a page over plain HTTP. Best effort: the name falls back
+// to the recorded path if this cannot be reached.
+async function fetchTitle(url) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5000);
+    const res = await fetch(url, { signal: controller.signal });
+    clearTimeout(timer);
+    if (!res.ok) return null;
+    const html = await res.text();
+    const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    return m ? m[1].replace(/\s+/g, ' ').trim() : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+function lastGoto(source) {
+  const gotos = [...String(source).matchAll(/page\.goto\(\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
+  return gotos.length ? gotos[gotos.length - 1] : null;
+}
+
+// Codegen calls every recording "test". Give it a name taken from what was
+// actually recorded: the last page navigated to, else the last thing clicked.
+function deriveTestName(source) {
+  const gotos = [...String(source).matchAll(/page\.goto\(\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
+  for (let i = gotos.length - 1; i >= 0; i--) {
+    let pathname = gotos[i];
+    try {
+      pathname = new URL(gotos[i]).pathname;
+    } catch (e) {
+      /* already a path */
+    }
+    const name = humanisePath(pathname);
+    if (name) return name;
+  }
+
+  const names = [...String(source).matchAll(/name:\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
+  if (names.length) return names[names.length - 1].trim();
+
+  const hosts = [...String(source).matchAll(/page\.goto\(\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
+  if (hosts.length) {
+    try {
+      const host = new URL(hosts[hosts.length - 1]).hostname.replace(/^www\./, '');
+      const label = humanisePath('/' + host.split('.')[0]);
+      if (label) return label;
+    } catch (e) {
+      /* fall through */
+    }
+  }
+  return null;
+}
+
+function slugify(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'recording';
+}
+
+// Renames the test inside the file, and the file to match. Only ever touches
+// the file codegen just wrote.
+async function nameRecording(relativeFile) {
+  const full = path.join(USER_DIR, relativeFile);
+  let src;
+  try {
+    src = fs.readFileSync(full, 'utf8');
+  } catch (err) {
+    return relativeFile;
+  }
+  // Only rename codegen's placeholder, never a name someone chose.
+  if (!/\btest\(\s*(['"])test\1/.test(src)) return relativeFile;
+
+  // The page title is the friendliest source; the recorded path is the
+  // fallback when the site cannot be reached.
+  const visited = lastGoto(src);
+  const name = (visited ? nameFromTitle(await fetchTitle(visited)) : null) || deriveTestName(src);
+  if (!name) return relativeFile;
+
+  const safeName = name.replace(/'/g, "\\'");
+  const updated = src.replace(/\btest\(\s*(['"])test\1/, "test('" + safeName + "'");
+
+  let target = path.join('tests', slugify(name) + '.spec.js');
+  let attempt = 1;
+  while (fs.existsSync(path.join(USER_DIR, target)) && path.join(USER_DIR, target) !== full) {
+    attempt += 1;
+    target = path.join('tests', slugify(name) + '-' + attempt + '.spec.js');
+  }
+
+  try {
+    fs.writeFileSync(full, updated, 'utf8');
+    if (path.join(USER_DIR, target) !== full) {
+      fs.renameSync(full, path.join(USER_DIR, target));
+      return target;
+    }
+  } catch (err) {
+    return relativeFile;
+  }
+  return target;
+}
+
+async function record(url) {
+  if (!url) {
+    console.error('');
+    console.error('  Which address should I open?');
+    console.error('');
+    console.error('  Add the web address of your app, for example:');
+    console.error('    kryptheon record https://www.example.com');
+    console.error('');
+    return 1;
+  }
+  if (!ensureBrowser()) return 1;
+
+  try {
+    fs.mkdirSync(TESTS_DIR, { recursive: true });
+  } catch (err) {
+    /* codegen will report if it cannot write */
+  }
+
+  let outFile = path.join('tests', timestampName());
+
+  console.log('');
+  console.log('  Opening ' + url + ' in a browser.');
+  console.log('');
+  console.log('  Use your app normally - click, type, sign in, whatever you want');
+  console.log('  covered. Every step is recorded as you go.');
+  console.log('');
+  console.log('  When you are done, close the browser window to save the test.');
+  console.log('');
+
+  const status = runPlaywright(['codegen', '--target', 'playwright-test', '-o', outFile, url]);
+
+  // Keyed off the file rather than the exit code: codegen still writes the
+  // recording when the window is force-closed, and that file should be wired
+  // up the same way.
+  if (fs.existsSync(path.join(USER_DIR, outFile))) {
+    pointAtFixture(outFile);
+    outFile = await nameRecording(outFile);
+    console.log('');
+    console.log('  Saved to ' + outFile);
+    console.log('  Run it any time with:  kryptheon check');
+    console.log('');
+  }
+  return status;
+}
+
+// Recordings import the fixture by package name, which only resolves if
+// kryptheon is in the user's own node_modules. Running through a bare `npx`
+// puts the package somewhere the tests cannot see.
+// Deliberately a filesystem walk, not require.resolve: this file lives inside
+// the kryptheon package, and a package with a name and an "exports" map can
+// always resolve itself by name, so require.resolve would answer "yes" even
+// when the user's tests have no way to find it.
+function fixtureResolvesForUser() {
+  let dir = USER_DIR;
+  for (;;) {
+    if (fs.existsSync(path.join(dir, 'node_modules', 'kryptheon', 'kryptheon-fixture.js'))) {
+      return true;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+
+// Only a problem if a recording actually asks for it: specs written against a
+// relative path (as in this repo) resolve on their own.
+function specsNeedThePackage() {
+  return listSpecFiles().some(function (name) {
+    try {
+      return fs.readFileSync(path.join(TESTS_DIR, name), 'utf8').indexOf('kryptheon/kryptheon-fixture') !== -1;
+    } catch (err) {
+      return false;
+    }
+  });
+}
+
+function check() {
+  if (!listSpecFiles().length) {
+    console.log('');
+    console.log('  There is nothing to check yet.');
+    console.log('');
+    console.log('  Record something first, for example:');
+    console.log('    kryptheon record https://www.example.com');
+    console.log('');
+    console.log('  Use your app in the browser that opens, then close it.');
+    console.log('');
+    return 1;
+  }
+  if (!fixtureResolvesForUser() && specsNeedThePackage()) {
+    console.log('');
+    console.log('  Your recordings cannot find kryptheon.');
+    console.log('');
+    console.log('  They are saved in this folder, but kryptheon itself is installed');
+    console.log('  somewhere else, so they have nothing to load. Add it here:');
+    console.log('');
+    console.log('    npm i -D kryptheon');
+    console.log('');
+    console.log('  Then run "kryptheon check" again.');
+    console.log('');
+    return 1;
+  }
+  if (!ensureBrowser()) return 1;
+  return runPlaywright(['test', '--config', CONFIG]);
+}
+
+// --- accept -----------------------------------------------------------------
+
+function baselineApi() {
+  try {
+    return require(path.join(PACKAGE_DIR, 'kryptheon-fixture.js'));
+  } catch (err) {
+    console.error('');
+    console.error('  Could not read the saved results: ' + err.message);
+    console.error('');
+    return null;
+  }
+}
+
+// A key looks like "tests/login.spec.js :: Login".
+function titleOf(key) {
+  const at = key.indexOf(' :: ');
+  return at === -1 ? key : key.slice(at + 4);
+}
+
+function listBaselines(api) {
+  const all = api.readBaselines(api.BASELINE_FILE);
+  const keys = Object.keys(all);
+
+  console.log('');
+  if (!keys.length) {
+    console.log('  No tests have a saved result yet.');
+    console.log('  Run "kryptheon check" once and they will be saved automatically.');
+    console.log('');
+    return 0;
+  }
+
+  console.log('  Tests with a saved result:');
+  console.log('');
+  for (const key of keys) {
+    const waiting = all[key] && all[key].pending ? '   (has a new result waiting)' : '';
+    console.log('    ' + titleOf(key) + waiting);
+    console.log('      from ' + key.split(' :: ')[0]);
+  }
+  console.log('');
+  console.log('  To agree that a new result is correct:');
+  console.log('    kryptheon accept "<name>"');
+  console.log('');
+  return 0;
+}
+
+function accept(name) {
+  const api = baselineApi();
+  if (!api) return 1;
+  if (!name) return listBaselines(api);
+
+  const all = api.readBaselines(api.BASELINE_FILE);
+  const wanted = String(name).trim().toLowerCase();
+  const matches = Object.keys(all).filter(function (key) {
+    return titleOf(key).toLowerCase() === wanted || key.toLowerCase() === wanted;
+  });
+
+  if (!matches.length) {
+    console.error('');
+    console.error('  No saved result for a test called "' + name + '".');
+    console.error('  Run "kryptheon accept" on its own to see the names.');
+    console.error('');
+    return 1;
+  }
+  if (matches.length > 1) {
+    console.error('');
+    console.error('  More than one test is called "' + name + '":');
+    matches.forEach((k) => console.error('    ' + k));
+    console.error('');
+    console.error('  Pass the full line above instead.');
+    console.error('');
+    return 1;
+  }
+
+  const key = matches[0];
+  const result = api.acceptBaseline(api.BASELINE_FILE, key);
+
+  if (result.ok) {
+    console.log('');
+    console.log('  Updated the saved result for "' + titleOf(key) + '".');
+    console.log('    Address: ' + result.entry.url);
+    console.log('    Title:   ' + result.entry.title);
+    console.log('');
+    console.log('  Every other test was left alone.');
+    console.log('');
+    return 0;
+  }
+
+  console.error('');
+  if (result.reason === 'nothing-pending') {
+    console.error('  "' + titleOf(key) + '" has no new result waiting.');
+    console.error('  Nothing to accept - it last matched its saved result.');
+  } else if (result.reason === 'no-entry') {
+    console.error('  "' + titleOf(key) + '" has no saved result yet.');
+  } else {
+    console.error('  Could not update the saved result for "' + titleOf(key) + '".');
+  }
+  console.error('');
+  return 1;
+}
+
+const [command, ...rest] = process.argv.slice(2);
+
+async function main() {
+  if (nodeIsTooOld()) {
+    console.error('');
+    console.error('  This tool needs a newer version of Node.');
+    console.error('    You have:  ' + process.versions.node);
+    console.error('    You need:  20.6.0 or later');
+    console.error('');
+    console.error('  Download the latest from https://nodejs.org and try again.');
+    console.error('');
+    process.exit(1);
+  }
+
+  switch (command) {
+    case 'record':
+      process.exit(await record(rest[0]));
+      break;
+    case 'check':
+      process.exit(check());
+      break;
+    case 'accept':
+      process.exit(accept(rest.join(' ').trim()));
+      break;
+    case undefined:
+    case '-h':
+    case '--help':
+    case 'help':
+      usage();
+      process.exit(0);
+      break;
+    default:
+      console.error('');
+      console.error('  Unknown command: ' + command);
+      usage();
+      process.exit(1);
+  }
+}
+
+// Exported so the naming logic can be checked without opening a browser.
+module.exports = {
+  humanisePath: humanisePath,
+  nameFromTitle: nameFromTitle,
+  deriveTestName: deriveTestName,
+  slugify: slugify,
+  nameRecording: nameRecording,
+  pointAtFixture: pointAtFixture,
+  listSpecFiles: listSpecFiles,
+  nodeIsTooOld: nodeIsTooOld,
+};
+
+if (require.main === module) main();