kryptheon 0.1.11 → 0.1.13

package/kryptheon-project.js

@@ -23,6 +23,12 @@ const path = require('path');
 // stumble into.
 const ESCAPE_HATCH = 'KRYPTHEON_ALLOW_NO_PACKAGE_JSON';
 
+// Where `record` keeps recordings for somebody who ran it in their home folder.
+// A new terminal opens there, so for anyone who has only a web address - an
+// app built in Lovable, no source folder anywhere - it is where the command
+// gets typed.
+const HOME_RECORDINGS = 'kryptheon-tests';
+
 function hasPackageJson(dir) {
   try {
     return fs.statSync(path.join(dir, 'package.json')).isFile();
@@ -107,6 +113,13 @@ function inspectProject(dir, env) {
   const personal = isHomeOrSystem(dir);
   const base = { dir: dir, packaged: packaged, personal: personal, allowed: allowed };
 
+  // Somebody whose recordings `record` put in a folder of their own, standing
+  // in their home folder again because that is where a new terminal opens.
+  // Pointed at by name, rather than told to go and find a project they never
+  // had.
+  const kept = tidy(dir) === tidy(os.homedir()) ? path.join(path.resolve(dir), HOME_RECORDINGS) : null;
+  if (kept && hasPackageJson(kept)) base.recordingsAt = kept;
+
   if (allowed) return Object.assign({ ok: true, reason: null }, base);
 
   // A home folder is refused even when it has a package.json, and this is not
@@ -131,6 +144,19 @@ function inspectProject(dir, env) {
 function noProjectLines(inspection) {
   const lines = [''];
 
+  if (inspection.recordingsAt) {
+    lines.push('  This is your home folder, not a project.');
+    lines.push('');
+    lines.push('  Your recordings are in:  ' + inspection.recordingsAt);
+    lines.push('');
+    lines.push('  To check them:');
+    lines.push('');
+    lines.push('    cd "' + inspection.recordingsAt + '"');
+    lines.push('    npx kryptheon check');
+    lines.push('');
+    return lines;
+  }
+
   if (inspection.personal) {
     lines.push('  This is your home or a system folder, not a project.');
     lines.push('');
@@ -163,6 +189,16 @@ function noProjectLines(inspection) {
   lines.push('    cd path\\to\\your\\project');
   lines.push('    kryptheon check');
   lines.push('');
+  // The person with a web address and no folder at all - an app built in
+  // Lovable - has no project to change into, and would be stuck on the line
+  // above. Not offered in a system folder: record refuses to set one up.
+  if (!inspection.personal || tidy(inspection.dir) === tidy(os.homedir())) {
+    lines.push('  No project folder, only a web address? Record from here and it');
+    lines.push('  will be set up for you:');
+    lines.push('');
+    lines.push('    npx kryptheon record https://your-app.example.com');
+    lines.push('');
+  }
   lines.push('  If you really do keep recordings outside a package, set');
   lines.push('  ' + ESCAPE_HATCH + '=1 and this will run anyway.');
   lines.push('');
@@ -187,8 +223,296 @@ function noRecordingsLines() {
   ];
 }
 
+// --- Setting a folder up, before recording into it ---------------------------
+//
+// Somebody who built their app in Lovable has an address and nothing else: no
+// source folder, no package.json, nothing to change into. Their recordings
+// still need somewhere to live, `check` refuses a folder with no package.json,
+// and a recording cannot load the fixture unless kryptheon is installed where
+// the recording is.
+//
+// `record` used to find all of that out afterwards. Measured in an empty
+// folder: it started the browser, would have let the person spend five minutes
+// using their app and saved the recording - and then `check`, in that same
+// folder, said "There is no project here". So record now works out what is
+// missing before the browser, which is a 200MB download on a new machine, and
+// offers to add it.
+
+/**
+ * Whether kryptheon can be loaded by a recording saved in this folder.
+ *
+ * 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
+ * recordings have no way to find it.
+ */
+function kryptheonReachableFrom(dir) {
+  let current = path.resolve(String(dir || ''));
+  if (insideKryptheonItself(current)) return true;
+  for (;;) {
+    if (fs.existsSync(path.join(current, 'node_modules', 'kryptheon', 'kryptheon-fixture.js'))) {
+      return true;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
+
+/**
+ * Inside the kryptheon package's own folder - this repository.
+ *
+ * Node lets a package load itself by its own name, so a recording made here
+ * finds the fixture with no node_modules/kryptheon anywhere. Without this,
+ * record in this repository offered to npm install kryptheon into kryptheon.
+ * Only the nearest package.json counts: that is the package a file belongs to.
+ */
+function insideKryptheonItself(dir) {
+  let current = dir;
+  for (;;) {
+    if (hasPackageJson(current)) {
+      // The name alone is not enough: somebody's own app can be called that.
+      // The fixture beside it is what makes it this package.
+      try {
+        return JSON.parse(fs.readFileSync(path.join(current, 'package.json'), 'utf8')).name === 'kryptheon' &&
+          fs.existsSync(path.join(current, 'kryptheon-fixture.js'));
+      } catch (err) {
+        return false;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
+
+/**
+ * Installed in this folder itself, not borrowed from one above it.
+ *
+ * A folder record sets up gets its own copy even when one is reachable from
+ * further up. The copy further up is, on the one machine where this was looked
+ * at, a stray install in a home folder - and recordings that lean on that stop
+ * working the day somebody tidies it away.
+ */
+function kryptheonInstalledIn(dir) {
+  return fs.existsSync(path.join(path.resolve(String(dir || '')), 'node_modules', 'kryptheon', 'kryptheon-fixture.js'));
+}
+
+/**
+ * The nearest folder above this one that is a project.
+ *
+ * Stops at a home or system folder rather than walking through it: the one
+ * package.json most likely to be found up there is the stray one a mistaken
+ * install left in a home folder, and that is nobody's project.
+ */
+function projectAbove(dir) {
+  let current = path.resolve(String(dir || ''));
+  for (;;) {
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    if (isHomeOrSystem(parent)) return null;
+    if (hasPackageJson(parent)) return parent;
+    current = parent;
+  }
+}
+
+/** A folder record set up on an earlier run - its package.json asks for kryptheon. */
+function setUpForKryptheon(dir) {
+  try {
+    const json = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    return !!((json.devDependencies && json.devDependencies.kryptheon) ||
+              (json.dependencies && json.dependencies.kryptheon));
+  } catch (err) {
+    return false;
+  }
+}
+
+function isEmptyFolder(dir) {
+  try {
+    return fs.statSync(dir).isDirectory() && fs.readdirSync(dir).length === 0;
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * What this folder needs before a recording made in it can be checked. Only
+ * looks; never writes.
+ *
+ *   ready    nothing
+ *   create   no package.json and no project above: make one, then install
+ *   install  a project without kryptheon: install it
+ *   above    no package.json, but a project sits above this folder
+ *   home     a home folder: record in a kryptheon-tests folder inside it
+ *   refuse   a system folder, or a home whose kryptheon-tests is taken
+ */
+function setupPlan(dir, env) {
+  const environment = env || process.env;
+  const here = path.resolve(String(dir || ''));
+
+  // Somebody who has said they keep recordings outside a package is left
+  // exactly as they were before any of this existed.
+  if (String(environment[ESCAPE_HATCH] || '') !== '') return { action: 'ready', dir: here };
+
+  if (tidy(here) === tidy(os.homedir())) {
+    const into = path.join(here, HOME_RECORDINGS);
+    // Used only if it is plainly ours or plainly nothing. A folder of that name
+    // holding something else is somebody's, and recording into it would put a
+    // package.json and node_modules in the middle of it.
+    if (!fs.existsSync(into) || isEmptyFolder(into) || setUpForKryptheon(into)) {
+      return { action: 'home', dir: here, into: into };
+    }
+    return { action: 'refuse', reason: 'taken', dir: here, into: into };
+  }
+  if (isHomeOrSystem(here)) return { action: 'refuse', reason: 'system', dir: here };
+
+  if (!hasPackageJson(here)) {
+    const above = projectAbove(here);
+    if (above) return { action: 'above', dir: here, project: above };
+    return { action: 'create', dir: here };
+  }
+  if (!kryptheonReachableFrom(here)) return { action: 'install', dir: here };
+  return { action: 'ready', dir: here };
+}
+
+/** What is about to happen to this folder, said before it happens. */
+function setupLines(plan, url) {
+  const address = url || 'https://your-app.example.com';
+  const lines = [''];
+
+  if (plan.action === 'create') {
+    lines.push('  This folder is not set up for recordings yet.');
+    lines.push('');
+    lines.push('  You are in:  ' + plan.dir);
+    lines.push('');
+    lines.push('  Your recordings are saved here, and kryptheon has to be installed');
+    lines.push('  beside them or they cannot be checked later. So I will add:');
+    lines.push('');
+    lines.push('    package.json     a small file that marks this folder as a project');
+    lines.push('    node_modules     kryptheon itself, about 20MB');
+    lines.push('');
+    lines.push('  Nothing already in this folder is touched.');
+  } else if (plan.action === 'install') {
+    lines.push('  kryptheon is not installed in this project yet.');
+    lines.push('');
+    lines.push('  You are in:  ' + plan.dir);
+    lines.push('');
+    lines.push('  Recordings load it by name, so without it here they cannot be');
+    lines.push('  checked later. I will run:');
+    lines.push('');
+    lines.push('    npm install --save-dev kryptheon');
+    lines.push('');
+    lines.push('  which adds one line to package.json and about 20MB to node_modules.');
+  } else if (plan.action === 'above') {
+    lines.push('  This folder is inside a project:');
+    lines.push('');
+    lines.push('    ' + plan.project);
+    lines.push('');
+    lines.push('  Recordings belong beside the app they test, so the usual thing is');
+    lines.push('  to run this from there:');
+    lines.push('');
+    lines.push('    cd "' + plan.project + '"');
+    lines.push('    npx kryptheon record ' + address);
+    lines.push('');
+    lines.push('  If that is not your project - a package.json can be left behind by');
+    lines.push('  an install run in the wrong place - I can set this folder up on its');
+    lines.push('  own instead.');
+  } else if (plan.action === 'home') {
+    lines.push('  You are in your home folder.');
+    lines.push('');
+    lines.push('  Recordings are kept in a folder of their own rather than loose in');
+    lines.push('  here, so I will ' + (fs.existsSync(plan.into) ? 'use this one' : 'make one') + ' and work in that:');
+    lines.push('');
+    lines.push('    ' + plan.into);
+  } else if (plan.action === 'refuse' && plan.reason === 'taken') {
+    lines.push('  You are in your home folder. Recordings are kept in a folder of');
+    lines.push('  their own, and I would normally use:');
+    lines.push('');
+    lines.push('    ' + plan.into);
+    lines.push('');
+    lines.push('  but something else is already there, and it is not one I made.');
+    lines.push('  Nothing was changed.');
+    lines.push('');
+    lines.push('  Make a new folder of your own, open a terminal in it, and run the');
+    lines.push('  same command again.');
+  } else if (plan.action === 'refuse') {
+    lines.push('  This is a system folder, not somewhere to keep recordings.');
+    lines.push('');
+    lines.push('  You are in:  ' + plan.dir);
+    lines.push('');
+    lines.push('  Nothing was changed. Make a new folder of your own - on the Desktop');
+    lines.push('  is fine - open a terminal in it, and run the same command again.');
+    if (process.platform === 'win32') {
+      lines.push('  (In File Explorer: right-click inside the folder, Open in Terminal.)');
+    }
+  }
+  lines.push('');
+  return lines;
+}
+
+/**
+ * The question, and which way Enter answers it.
+ *
+ * Yes by default where saying yes is what the person came for. No by default
+ * for a folder inside another project, where yes puts a second project inside
+ * somebody's first.
+ */
+function setupQuestion(plan) {
+  if (plan.action === 'above') return { text: '  Set this folder up on its own instead? [y/N] ', yesByDefault: false };
+  if (plan.action === 'install') return { text: '  Install it? [Y/n] ', yesByDefault: true };
+  if (plan.action === 'home') return { text: '  Go ahead? [Y/n] ', yesByDefault: true };
+  return { text: '  Set this folder up? [Y/n] ', yesByDefault: true };
+}
+
+/** An answer typed at the question, read the way the question offered it. */
+function answeredYes(answer, yesByDefault) {
+  const typed = String(answer || '').trim();
+  if (!typed) return !!yesByDefault;
+  return /^y/i.test(typed);
+}
+
+/** After recording from a home folder: where the recordings went, and how to get back to them. */
+function homeDoneLines(into) {
+  return [
+    '',
+    '  Your recordings are in:  ' + into,
+    '',
+    '  To check them after a change, open a terminal and run:',
+    '',
+    '    cd "' + into + '"',
+    '    npx kryptheon check',
+    '',
+  ];
+}
+
+/** The install did not finish. Nothing needs undoing: running again picks up where this stopped. */
+function installFailedLines() {
+  return [
+    '',
+    '  kryptheon could not be installed in this folder.',
+    '',
+    '  Installing needs an internet connection. Check it, then run the same',
+    '  command again - nothing needs undoing first.',
+    '',
+    '  Or install it yourself, then record:',
+    '',
+    '    npm install --save-dev kryptheon',
+    '',
+  ];
+}
+
 module.exports = {
   ESCAPE_HATCH: ESCAPE_HATCH,
+  HOME_RECORDINGS: HOME_RECORDINGS,
+  kryptheonReachableFrom: kryptheonReachableFrom,
+  kryptheonInstalledIn: kryptheonInstalledIn,
+  projectAbove: projectAbove,
+  setupPlan: setupPlan,
+  setupLines: setupLines,
+  setupQuestion: setupQuestion,
+  answeredYes: answeredYes,
+  homeDoneLines: homeDoneLines,
+  installFailedLines: installFailedLines,
   hasPackageJson: hasPackageJson,
   systemFolders: systemFolders,
   tidy: tidy,

package/kryptheon-reporter.js

@@ -170,6 +170,94 @@ function firstMeaningfulLine(message) {
   return line ? line.replace(/^(TimeoutError|Error):\s*/, '').trim() : 'The test failed.';
 }
 
+// ---------------------------------------------------------------------------
+// Errors that belong to no test.
+//
+// A spec file with a syntax error, or one importing something that is not
+// there, never becomes a test at all - so nothing calls onTestEnd and the run
+// ends with no results. Playwright reports it through onError. A reporter that
+// does not implement onError prints a summary of nothing and exits 1, and the
+// person is left with a silent failure and no idea which file is at fault.
+// ---------------------------------------------------------------------------
+
+// Playwright says this once the load errors have already been reported. On its
+// own it means an empty tests folder; after a real error it is a consequence,
+// not a cause, and repeating it just buries the thing that has to be fixed.
+function isNoTestsFound(error) {
+  return /No tests found/i.test(String((error && error.message) || ''));
+}
+
+/**
+ * A load error, reduced to the file, the line and one sentence.
+ *
+ * The message carries a code frame in ANSI colour and repeats the absolute
+ * path inside its own first line. Neither helps here: the path is printed
+ * separately and relative, and the frame belongs in an editor.
+ */
+function readLoadError(error, userDir) {
+  const raw = stripAnsi((error && error.message) || (error && error.value) || String(error || ""));
+  const location = (error && error.location) || {};
+
+  let file = location.file || null;
+  if (file) {
+    try {
+      file = path.relative(userDir || process.cwd(), file);
+    } catch (e) {
+      /* an absolute path is still better than nothing */
+    }
+  }
+
+  // First line only, with the absolute path taken back out of it.
+  let message = raw.split("\n").map(function (l) { return l.trim(); }).filter(Boolean)[0] || "The file could not be read.";
+  if (location.file) message = message.split(location.file + ": ").join("");
+  message = message.replace(/\s*\(\d+:\d+\)\s*$/, "");
+
+  return {
+    file: file,
+    line: typeof location.line === "number" ? location.line : null,
+    message: message,
+  };
+}
+
+/**
+ * What to print when nothing could be loaded.
+ *
+ * Said as "this file", not "the tests failed", because nothing was tested. The
+ * app may be perfectly fine; a file in the tests folder is not.
+ */
+function loadErrorLines(errors, userDir) {
+  const real = (errors || []).filter(function (e) { return !isNoTestsFound(e); });
+  const lines = [];
+
+  if (!real.length) {
+    // Nothing ran and nothing explained why. Saying so is still better than a
+    // summary of zero, which reads as "everything is fine".
+    lines.push("Nothing ran.");
+    lines.push("");
+    lines.push("No recording produced a result, and the test runner gave no reason.");
+    lines.push("Check that the files in tests/ contain a test.");
+    lines.push("");
+    return lines;
+  }
+
+  const many = real.length > 1;
+  lines.push(many ? real.length + " of your recordings could not be read:" : "One of your recordings could not be read:");
+  lines.push("");
+  for (const error of real) {
+    const read = readLoadError(error, userDir);
+    const where = read.file ? read.file + (read.line ? "  line " + read.line : "") : "(the file was not named)";
+    lines.push("  " + where);
+    lines.push("  " + read.message);
+    lines.push("");
+  }
+  lines.push(many
+    ? "Nothing else ran, because those files could not be loaded at all."
+    : "Nothing else ran, because that file could not be loaded at all.");
+  lines.push("Fix it and run this again.");
+  lines.push("");
+  return lines;
+}
+
 // ---------------------------------------------------------------------------
 // Translation: Playwright error -> { reason, advice }
 // ---------------------------------------------------------------------------
@@ -575,10 +663,19 @@ class KryptheonReporter {
     this.previousRuns = [];
     this.records = [];
     this.startedAt = new Date();
+    // Errors that belong to no test: a spec file that would not load.
+    this.loadErrors = [];
     // Set by any test whose page never said what encoding it was in.
     this.sawGuessedEncoding = false;
   }
 
+  // Playwright calls this for anything that happened outside a test: a spec
+  // file that would not load, most often. Kept rather than printed here, so
+  // the reason lands beside the summary instead of ahead of the run.
+  onError(error) {
+    this.loadErrors.push(error);
+  }
+
   onBegin() {
     this.startedAt = new Date();
     // Read history before this run is appended, so "was working on" looks
@@ -807,10 +904,35 @@ class KryptheonReporter {
     // has ever had a baseline - says the app is at fault when nothing is.
     const counts = recordings.summarise(this.records);
 
-    // The one line stands in for the whole report only when there is no report
-    // to make. A recording that has never passed is not counted as broken, but
-    // it did fail and its reasons were printed above, so the run still owes the
-    // reader its closing count.
+    // A file that would not load is said first, and always - before the quiet
+    // shortcut, and whatever else the run managed to do.
+    //
+    // In practice a file that will not load stops the whole run, so nothing
+    // else has anything to report and the block below returns. This is not
+    // written as though that were guaranteed: onError also carries errors that
+    // arrive outside any test, and one of those turning up after results would
+    // otherwise be dropped in silence - which is the bug this whole thing is
+    // here to fix.
+    const unreadable = this.loadErrors.some(function (e) { return !isNoTestsFound(e); });
+    if (unreadable) {
+      process.stdout.write(
+        String.fromCharCode(10) + loadErrorLines(this.loadErrors, USER_DIR).join(String.fromCharCode(10)),
+      );
+    }
+
+    // Nothing ran at all. A summary of zero reads as good news, and in quiet
+    // mode it would say "0 recordings still working" over the top of a file
+    // that does not compile, so neither is printed. If the reason has not
+    // already been given above, it is given now.
+    if (!this.records.length) {
+      if (!unreadable) {
+        process.stdout.write(
+          String.fromCharCode(10) + loadErrorLines(this.loadErrors, USER_DIR).join(String.fromCharCode(10)),
+        );
+      }
+      return;
+    }
+
     if (QUIET && !counts.broken && !counts.unproven) {
       const s = counts.working === 1 ? '' : 's';
       process.stdout.write('OK  ' + counts.working + ' recording' + s + ' still working.\n');
@@ -838,3 +960,7 @@ module.exports = KryptheonReporter;
 // Shared with the fixture so baselines strip hosts exactly the same way.
 // Attached to the exported class, so `new (require(...))()` keeps working.
 module.exports.requestPath = requestPath;
+
+// Exported for the checks: what a file that would not load turns into.
+module.exports.readLoadError = readLoadError;
+module.exports.loadErrorLines = loadErrorLines;