@lullabot/playwright-testing 0.1.0

package/lib/visualdiff.js

@@ -0,0 +1,197 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VisualDiffTestCases = void 0;
+exports.defineVisualDiffConfig = defineVisualDiffConfig;
+exports.defaultTestFunction = defaultTestFunction;
+const test_1 = require("@playwright/test");
+const accessible_screenshot_js_1 = require("./accessible-screenshot.js");
+const pseudo_state_js_1 = require("./pseudo-state.js");
+function defineVisualDiffConfig(cases, preset) {
+    return new VisualDiffTestCases(cases, preset);
+}
+function defaultTestFunction(testCase, group, config, preset) {
+    return async ({ page, context }, testInfo) => {
+        const MockClass = testCase.mockClass ?? group.mockClass ?? config?.mockClass;
+        if (MockClass) {
+            const mock = new MockClass();
+            await mock.mock(page);
+        }
+        // Log any errors to the Playwright console too.
+        context.on('weberror', (webError) => console.log(webError.error()));
+        testInfo.annotations.push({
+            type: 'Description',
+            description: testCase.description,
+        });
+        const representativeUrl = testCase.representativeUrl
+            ?? group.representativeUrl
+            ?? config?.representativeUrl;
+        if (representativeUrl) {
+            testInfo.annotations.push({
+                type: 'Representative URL',
+                description: representativeUrl,
+            });
+        }
+        const path = `${config?.pathPrefix ?? ''}${group.pathPrefix ?? ''}${testCase.path}`;
+        await page.goto(path);
+        const configuredScreenshotOptions = typeof preset?.screenshotOptions === 'function'
+            ? await preset.screenshotOptions({ page, testInfo, testCase, group, config })
+            : preset?.screenshotOptions ?? {};
+        // Merge masks from all three levels: config, group, and testCase.
+        const maskSelectors = [
+            ...(config?.mask ?? []),
+            ...(group.mask ?? []),
+            ...(testCase.mask ?? []),
+        ];
+        const maskLocators = [
+            ...(configuredScreenshotOptions.mask ?? []),
+            ...maskSelectors.map(selector => page.locator(selector)),
+        ];
+        // Most-specific-wins for maskColor: testCase > group > config.
+        const maskColor = testCase.maskColor
+            ?? group.maskColor
+            ?? config?.maskColor
+            ?? configuredScreenshotOptions.maskColor;
+        const screenshotOptions = {
+            ...configuredScreenshotOptions,
+            fullPage: true,
+        };
+        if (maskLocators.length > 0) {
+            screenshotOptions.mask = maskLocators;
+        }
+        if (maskColor) {
+            screenshotOptions.maskColor = maskColor;
+        }
+        const a11yBaseline = testCase.a11yBaseline
+            ?? group.a11yBaseline
+            ?? config?.a11yBaseline
+            ?? configuredScreenshotOptions.accessibility?.baseline;
+        if (a11yBaseline || configuredScreenshotOptions.accessibility) {
+            screenshotOptions.accessibility = {
+                ...configuredScreenshotOptions.accessibility,
+                ...(a11yBaseline ? { baseline: a11yBaseline } : {}),
+            };
+        }
+        const interactionStates = [
+            ...(config?.interactionStates ?? []),
+            ...(group.interactionStates ?? []),
+            ...(testCase.interactionStates ?? []),
+        ];
+        if (interactionStates.length > 0 || configuredScreenshotOptions.interactionStates) {
+            screenshotOptions.interactionStates = [
+                ...(configuredScreenshotOptions.interactionStates ?? []),
+                ...interactionStates.map(({ selector, states }) => ({
+                    locator: page.locator(selector),
+                    states,
+                })),
+            ];
+        }
+        // Force declared pseudo-states after navigation and keep them active
+        // through both the screenshot and the accessibility scan. These synthetic
+        // states are unaffected by takeAccessibleScreenshot() clearing incidental
+        // pointer hover and DOM focus.
+        const pseudoStates = [
+            ...(config?.pseudoStates ?? []),
+            ...(group.pseudoStates ?? []),
+            ...(testCase.pseudoStates ?? []),
+        ];
+        const clearPseudoStates = [];
+        let operationFailed = false;
+        let operationError;
+        try {
+            for (const pseudoState of pseudoStates) {
+                clearPseudoStates.push(await (0, pseudo_state_js_1.forcePseudoState)(page, pseudoState.selector, pseudoState.pseudoClasses));
+            }
+            await (0, accessible_screenshot_js_1.takeAccessibleScreenshot)(page, testInfo, screenshotOptions);
+        }
+        catch (error) {
+            operationFailed = true;
+            operationError = error;
+        }
+        const cleanupErrors = [];
+        for (const clearPseudoState of clearPseudoStates.reverse()) {
+            try {
+                await clearPseudoState();
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        if (operationFailed) {
+            if (cleanupErrors.length > 0) {
+                throw new AggregateError([operationError, ...cleanupErrors], 'Visual diff capture and pseudo-state cleanup failed.');
+            }
+            throw operationError;
+        }
+        if (cleanupErrors.length === 1) {
+            throw cleanupErrors[0];
+        }
+        if (cleanupErrors.length > 1) {
+            throw new AggregateError(cleanupErrors, 'Multiple pseudo-state cleanup operations failed.');
+        }
+    };
+}
+/**
+ * Execute a set of visual diffs against groups of test cases.
+ */
+class VisualDiffTestCases {
+    /**
+     * The configuration object containing all visual diff test cases.
+     * @private
+     */
+    config;
+    preset;
+    /**
+     * Construct a new set of VisualDiffTestCases
+     *
+     * @param config The config that has been imported via "import ..."
+     */
+    constructor(config, preset) {
+        this.config = config;
+        this.preset = preset;
+    }
+    /**
+     * Describe, execute, and skip test cases
+     *
+     * @param overriddenTestFunction An optional custom test function. Note: when
+     *   using a custom test function, automatic mask, interaction-state, and
+     *   pseudo-state handling is bypassed. You must apply them yourself.
+     */
+    describe(overriddenTestFunction) {
+        // Handle skipping of test cases, either based on a simple boolean or a callback.
+        function shouldSkip(testCase) {
+            return testCase.skip !== undefined
+                && (testCase.skip.callback === undefined || testCase.skip.callback(testCase));
+        }
+        function registerSkip(testCase) {
+            const skip = testCase.skip;
+            test_1.test.skip(`${testCase.name}: ${skip.reason} <${skip.willBeFixedIn}>`, async () => { });
+        }
+        this.config.groups.forEach((group) => {
+            // Allow skipping of entire groups of tests.
+            if (shouldSkip(group)) {
+                registerSkip(group);
+                return;
+            }
+            // Actually describe the group.
+            test_1.test.describe(group.name, () => {
+                group.testCases.forEach((testCase => {
+                    // Allow skipping of individual test cases.
+                    if (shouldSkip(testCase)) {
+                        registerSkip(testCase);
+                        return;
+                    }
+                    // Define a default function for test cases.
+                    let testFunction;
+                    if (typeof overriddenTestFunction != 'function') {
+                        testFunction = defaultTestFunction(testCase, group, this.config, this.preset);
+                    }
+                    else {
+                        testFunction = overriddenTestFunction(testCase, group);
+                    }
+                    (0, test_1.test)(`${testCase.name}: ${testCase.path}`, testFunction);
+                }));
+            });
+        });
+    }
+}
+exports.VisualDiffTestCases = VisualDiffTestCases;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@lullabot/playwright-testing",
+  "version": "0.1.0",
+  "description": "Framework-neutral Playwright testing utilities",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lullabot/playwright-drupal.git",
+    "directory": "packages/playwright-testing"
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "bin/",
+    "lib/",
+    "src/",
+    "README.md"
+  ],
+  "bin": {
+    "playwright-testing-a11y-summary": "./bin/github-a11y-summary",
+    "playwright-testing-failure-summary": "./bin/github-failure-summary"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./github": {
+      "types": "./lib/github/index.d.ts",
+      "default": "./lib/github/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.8.5",
+    "@playwright/test": "^1.39.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.2.2 || ^6.0.0 || ^7.0.0",
+    "vitest": "^5.0.0"
+  }
+}

