npm - tuffgal - Versions diffs - 0.1.0-alpha.0 - Mend

tuffgal 0.1.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/LICENSE +21 -0
package/README.md +86 -0
package/bin/tuffgal.mjs +2 -0
package/package.json +70 -0
package/src/.gitkeep +0 -0
package/src/cli.ts +158 -0
package/src/commands/init.ts +140 -0
package/src/commands/supervise.ts +267 -0
package/src/config.ts +222 -0
package/src/coverage/flows.ts +90 -0
package/src/coverage/screens.ts +52 -0
package/src/index.ts +28 -0
package/src/reporter/assets/report.css +510 -0
package/src/reporter/assets/report.js +45 -0
package/src/reporter/template.ts +355 -0
package/src/reporter/writeReport.ts +37 -0
package/src/runner/approve.ts +65 -0
package/src/runner/bridges/database.ts +34 -0
package/src/runner/bridges/devServers.ts +174 -0
package/src/runner/coverage.ts +76 -0
package/src/runner/interpolate.ts +36 -0
package/src/runner/resolveLocator.ts +47 -0
package/src/runner/run.ts +177 -0
package/src/runner/runAction.ts +422 -0
package/src/runner/runStory.ts +195 -0
package/src/runner/scheduler.ts +223 -0
package/src/runner/steps/click.ts +16 -0
package/src/runner/steps/input.ts +17 -0
package/src/runner/steps/intercept.ts +28 -0
package/src/runner/steps/navigate.ts +14 -0
package/src/runner/steps/read.ts +20 -0
package/src/runner/steps/scroll.ts +12 -0
package/src/runner/steps/type.ts +11 -0
package/src/runner/steps/wait.ts +5 -0
package/src/runner/steps/waitFor.ts +16 -0
package/src/schema/action.ts +176 -0
package/src/schema/load.ts +94 -0
package/src/schema/result.ts +83 -0
package/src/schema/story.ts +58 -0
package/src/screenshots/baselineStore.ts +114 -0
package/src/screenshots/capture.ts +19 -0
package/src/screenshots/diff.ts +101 -0

package/src/reporter/template.ts ADDED Viewed

