npm - @ozsarman/clarityjs - Versions diffs - 0.6.0 - Mend

@ozsarman/clarityjs 0.6.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/src/clarity-test.js ADDED Viewed

@@ -0,0 +1,622 @@
+/**
+ * Clarity.js Test Utilities
+ *
+ * Lightweight helpers for unit-testing Clarity components with jsdom.
+ *
+ * Peer dependency: jsdom (npm install --save-dev jsdom)
+ *
+ * Usage (Node + jsdom):
+ *   import { setupDOM, render, query, queryAll, fireEvent, act, cleanup } from '@ozsarman/clarityjs/test'
+ *
+ *   // Bootstrap once per test file (or in a beforeAll hook):
+ *   setupDOM()
+ *
+ *   test('Counter increments', async () => {
+ *     const { container } = render(Counter)
+ *     const btn = query(container, 'button')
+ *     await act(() => fireEvent(btn, 'click'))
+ *     assert.equal(query(container, 'h1').textContent, '1')
+ *   })
+ *
+ *   afterEach(cleanup)   // unmount all rendered components
+ *
+ * Usage (browser / Vitest with happy-dom):
+ *   No setup needed — document / window already exist.
+ *   Just import and call render(), query(), etc.
+ *
+ * Author: Claude (Anthropic)
+ */
+// ─── Environment bootstrap ────────────────────────────────────────────────────
+let _dom = null; // jsdom JSDOM instance (Node only)
+/**
+ * Install a jsdom window/document into the global scope.
+ * Call once at the top of a test file when running in Node.js.
+ *
+ * @param {string} html  Optional initial HTML (default: <body></body>)
+ * @param {object} opts  Additional JSDOM options (url, resources, …)
+ */
+export async function setupDOM(html = '<!DOCTYPE html><html><body></body></html>', opts = {}) {
+  // No-op in browser environments
+  if (typeof window !== 'undefined' && typeof window.document !== 'undefined') return;
+  try {
+    const { JSDOM } = await import('jsdom');
+    _dom = new JSDOM(html, {
+      url:              opts.url ?? 'http://localhost/',
+      pretendToBeVisual: opts.pretendToBeVisual ?? true,
+      ...opts,
+    });
+    // Inject into global scope so clarity-runtime.js works
+    const { window: win } = _dom;
+    global.window    = win;
+    global.document  = win.document;
+    global.navigator = win.navigator;
+    global.Node      = win.Node;
+    global.Element   = win.Element;
+    global.HTMLElement = win.HTMLElement;
+    global.DocumentFragment = win.DocumentFragment;
+    global.MutationObserver = win.MutationObserver;
+    global.requestAnimationFrame = (fn) => setTimeout(fn, 16);
+    global.queueMicrotask = global.queueMicrotask ?? ((fn) => Promise.resolve().then(fn));
+  } catch (err) {
+    throw new Error(
+      '[Clarity Test] jsdom not found.\n' +
+      'Run: npm install --save-dev jsdom\n' +
+      'Original error: ' + err.message
+    );
+  }
+}
+// ─── Render registry (for cleanup) ───────────────────────────────────────────
+const _rendered = [];
+/**
+ * Render a Clarity component into a detached container element.
+ *
+ * @param {function} ComponentFn  The component function (exported from .clarity)
+ * @param {object}   props        Props to pass (default: {})
+ * @param {object}   options      { container } — use an existing element
+ * @returns {{ container, element, unmount }}
+ */
+export function render(ComponentFn, props = {}, options = {}) {
+  const container = options.container ?? document.createElement('div');
+  // Append to body so effects that query the document work
+  document.body.appendChild(container);
+  const el = ComponentFn(props);
+  if (!(el instanceof Node)) {
+    throw new Error(
+      `[Clarity Test] render: ${ComponentFn.name || 'component'} did not return a DOM Node.\n` +
+      `Got: ${typeof el}`
+    );
+  }
+  container.appendChild(el);
+  // Call onMount lifecycle hook
+  if (typeof el.__clarity_mount__ === 'function') {
+    el.__clarity_mount__();
+  }
+  const unmount = () => {
+    if (typeof el.__clarity_cleanup__ === 'function') {
+      el.__clarity_cleanup__();
+    }
+    container.innerHTML = '';
+    container.parentNode?.removeChild(container);
+  };
+  _rendered.push(unmount);
+  return { container, element: el, unmount };
+}
+/**
+ * Unmount all components rendered since the last cleanup().
+ * Call in afterEach to prevent test pollution.
+ */
+export function cleanup() {
+  _rendered.splice(0).forEach(fn => {
+    try { fn(); } catch (_) { /* ignore cleanup errors */ }
+  });
+}
+// ─── DOM helpers ──────────────────────────────────────────────────────────────
+/**
+ * Query a single element inside a container.
+ *
+ * @param {Element} container
+ * @param {string}  selector  CSS selector
+ * @returns {Element|null}
+ */
+export function query(container, selector) {
+  return container.querySelector(selector);
+}
+/**
+ * Query all elements matching a selector inside a container.
+ *
+ * @param {Element} container
+ * @param {string}  selector
+ * @returns {Element[]}
+ */
+export function queryAll(container, selector) {
+  return [...container.querySelectorAll(selector)];
+}
+/**
+ * Find an element by its text content (exact or partial match).
+ *
+ * @param {Element} container
+ * @param {string}  text
+ * @param {string}  selector  Optional tag/selector filter (default: '*')
+ * @returns {Element|null}
+ */
+export function queryByText(container, text, selector = '*') {
+  const els = [...container.querySelectorAll(selector)];
+  return els.find(el => el.textContent.includes(text)) ?? null;
+}
+// ─── Event helpers ────────────────────────────────────────────────────────────
+/**
+ * Fire a DOM event on an element.
+ *
+ * @param {Element} element
+ * @param {string}  type   Event type ('click', 'input', 'submit', …)
+ * @param {object}  init   EventInit options (bubbles, cancelable, detail, …)
+ */
+export function fireEvent(element, type, init = {}) {
+  const event = new Event(type, { bubbles: true, cancelable: true, ...init });
+  element.dispatchEvent(event);
+}
+/**
+ * Convenience: fire a click on an element.
+ */
+export function click(element) {
+  fireEvent(element, 'click');
+}
+/**
+ * Convenience: fire an input event and update the element's value.
+ * Simulates typing into <input> or <textarea>.
+ *
+ * @param {HTMLInputElement} element
+ * @param {string}           value
+ */
+export function type(element, value) {
+  element.value = value;
+  fireEvent(element, 'input');
+  fireEvent(element, 'change');
+}
+/**
+ * Fire a keyboard event on an element.
+ *
+ * @param {Element} element
+ * @param {string}  type   'keydown' | 'keyup' | 'keypress'
+ * @param {string}  key    Key name ('Enter', 'Escape', 'a', …)
+ * @param {object}  init   Additional KeyboardEventInit options
+ */
+export function keyEvent(element, type, key, init = {}) {
+  const event = new KeyboardEvent(type, { key, bubbles: true, cancelable: true, ...init });
+  element.dispatchEvent(event);
+}
+// ─── Act (flush async updates) ────────────────────────────────────────────────
+/**
+ * Run a function and flush all pending microtasks / queueMicrotask callbacks.
+ *
+ * Clarity uses queueMicrotask() for <when>, <list>, and <Route> effects.
+ * After a state change + fireEvent, call await act() so those deferred
+ * updates run before your assertions.
+ *
+ * @param {function} fn  Optional synchronous action to run first
+ * @returns {Promise<void>}
+ */
+export async function act(fn) {
+  if (typeof fn === 'function') fn();
+  // Flush microtasks
+  await new Promise(resolve => setTimeout(resolve, 0));
+}
+/**
+ * Wait until a condition becomes true, polling every `interval` ms.
+ *
+ * Useful for lazy() components that load asynchronously.
+ *
+ * @param {function}  condition  () => boolean
+ * @param {number}    timeout    Max wait in ms (default: 2000)
+ * @param {number}    interval   Poll interval in ms (default: 50)
+ * @returns {Promise<void>}
+ */
+export function waitFor(condition, timeout = 2000, interval = 50) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const poll  = () => {
+      if (condition()) {
+        resolve();
+      } else if (Date.now() - start >= timeout) {
+        reject(new Error(`[Clarity Test] waitFor timed out after ${timeout}ms`));
+      } else {
+        setTimeout(poll, interval);
+      }
+    };
+    poll();
+  });
+}
+// ─── Snapshot helpers ─────────────────────────────────────────────────────────
+/**
+ * Serialize an element's inner HTML with normalized whitespace.
+ * Useful for snapshot-style assertions.
+ *
+ * @param {Element} element
+ * @returns {string}
+ */
+export function toHTML(element) {
+  return element.innerHTML.replace(/\s+/g, ' ').trim();
+}
+/**
+ * Get an element's text content with normalized whitespace.
+ *
+ * @param {Element} element
+ * @returns {string}
+ */
+export function getText(element) {
+  return (element.textContent ?? '').replace(/\s+/g, ' ').trim();
+}
+// ─── Signal testing helpers ───────────────────────────────────────────────────
+/**
+ * Spy on a signal: returns an array that records every .set() call.
+ *
+ * @param {{ get(): any, set(v: any): void }}  sig   A Clarity signal
+ * @returns {{ values: any[], restore: function }}
+ */
+export function spySignal(sig) {
+  const values  = [];
+  const origSet = sig.set.bind(sig);
+  sig.set = (v) => {
+    values.push(v);
+    origSet(v);
+  };
+  return {
+    values,
+    restore() { sig.set = origSet; },
+  };
+}
+// ─── Snapshot system ──────────────────────────────────────────────────────────
+//
+// Snapshots are stored in .clarity-snapshots/<basename>.snap files next to
+// the test file.  Each snapshot is a named HTML string.
+//
+// Usage:
+//   const { container } = render(MyComponent);
+//   toMatchSnapshot(container, 'MyComponent default state');
+//
+// To update snapshots, set the environment variable:
+//   CLARITY_UPDATE_SNAPSHOTS=1  (or pass { update: true } as option)
+const _UPDATE_SNAPSHOTS = typeof process !== 'undefined'
+  ? (process.env.CLARITY_UPDATE_SNAPSHOTS === '1' || process.argv.includes('--update-snapshots'))
+  : false;
+/** In-memory snapshot store: Map<snapshotFile, Map<name, html>> */
+const _snapStore = new Map();
+/** Tracks which snapshots were used in this run */
+const _snapUsed  = new Set();
+/** Tracks new/updated snapshots to write back */
+const _snapDirty = new Set();
+function _snapFilePath(testFile) {
+  if (!testFile) return null;
+  const { dirname: dirn, basename: basen } = _nodePath();
+  const dir  = dirn(testFile);
+  const base = basen(testFile).replace(/\.(test|spec)\.(js|ts|mjs|cjs)$/, '') || basen(testFile);
+  return _nodeJoin(dir, '.clarity-snapshots', `${base}.snap`);
+}
+function _nodePath() {
+  // Lazy import — not available in browser
+  try { return require('node:path'); } catch { return { dirname: p => p.split('/').slice(0,-1).join('/'), basename: p => p.split('/').pop() }; }
+}
+function _nodeJoin(...parts) {
+  try { return require('node:path').join(...parts); } catch { return parts.join('/'); }
+}
+function _loadSnapFile(snapFile) {
+  if (!snapFile || _snapStore.has(snapFile)) return;
+  const map = new Map();
+  _snapStore.set(snapFile, map);
+  try {
+    const { readFileSync } = require('node:fs');
+    const raw = readFileSync(snapFile, 'utf8');
+    // Format: each snapshot is "// Snapshot: <name>\n<html>\n---\n"
+    const blocks = raw.split(/^---$/m);
+    for (const block of blocks) {
+      const m = block.match(/^\/\/ Snapshot: (.+)\n([\s\S]*)$/m);
+      if (m) map.set(m[1].trim(), m[2].trim());
+    }
+  } catch { /* file doesn't exist yet — will be created */ }
+}
+function _saveSnapFile(snapFile) {
+  if (!snapFile) return;
+  const map = _snapStore.get(snapFile);
+  if (!map) return;
+  let out = '';
+  for (const [name, html] of map) {
+    out += `// Snapshot: ${name}\n${html}\n---\n`;
+  }
+  try {
+    const { mkdirSync, writeFileSync } = require('node:fs');
+    const { dirname: dirn } = require('node:path');
+    mkdirSync(dirn(snapFile), { recursive: true });
+    writeFileSync(snapFile, out, 'utf8');
+  } catch (e) {
+    console.warn(`[Clarity Test] Could not write snapshot file: ${snapFile}\n${e.message}`);
+  }
+}
+/**
+ * Assert that an element's outer/inner HTML matches a stored snapshot.
+ * On first run (no snapshot exists), creates the snapshot.
+ * On mismatch, throws a descriptive error.
+ *
+ * @param {Element} element    - DOM element to snapshot
+ * @param {string}  name       - Unique snapshot name within this test file
+ * @param {object}  [opts]
+ * @param {boolean} [opts.update=false]  - Force update this snapshot
+ * @param {string}  [opts.testFile]      - Absolute path to the test file (auto-detected when possible)
+ * @param {boolean} [opts.outer=false]   - Use outerHTML instead of innerHTML
+ */
+export function toMatchSnapshot(element, name, opts = {}) {
+  const update  = opts.update ?? _UPDATE_SNAPSHOTS;
+  const outer   = opts.outer  ?? false;
+  const testFile = opts.testFile ?? _detectTestFile();
+  const snapFile = _snapFilePath(testFile);
+  _loadSnapFile(snapFile);
+  const html = _normalizeHTML(outer ? element.outerHTML : element.innerHTML);
+  const key  = `${snapFile ?? 'anonymous'}::${name}`;
+  _snapUsed.add(key);
+  const map      = snapFile ? _snapStore.get(snapFile) : null;
+  const existing = map?.get(name);
+  if (existing === undefined || update) {
+    // First run or update — store the snapshot
+    if (map) {
+      map.set(name, html);
+      _snapDirty.add(snapFile);
+      _saveSnapFile(snapFile);
+    }
+    if (update && existing !== undefined && existing !== html) {
+      console.log(`[Clarity Snapshot] Updated: "${name}"`);
+    } else if (existing === undefined) {
+      console.log(`[Clarity Snapshot] Created: "${name}"`);
+    }
+    return;
+  }
+  // Compare
+  if (html !== existing) {
+    throw new SnapshotMismatchError(name, existing, html);
+  }
+}
+class SnapshotMismatchError extends Error {
+  constructor(name, expected, received) {
+    const diff = _simpleDiff(expected, received);
+    super(
+      `[Clarity Snapshot] Mismatch: "${name}"\n\n` +
+      `Expected:\n${_indent(expected)}\n\n` +
+      `Received:\n${_indent(received)}\n\n` +
+      `Diff:\n${diff}\n\n` +
+      `Run with CLARITY_UPDATE_SNAPSHOTS=1 to accept the new snapshot.`
+    );
+    this.name = 'SnapshotMismatchError';
+  }
+}
+/**
+ * Force-update a named snapshot. Call before `toMatchSnapshot` to refresh it.
+ * Useful in a test: `updateSnapshot('my-snap'); toMatchSnapshot(el, 'my-snap');`
+ */
+export function updateSnapshot(name, testFile) {
+  const snapFile = _snapFilePath(testFile ?? _detectTestFile());
+  _loadSnapFile(snapFile);
+  const map = snapFile ? _snapStore.get(snapFile) : null;
+  if (map) map.delete(name);
+}
+/**
+ * Delete snapshots that were not used in this run (obsolete snapshots).
+ * Call in afterAll() to keep snapshot files clean.
+ */
+export function pruneSnapshots(testFile) {
+  const snapFile = _snapFilePath(testFile ?? _detectTestFile());
+  _loadSnapFile(snapFile);
+  const map = snapFile ? _snapStore.get(snapFile) : null;
+  if (!map) return;
+  let pruned = 0;
+  for (const name of map.keys()) {
+    const key = `${snapFile}::${name}`;
+    if (!_snapUsed.has(key)) {
+      map.delete(name);
+      pruned++;
+    }
+  }
+  if (pruned > 0) {
+    _saveSnapFile(snapFile);
+    console.log(`[Clarity Snapshot] Pruned ${pruned} obsolete snapshot(s)`);
+  }
+}
+function _normalizeHTML(html) {
+  return (html ?? '')
+    .replace(/\s+/g, ' ')
+    .replace(/> </g, '>\n<')
+    .trim();
+}
+function _indent(str) {
+  return str.split('\n').map(l => '  ' + l).join('\n');
+}
+function _simpleDiff(a, b) {
+  const aLines = a.split('\n');
+  const bLines = b.split('\n');
+  const lines  = [];
+  const max    = Math.max(aLines.length, bLines.length);
+  for (let i = 0; i < max; i++) {
+    if (aLines[i] === bLines[i]) {
+      lines.push(`  ${aLines[i] ?? ''}`);
+    } else {
+      if (aLines[i] !== undefined) lines.push(`- ${aLines[i]}`);
+      if (bLines[i] !== undefined) lines.push(`+ ${bLines[i]}`);
+    }
+  }
+  return lines.slice(0, 30).join('\n') + (lines.length > 30 ? '\n  …' : '');
+}
+function _detectTestFile() {
+  // Try to read the test file path from Node.js stack trace
+  try {
+    const e = new Error();
+    const stack = e.stack?.split('\n') ?? [];
+    for (const line of stack) {
+      const m = line.match(/\((.+\.(?:test|spec)\.[mc]?[jt]s):\d+:\d+\)/);
+      if (m) return m[1];
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+// ─── Component mocks ──────────────────────────────────────────────────────────
+const _componentMocks = new Map();
+/**
+ * Replace a component function with a mock implementation for testing.
+ *
+ * Usage:
+ *   const { restore } = mockComponent(Header, ({ title }) => {
+ *     const el = document.createElement('div');
+ *     el.textContent = `[MockHeader: ${title}]`;
+ *     return el;
+ *   });
+ *   // ...test...
+ *   restore();
+ *
+ * @param {function} ComponentFn  The real component function
+ * @param {function} [mockImpl]   Mock implementation (default: renders a placeholder div)
+ * @returns {{ mock: function, calls: Array, restore: function }}
+ */
+export function mockComponent(ComponentFn, mockImpl) {
+  const calls = [];
+  const originalName = ComponentFn.name ?? 'Component';
+  const mock = function MockedComponent(props) {
+    calls.push({ props });
+    if (mockImpl) return mockImpl(props);
+    // Default: render a labelled placeholder
+    const el = document.createElement('div');
+    el.setAttribute('data-clarity-mock', originalName);
+    el.textContent = `[Mock: ${originalName}]`;
+    return el;
+  };
+  Object.defineProperty(mock, 'name', { value: originalName });
+  // Store the mock for potential lookup by import path
+  _componentMocks.set(ComponentFn, { original: ComponentFn, mock, calls });
+  function restore() {
+    _componentMocks.delete(ComponentFn);
+  }
+  return { mock, calls, restore };
+}
+/**
+ * Check if a component has been mocked.
+ * Used internally by render() to swap implementations.
+ */
+export function getMockedComponent(ComponentFn) {
+  return _componentMocks.get(ComponentFn)?.mock ?? ComponentFn;
+}
+/**
+ * Clear all component mocks.
+ */
+export function clearComponentMocks() {
+  _componentMocks.clear();
+}
+// ─── Signal mocks ─────────────────────────────────────────────────────────────
+/**
+ * Create a mock signal that records all .set() calls.
+ *
+ * Mirrors the { get, set, peek, update, subscribe } interface of real signals
+ * but is entirely self-contained — no reactivity runtime required.
+ *
+ * Usage:
+ *   const [nameSig, nameHistory] = mockSignal('Alice');
+ *   nameSig.set('Bob');
+ *   assert.deepEqual(nameHistory, ['Alice', 'Bob']);  // initial + set
+ *
+ * @param {*} initialValue
+ * @returns {[signal, valuesArray]}
+ */
+export function mockSignal(initialValue) {
+  let _val = initialValue;
+  const _subs = new Set();
+  const history = [initialValue];
+  const sig = {
+    get()   { return _val; },
+    peek()  { return _val; },
+    set(v)  {
+      _val = v;
+      history.push(v);
+      for (const fn of _subs) { try { fn(v); } catch {} }
+    },
+    update(fn) { sig.set(fn(_val)); },
+    subscribe(fn) {
+      _subs.add(fn);
+      fn(_val); // call immediately like real signals
+      return () => _subs.delete(fn);
+    },
+    __isMockSignal: true,
+  };
+  return [sig, history];
+}
+// ─── Re-exports for convenience ───────────────────────────────────────────────
+// Users can write: import { render, act, click, query } from '@ozsarman/clarityjs/test'
+export default {
+  setupDOM, render, cleanup,
+  query, queryAll, queryByText,
+  fireEvent, click, type, keyEvent,
+  act, waitFor,
+  toHTML, getText,
+  spySignal,
+  toMatchSnapshot, updateSnapshot, pruneSnapshots,
+  mockComponent, getMockedComponent, clearComponentMocks,
+  mockSignal,
+};