kryptheon 0.1.0 → 0.1.1

package/bin/kryptheon.js

@@ -58,28 +58,36 @@ function findPlaywrightCli() {
 
 // 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) {
+// Returns { status, stderr }. With quietErrors the child's stderr is captured
+// rather than inherited, so a Node or Playwright stack trace never reaches the
+// person running the command.
+function runPlaywright(args, options) {
+  const quiet = !!(options && options.quietErrors);
   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;
+    return { status: 1, stderr: '' };
   }
 
   const result = spawnSync(process.execPath, [cli].concat(args), {
     cwd: USER_DIR,
-    stdio: 'inherit',
+    stdio: quiet ? ['inherit', 'inherit', 'pipe'] : 'inherit',
+    encoding: 'utf8',
   });
 
   if (result.error) {
     console.error('');
     console.error('  Could not start the testing engine: ' + result.error.message);
     console.error('');
-    return 1;
+    return { status: 1, stderr: String(result.stderr || '') };
   }
-  return result.status === null ? 1 : result.status;
+  return {
+    status: result.status === null ? 1 : result.status,
+    stderr: String(result.stderr || ''),
+  };
 }
 
 // Chromium is a separate download from the npm package, so the first run on a
@@ -97,7 +105,7 @@ function ensureBrowser() {
   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']);
+  const status = runPlaywright(['install', 'chromium']).status;
   if (status !== 0) {
     console.error('');
     console.error('  The browser download did not finish.');
@@ -125,6 +133,124 @@ function listSpecFiles() {
     .filter((name) => /\.(spec|test)\.(c|m)?[jt]sx?$/.test(name));
 }
 
+// --- is the address actually there? ----------------------------------------
+
+// "localhost:3000" is what people type; give it a scheme before using it.
+function normaliseRecordUrl(url) {
+  const s = String(url == null ? '' : url).trim();
+  if (!s) return s;
+  if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(s)) return s;
+  return 'http://' + s;
+}
+
+function isLocalAddress(url) {
+  let host;
+  try {
+    host = new URL(url).hostname.toLowerCase();
+  } catch (err) {
+    return false;
+  }
+  return (
+    host === 'localhost' ||
+    host === '127.0.0.1' ||
+    host === '0.0.0.0' ||
+    host === '::1' ||
+    host === '[::1]' ||
+    host.endsWith('.local') ||
+    host.endsWith('.localhost')
+  );
+}
+
+// Turns a fetch failure into one of a few plain kinds. Split out from the
+// network call so it can be checked without a network.
+function classifyFetchError(err) {
+  const code = (err && err.cause && err.cause.code) || (err && err.code) || null;
+  if (code === 'ECONNREFUSED') return 'refused';
+  if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return 'unknown-address';
+  if (err && err.name === 'AbortError') return 'timeout';
+  if (code === 'ETIMEDOUT' || code === 'ECONNRESET') return 'timeout';
+  // A certificate complaint means something IS answering there. Let the
+  // browser deal with it rather than blocking the recording.
+  if (code && /CERT|SSL|SELF_SIGNED|VERIFY/i.test(String(code))) return 'reachable';
+  return 'other';
+}
+
+async function reachability(url, timeoutMs) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs || 8000);
+    await fetch(url, { signal: controller.signal, redirect: 'manual' });
+    clearTimeout(timer);
+    return { ok: true, kind: 'reachable' };
+  } catch (err) {
+    const kind = classifyFetchError(err);
+    return kind === 'reachable' ? { ok: true, kind: kind } : { ok: false, kind: kind };
+  }
+}
+
+// One place that explains an address not answering, used both before codegen
+// starts and if codegen itself reports the same thing.
+function explainUnreachable(url, kind) {
+  const local = isLocalAddress(url);
+  console.error('');
+  console.error('  Nothing answered at ' + url);
+  console.error('');
+
+  if (kind === 'unknown-address') {
+    console.error('  That web address could not be found.');
+    console.error('  Check the spelling, and that you are connected to the internet.');
+  } else if (kind === 'timeout') {
+    console.error('  The address did not answer in time.');
+    console.error('  It may be slow, or blocked by a firewall or VPN.');
+  } else if (local) {
+    console.error('  Your app does not look like it is running.');
+    console.error('');
+    console.error('  For an app on your own machine, start it first - usually:');
+    console.error('    npm run dev');
+    console.error('');
+    console.error('  Then check the address and port match what it printed.');
+  } else {
+    console.error('  Nothing is listening at that address.');
+    console.error('  Check the address, including the port number, and that the site is up.');
+  }
+
+  console.error('');
+  console.error('  Nothing was recorded.');
+  console.error('');
+}
+
+// Codegen writes Node/Playwright traces to stderr. We never show those; we
+// pick out the part that means something and say it in plain words.
+function explainCodegenFailure(url, stderr) {
+  const text = String(stderr || '');
+  if (/ERR_CONNECTION_REFUSED/.test(text)) return explainUnreachable(url, 'refused');
+  if (/ERR_NAME_NOT_RESOLVED/.test(text)) return explainUnreachable(url, 'unknown-address');
+  if (/ERR_CONNECTION_TIMED_OUT|ERR_TIMED_OUT/.test(text)) return explainUnreachable(url, 'timeout');
+  if (/ERR_INTERNET_DISCONNECTED/.test(text)) {
+    console.error('');
+    console.error('  There is no internet connection.');
+    console.error('');
+    console.error('  Nothing was recorded.');
+    console.error('');
+    return;
+  }
+  console.error('');
+  console.error('  The browser closed before anything could be recorded.');
+  console.error('');
+  console.error('  Check that ' + url + ' opens normally in your own browser,');
+  console.error('  then try again.');
+  console.error('');
+  console.error('  Nothing was recorded.');
+  console.error('');
+}
+
+// A recording is only worth keeping if the browser actually did something.
+// An abandoned or failed run leaves a test body with no page calls at all.
+function countRecordedActions(source) {
+  const found = String(source || '').match(/\bpage\s*\.\s*[A-Za-z_$][\w$]*\s*\(/g);
+  return found ? found.length : 0;
+}
+
 function timestampName() {
   const d = new Date();
   const pad = (n) => String(n).padStart(2, '0');
@@ -305,8 +431,18 @@ async function record(url) {
     console.error('');
     return 1;
   }
+  const target = normaliseRecordUrl(url);
+
+  // Fail early and kindly rather than letting codegen throw a stack trace.
+  const reach = await reachability(target);
+  if (!reach.ok) {
+    explainUnreachable(target, reach.kind);
+    return 1;
+  }
+
   if (!ensureBrowser()) return 1;
 
+  const hadTestsDir = fs.existsSync(TESTS_DIR);
   try {
     fs.mkdirSync(TESTS_DIR, { recursive: true });
   } catch (err) {
@@ -316,7 +452,7 @@ async function record(url) {
   let outFile = path.join('tests', timestampName());
 
   console.log('');
-  console.log('  Opening ' + url + ' in a browser.');
+  console.log('  Opening ' + target + ' 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.');
@@ -324,20 +460,58 @@ async function record(url) {
   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]);
+  const run = runPlaywright(['codegen', '--target', 'playwright-test', '-o', outFile, target], {
+    quietErrors: true,
+  });
+
+  const specPath = path.join(USER_DIR, outFile);
+  let source = null;
+  try {
+    source = fs.readFileSync(specPath, 'utf8');
+  } catch (err) {
+    source = null; // codegen wrote nothing at all
+  }
 
-  // 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))) {
+  // Keyed off what is in the file rather than the exit code: codegen still
+  // writes a recording when the window is force-closed, and still leaves an
+  // empty shell behind when the page never loaded.
+  if (source !== null && countRecordedActions(source) > 0) {
     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 0;
+  }
+
+  // Nothing usable: leave no empty file behind.
+  if (source !== null) {
+    try {
+      fs.unlinkSync(specPath);
+    } catch (err) {
+      /* nothing more we can do */
+    }
+  }
+  if (!hadTestsDir) {
+    try {
+      if (fs.readdirSync(TESTS_DIR).length === 0) fs.rmdirSync(TESTS_DIR);
+    } catch (err) {
+      /* only tidying up */
+    }
+  }
+
+  if (run.status !== 0 || source === null) {
+    explainCodegenFailure(target, run.stderr);
+  } else {
+    console.log('');
+    console.log('  Nothing was recorded.');
+    console.log('');
+    console.log('  The browser closed before anything was clicked or typed.');
+    console.log('  Run the same command again and use your app before closing it.');
+    console.log('');
   }
-  return status;
+  return 1;
 }
 
 // Recordings import the fixture by package name, which only resolves if
@@ -397,7 +571,7 @@ function check() {
     return 1;
   }
   if (!ensureBrowser()) return 1;
-  return runPlaywright(['test', '--config', CONFIG]);
+  return runPlaywright(['test', '--config', CONFIG]).status;
 }
 
 // --- accept -----------------------------------------------------------------
@@ -548,6 +722,10 @@ module.exports = {
   nameRecording: nameRecording,
   pointAtFixture: pointAtFixture,
   listSpecFiles: listSpecFiles,
+  countRecordedActions: countRecordedActions,
+  classifyFetchError: classifyFetchError,
+  normaliseRecordUrl: normaliseRecordUrl,
+  isLocalAddress: isLocalAddress,
   nodeIsTooOld: nodeIsTooOld,
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kryptheon",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Record what you do in your app and get plain-language reports when it breaks.",
   "license": "MIT",
   "type": "commonjs",