@@ -0,0 +1,355 @@
+import { relative } from 'node:path';
+import type {
+  ActionResult,
+  ActionStatus,
+  RunResult,
+  StoryResult,
+} from '../schema/result.ts';
+const STATUS_LABELS: Record<ActionStatus, string> = {
+  pass: 'pass',
+  changed: 'changed',
+  failed: 'failed',
+  skipped: 'skipped',
+  new: 'new baseline',
+};
+const STATUS_LETTERS: Record<ActionStatus, string> = {
+  pass: 'P',
+  changed: 'C',
+  failed: 'F',
+  skipped: '·',
+  new: 'N',
+};
+/**
+ * Static HTML report. Console / dev-tool aesthetic: dark by default, mono for
+ * data, sans for prose, sharp 1px borders, tree branches in box-drawing
+ * characters that are hidden from assistive tech. Stories + actions are
+ * conveyed semantically through nested `<ol>` elements; the glyphs are
+ * pure presentation.
+ */
+export function renderReport(result: RunResult, reportDir: string): string {
+  const failures = collectFailures(result);
+  const dateLabel = formatDate(result.finishedAt);
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>tuffgal report — ${dateLabel}</title>
+<link rel="stylesheet" href="assets/report.css" />
+</head>
+<body>
+<a class="skip-link" href="#main">Skip to report</a>
+<header class="report-header">
+  <h1>tuffgal report</h1>
+  <p class="report-meta">
+    <time datetime="${result.finishedAt}">${dateLabel}</time>
+    <span aria-hidden="true">·</span>
+    duration ${formatDuration(result.durationMs)}
+  </p>
+</header>
+<main id="main" tabindex="-1">
+  ${renderSummary(result)}
+  ${renderStories(result, reportDir)}
+  ${renderFailures(failures, reportDir)}
+</main>
+<script src="assets/report.js"></script>
+</body>
+</html>
+`;
+}
+function renderSummary(result: RunResult): string {
+  const screens = result.customCoverage.screens;
+  const flows = result.customCoverage.flows;
+  return `
+<section class="summary" aria-labelledby="summary-heading">
+  <h2 id="summary-heading">summary</h2>
+  <ul class="summary-list" aria-label="Run totals">
+    ${summaryItem('stories', result.totals.stories)}
+    ${summaryItem('pass', result.totals.passed, 'pass')}
+    ${summaryItem('changed', result.totals.changed, 'changed')}
+    ${summaryItem('failed', result.totals.failed, 'failed')}
+    ${coverageItem('screens', screens)}
+    ${coverageItem('flows', flows)}
+  </ul>
+</section>`;
+}
+function coverageItem(
+  label: string,
+  metric: { total: number; covered: number; ratio: number },
+): string {
+  const pct = `${(metric.ratio * 100).toFixed(0)}%`;
+  return `<li class="summary-item coverage"><span class="count">${pct}</span><span class="label">${label}</span><span class="coverage-detail" aria-hidden="true">${metric.covered}/${metric.total}</span><span class="sr-only">${metric.covered} of ${metric.total} ${label} covered</span></li>`;
+}
+function summaryItem(
+  label: string,
+  value: number,
+  statusKey?: ActionStatus,
+): string {
+  const indicator = statusKey
+    ? `<span class="indicator" data-status="${statusKey}" aria-hidden="true"></span>`
+    : '';
+  return `<li class="summary-item"${
+    statusKey ? ` data-status="${statusKey}"` : ''
+  }><span class="count">${value}</span>${indicator}<span class="label">${label}</span></li>`;
+}
+function renderStories(result: RunResult, reportDir: string): string {
+  const items = result.stories
+    .map((story, index) => renderStory(story, index, reportDir))
+    .join('\n');
+  return `
+<section aria-labelledby="stories-heading">
+  <h2 id="stories-heading">stories</h2>
+  <ol class="stories" aria-label="Stories executed in dependency order">
+    ${items}
+  </ol>
+</section>`;
+}
+function renderStory(
+  story: StoryResult,
+  storyIndex: number,
+  reportDir: string,
+): string {
+  const actions = story.actions
+    .map((action, actionIndex, all) =>
+      renderAction(
+        action,
+        `s${storyIndex}-a${actionIndex}`,
+        actionIndex === all.length - 1,
+        reportDir,
+      ),
+    )
+    .join('\n');
+  return `
+<li class="story" data-status="${story.status}">
+  <div class="story-row">
+    ${storyBadge(story.status)}
+    <code class="story-file">${escapeHtml(story.file)}</code>
+    <span class="story-duration">${formatDuration(story.durationMs)}</span>
+  </div>
+  <p class="story-prose">${escapeHtml(story.story)}</p>
+  <ol class="actions" aria-label="Actions">
+    ${actions}
+  </ol>
+</li>`;
+}
+function renderAction(
+  action: ActionResult,
+  actionId: string,
+  isLast: boolean,
+  reportDir: string,
+): string {
+  const branch = isLast ? '└─' : '├─';
+  const screenshots = renderScreenshots(action, actionId, reportDir);
+  const errorBlock =
+    action.status === 'failed'
+      ? `<pre class="action-error">${escapeHtml(action.failureMessage ?? 'unknown error')}</pre>`
+      : '';
+  const parameters = renderParameters(action.parameters);
+  return `
+<li class="action" data-status="${action.status}">
+  <div class="action-row">
+    <span class="branch" aria-hidden="true">${branch}</span>
+    ${statusBadge(action.status)}
+    <code class="action-name">${escapeHtml(action.action)}</code>
+    <span class="action-duration">${formatDuration(action.durationMs)}</span>
+    ${screenshots ? `<span class="action-shots">${screenshots}</span>` : ''}
+  </div>
+  ${parameters}
+  ${errorBlock}
+</li>`;
+}
+function renderParameters(
+  parameters: Record<string, string> | undefined,
+): string {
+  if (!parameters || Object.keys(parameters).length === 0) {
+    return '';
+  }
+  const entries = Object.entries(parameters)
+    .map(
+      ([key, value]) =>
+        `<dt>${escapeHtml(key)}</dt><dd>${escapeHtml(value)}</dd>`,
+    )
+    .join('');
+  return `<dl class="action-parameters">${entries}</dl>`;
+}
+function renderScreenshots(
+  action: ActionResult,
+  actionId: string,
+  reportDir: string,
+): string {
+  if (!action.actualPath && !action.baselinePath) {
+    return '';
+  }
+  const baseline = action.baselinePath
+    ? toReportRelative(reportDir, action.baselinePath)
+    : undefined;
+  const actual = action.actualPath
+    ? toReportRelative(reportDir, action.actualPath)
+    : undefined;
+  const diff = action.diffPath
+    ? toReportRelative(reportDir, action.diffPath)
+    : undefined;
+  const defaultTab = diff ? 'diff' : 'actual';
+  const diffStatsId = `${actionId}-diff-stats`;
+  const diffStats =
+    action.diffRatio !== undefined
+      ? `<p class="diff-stats" id="${diffStatsId}">${action.diffPixels} pixels differ (${(action.diffRatio * 100).toFixed(3)}%)</p>`
+      : '';
+  return `
+<details class="shots">
+  <summary><span aria-hidden="true">[</span>view<span aria-hidden="true">]</span></summary>
+  <fieldset class="shot-radio" data-default-tab="${defaultTab}">
+    <legend class="sr-only">Screenshot to display</legend>
+    ${shotRadio(actionId, 'baseline', baseline === undefined)}
+    ${shotRadio(actionId, 'actual', actual === undefined)}
+    ${shotRadio(actionId, 'diff', diff === undefined)}
+  </fieldset>
+  ${shotPanel(actionId, 'baseline', baseline, `${action.action} baseline screenshot`)}
+  ${shotPanel(actionId, 'actual', actual, `${action.action} actual screenshot from this run`)}
+  ${shotPanel(actionId, 'diff', diff, `Pixel diff overlay for ${action.action}: red pixels mark changed regions`, action.diffRatio !== undefined ? diffStatsId : undefined)}
+  ${diffStats}
+</details>`;
+}
+function shotRadio(actionId: string, name: string, disabled: boolean): string {
+  const inputId = `${actionId}-radio-${name}`;
+  return `<label for="${inputId}" class="shot-radio-label">
+    <input
+      type="radio"
+      name="${actionId}-shot"
+      id="${inputId}"
+      value="${name}"
+      data-tab="${name}"
+      ${disabled ? 'disabled' : ''}
+    />
+    ${name}
+  </label>`;
+}
+function shotPanel(
+  actionId: string,
+  name: string,
+  src: string | undefined,
+  alt: string,
+  describedById?: string,
+): string {
+  return `<div
+    class="shot-panel"
+    id="panel-${actionId}-${name}"
+    data-tab="${name}"
+    hidden
+  >
+    ${
+      src
+        ? `<img src="${escapeAttribute(src)}" alt="${escapeAttribute(alt)}" loading="lazy"${describedById ? ` aria-describedby="${describedById}"` : ''} />`
+        : `<p class="shot-missing">no ${name} screenshot for this action</p>`
+    }
+  </div>`;
+}
+function renderFailures(failures: FailureRecord[], reportDir: string): string {
+  if (failures.length === 0) {
+    return `
+<section aria-labelledby="failures-heading">
+  <h2 id="failures-heading">failures</h2>
+  <p class="prose-block empty">(none)</p>
+</section>`;
+  }
+  const items = failures
+    .map(
+      (failure) => `
+<article class="failure">
+  <header class="failure-head">
+    <code>${escapeHtml(failure.storyFile)}</code>
+    <span aria-hidden="true">·</span>
+    <code>${escapeHtml(failure.actionName)}</code>
+  </header>
+  <pre class="failure-message">${escapeHtml(failure.message)}</pre>
+  ${
+    failure.tracePath
+      ? `<p class="failure-trace">trace: <a href="${escapeAttribute(toReportRelative(reportDir, failure.tracePath))}">${escapeHtml(toReportRelative(reportDir, failure.tracePath))}</a></p>`
+      : ''
+  }
+</article>`,
+    )
+    .join('\n');
+  return `
+<section aria-labelledby="failures-heading">
+  <h2 id="failures-heading">failures</h2>
+  <ol class="failures" aria-label="Failed actions">
+    ${items}
+  </ol>
+</section>`;
+}
+interface FailureRecord {
+  storyFile: string;
+  actionName: string;
+  message: string;
+  tracePath?: string;
+}
+function collectFailures(result: RunResult): FailureRecord[] {
+  const out: FailureRecord[] = [];
+  for (const story of result.stories) {
+    for (const action of story.actions) {
+      if (action.status === 'failed') {
+        out.push({
+          storyFile: story.file,
+          actionName: action.action,
+          message: action.failureMessage ?? 'unknown error',
+          tracePath: story.tracePath,
+        });
+      }
+    }
+  }
+  return out;
+}
+function statusBadge(status: ActionStatus): string {
+  return `<span class="status" data-status="${status}">
+    <span class="status-letter" aria-hidden="true">${STATUS_LETTERS[status]}</span><span class="sr-only">${STATUS_LABELS[status]}</span><span class="status-label" aria-hidden="true">${STATUS_LABELS[status]}</span>
+  </span>`;
+}
+function storyBadge(status: ActionStatus): string {
+  return statusBadge(status);
+}
+function toReportRelative(reportDir: string, absolute: string): string {
+  return relative(reportDir, absolute);
+}
+function formatDate(iso: string): string {
+  const date = new Date(iso);
+  return date.toISOString().replace('T', ' ').slice(0, 19);
+}
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+function escapeAttribute(value: string): string {
+  return escapeHtml(value);
+}

package/src/reporter/writeReport.ts ADDED Viewed

@@ -0,0 +1,37 @@
+import { copyFile, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { RunResult } from '../schema/result.ts';
+import { renderReport } from './template.ts';
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const ASSETS_SOURCE_DIR = join(moduleDir, 'assets');
+/**
+ * Writes the HTML report, the static CSS/JS assets, and the raw `results.json`
+ * to the configured report directory. The JSON file is what `tuffgal approve`
+ * reads to locate actuals that should be promoted to baselines.
+ */
+export async function writeReport(
+  reportDir: string,
+  result: RunResult,
+): Promise<string> {
+  await mkdir(join(reportDir, 'assets'), { recursive: true });
+  const html = renderReport(result, reportDir);
+  const htmlPath = join(reportDir, 'index.html');
+  await writeFile(htmlPath, html, 'utf8');
+  await writeFile(
+    join(reportDir, 'results.json'),
+    JSON.stringify(result, null, 2),
+    'utf8',
+  );
+  await copyFile(
+    join(ASSETS_SOURCE_DIR, 'report.css'),
+    join(reportDir, 'assets', 'report.css'),
+  );
+  await copyFile(
+    join(ASSETS_SOURCE_DIR, 'report.js'),
+    join(reportDir, 'assets', 'report.js'),
+  );
+  return htmlPath;
+}

package/src/runner/approve.ts ADDED Viewed

@@ -0,0 +1,65 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { ResolvedConfig } from '../config.ts';
+import { copyToBaseline } from '../screenshots/baselineStore.ts';
+import type { ActionResult, RunResult } from '../schema/result.ts';
+export interface ApproveOptions {
+  storyFilter?: string;
+}
+export interface ApproveSummary {
+  approved: number;
+  skipped: number;
+}
+/**
+ * Reads `<report>/results.json` from the previous run and promotes every
+ * `changed` or `new` action's actual screenshot to its baseline. Optional
+ * `storyFilter` limits the approval to one story file.
+ */
+export async function approveAll(
+  config: ResolvedConfig,
+  options: ApproveOptions,
+): Promise<ApproveSummary> {
+  const resultsPath = join(config.paths.report, 'results.json');
+  const raw = await readFile(resultsPath, 'utf8').catch(() => {
+    throw new Error(
+      `No prior run found at ${resultsPath}. Run \`tuffgal run\` first.`,
+    );
+  });
+  const result = JSON.parse(raw) as RunResult;
+  let approved = 0;
+  let skipped = 0;
+  for (const story of result.stories) {
+    if (
+      options.storyFilter &&
+      story.file !== options.storyFilter &&
+      story.file !== `${options.storyFilter}.json`
+    ) {
+      continue;
+    }
+    for (const action of story.actions) {
+      if (!isApprovable(action)) {
+        skipped += 1;
+        continue;
+      }
+      await copyToBaseline(action.actualPath, action.baselinePath);
+      approved += 1;
+      process.stdout.write(`  approved ${action.action}\n`);
+    }
+  }
+  return { approved, skipped };
+}
+type ApprovableAction = ActionResult & {
+  actualPath: string;
+  baselinePath: string;
+};
+function isApprovable(action: ActionResult): action is ApprovableAction {
+  if (action.status !== 'changed' && action.status !== 'new') {
+    return false;
+  }
+  return Boolean(action.actualPath && action.baselinePath);
+}