package/src/accessibility-baseline-file.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { promises as fs } from 'fs'
+import os from 'os'
+import path from 'path'
+import {
+  baselineFilePath,
+  buildSeed,
+  nextAccessibilityScanCount,
+  readBaselineFile,
+  resetAccessibilityScanCounts,
+  snapshotExists,
+  writeBaselineFile,
+} from './accessibility-baseline-file'
+
+function makeTestInfo(opts: { dir: string; title?: string; titlePath?: string[] }) {
+  const title = opts.title ?? 'standalone accessibility check works'
+  const titlePath = opts.titlePath ?? ['file.spec.ts', title]
+  return {
+    testId: `${title}-${Math.random()}`,
+    title,
+    titlePath,
+    snapshotPath: (...segs: string[]) => path.join(opts.dir, ...segs),
+  }
+}
+
+describe('accessibility-baseline-file', () => {
+  let tmpDir: string
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'a11y-baseline-'))
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  describe('baselineFilePath', () => {
+    it('builds a deterministic projectless path with counter and scan-kind suffix', () => {
+      const ti = makeTestInfo({ dir: tmpDir })
+      const wcag = baselineFilePath(ti, 'wcag', 1)
+      const bp = baselineFilePath(ti, 'best-practice', 1)
+      expect(wcag).toBe(path.join(tmpDir, 'standalone-accessibility-check-works-1.a11y-baseline.json'))
+      expect(bp).toBe(path.join(tmpDir, 'standalone-accessibility-check-works-1.a11y-baseline-best-practice.json'))
+    })
+
+    it('uses an incremented counter for multi-call tests', () => {
+      const ti = makeTestInfo({ dir: tmpDir })
+      const path2 = baselineFilePath(ti, 'wcag', 2)
+      expect(path2).toContain('-2.a11y-baseline.json')
+    })
+  })
+
+  describe('nextAccessibilityScanCount', () => {
+    it('returns sequential numbers per (testInfo, scan)', () => {
+      const ti = {} as any
+      try {
+        expect(nextAccessibilityScanCount(ti, 'wcag')).toBe(1)
+        expect(nextAccessibilityScanCount(ti, 'wcag')).toBe(2)
+        expect(nextAccessibilityScanCount(ti, 'best-practice')).toBe(1)
+        expect(nextAccessibilityScanCount(ti, 'wcag')).toBe(3)
+      } finally {
+        resetAccessibilityScanCounts(ti)
+      }
+    })
+  })
+
+  describe('snapshotExists', () => {
+    it('returns false when the snapshots dir is missing', async () => {
+      const ti = makeTestInfo({ dir: path.join(tmpDir, 'does-not-exist') })
+      expect(await snapshotExists(ti)).toBe(false)
+    })
+
+    it('returns false when no snapshot file matches the test slug', async () => {
+      await fs.writeFile(path.join(tmpDir, 'other-test-1-chromium-linux.txt'), 'data')
+      const ti = makeTestInfo({ dir: tmpDir })
+      expect(await snapshotExists(ti)).toBe(false)
+    })
+
+    it('returns true when a snapshot file matching the test slug exists', async () => {
+      await fs.writeFile(
+        path.join(tmpDir, 'standalone-accessibility-check-works-1-chromium-linux.txt'),
+        'data',
+      )
+      const ti = makeTestInfo({ dir: tmpDir })
+      expect(await snapshotExists(ti)).toBe(true)
+    })
+  })
+
+  describe('snapshotExists with Playwright-named snapshots', () => {
+    const touch = (name: string) => fs.writeFile(path.join(tmpDir, name), 'data')
+
+    it('matches a capitalised title with punctuation and project suffix', async () => {
+      await touch('Test-error-pages-ID-3303-2-desktop-chrome-linux.txt')
+      const ti = makeTestInfo({ dir: tmpDir, title: 'Test error pages: ID 3303' })
+      expect(await snapshotExists(ti)).toBe(true)
+    })
+
+    it('matches with different project suffixes', async () => {
+      await touch('Login-Works-1-mobile-safari-darwin.txt')
+      const ti = makeTestInfo({ dir: tmpDir, title: 'Login Works' })
+      expect(await snapshotExists(ti)).toBe(true)
+    })
+
+    it('does not match a title that differs only by case', async () => {
+      await touch('login-works-1-desktop-chrome-linux.txt')
+      const ti = makeTestInfo({ dir: tmpDir, title: 'Login Works' })
+      expect(await snapshotExists(ti)).toBe(false)
+    })
+
+    it('returns false when nothing matches', async () => {
+      await touch('Other-Test-1-desktop-chrome-linux.txt')
+      const ti = makeTestInfo({ dir: tmpDir, title: 'Login Works' })
+      expect(await snapshotExists(ti)).toBe(false)
+    })
+
+    it('ignores a matching .png without a .txt', async () => {
+      await touch('Login-Works-1-desktop-chrome-linux.png')
+      const ti = makeTestInfo({ dir: tmpDir, title: 'Login Works' })
+      expect(await snapshotExists(ti)).toBe(false)
+    })
+
+    it('does not match a different test whose title extends this one', async () => {
+      await touch('CRUD-tests-Video-Promo-1-desktop-chrome-linux.txt')
+      const ti = makeTestInfo({ dir: tmpDir, title: 'CRUD tests - Video' })
+      expect(await snapshotExists(ti)).toBe(false)
+    })
+  })
+
+  describe('readBaselineFile / writeBaselineFile', () => {
+    it('round-trips object schema with note and violations', async () => {
+      const file = path.join(tmpDir, 'rt.a11y-baseline.json')
+      await writeBaselineFile(file, {
+        note: 'No accessibility violations found',
+        violations: [],
+      })
+      const back = await readBaselineFile(file)
+      expect(back).toEqual({ note: 'No accessibility violations found', violations: [] })
+    })
+
+    it('returns null when file is missing', async () => {
+      const file = path.join(tmpDir, 'missing.json')
+      expect(await readBaselineFile(file)).toBeNull()
+    })
+
+    it('does not throw on EEXIST (idempotent first-write)', async () => {
+      const file = path.join(tmpDir, 'idem.json')
+      await writeBaselineFile(file, { note: 'first', violations: [] })
+      await writeBaselineFile(file, { note: 'second', violations: [] })
+      const back = await readBaselineFile(file)
+      expect(back?.note).toBe('first')
+    })
+
+    it('throws a clear error on malformed JSON', async () => {
+      const file = path.join(tmpDir, 'bad.json')
+      await fs.writeFile(file, '{not json')
+      await expect(readBaselineFile(file)).rejects.toThrow(/Malformed baseline file/)
+    })
+
+    it('creates parent directories on write', async () => {
+      const file = path.join(tmpDir, 'nested', 'sub', 'baseline.json')
+      await writeBaselineFile(file, { note: 'x', violations: [] })
+      expect((await readBaselineFile(file))?.note).toBe('x')
+    })
+  })
+
+  describe('buildSeed', () => {
+    it('produces a clean-state payload for zero violations', () => {
+      expect(buildSeed([])).toEqual({
+        note: 'No accessibility violations found',
+        violations: [],
+      })
+    })
+
+    it('produces a TODO-prompted payload for non-zero violations', () => {
+      const v = [{ rule: 'color-contrast', targets: ['#x'], reason: 'TODO', willBeFixedIn: 'TODO' }]
+      const seed = buildSeed(v)
+      expect(seed.note).toMatch(/TODO/)
+      expect(seed.violations).toEqual(v)
+    })
+  })
+})

