staysfixed 0.2.2 → 0.3.0

package/src/guard/api.js

@@ -5,6 +5,14 @@
  * who wrote it has forgotten the bug. That is why assertions are a sentence plus
  * a check, and never a bare comparison: `expect('the sidebar is hidden', ...)`
  * fails with "expected: the sidebar is hidden", which anyone can act on.
+ *
+ * Those sentences are also the answer to the fairest question anyone asks about
+ * this tool: "is it only about how things look?" It is not — a guard drives the
+ * app and asserts what it still does — but that was invisible, because a guard
+ * reported one line however many things it proved. So every claim, and every
+ * action between the claims, now says itself out loud the moment it happens:
+ * announced as it starts, settled as it finishes. The list a person watches tick
+ * off IS the guard's own words, in the guard's own order.
  */
 
 import { exec } from 'node:child_process';
@@ -28,15 +36,79 @@ const DEFAULT_RUN_TIMEOUT = 60_000;
 /** Commands can print a lot; 10MB before we cut them off. */
 const MAX_OUTPUT = 10 * 1024 * 1024;
 
+/** Longest a selector, path or command is shown before it is cut short. */
+const MAX_LABEL = 80;
+
+/**
+ * How a step's id says what kind of step it is.
+ *
+ * An assertion is the point of a guard; opening a page or clicking a button is
+ * the setup that gets there. `CheckStep` has no room for that difference — and
+ * should not grow one for the sake of a colour — so it rides on the id, which
+ * every step needs anyway. Anything watching can draw `claim-` lines loud and
+ * `did-` lines quiet; anything that does not care sees a perfectly ordinary list.
+ */
+const CLAIM = 'claim';
+const ACTION = 'did';
+
+/**
+ * What a guard is told to report to, when anyone is collecting.
+ * @typedef {object} GuardApiOptions
+ * @property {(step: import('../types.js').CheckStep) => void} [onStep]
+ *           Called as each claim and each action starts, and again as it settles.
+ *           The two calls carry the same `key`.
+ */
+
 /**
  * Build the object passed to a guard's `run`.
  *
  * @param {import('../types.js').PageApi} page
  * @param {import('../types.js').Project} project
+ * @param {GuardApiOptions} [opts]
  * @returns {import('../types.js').GuardApi}
  */