package/src/runner/bridges/database.ts ADDED Viewed

@@ -0,0 +1,34 @@
+import type { ResolvedConfig } from '../../config.ts';
+/**
+ * Invokes the consumer-supplied database reset. Called once at the start of
+ * a run, before any story dispatches. No-op when the consumer did not supply
+ * a `database.reset` function (e.g., a static site with no backend).
+ */
+export async function resetDatabase(config: ResolvedConfig): Promise<void> {
+  const reset = config.database?.reset;
+  if (!reset) {
+    return;
+  }
+  await reset();
+}
+/**
+ * Looks up and invokes a named fixture. Called once per story per fixture
+ * declaration, before the browser launches. Throws with a discoverable
+ * error when the consumer's config does not register the named fixture so
+ * a typo in a story file fails loudly.
+ */
+export async function applyFixture(
+  config: ResolvedConfig,
+  name: string,
+): Promise<void> {
+  const fixtures = config.database?.fixtures;
+  if (!fixtures || !fixtures[name]) {
+    const known = fixtures ? Object.keys(fixtures).join(', ') : '(none)';
+    throw new Error(
+      `Unknown fixture: "${name}". Known fixtures in tuffgal.config.ts: ${known}`,
+    );
+  }
+  await fixtures[name]();
+}

package/src/runner/bridges/devServers.ts ADDED Viewed

