staysfixed 0.1.1 → 0.2.1

package/src/picture/capture.js

@@ -13,6 +13,10 @@ import { applyFreeze, prepareForShutter } from '../freeze/index.js';
 import { settle } from '../freeze/settle.js';
 import { resolveMasks, paintMasks } from '../freeze/mask.js';
 import { StaysFixedError, isExpected, messageOf } from '../core/errors.js';
+// store.js reads `pngSize` back out of this file. Two modules about the same pictures
+// leaning on each other is fine here — both sides are plain functions, so neither is
+// half-built when the other asks for it.
+import { thumbnailOf } from './store.js';
 
 /**
  * Every instruction a declarative step is allowed to give, in the order they run
@@ -47,10 +51,20 @@ const KNOWN_KEYS = new Set([...ACTION_ORDER, 'text', 'note']);
  *   freeze: import('../types.js').FreezeConfig,
  *   masks: import('../types.js').Mask[],
  * }} settings
- * @param {{fixturesDir: string, record?: boolean, timeoutMs?: number}} ctx
- * @returns {Promise<import('../types.js').CaptureReport & {masks: import('../types.js').MaskRect[]}>}
- *   The standard report plus the mask rectangles that were painted, so the
- *   comparison can paint the exact same rectangles onto the approved picture.
+ * @param {{fixturesDir: string, record?: boolean, timeoutMs?: number, thumbnail?: boolean}} ctx
+ *   `thumbnail` is asked for only while somebody is watching the run happen; it costs a
+ *   decode of the picture that was just taken (skipped when the masks already decoded it)
+ *   plus about forty milliseconds of shrinking, so it is off unless it is wanted.
+ * @returns {Promise<import('../types.js').CaptureReport & {
+ *   masks: import('../types.js').MaskRect[],
+ *   timings: {steps: number, prepare: number, settle: number},
+ *   spent: {steps: number, prepare: number, settle: number},
+ *   thumbnail?: string,
+ * }>}
+ *   The standard report, plus the mask rectangles that were painted so the comparison can
+ *   paint the exact same rectangles onto the approved picture, plus where the time went.
+ *   Only this function knows how its own milliseconds were spent, so it says, rather than
+ *   leaving the run to guess by wrapping things it cannot see inside.
  */
 export async function captureScreen(page, screen, settings, ctx) {
   const deviceScaleFactor = settings.viewport.deviceScaleFactor ?? 2;
@@ -67,6 +81,14 @@ export async function captureScreen(page, screen, settings, ctx) {
     deviceScaleFactor,
   });
 