-export function makeGuardApi(page, project) {
+export function makeGuardApi(page, project, opts = {}) {
   const root = project.paths.root;
+  const onStep = typeof opts.onStep === 'function' ? opts.onStep : null;
+  let counted = 0;
+
+  /**
+   * Hand one step out, and never let that matter.
+   *
+   * Reporting is a convenience laid over a check; a listener that throws must not
+   * change whether a bug that was fixed is still fixed.
+   *
+   * @param {import('../types.js').CheckStep} step
+   * @returns {void}
+   */
+  function tell(step) {
+    if (!onStep) return;
+    try {
+      onStep(step);
+    } catch {
+      // Watching is never worth a guard.
+    }
+  }
+
+  /**
+   * Say a thing has started, and hand back the way to say how it went.
+   *
+   * When nobody is collecting this allocates nothing and returns a function that
+   * does nothing, so a guard run with no watcher costs exactly what it did before.
+   *
+   * @param {string} kind   CLAIM or ACTION.
+   * @param {string} label  Plain language, already final — the same words settle it.
+   * @returns {(state: import('../types.js').CheckStep['state'], detail?: string) => void}
+   */
+  function announce(kind, label) {
+    if (!onStep) return () => {};
+    counted += 1;
+    const key = `${kind}-${counted}`;
+    tell({ key, label, state: 'running' });
+    return (state, detail) => {
+      tell(detail ? { key, label, detail, state } : { key, label, state });
+    };
+  }
 
   return {
     page,
@@ -46,16 +118,30 @@ export function makeGuardApi(page, project) {
      * @param {string} to
      * @returns {Promise<void>}
      */
-    open(to) {
-      return page.goto(to);
+    async open(to) {
+      const settle = announce(ACTION, `opened ${short(to)}`);
+      try {
+        await page.goto(to);
+      } catch (error) {
+        settle('bad', reasonOf(error));
+        throw error;
+      }
+      settle('ok');
     },
 
     /**
      * @param {string} selector
      * @returns {Promise<void>}
      */
-    click(selector) {
-      return page.click(selector);
+    async click(selector) {
+      const settle = announce(ACTION, `clicked ${short(selector)}`);
+      try {
+        await page.click(selector);
+      } catch (error) {
+        settle('bad', reasonOf(error));
+        throw error;
+      }
+      settle('ok');
     },
 
     /**
@@ -75,18 +161,32 @@ export function makeGuardApi(page, project) {
         });
       }
 
+      // The claim goes out before it is checked, not after. A person watching
+      // sees what is being asked while it is being asked — which is the whole
+      // difference between a list that ticks and a table that appears.
+      const settle = announce(CLAIM, claim.trim());
+
       let result;
       try {
         result = await check();
       } catch (cause) {
         // A nested expectation already reads well — do not bury it in another layer.
-        if (cause instanceof ExpectationFailed) throw cause;
-        throw new Error(`while checking '${claim}': ${cause instanceof Error ? cause.message : String(cause)}`, {
+        if (cause instanceof ExpectationFailed) {
+          settle('bad', cause.claim === claim.trim() ? undefined : `inside it: ${cause.claim}`);
+          throw cause;
+        }
+        const why = cause instanceof Error ? cause.message : String(cause);
+        settle('bad', firstLine(why));
+        throw new Error(`while checking '${claim}': ${why}`, {
           cause,
         });
       }
 
-      if (isNegative(result)) throw new ExpectationFailed(claim);
+      if (isNegative(result)) {
+        settle('bad', 'this is not true any more');
+        throw new ExpectationFailed(claim);
+      }
+      settle('ok');
     },
 
     /**
@@ -94,15 +194,17 @@ export function makeGuardApi(page, project) {
      * must still succeed, a file that must still be generated — live here.
      *
      * A non-zero exit is returned, never thrown: whether it means failure is the
-     * guard's decision, not ours.
+     * guard's decision, not ours. The step says so the same way — a command that
+     * came back unhappy is worth noticing, and is still not a verdict.
      *
      * @param {string} cmd
      * @param {{cwd?: string, timeoutMs?: number}} [runOpts]
      * @returns {Promise<{code: number, stdout: string, stderr: string}>}
      */
-    run(cmd, runOpts = {}) {
+    async run(cmd, runOpts = {}) {
       const cwd = runOpts.cwd ? path.resolve(root, runOpts.cwd) : root;
       const timeoutMs = runOpts.timeoutMs ?? DEFAULT_RUN_TIMEOUT;
+      const settle = announce(ACTION, `ran ${short(cmd)}`);
 
       /** @type {Promise<{code: number, stdout: string, stderr: string}>} */
       const finished = new Promise((resolve) => {
@@ -129,7 +231,13 @@ export function makeGuardApi(page, project) {
           },
         );
       });
-      return finished;
+
+      const outcome = await finished;
+      if (outcome.code === 0) settle('ok', 'finished cleanly, code 0');
+      else if (outcome.code === 124) {
+        settle('warn', `stopped after ${humanTime(timeoutMs)}, code 124`);
+      } else settle('warn', `came back with code ${outcome.code}`);
+      return outcome;
     },
 
     /**
@@ -149,20 +257,30 @@ export function makeGuardApi(page, project) {
         });
       }
 
+      const settle = announce(ACTION, `read ${short(relative)}`);
+      /** @type {string} */
+      let text;
       try {
-        return await fsp.readFile(full, 'utf8');
+        text = await fsp.readFile(full, 'utf8');
       } catch (cause) {
         const code = /** @type {any} */ (cause)?.code;
         if (code === 'ENOENT') {
+          settle('bad', 'there is no such file');
           throw new StaysFixedError(`There is no file called "${relative}" in the project.`, { cause });
         }
         if (code === 'EISDIR') {
+          settle('bad', 'that is a folder, not a file');
           throw new StaysFixedError(`"${relative}" is a folder, not a file.`, { cause });
         }
+        settle('bad', reasonOf(cause));
         throw new StaysFixedError(`Could not read "${relative}": ${cause instanceof Error ? cause.message : String(cause)}`, {
           cause,
         });
       }
+
+      const lines = text === '' ? 0 : text.split('\n').length;
+      settle('ok', `${count(lines)} ${lines === 1 ? 'line' : 'lines'}`);
+      return text;
     },
   };
 }
@@ -186,6 +304,44 @@ function isNegative(value) {
   return false;
 }
 
+/**
+ * A selector, path or command, short enough to read in a list.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function short(text) {
+  const one = String(text ?? '').replace(/\s+/g, ' ').trim();
+  if (one === '') return 'nothing';
+  return one.length > MAX_LABEL ? `${one.slice(0, MAX_LABEL - 1)}…` : one;
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function reasonOf(error) {
+  return firstLine(error instanceof Error ? error.message : String(error));
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function firstLine(text) {
+  const line = String(text ?? '').split('\n')[0].trim();
+  if (line === '') return 'it did not say why';
+  return line.length > 120 ? `${line.slice(0, 119)}…` : line;
+}
+
+/**
+ * @param {number} n
+ * @returns {string}
+ */
+function count(n) {
+  return Number.isFinite(n) ? Math.round(n).toLocaleString('en-US') : String(n);
+}
+
 /**
  * @param {number} ms
  * @returns {string}

package/src/guard/run.js

@@ -6,6 +6,14 @@
  * from the same clean state, a guard that needs a second go is recorded as
  * wobbly rather than green, and the failure message carries the story of the
  * original bug so nobody has to go looking for it.
+ *
+ * A guard also has to be watchable while it happens. It is the part of this tool
+ * that checks behaviour rather than looks — it drives the app and asserts what it
+ * still does — and reporting it as a single line hid every one of those
+ * assertions. So each claim and each action is passed straight out as it starts
+ * and again as it settles, and the whole list travels with the result. A guard
+ * that fails on its fifth claim still shows the four that held: "these are fine,
+ * this one is not" is most of the value of running it at all.
  */
 
 import { makeGuardApi, ExpectationFailed } from './api.js';
@@ -14,8 +22,14 @@ import { emitEvent } from '../core/events.js';
 
 const DEFAULT_TIMEOUT = 30_000;
 
+/** How the runner names its own first step — the clean start every guard gets. */
+const FRESH_KEY = 'fresh';
+
 /**
- * @typedef {import('../types.js').GuardResult & {retriedToPass?: boolean}} GuardRunResult
+ * @typedef {import('../types.js').GuardResult & {
+ *   retriedToPass?: boolean,
+ *   checks?: import('../types.js').CheckStep[],
+ * }} GuardRunResult
  */
 
 /**
@@ -25,6 +39,8 @@ const DEFAULT_TIMEOUT = 30_000;
  * @property {string} [failedAt]
  */
 
+/** @typedef {(step: import('../types.js').CheckStep) => void} StepSink */
+
 /**
  * Run every guard against an app that is already open.
  *
@@ -91,10 +107,31 @@ export async function runGuards(project, app, guards, opts = {}) {
     /** @type {AttemptOutcome} */
     let outcome = { ok: false, message: 'This guard did not run.' };
     let attempts = 0;
+    /** @type {import('../types.js').CheckStep[]} */
+    let checks = [];
 
     while (attempts < retries + 1) {
       attempts += 1;
-      outcome = await attemptGuard(project, app, guard, baseUrl, timeoutMs);
+      // A second go starts the list again. What a person needs to see is what the
+      // verdict was actually made on, and that is the last attempt — the earlier
+      // one is already recorded, more usefully, as "it only passed on try 2".
+      const attempt = attempts;
+      /** @type {import('../types.js').CheckStep[]} */
+      const collected = [];
+      checks = collected;
+
+      /** @type {StepSink} */
+      const onStep = (step) => {
+        // Keys are unique inside one attempt; a retry re-announces the same
+        // claims, and a watcher must not mistake the second run of a claim for
+        // the settling of the first.
+        const stamped =
+          attempt > 1 && step.key ? { ...step, key: `try${attempt}-${step.key}` } : step;
+        record(collected, stamped);
+        emitEvent(events, { type: 'guard:step', name: guard.name, step: stamped });
+      };
+
+      outcome = await attemptGuard(project, app, guard, baseUrl, timeoutMs, onStep);
       if (outcome.ok) break;
       if (opts.signal?.aborted) break;
     }
@@ -108,6 +145,7 @@ export async function runGuards(project, app, guards, opts = {}) {
       durationMs: Date.now() - startedAt,
       attempts,
     };
+    if (checks.length > 0) result.checks = checks;
 
     if (outcome.ok) {
       // Passing only on the second go is not passing. The flake register picks
@@ -127,6 +165,29 @@ export async function runGuards(project, app, guards, opts = {}) {
   return results;
 }
 
+/**
+ * Put one step into the list it belongs to.
+ *
+ * A step is said twice — once as it starts, once as it finishes — and the list
+ * should hold one line per thing, not two. The settled version replaces the
+ * running one in place, so the order stays the order it happened in.
+ *
+ * @param {import('../types.js').CheckStep[]} into
+ * @param {import('../types.js').CheckStep} step
+ * @returns {void}
+ */
+function record(into, step) {
+  if (step.key) {
+    for (let i = 0; i < into.length; i++) {
+      if (into[i].key === step.key) {
+        into[i] = step;
+        return;
+      }
+    }
+  }
+  into.push(step);
+}
+
 /**
  * @param {import('../types.js').RunEvents|undefined} events
  * @param {GuardRunResult} result
@@ -141,6 +202,10 @@ function emitGuardDone(events, result) {
     message: result.message,
     failedAt: result.failedAt,
     because: result.because,
+    // Everything this guard actually asserted, in its own words and its own
+    // order — so a listener that arrived late, or one that only keeps the
+    // verdicts, still has the working.
+    checks: result.checks,
   });
 }
 
@@ -152,12 +217,26 @@ function emitGuardDone(events, result) {
  * @param {import('../types.js').Guard} guard
  * @param {string|undefined} baseUrl
  * @param {number} timeoutMs
+ * @param {StepSink} [onStep]
  * @returns {Promise<AttemptOutcome>}
  */
-async function attemptGuard(project, app, guard, baseUrl, timeoutMs) {
+async function attemptGuard(project, app, guard, baseUrl, timeoutMs, onStep) {
   /** @type {ReturnType<typeof setTimeout>|undefined} */
   let timer;
 
+  /**
+   * @param {import('../types.js').CheckStep} step
+   * @returns {void}
+   */
+  const tell = (step) => {
+    if (!onStep) return;
+    try {
+      onStep(step);
+    } catch {
+      // Watching a guard must never be able to fail one.
+    }
+  };
+
   try {
     await Promise.race([
       (async () => {
@@ -171,10 +250,29 @@ async function attemptGuard(project, app, guard, baseUrl, timeoutMs) {
         // own, which is the single most confusing shape a failure can take. So an
         // Electron window is reloaded instead. Its main process keeps whatever it
         // was holding; only the screen goes back to how it opened.
-        if (baseUrl) await app.page.goto(baseUrl);
-        else await resetWindow(app);
+        const fresh = 'started from a clean screen';
+        tell({ key: FRESH_KEY, label: fresh, state: 'running' });
+        try {
+          if (baseUrl) await app.page.goto(baseUrl);
+          else await resetWindow(app);
+        } catch (error) {
+          tell({
+            key: FRESH_KEY,
+            label: fresh,
+            detail: error instanceof Error ? error.message : String(error),
+            state: 'bad',
+          });
+          throw error;
+        }
+        tell({
+          key: FRESH_KEY,
+          label: fresh,
+          detail: baseUrl ? 'back to the front door' : 'the window was reloaded',
+          state: 'ok',
+        });
+
         clearConsole(app);
-        await guard.run(makeGuardApi(app.page, project));
+        await guard.run(makeGuardApi(app.page, project, onStep ? { onStep } : {}));
       })(),
       new Promise((_resolve, reject) => {
         timer = setTimeout(() => {