@@ -0,0 +1,174 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { join, resolve } from 'node:path';
+import type { ResolvedConfig } from '../../config.ts';
+const DEFAULT_READY_TIMEOUT_MS = 60_000;
+const DEFAULT_SHUTDOWN_GRACE_MS = 5_000;
+export interface ManagedDevServers {
+  stop(): Promise<void>;
+}
+/**
+ * Spawns the consumer-declared `devServers.command` in a new process group,
+ * tees its combined output to `<report>/dev-servers.log`, and waits until
+ * every declared health-check URL accepts a TCP connection on its port.
+ * Returns a handle whose `stop()` method tears the whole tree down with
+ * the configured signal (default SIGTERM) followed by SIGKILL after the
+ * grace window.
+ *
+ * Used by the CLI's `--manage-servers` flag.
+ */
+export async function startManagedDevServers(
+  config: ResolvedConfig,
+): Promise<ManagedDevServers> {
+  if (!config.devServers) {
+    throw new Error(
+      '--manage-servers passed but tuffgal.config.ts has no `devServers` block. ' +
+        'Either remove the flag or declare `devServers: { command, healthCheck: [...] }`.',
+    );
+  }
+  const logsDirectory = config.paths.report;
+  mkdirSync(logsDirectory, { recursive: true });
+  const logPath = join(logsDirectory, 'dev-servers.log');
+  const logStream = createWriteStream(logPath, { flags: 'w' });
+  process.stdout.write(`Spawning dev servers (output → ${logPath})…\n`);
+  const cwd = config.devServers.cwd
+    ? resolve(config.rootDir, config.devServers.cwd)
+    : config.rootDir;
+  const child = spawn('sh', ['-c', config.devServers.command], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    detached: true,
+  });
+  if (child.stdout) child.stdout.pipe(logStream);
+  if (child.stderr) child.stderr.pipe(logStream);
+  let earlyExit: Error | undefined;
+  child.once('exit', (code, signal) => {
+    if (code !== null && code !== 0) {
+      earlyExit = new Error(
+        `Dev server command exited early with code ${code}${
+          signal ? ` (${signal})` : ''
+        }`,
+      );
+    }
+  });
+  try {
+    await Promise.all(
+      config.devServers.healthCheck.map((check) =>
+        waitForUrl(
+          check.url,
+          check.timeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+          () => earlyExit,
+        ),
+      ),
+    );
+  } catch (error) {
+    await stopChild(child, config);
+    logStream.end();
+    if (earlyExit) throw earlyExit;
+    throw error;
+  }
+  return {
+    async stop(): Promise<void> {
+      await stopChild(child, config);
+      logStream.end();
+    },
+  };
+}
+async function stopChild(
+  child: ChildProcess,
+  config: ResolvedConfig,
+): Promise<void> {
+  if (!child.pid || child.exitCode !== null) {
+    return;
+  }
+  const pid = child.pid;
+  const signal = config.devServers?.shutdownSignal ?? 'SIGTERM';
+  const graceMs = config.devServers?.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS;
+  process.stdout.write('Stopping dev servers…\n');
+  await new Promise<void>((resolveOuter) => {
+    let killed = false;
+    const finish = (): void => {
+      if (killed) return;
+      killed = true;
+      resolveOuter();
+    };
+    child.once('exit', finish);
+    try {
+      // Negative pid targets the entire process group created by detached: true.
+      process.kill(-pid, signal);
+    } catch {
+      // The group might already be gone; treat as resolved.
+      finish();
+      return;
+    }
+    setTimeout(() => {
+      if (child.exitCode === null) {
+        try {
+          process.kill(-pid, 'SIGKILL');
+        } catch {
+          // Already exited or unreachable; finishing is fine either way.
+        }
+      }
+    }, graceMs);
+  });
+}
+async function waitForUrl(
+  url: string,
+  timeoutMs: number,
+  getEarlyExit: () => Error | undefined,
+): Promise<void> {
+  const parsed = new URL(url);
+  const port = parsed.port
+    ? Number(parsed.port)
+    : parsed.protocol === 'https:'
+      ? 443
+      : 80;
+  const host = parsed.hostname;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const earlyExit = getEarlyExit();
+    if (earlyExit) {
+      throw earlyExit;
+    }
+    const open = await probePort(host, port);
+    if (open) {
+      return;
+    }
+    await sleep(500);
+  }
+  throw new Error(
+    `Health-check URL ${url} (TCP ${host}:${port}) did not respond within ${timeoutMs}ms`,
+  );
+}
+function probePort(host: string, port: number): Promise<boolean> {
+  return new Promise((resolveProbe) => {
+    const socket = createConnection({ port, host });
+    const cleanup = (result: boolean): void => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolveProbe(result);
+    };
+    socket.once('connect', () => cleanup(true));
+    socket.once('error', () => cleanup(false));
+    socket.once('timeout', () => cleanup(false));
+    socket.setTimeout(1_500);
+  });
+}
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolveSleep) => {
+    setTimeout(resolveSleep, ms);
+  });
+}