+  // A frozen clock cannot time anything, so the stopwatch is the host's own, and it is
+  // the monotonic one: a machine that adjusts its clock mid-run must not be able to
+  // report that a screen took a negative amount of time.
+  const clock = process.hrtime.bigint;
+  const startedSteps = clock();
+  /** @type {{steps: number, prepare: number, settle: number}} */
+  const spent = { steps: 0, prepare: 0, settle: 0 };
+
   try {
     if (typeof screen.do === 'function') {
       await screen.do(page);
@@ -79,6 +101,9 @@ export async function captureScreen(page, screen, settings, ctx) {
     const scrolledOnPurpose =
       typeof screen.do === 'function' || (screen.steps ?? []).some((s) => s.scrollTo !== undefined);
 
+    const startedPrepare = clock();
+    spent.steps = since(startedSteps, startedPrepare);
+
     await prepareForShutter(page, {
       fonts: settings.freeze.fonts !== false,
       timeoutMs,
@@ -90,16 +115,32 @@ export async function captureScreen(page, screen, settings, ctx) {
     if (screen.fullPage) shotOptions.fullPage = true;
     if (screen.clip) shotOptions.clip = screen.clip;
 
+    // The same frame, asked for cheaply. The settle loop shoots the screen over and over
+    // to find out whether anything moved and throws every one of those pictures away, so
+    // it gets a small lossy one; the picture that is kept and compared is always the PNG.
+    /** @type {import('../types.js').CaptureOptions & {format: 'jpeg', quality: number}} */
+    const probeOptions = { ...shotOptions, format: 'jpeg', quality: 50 };
+
+    const startedSettle = clock();
+    spent.prepare = since(startedPrepare, startedSettle);
+
     const held = await settle(page, {
       frames: settleConfig.frames ?? 2,
       intervalMs: settleConfig.intervalMs ?? 250,
       timeoutMs: settleConfig.timeoutMs ?? 10_000,
       maxDriftPixels: settleConfig.maxDriftPixels ?? 0,
       capture: () => page.shoot(shotOptions),
+      probe: () => page.shoot(probeOptions),
     });
+    spent.settle = since(startedSettle, clock());
 
     const rects = await resolveMasks(page, settings.masks ?? [], { deviceScaleFactor });
-    const png = rects.length > 0 ? paintInto(held.png, rects) : held.png;
+    // Masks force us to decode the picture; hold on to those pixels. The preview a
+    // watcher is shown is made from the very same ones — the picture that gets
+    // compared, blackout boxes and all — so a masked screen decodes a retina
+    // screenshot once instead of twice, which is about eighty milliseconds a screen.
+    const painted = rects.length > 0 ? paintInto(held.png, rects) : null;
+    const png = painted ? painted.png : held.png;
     const size = pngSize(png);
 
     // The picture is taken; now put the app back if this screen asked us to.
@@ -115,7 +156,8 @@ export async function captureScreen(page, screen, settings, ctx) {
       await runSteps(page, screen.after);
     }
 
-    return {
+    /** @type {import('../types.js').CaptureReport & {masks: import('../types.js').MaskRect[], timings: typeof spent, spent: typeof spent, thumbnail?: string}} */
+    const report = {
       png,
       width: size.width,
       height: size.height,
@@ -123,7 +165,15 @@ export async function captureScreen(page, screen, settings, ctx) {
       consoleErrors: page.consoleErrors(),
       freeze: frozen.stats(),
       masks: rects,
+      // The same three numbers under both names the rest of the tool asks for them by.
+      timings: spent,
+      spent,
     };
+    if (ctx.thumbnail === true) {
+      const small = await thumbnailOf(painted ? painted.image : png);
+      if (small) report.thumbnail = small;
+    }
+    return report;
   } finally {
     // Releasing must never be the thing that hides a real failure.
     try {
@@ -134,16 +184,31 @@ export async function captureScreen(page, screen, settings, ctx) {
   }
 }
 
+/**
+ * Milliseconds between two readings of the monotonic clock.
+ * @param {bigint} from
+ * @param {bigint} to
+ * @returns {number}
+ */
+function since(from, to) {
+  return Number(to - from) / 1e6;
+}
+
 /**
  * Paint the masks into a screenshot and re-encode it.
+ *
+ * Hands back the decoded picture as well as the bytes. Whoever wants a preview of this
+ * screen would otherwise decode the very same megapixels a second time, and on a retina
+ * screenshot that is the most expensive thing either of them does.
+ *
  * @param {Buffer} buffer
  * @param {import('../types.js').MaskRect[]} rects
- * @returns {Buffer}
+ * @returns {{png: Buffer, image: import('pngjs').PNG}}
  */
 function paintInto(buffer, rects) {
   const image = PNG.sync.read(buffer);
   paintMasks(image, rects);
-  return PNG.sync.write(image);
+  return { png: PNG.sync.write(image), image };
 }
 
 /**

package/src/picture/compare.js

@@ -13,6 +13,66 @@ import pixelmatch from 'pixelmatch';
 import { paintMasks } from '../freeze/mask.js';
 import { DEFAULT_TOLERANCE } from '../core/config.js';
 import { StaysFixedError } from '../core/errors.js';
+import { pngSize } from './capture.js';
+
+/**
+ * Whether two pictures are the very same file.
+ * @param {Buffer} a
+ * @param {Buffer} b
+ * @returns {boolean}
+ */
+export function sameBytes(a, b) {
+  return Boolean(a) && Boolean(b) && a.length === b.length && a.equals(b);
+}
+
+/**
+ * The same comparison, without the work when there is nothing to compare.
+ *
+ * On a healthy project every screen is unchanged, which means the new picture is the very
+ * same file as the approved one — the encoder is deterministic, so identical pixels
+ * produce identical bytes. Decoding two full retina PNGs to prove that costs a quarter of
+ * a second per screen, every run, to reach a conclusion the file lengths already gave
+ * away.
+ *
+ * This is not a looser check, it is the same answer arrived at honestly. Identical bytes
+ * are identical pixels, so nothing differs, so nothing can exceed any allowance. Masks do
+ * not change that: a mask paints the same rectangle onto both pictures, and painting the
+ * same thing onto two identical pictures leaves them identical. The size comes out of the
+ * PNG header, which is where `comparePng` would have got it too.
+ *
+ * @param {Buffer} approvedBuf
+ * @param {Buffer} actualBuf
+ * @param {import('../types.js').ToleranceConfig} tolerance
+ * @param {import('../types.js').MaskRect[]} [maskRects]
+ * @returns {import('../types.js').CompareReport}
+ */
+export function compareFast(approvedBuf, actualBuf, tolerance, maskRects = []) {
+  if (sameBytes(approvedBuf, actualBuf)) {
+    try {
+      const size = pngSize(actualBuf);
+      const allowed =
+        tolerance.maxPixels ??
+        Math.floor(size.width * size.height * (tolerance.pixels ?? DEFAULT_TOLERANCE.pixels));
+      // A negative allowance is a setting that says even a perfect match is a failure.
+      // Nonsense, but it is the caller's nonsense, and the long way round is the only one
+      // that can answer it the same way it always has.
+      if (allowed >= 0) {
+        return {
+          equal: true,
+          diffPixels: 0,
+          diffRatio: 0,
+          diffPng: null,
+          sizeMismatch: false,
+          size,
+          approvedSize: { width: size.width, height: size.height },
+        };
+      }
+    } catch {
+      // Not a readable PNG header. Let the full path throw the sentence it always throws.
+    }
+  }
+  return comparePng(approvedBuf, actualBuf, tolerance, maskRects);
+}
 
 /**
  * @param {Buffer} approvedBuf

package/src/picture/run.js

@@ -12,8 +12,8 @@
  */
 
 import { captureScreen } from './capture.js';
-import { comparePng, describeDifference } from './compare.js';
-import { readApproved, writeResult, writeDiff, approveFromResult } from './store.js';
+import { compareFast, describeDifference } from './compare.js';
+import { readApproved, writeResult, writeDiff, approveFromResult, thumbnailOf } from './store.js';
 import { settingsForScreen } from '../core/config.js';
 import { approvedPicture, resultPicture } from '../core/paths.js';
 import { platformTag } from '../drive/find.js';
@@ -21,6 +21,7 @@ import { resetWindow } from '../drive/launch.js';
 import { gitInfo } from '../core/git.js';
 import { messageOf } from '../core/errors.js';
 import { detail } from '../core/log.js';
+import { emitEvent, fileUrl } from '../core/events.js';
 
 /**
  * A picture result plus the one extra fact the flake register needs: whether it
@@ -28,6 +29,29 @@ import { detail } from '../core/log.js';
  * @typedef {import('../types.js').PictureResult & {retriedToPass?: boolean}} PictureRunResult
  */
 
+/**
+ * What a watcher is shown of one screen, filled in as it is worked on.
+ *
+ * Two kinds of thing, for two different moments. The `file://` addresses are the real
+ * full-resolution pictures this run wrote, and they are what a person actually looks
+ * at and zooms into; they cost nothing to fill in, so they are always filled in. The
+ * base64 previews are the instant stand-in for the fraction of a second before a file
+ * loads, they cost real milliseconds to make, and they are only made when a window is
+ * open to show them in.
+ *
+ * All of it is kept apart from the result on purpose. A result is written to disk and
+ * read back by `approve` and `status`, and a base64 picture in there would bloat
+ * every saved run for the sake of a panel that was only open for a minute.
+ *
+ * @typedef {object} Thumbs
+ * @property {string} [shot]         Instant preview of the picture just taken.
+ * @property {string} [approved]     Instant preview of the approved picture, when this screen changed.
+ * @property {string} [diff]         Instant preview of what moved, when this screen changed.
+ * @property {string} [shotFile]     The picture just taken, on disk.
+ * @property {string} [approvedFile] The approved picture, on disk, when there is one.
+ * @property {string} [diffFile]     The difference picture, on disk, when one was written.
+ */
+
 /**
  * @param {import('../types.js').Project} project
  * @param {import('../types.js').LaunchedApp} app
@@ -39,6 +63,9 @@ import { detail } from '../core/log.js';
  *   retries?: number,
  *   tool?: string,
  *   signal?: AbortSignal,
+ *   events?: import('../types.js').RunEvents,
+ *   timings?: ReturnType<typeof import('../core/events.js').makeTimings>,
+ *   thumbnail?: boolean,
  * }} [opts]
  * @returns {Promise<PictureRunResult[]>}
  */
@@ -53,48 +80,124 @@ export async function runPictures(project, app, opts = {}) {
   // A desktop app has no url to go back to between screens, so it gets a reload instead.
   // A web app does not need one: every screen starts with a `goto`.
   const reset = config.app.kind === 'electron' ? () => resetWindow(app) : undefined;
+  const events = opts.events;
+
+  // Which screens are being photographed is settled before the first shutter, so
+  // anyone watching can be told how many there are and where each one sits in the
+  // queue rather than watching a list of unknown length crawl past.
+  const chosen = config.screens.filter((screen) => !only || only.has(screen.name));
+  const total = chosen.length;
 
   /** @type {PictureRunResult[]} */
   const results = [];
 
-  for (const screen of config.screens) {
+  for (let i = 0; i < chosen.length; i++) {
     if (opts.signal?.aborted) break;
-    if (only && !only.has(screen.name)) continue;
+    const screen = chosen[i];
+
+    emitEvent(events, {
+      type: 'screen:start',
+      name: screen.name,
+      describe: screen.describe,
+      index: i + 1,
+      total,
+    });
 
     if (screen.skip) {
-      results.push(
-        finish(opts, {
-          name: screen.name,
-          describe: screen.describe,
-          status: 'skipped',
-          message: `${screen.name} is switched off in the config.`,
-          durationMs: 0,
-        }),
-      );
+      const skipped = finish(opts, {
+        name: screen.name,
+        describe: screen.describe,
+        status: 'skipped',
+        message: `${screen.name} is switched off in the config.`,
+        durationMs: 0,
+      });
+      results.push(skipped);
+      emitDone(events, skipped, {});
       continue;
     }
 
-    results.push(
-      await runOneScreen(project, page, screen, {
-        record: opts.record,
-        updateNew: opts.updateNew,
-        tool: opts.tool,
-        onResult: opts.onResult,
-        retries,
-        here,
-        reset,
-      }),
-    );
+    // Filled in as the screen is worked on, and read once it is finished. The
+    // thumbnails exist only while somebody is watching, so they travel beside the
+    // result instead of inside it.
+    /** @type {Thumbs} */
+    const thumbs = {};
+
+    const result = await runOneScreen(project, page, screen, {
+      record: opts.record,
+      updateNew: opts.updateNew,
+      tool: opts.tool,
+      onResult: opts.onResult,
+      retries,
+      here,
+      reset,
+      events,
+      timings: opts.timings,
+      thumbnail: opts.thumbnail === true,
+      thumbs,
+    });
+    results.push(result);
+    emitDone(events, result, thumbs);
   }
 
   return results;
 }
 
+/**
+ * Tell anyone watching how a screen turned out, with the pictures if there are any.
+ *
+ * @param {import('../types.js').RunEvents|undefined} events
+ * @param {PictureRunResult} result
+ * @param {Thumbs} thumbs
+ * @returns {void}
+ */
+function emitDone(events, result, thumbs) {
+  emitEvent(events, {
+    type: 'screen:done',
+    name: result.name,
+    describe: result.describe,
+    status: result.status,
+    durationMs: result.durationMs,
+    diffPixels: result.diffPixels,
+    diffRatio: result.diffRatio,
+    message: result.message,
+    thumbnail: thumbs.shot,
+    approvedThumb: thumbs.approved,
+    diffThumb: thumbs.diff,
+    // The real pictures. Only ever set for a file that was written or read a moment
+    // ago, so anything that arrives here can be opened; a screen that was skipped, or
+    // one that could not be photographed at all, sends none of them.
+    shotFile: thumbs.shotFile,
+    approvedFile: thumbs.approvedFile,
+    diffFile: thumbs.diffFile,
+  });
+}
+
+/**
+ * Everything one screen needs, including where to leave what it learns.
+ *
+ * `thumbs` is written into rather than returned because a screen can finish down
+ * half a dozen different paths, and threading a second return value through all
+ * of them would bury the thing this function is actually for.
+ *
+ * @typedef {object} ScreenCtx
+ * @property {boolean} [record]
+ * @property {boolean} [updateNew]
+ * @property {string} [tool]
+ * @property {(r: PictureRunResult) => void} [onResult]
+ * @property {number} retries
+ * @property {string} here
+ * @property {() => Promise<void>} [reset]
+ * @property {import('../types.js').RunEvents} [events]
+ * @property {ReturnType<typeof import('../core/events.js').makeTimings>} [timings]
+ * @property {boolean} [thumbnail]        Make the small pictures a watcher needs.
+ * @property {Thumbs} [thumbs]            Where those small pictures are left.
+ */
+
 /**
  * @param {import('../types.js').Project} project
  * @param {import('../types.js').PageHandle} page
  * @param {import('../types.js').ScreenConfig} screen
- * @param {{record?: boolean, updateNew?: boolean, tool?: string, onResult?: (r: PictureRunResult) => void, retries: number, here: string, reset?: () => Promise<void>}} ctx
+ * @param {ScreenCtx} ctx
  * @returns {Promise<PictureRunResult>}
  */
 async function runOneScreen(project, page, screen, ctx) {
@@ -107,6 +210,11 @@ async function runOneScreen(project, page, screen, ctx) {
   const approved = await readApproved(paths, screen.name);
   const platformNote = platformWarning(approved?.meta?.platform, ctx.here);
 
+  // We have just read it, so it is certainly there. Pointed out even for a screen that
+  // ends up matching: "show me what this is supposed to look like" is a fair question
+  // about a screen that passed, and answering it costs one string.
+  if (approved && ctx.thumbs) ctx.thumbs.approvedFile = fileUrl(approvedPaths.png);
+
   /** @type {string[]} */
   let consoleErrors = [];
   /** @type {{width: number, height: number}|undefined} */
@@ -132,18 +240,43 @@ async function runOneScreen(project, page, screen, ctx) {
         fixturesDir: paths.fixtures,
         record: ctx.record ?? false,
         timeoutMs: settings.freeze.settle?.timeoutMs,
+        thumbnail: ctx.thumbnail === true,
       });
+      accountForCapture(ctx.timings, shot);
       consoleErrors = shot.consoleErrors;
       size = { width: shot.width, height: shot.height };
 
-      await writeResult(paths, screen.name, shot.png, {
+      const shotFile = await writeResult(paths, screen.name, shot.png, {
         deviceScaleFactor: settings.viewport.deviceScaleFactor,
         describe: screen.describe,
       });
 
+      // Said out loud before anything is compared, so a person watching sees the
+      // picture appear while the run is still deciding what it thinks of it — but
+      // AFTER the PNG is on disk, not the instant the shutter fires. The panel opens
+      // the real file to show true pixels, and an <img> pointed at a file that does
+      // not exist yet draws a torn page and never retries. The preview travels on the
+      // same event and covers the moment the file takes to load.
+      if (ctx.thumbs) {
+        if (shot.thumbnail) ctx.thumbs.shot = shot.thumbnail;
+        ctx.thumbs.shotFile = fileUrl(shotFile);
+      }
+      emitEvent(ctx.events, {
+        type: 'screen:shot',
+        name: screen.name,
+        thumbnail: shot.thumbnail,
+        shotFile: fileUrl(shotFile),
+      });
+
       if (!approved) break;
 
-      compare = comparePng(approved.png, shot.png, settings.tolerance, shot.masks);
+      const stopCompare = ctx.timings?.mark('compare');
+      // compareFast, not comparePng: identical bytes are answered from the PNG header
+      // instead of decoding two retina images pixel by pixel. Nothing changed on most
+      // screens on most runs, so this is the case that actually happens — it took the
+      // comparing stage from about a quarter of a second a screen to nothing at all.
+      compare = compareFast(approved.png, shot.png, settings.tolerance, shot.masks);
+      stopCompare?.();
       if (compare.equal) break;
       if (attempt <= ctx.retries) {
         detail(`${screen.name} looked different on attempt ${attempt} — taking it again.`);
@@ -184,6 +317,8 @@ async function runOneScreen(project, page, screen, ctx) {
         describe: screen.describe,
         deviceScaleFactor: settings.viewport.deviceScaleFactor,
       });
+      // It exists now, because that call is what wrote it.
+      if (ctx.thumbs) ctx.thumbs.approvedFile = fileUrl(approvedPaths.png);
       return finish(ctx, {
         ...base,
         status: 'new',
@@ -237,7 +372,27 @@ async function runOneScreen(project, page, screen, ctx) {
 
   /** @type {string|undefined} */
   let diffPath;
-  if (compare.diffPng) diffPath = await writeDiff(paths, screen.name, compare.diffPng);
+  if (compare.diffPng) {
+    diffPath = await writeDiff(paths, screen.name, compare.diffPng);
+    // Set only inside this branch: a screen that matched has no difference picture, and
+    // a stale one from a previous run is deleted before every run for exactly that
+    // reason. Pointing at one that is not there is how a panel starts lying.
+    if (ctx.thumbs) ctx.thumbs.diffFile = fileUrl(diffPath);
+  }
+
+  // Only for a screen that actually moved, and only when somebody is watching:
+  // this is the one moment a person wants the approved picture and the difference
+  // side by side with the new one.
+  //
+  // Both are made at the same size as the new picture's preview, because a person
+  // comparing three pictures must not be shown one sharp one and two blurred ones.
+  // Each costs a decode plus a shrink — about an eighth of a second on a retina
+  // screenshot — so this stays behind both gates, and behind `changed`. A run where
+  // everything held pays none of it.
+  if (ctx.thumbnail === true && ctx.thumbs) {
+    ctx.thumbs.approved = (await thumbnailOf(approved.png)) ?? undefined;
+    if (compare.diffPng) ctx.thumbs.diff = (await thumbnailOf(compare.diffPng)) ?? undefined;
+  }
 
   const what = describeDifference(compare, screen.name);
   const next = compare.sizeMismatch
@@ -252,6 +407,32 @@ async function runOneScreen(project, page, screen, ctx) {
   });
 }
 
+/**
+ * Put the time one picture took into the buckets it belongs in. The walk uses
+ * this too, so a walkthrough and a check file their time the same way.
+ *
+ * Only capture knows how its own milliseconds went, so it says, and this puts
+ * what it said where the profile can find it. If it ever stops saying, the one
+ * number still worth claiming is how long the screen was held still before the
+ * shutter; the rest goes unclaimed into `other` rather than being guessed at,
+ * because a made-up profile is worse than a missing one.
+ *
+ * @param {ReturnType<typeof import('../core/events.js').makeTimings>|undefined} timings
+ * @param {Awaited<ReturnType<typeof captureScreen>>} shot
+ * @returns {void}
+ */
+export function accountForCapture(timings, shot) {
+  if (!timings) return;
+  const reported = shot.timings;
+  if (reported) {
+    timings.add('steps', reported.steps);
+    timings.add('prepare', reported.prepare);
+    timings.add('settle', reported.settle);
+    return;
+  }
+  if (shot.settle) timings.add('settle', shot.settle.waitedMs);
+}
+
 /**
  * Font rendering differs between operating systems, so a picture approved on one
  * and checked on another is the single most common false alarm. Say it; never