package/src/accessibility-baseline-file.ts

@@ -0,0 +1,208 @@
+import { promises as fs } from 'fs'
+import path from 'path'
+import type { TestInfo } from '@playwright/test'
+import type { AccessibilityBaselineEntry } from './accessibility-baseline.js'
+
+export type ScanKind = 'wcag' | 'best-practice'
+
+export interface OnDiskBaselineFile {
+  note: string
+  violations: AccessibilityBaselineEntry[]
+}
+
+const scanInvocationCounters = new WeakMap<object, Map<ScanKind, number>>()
+
+/**
+ * Increment and return the 1-indexed invocation number for this scan kind
+ * within the current test. Every call to `checkAccessibility()` runs up to
+ * two scans (WCAG + best-practice); each scan gets its own counter so that
+ * a test calling `checkAccessibility()` twice produces distinct baseline
+ * file names (`…-1.a11y-baseline.json`, `…-2.a11y-baseline.json`) even when
+ * both scans share a single `checkAccessibility()` call.
+ *
+ * Counter state is keyed by the TestInfo object (held in a WeakMap so it
+ * is discarded with the test). Use `resetAccessibilityScanCounts()` to
+ * clear state explicitly — for example, between tests in a unit-test
+ * suite that reuses a mocked TestInfo.
+ */
+export function nextAccessibilityScanCount(
+  testInfo: Pick<TestInfo, 'testId'> | object,
+  scan: ScanKind,
+): number {
+  const key = testInfo as object
+  let counts = scanInvocationCounters.get(key)
+  if (!counts) {
+    counts = new Map()
+    scanInvocationCounters.set(key, counts)
+  }
+  const n = (counts.get(scan) ?? 0) + 1
+  counts.set(scan, n)
+  return n
+}
+
+export function resetAccessibilityScanCounts(testInfo: object): void {
+  scanInvocationCounters.delete(testInfo)
+}
+
+/**
+ * Slugify a test's fully qualified title the same way we use it as the
+ * stem of both on-disk baseline filenames and (for existence checks) the
+ * prefix of Playwright's auto-generated snapshot filenames.
+ *
+ * Implemented as a single-pass character scan to avoid regex-based
+ * polynomial backtracking on library-supplied input (CodeQL
+ * js/polynomial-redos).
+ */
+function slugifyTitle(testInfo: Pick<TestInfo, 'titlePath' | 'title'>): string {
+  const segments = testInfo.titlePath?.slice(1) ?? []
+  const raw = segments.length > 0 ? segments.join(' ') : testInfo.title
+  let out = ''
+  let lastWasHyphen = true // suppresses leading hyphen
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i)
+    const isLowerAlpha = code >= 97 && code <= 122 // a-z
+    const isUpperAlpha = code >= 65 && code <= 90 // A-Z
+    const isDigit = code >= 48 && code <= 57 // 0-9
+    if (isLowerAlpha || isDigit) {
+      out += raw[i]
+      lastWasHyphen = false
+    } else if (isUpperAlpha) {
+      out += String.fromCharCode(code + 32)
+      lastWasHyphen = false
+    } else if (!lastWasHyphen) {
+      out += '-'
+      lastWasHyphen = true
+    }
+  }
+  // Trim trailing hyphen.
+  if (out.endsWith('-')) out = out.slice(0, -1)
+  return out
+}
+
+/**
+ * Reproduce the stem Playwright uses for auto-named snapshot files: the
+ * title path (minus the spec file) joined with spaces, with every run of
+ * control/punctuation characters collapsed to a single hyphen. Unlike
+ * `slugifyTitle()` this preserves case and does not trim hyphens, so it
+ * matches committed snapshot filenames exactly. Mirrors Playwright's
+ * `sanitizeForFilePath()`. Very long titles, which Playwright truncates
+ * and hashes, are not handled.
+ */
+function playwrightSnapshotStem(testInfo: Pick<TestInfo, 'titlePath' | 'title'>): string {
+  const segments = testInfo.titlePath?.slice(1) ?? []
+  const raw = segments.length > 0 ? segments.join(' ') : testInfo.title
+  let out = ''
+  let lastWasReplaced = false
+  for (let i = 0; i < raw.length; i++) {
+    const code = raw.charCodeAt(i)
+    const replaced =
+      code <= 0x2c ||
+      (code >= 0x2e && code <= 0x2f) ||
+      (code >= 0x3a && code <= 0x40) ||
+      (code >= 0x5b && code <= 0x60) ||
+      (code >= 0x7b && code <= 0x7f)
+    if (replaced) {
+      if (!lastWasReplaced) out += '-'
+      lastWasReplaced = true
+    } else {
+      out += raw[i]
+      lastWasReplaced = false
+    }
+  }
+  return out
+}
+
+/**
+ * Build the on-disk baseline file path for a single scan call.
+ *
+ * Playwright exposes `testInfo.snapshotPath(...name)` as the public way to
+ * resolve a file under the test's snapshots directory (honoring any
+ * user-configured `snapshotPathTemplate`). We pass a filename that mixes
+ * the slugified test title + call counter + a scan-specific suffix, so two
+ * different tests in the same spec file don't collide and each scan has
+ * its own file.
+ *
+ * There is no reusable Playwright API that bakes the test title into an
+ * explicit-name snapshot path — that logic is private to `toMatchSnapshot()`
+ * for its auto-counter naming — so we build the stem ourselves.
+ */
+export function baselineFilePath(
+  testInfo: Pick<TestInfo, 'snapshotPath' | 'titlePath' | 'title'>,
+  scan: ScanKind,
+  callCount: number,
+): string {
+  const slug = slugifyTitle(testInfo)
+  const suffix = scan === 'wcag' ? 'a11y-baseline' : 'a11y-baseline-best-practice'
+  return testInfo.snapshotPath(`${slug}-${callCount}.${suffix}.json`)
+}
+
+/**
+ * Return true if a Playwright snapshot file already exists on disk for
+ * this test — i.e. the test has been previously committed under snapshot
+ * mode. Used to preserve snapshot-mode behaviour for existing tests while
+ * defaulting new (snapshotless) tests into on-disk baseline mode.
+ */
+export async function snapshotExists(
+  testInfo: Pick<TestInfo, 'snapshotPath' | 'titlePath' | 'title'>,
+): Promise<boolean> {
+  const dir = path.dirname(testInfo.snapshotPath('a11y-baseline-probe'))
+  let entries: string[]
+  try {
+    entries = await fs.readdir(dir)
+  } catch (err: any) {
+    if (err?.code === 'ENOENT') return false
+    throw err
+  }
+  // Playwright names snapshots `<stem>-<counter>[-<project>-<platform>].txt`.
+  // Require the counter so a title that merely extends this one (e.g.
+  // "Video" vs "Video Promo") is not mistaken for this test's snapshot.
+  const prefix = `${playwrightSnapshotStem(testInfo)}-`
+  return entries.some(name => {
+    if (!name.startsWith(prefix) || !name.endsWith('.txt')) return false
+    let i = prefix.length
+    while (i < name.length && name.charCodeAt(i) >= 48 && name.charCodeAt(i) <= 57) i++
+    return i > prefix.length && (name[i] === '-' || name[i] === '.')
+  })
+}
+
+export async function readBaselineFile(filePath: string): Promise<OnDiskBaselineFile | null> {
+  let raw: string
+  try {
+    raw = await fs.readFile(filePath, 'utf8')
+  } catch (err: any) {
+    if (err?.code === 'ENOENT') return null
+    throw err
+  }
+  try {
+    const parsed = JSON.parse(raw)
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.violations)) {
+      throw new Error('expected an object with a "violations" array')
+    }
+    return {
+      note: typeof parsed.note === 'string' ? parsed.note : '',
+      violations: parsed.violations as AccessibilityBaselineEntry[],
+    }
+  } catch (err) {
+    throw new Error(`Malformed baseline file at ${filePath}: ${(err as Error).message}`)
+  }
+}
+
+export async function writeBaselineFile(filePath: string, data: OnDiskBaselineFile): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+  try {
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2) + '\n', { flag: 'wx' })
+  } catch (err: any) {
+    if (err?.code === 'EEXIST') return
+    throw err
+  }
+}
+
+export function buildSeed(violations: AccessibilityBaselineEntry[]): OnDiskBaselineFile {
+  if (violations.length === 0) {
+    return { note: 'No accessibility violations found', violations: [] }
+  }
+  return {
+    note: 'TODO: fill in reason and willBeFixedIn for each entry before committing.',
+    violations,
+  }
+}