astro-better-declarative-screenshots 0.1.0

package/src/highlight.mjs

@@ -0,0 +1,133 @@
+// injects visual highlights into a Playwright page before taking a screenshot.
+// supports 'border' (colored outline), 'arrow' (pointer from outside), and 'both'.
+
+/**
+ * @typedef {Object} HighlightSpec
+ * @property {string} selector
+ * @property {'border'|'arrow'|'both'} style
+ * @property {string} color
+ * @property {string} label
+ * @property {number} borderWidth
+ */
+
+/**
+ * Inject highlight overlays into the page.
+ * Returns a cleanup function that removes injected elements.
+ *
+ * @param {import('playwright').Page} page
+ * @param {HighlightSpec[]} highlights
+ * @returns {Promise<() => Promise<void>>} cleanup fn
+ */
+export async function injectHighlights(page, highlights) {
+  if (!highlights.length) return async () => {};
+
+  const ids = await page.evaluate((specs) => {
+    const injectedIds = [];
+
+    for (const spec of specs) {
+      const target = document.querySelector(spec.selector);
+      if (!target) {
+        console.warn(`[screenshot] selector not found: ${spec.selector}`);
+        continue;
+      }
+
+      const rect = target.getBoundingClientRect();
+      const scrollX = window.scrollX;
+      const scrollY = window.scrollY;
+
+      const top    = rect.top    + scrollY;
+      const left   = rect.left   + scrollX;
+      const width  = rect.width;
+      const height = rect.height;
+
+      const id = `__screenshot_hl_${Math.random().toString(36).slice(2)}`;
+      injectedIds.push(id);
+
+      if (spec.style === 'border' || spec.style === 'both') {
+        const border = document.createElement('div');
+        border.id = id + '_border';
+        injectedIds.push(id + '_border');
+        Object.assign(border.style, {
+          position:      'absolute',
+          top:           `${top - spec.borderWidth}px`,
+          left:          `${left - spec.borderWidth}px`,
+          width:         `${width  + spec.borderWidth * 2}px`,
+          height:        `${height + spec.borderWidth * 2}px`,
+          border:        `${spec.borderWidth}px solid ${spec.color}`,
+          borderRadius:  '3px',
+          pointerEvents: 'none',
+          zIndex:        '99999',
+          boxSizing:     'border-box',
+        });
+        document.documentElement.appendChild(border);
+      }
+
+      if (spec.style === 'arrow' || spec.style === 'both') {
+        const arrowSize = 28;
+        const arrowX = left - arrowSize - 6;
+        const arrowY = top + height / 2 - arrowSize / 2;
+
+        const arrow = document.createElement('div');
+        arrow.id = id + '_arrow';
+        injectedIds.push(id + '_arrow');
+        // right-pointing triangle via SVG
+        arrow.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" width="${arrowSize}" height="${arrowSize}" viewBox="0 0 24 24">
+          <polygon points="4,4 20,12 4,20" fill="${spec.color}"/>
+        </svg>`;
+        Object.assign(arrow.style, {
+          position:      'absolute',
+          top:           `${arrowY}px`,
+          left:          `${arrowX}px`,
+          pointerEvents: 'none',
+          zIndex:        '99999',
+        });
+        document.documentElement.appendChild(arrow);
+      }
+
+      if (spec.label) {
+        const label = document.createElement('div');
+        label.id = id + '_label';
+        injectedIds.push(id + '_label');
+        label.textContent = spec.label;
+        Object.assign(label.style, {
+          position:   'absolute',
+          top:        `${top - 24}px`,
+          left:       `${left}px`,
+          background: spec.color,
+          color:      '#fff',
+          fontSize:   '12px',
+          fontFamily: 'sans-serif',
+          padding:    '2px 6px',
+          borderRadius: '3px',
+          pointerEvents: 'none',
+          zIndex:     '99999',
+          whiteSpace: 'nowrap',
+        });
+        document.documentElement.appendChild(label);
+      }
+    }
+
+    return injectedIds;
+  }, highlights);
+
+  return async () => {
+    await page.evaluate((injectedIds) => {
+      for (const id of injectedIds) {
+        const el = document.getElementById(id);
+        if (el) el.remove();
+      }
+    }, ids);
+  };
+}
+
+/**
+ * Scroll an element into view before screenshotting.
+ * @param {import('playwright').Page} page
+ * @param {string} selector
+ */
+export async function scrollIntoView(page, selector) {
+  await page.evaluate((sel) => {
+    const el = document.querySelector(sel);
+    if (el) el.scrollIntoView({ block: 'center' });
+  }, selector);
+}

package/src/naming.mjs

@@ -0,0 +1,78 @@
+// derives a filename from a URL path + an optional list of highlight selectors.
+// the goal: human-readable, filesystem-safe, collision-resistant.
+//
+// /admin/group/add + selector #id  => admin-group-add-id.png
+// /admin/group     + no selector   => admin-group.png
+// /admin/group     + two calls     => admin-group.png, admin-group-1.png
+
+/**
+ * @param {string} url - the URL path, e.g. '/admin/group/add' or 'http://...'
+ * @param {Array<{selector?: string}>} highlights - highlight configs
+ * @param {Set<string>} used - filenames already claimed this run (mutated by this function)
+ * @returns {string} filename without extension
+ */
+export function deriveName(url, highlights = [], used = new Set()) {
+  const pathname = extractPath(url);
+  const parts = slugifyPath(pathname);
+
+  const selectorParts = highlights
+    .map(h => h.selector)
+    .filter(Boolean)
+    .flatMap(sel => slugifySelector(sel))
+    .filter(Boolean);
+
+  const base = [...parts, ...selectorParts].filter(Boolean).join('-') || 'screenshot';
+
+  // resolve collisions by appending -1, -2, ...
+  let candidate = base;
+  let counter = 0;
+  while (used.has(candidate)) {
+    counter++;
+    candidate = `${base}-${counter}`;
+  }
+
+  used.add(candidate);
+  return candidate;
+}
+
+function extractPath(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    // not a full URL, treat as path
+    return url.split('?')[0].split('#')[0];
+  }
+}
+
+function slugifyPath(pathname) {
+  return pathname
+    .split('/')
+    .map(segment => segment.trim())
+    .filter(Boolean)
+    .map(segment =>
+      segment
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+    )
+    .filter(Boolean);
+}
+
+function slugifySelector(selector) {
+  // turn '.group-name' => ['group-name']
+  // turn '#id'         => ['id']
+  // turn 'input[type="text"]' => ['input-type-text']
+  // turn '.foo .bar'  => ['foo', 'bar']
+  return selector
+    .split(/\s+/)
+    .map(part =>
+      part
+        .replace(/^[.#]/, '')
+        .replace(/[\[\]"'=]/g, '-')
+        .replace(/[^a-z0-9-]+/gi, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase()
+    )
+    .filter(Boolean);
+}

package/src/placeholder.mjs

@@ -0,0 +1,53 @@
+// generates a placeholder PNG for a screenshot that has not yet been taken.
+// the placeholder is gray with white centered text showing the filename.
+// sharp is used so the placeholder is a real PNG, not a data URI.
+
+import sharp from 'sharp';
+
+/**
+ * @param {object} opts
+ * @param {string} opts.name - screenshot name (without extension), shown as label
+ * @param {number} [opts.width=1280]
+ * @param {number} [opts.height=800]
+ * @returns {Promise<Buffer>} PNG buffer
+ */
+export async function generatePlaceholder({ name, width = 1280, height = 800 }) {
+  const label = name + '.png';
+  const fontSize = Math.min(20, Math.floor(width / 40));
+
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+    <rect width="${width}" height="${height}" fill="#e8e8e8"/>
+    <line x1="0" y1="0" x2="${width}" y2="${height}" stroke="#ccc" stroke-width="1"/>
+    <line x1="${width}" y1="0" x2="0" y2="${height}" stroke="#ccc" stroke-width="1"/>
+    <rect x="${width / 2 - 200}" y="${height / 2 - 40}" width="400" height="80" rx="8" fill="white" opacity="0.8"/>
+    <text
+      x="${width / 2}"
+      y="${height / 2 - 6}"
+      text-anchor="middle"
+      dominant-baseline="middle"
+      font-family="sans-serif"
+      font-size="${fontSize}"
+      fill="#666"
+    >Screenshot not generated</text>
+    <text
+      x="${width / 2}"
+      y="${height / 2 + fontSize + 4}"
+      text-anchor="middle"
+      dominant-baseline="middle"
+      font-family="monospace"
+      font-size="${Math.max(10, fontSize - 4)}"
+      fill="#999"
+    >${escapeXml(label)}</text>
+  </svg>`;
+
+  return sharp(Buffer.from(svg)).png().toBuffer();
+}
+
+function escapeXml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}

package/tests/chrome.test.mjs

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { addChrome } from '../src/chrome.mjs';
+import sharp from 'sharp';
+
+// create a minimal 100x80 solid-color PNG to use as the page content
+async function makeTestImage(width = 100, height = 80) {
+  return sharp({
+    create: { width, height, channels: 3, background: { r: 200, g: 220, b: 240 } },
+  }).png().toBuffer();
+}
+
+describe('addChrome', () => {
+  it('returns a Buffer', async () => {
+    const page = await makeTestImage();
+    const result = await addChrome(page);
+    expect(Buffer.isBuffer(result)).toBe(true);
+  });
+
+  it('produces a valid PNG', async () => {
+    const page = await makeTestImage();
+    const result = await addChrome(page);
+    const meta = await sharp(result).metadata();
+    expect(meta.format).toBe('png');
+  });
+
+  it('output is taller than the input (chrome was added)', async () => {
+    const page = await makeTestImage(100, 80);
+    const result = await addChrome(page, { shadowBlur: 0 });
+    const meta = await sharp(result).metadata();
+    expect(meta.height).toBeGreaterThan(80);
+  });
+
+  it('output is wider with shadow padding', async () => {
+    const page = await makeTestImage(100, 80);
+    const resultWithShadow = await addChrome(page, { shadowBlur: 20, shadowPadding: 30 });
+    const resultNoShadow = await addChrome(page, { shadowBlur: 0 });
+    const metaWithShadow = await sharp(resultWithShadow).metadata();
+    const metaNoShadow = await sharp(resultNoShadow).metadata();
+    expect(metaWithShadow.width).toBeGreaterThan(metaNoShadow.width);
+  });
+
+  it('showUrl: false produces a shorter output than showUrl: true', async () => {
+    const page = await makeTestImage(100, 80);
+    const withUrl = await addChrome(page, { shadowBlur: 0, showUrl: true });
+    const withoutUrl = await addChrome(page, { shadowBlur: 0, showUrl: false });
+    const metaWith = await sharp(withUrl).metadata();
+    const metaWithout = await sharp(withoutUrl).metadata();
+    expect(metaWith.height).toBeGreaterThan(metaWithout.height);
+  });
+
+  it('does not error with a long URL', async () => {
+    const page = await makeTestImage();
+    const longUrl = 'http://localhost:9011/' + 'a'.repeat(200);
+    await expect(addChrome(page, { url: longUrl })).resolves.toBeTruthy();
+  });
+
+  it('dark option does not throw', async () => {
+    const page = await makeTestImage();
+    await expect(addChrome(page, { dark: true })).resolves.toBeTruthy();
+  });
+});

package/tests/config.test.mjs

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { loadConfig } from '../src/config.mjs';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import path from 'path';
+import os from 'os';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = path.join(os.tmpdir(), `config-test-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function writeConfig(content) {
+  writeFileSync(path.join(tmpDir, 'screenshot.config.mjs'), content);
+}
+
+describe('loadConfig', () => {
+  it('throws when no config file exists', async () => {
+    await expect(loadConfig(tmpDir)).rejects.toThrow(/No screenshot.config.mjs/);
+  });
+
+  it('loads a minimal valid config (no docker)', async () => {
+    writeConfig(`
+export default {
+  baseUrl: 'http://localhost:9011',
+};
+`);
+    const config = await loadConfig(tmpDir);
+    expect(config.baseUrl).toBe('http://localhost:9011');
+    expect(config.docker).toBeUndefined();
+    // defaults applied
+    expect(config.browser).toBe('webkit');
+    expect(config.outputDir).toBe('./src/assets/screenshots');
+    expect(config.colorScheme).toBe('light');
+  });
+
+  it('loads a config with docker settings', async () => {
+    writeConfig(`
+export default {
+  baseUrl: 'http://localhost:9011',
+  docker: {
+    healthcheck: { url: 'http://localhost:9011/api/status' },
+  },
+};
+`);
+    const config = await loadConfig(tmpDir);
+    expect(config.docker.healthcheck.url).toBe('http://localhost:9011/api/status');
+  });
+
+  it('applies window defaults', async () => {
+    writeConfig(`export default { baseUrl: 'http://localhost:9011' };`);
+    const config = await loadConfig(tmpDir);
+    expect(config.window.width).toBe(1280);
+    expect(config.window.height).toBe(800);
+  });
+
+  it('applies chrome defaults', async () => {
+    writeConfig(`export default { baseUrl: 'http://localhost:9011' };`);
+    const config = await loadConfig(tmpDir);
+    expect(config.chrome.style).toBe('safari-macos');
+    expect(config.chrome.showUrl).toBe(true);
+    expect(config.chrome.shadowBlur).toBe(40);
+  });
+
+  it('accepts a custom outputDir', async () => {
+    writeConfig(`
+export default {
+  baseUrl: 'http://localhost:9011',
+  outputDir: 'public/screenshots',
+};
+`);
+    const config = await loadConfig(tmpDir);
+    expect(config.outputDir).toBe('public/screenshots');
+  });
+
+  it('rejects an invalid baseUrl', async () => {
+    writeConfig(`export default { baseUrl: 'not-a-url' };`);
+    await expect(loadConfig(tmpDir)).rejects.toThrow(/invalid/i);
+  });
+
+  it('accepts beforeScreenshot as a function', async () => {
+    writeConfig(`
+export default {
+  baseUrl: 'http://localhost:9011',
+  beforeScreenshot: async (page, spec) => {},
+};
+`);
+    const config = await loadConfig(tmpDir);
+    expect(typeof config.beforeScreenshot).toBe('function');
+  });
+});

package/tests/diff.test.mjs

@@ -0,0 +1,85 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { diffScreenshot } from '../src/diff.mjs';
+import sharp from 'sharp';
+import { writeFileSync, mkdirSync, rmSync } from 'fs';
+import path from 'path';
+import os from 'os';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = path.join(os.tmpdir(), `diff-test-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(tmpDir, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+async function makeImage(r, g, b, width = 50, height = 50) {
+  return sharp({
+    create: { width, height, channels: 3, background: { r, g, b } },
+  }).png().toBuffer();
+}
+
+describe('diffScreenshot', () => {
+  it('returns ratio=1 when reference file is missing', async () => {
+    const newBuf = await makeImage(200, 200, 200);
+    const result = await diffScreenshot('/nonexistent/path.png', newBuf);
+    expect(result.pixels).toBe(-1);
+    expect(result.ratio).toBe(1);
+  });
+
+  it('returns ratio=0 for identical images', async () => {
+    const buf = await makeImage(128, 128, 128);
+    const refPath = path.join(tmpDir, 'ref.png');
+    writeFileSync(refPath, buf);
+
+    const result = await diffScreenshot(refPath, buf);
+    expect(result.ratio).toBe(0);
+    expect(result.pixels).toBe(0);
+  });
+
+  it('detects pixel differences between different-colored images', async () => {
+    const ref = await makeImage(0, 0, 0);
+    const newer = await makeImage(255, 255, 255);
+    const refPath = path.join(tmpDir, 'ref.png');
+    writeFileSync(refPath, ref);
+
+    const result = await diffScreenshot(refPath, newer, { threshold: 0.1 });
+    expect(result.pixels).toBeGreaterThan(0);
+    expect(result.ratio).toBeGreaterThan(0);
+  });
+
+  it('returns null diffImage when writeDiff is false', async () => {
+    const ref = await makeImage(0, 0, 0);
+    const refPath = path.join(tmpDir, 'ref.png');
+    writeFileSync(refPath, ref);
+
+    const result = await diffScreenshot(refPath, ref, { writeDiff: false });
+    expect(result.diffImage).toBeNull();
+  });
+
+  it('returns a diffImage buffer when writeDiff is true and images differ', async () => {
+    const ref = await makeImage(0, 0, 0);
+    const newer = await makeImage(255, 0, 0);
+    const refPath = path.join(tmpDir, 'ref.png');
+    writeFileSync(refPath, ref);
+
+    const result = await diffScreenshot(refPath, newer, { writeDiff: true, threshold: 0.1 });
+    expect(Buffer.isBuffer(result.diffImage)).toBe(true);
+    // the diff image should be a valid PNG
+    const meta = await sharp(result.diffImage).metadata();
+    expect(meta.format).toBe('png');
+  });
+
+  it('returns ratio=1 for images of different dimensions', async () => {
+    const ref = await makeImage(0, 0, 0, 100, 100);
+    const newer = await makeImage(0, 0, 0, 200, 200);
+    const refPath = path.join(tmpDir, 'ref.png');
+    writeFileSync(refPath, ref);
+
+    const result = await diffScreenshot(refPath, newer);
+    expect(result.ratio).toBe(1);
+  });
+});

package/tests/discover.test.mjs

@@ -0,0 +1,118 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { discoverScreenshots } from '../src/discover.mjs';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import path from 'path';
+import os from 'os';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = path.join(os.tmpdir(), `discover-test-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(path.join(tmpDir, 'src/content/docs'), { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function write(filename, content) {
+  const fullPath = path.join(tmpDir, filename);
+  mkdirSync(path.dirname(fullPath), { recursive: true });
+  writeFileSync(fullPath, content);
+}
+
+describe('discoverScreenshots', () => {
+  it('finds a simple Screenshot component', async () => {
+    write('src/content/docs/groups.mdx', `
+import Screenshot from 'astro-better-declarative-screenshots/Screenshot.astro';
+
+<Screenshot url="/admin/group" />
+`);
+
+    const specs = await discoverScreenshots(tmpDir);
+    expect(specs).toHaveLength(1);
+    expect(specs[0].url).toBe('/admin/group');
+    expect(specs[0].name).toBe('admin-group');
+  });
+
+  it('finds Screenshot with Highlight children', async () => {
+    write('src/content/docs/page.mdx', `
+<Screenshot url="/admin/group">
+  <Highlight selector="#name" style="border" color="#f60" label="Name field" />
+</Screenshot>
+`);
+    const specs = await discoverScreenshots(tmpDir);
+    expect(specs).toHaveLength(1);
+    expect(specs[0].highlights).toHaveLength(1);
+    expect(specs[0].highlights[0].selector).toBe('#name');
+    expect(specs[0].highlights[0].color).toBe('#f60');
+    expect(specs[0].name).toBe('admin-group-name');
+  });
+
+  it('finds multiple Screenshot components in one file', async () => {
+    write('src/content/docs/page.mdx', `
+<Screenshot url="/admin/group" />
+<Screenshot url="/admin/user" />
+`);
+    const specs = await discoverScreenshots(tmpDir);
+    expect(specs).toHaveLength(2);
+    expect(specs[0].url).toBe('/admin/group');
+    expect(specs[1].url).toBe('/admin/user');
+  });
+
+  it('respects an explicit id prop', async () => {
+    write('src/content/docs/page.mdx', `
+<Screenshot url="/admin/group" id="my-custom-name" />
+`);
+    const specs = await discoverScreenshots(tmpDir);
+    expect(specs[0].name).toBe('my-custom-name');
+  });
+
+  it('extracts width/height/fullPage props', async () => {
+    write('src/content/docs/page.mdx', `
+<Screenshot url="/admin" width={1440} height={900} fullPage={true} />
+`);
+    const specs = await discoverScreenshots(tmpDir);
+    expect(specs[0].width).toBe(1440);
+    expect(specs[0].height).toBe(900);
+    expect(specs[0].fullPage).toBe(true);
+  });
+
+  it('handles same URL with different highlights -- no collision', async () => {
+    write('src/content/docs/page.mdx', `
+<Screenshot url="/admin/group">
+  <Highlight selector="#name" />
+</Screenshot>
+<Screenshot url="/admin/group">
+  <Highlight selector="#id" />
+</Screenshot>
+`);
+    const specs = await discoverScreenshots(tmpDir);
+    expect(specs).toHaveLength(2);
+    expect(specs[0].name).toBe('admin-group-name');
+    expect(specs[1].name).toBe('admin-group-id');
+  });
+
+  it('resolves same URL + same highlights collision with numeric suffix', async () => {
+    write('src/content/docs/page.mdx', `
+<Screenshot url="/admin/group" />
+<Screenshot url="/admin/group" />
+`);
+    const specs = await discoverScreenshots(tmpDir);
+    expect(specs[0].name).toBe('admin-group');
+    expect(specs[1].name).toBe('admin-group-1');
+  });
+
+  it('returns empty array when no Screenshot components found', async () => {
+    write('src/content/docs/page.mdx', 'Just some markdown content.\n');
+    const specs = await discoverScreenshots(tmpDir);
+    expect(specs).toHaveLength(0);
+  });
+
+  it('records the source file path', async () => {
+    const filePath = 'src/content/docs/groups.mdx';
+    write(filePath, '<Screenshot url="/admin" />');
+    const specs = await discoverScreenshots(tmpDir);
+    expect(specs[0].sourceFile).toBe(path.join(tmpDir, filePath));
+  });
+});