Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(ci): retry visual promotion from archived acceptance (#5595)

Cindy Zhang9fb6144691f4
diff --git a/.github/scripts/visual-gate/lib/canonical-png.mjs b/.github/scripts/visual-gate/lib/canonical-png.mjs
new file mode 100644
index 0000000000..b050bb58e9
--- /dev/null
+++ b/.github/scripts/visual-gate/lib/canonical-png.mjs
@@ -0,0 +1,29 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {createRequire} from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export const CANONICAL_PNG_OPTIONS = Object.freeze({
+ bitDepth: 8,
+ colorType: 6,
+ deflateChunkSize: 32 * 1024,
+ deflateLevel: 9,
+ deflateStrategy: 3,
+ filterType: -1,
+ inputColorType: 6,
+ inputHasAlpha: true,
+});
+
+export function canonicalizePng(bytes) {
+ const {PNG} = require('pngjs');
+ const image = PNG.sync.read(bytes, {checkCRC: true});
+ return {
+ bytes: PNG.sync.write(
+ {data: image.data, height: image.height, width: image.width},
+ {...CANONICAL_PNG_OPTIONS},
+ ),
+ height: image.height,
+ width: image.width,
+ };
+}
diff --git a/.github/scripts/visual-gate/lib/canonical-png.test.mjs b/.github/scripts/visual-gate/lib/canonical-png.test.mjs
new file mode 100644
index 0000000000..d04e70554c
--- /dev/null
+++ b/.github/scripts/visual-gate/lib/canonical-png.test.mjs
@@ -0,0 +1,56 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {PNG} from 'pngjs';
+
+import {CANONICAL_PNG_OPTIONS, canonicalizePng} from './canonical-png.mjs';
+
+function image(red, green = 0, blue = 0) {
+ const value = new PNG({width: 2, height: 2});
+ for (let offset = 0; offset < value.data.length; offset += 4) {
+ value.data[offset] = red;
+ value.data[offset + 1] = green;
+ value.data[offset + 2] = blue;
+ value.data[offset + 3] = 255;
+ }
+ return value;
+}
+
+describe('canonical PNG encoding', () => {
+ it('pins every encoder option that affects durable bytes', () => {
+ expect(CANONICAL_PNG_OPTIONS).toEqual({
+ bitDepth: 8,
+ colorType: 6,
+ deflateChunkSize: 32 * 1024,
+ deflateLevel: 9,
+ deflateStrategy: 3,
+ filterType: -1,
+ inputColorType: 6,
+ inputHasAlpha: true,
+ });
+ });
+
+ it('normalizes compression and metadata without changing pixels', () => {
+ const plain = PNG.sync.write(image(0, 0, 255));
+ const withMetadata = image(0, 0, 255);
+ withMetadata.gamma = 0.45455;
+ const alternate = PNG.sync.write(withMetadata, {
+ deflateLevel: 0,
+ deflateStrategy: 0,
+ filterType: 0,
+ });
+
+ expect(alternate).not.toEqual(plain);
+ expect(PNG.sync.read(alternate).data).toEqual(PNG.sync.read(plain).data);
+ expect(canonicalizePng(alternate).bytes).toEqual(
+ canonicalizePng(plain).bytes,
+ );
+ });
+
+ it('keeps changed pixels distinct and rejects corrupt bytes', () => {
+ expect(canonicalizePng(PNG.sync.write(image(255))).bytes).not.toEqual(
+ canonicalizePng(PNG.sync.write(image(0, 255))).bytes,
+ );
+ expect(() => canonicalizePng(Buffer.from('not a PNG'))).toThrow();
+ });
+});
diff --git a/.github/scripts/visual-gate/publish-pr-report.mjs b/.github/scripts/visual-gate/publish-pr-report.mjs
index 15c10ef824..36a74ca4b3 100644
--- a/.github/scripts/visual-gate/publish-pr-report.mjs
+++ b/.github/scripts/visual-gate/publish-pr-report.mjs
@@ -13,9 +13,9 @@
import {createHash} from 'node:crypto';
import fs from 'node:fs';
import path from 'node:path';
-import {PNG} from 'pngjs';
import {incomparable} from './lib/baseline.mjs';
+import {canonicalizePng} from './lib/canonical-png.mjs';
import {buildVerdict, compareCaptures} from './lib/compare.mjs';
import {shotKey} from './lib/plan.mjs';
import {renderReport} from './lib/report.mjs';
@@ -35,7 +35,10 @@ const headSha = flag('head-sha') ?? '';
const runId = flag('run-id') ?? '';
const runAttempt = flag('run-attempt') ?? '';
const config = JSON.parse(
- fs.readFileSync(new URL('./visual-gate.config.json', import.meta.url), 'utf8'),
+ fs.readFileSync(
+ new URL('./visual-gate.config.json', import.meta.url),
+ 'utf8',
+ ),
);
const KEY = /^[A-Za-z0-9._-]{1,240}$/;
@@ -64,25 +67,33 @@ function shaFile(file) {
function copyPng(source, target, label) {
if (!fs.existsSync(source)) fail(`${label} is missing`);
const stat = fs.lstatSync(source);
- if (!stat.isFile() || stat.isSymbolicLink()) fail(`${label} is not a regular file`);
- if (stat.size <= 0 || stat.size > MAX_PNG_BYTES) fail(`${label} has invalid size`);
+ if (!stat.isFile() || stat.isSymbolicLink())
+ fail(`${label} is not a regular file`);
+ if (stat.size <= 0 || stat.size > MAX_PNG_BYTES)
+ fail(`${label} has invalid size`);
let image;
try {
- image = PNG.sync.read(fs.readFileSync(source), {checkCRC: true});
+ image = canonicalizePng(fs.readFileSync(source));
} catch (error) {
fail(`${label} is not a valid PNG: ${error.message}`);
}
- if (image.width <= 0 || image.height <= 0 || image.width > MAX_EDGE || image.height > MAX_EDGE) {
+ if (
+ image.width <= 0 ||
+ image.height <= 0 ||
+ image.width > MAX_EDGE ||
+ image.height > MAX_EDGE
+ ) {
fail(`${label} has invalid dimensions ${image.width}x${image.height}`);
}
fs.mkdirSync(path.dirname(target), {recursive: true});
- fs.writeFileSync(target, PNG.sync.write(image));
+ fs.writeFileSync(target, image.bytes);
return image;
}
if (!Number.isSafeInteger(pr) || pr <= 0) fail('invalid PR number');
if (!SHA.test(headSha)) fail('invalid trusted head SHA');
-if (!/^\d+$/.test(runId) || !/^\d+$/.test(runAttempt)) fail('invalid run identity');
+if (!/^\d+$/.test(runId) || !/^\d+$/.test(runAttempt))
+ fail('invalid run identity');
if (
scope?.hasStableVisual !== true ||
typeof scope.broadStableVisual !== 'boolean' ||
@@ -95,7 +106,10 @@ if (
}
const manifestPath = path.join(input, 'manifest.json');
-if (!fs.existsSync(manifestPath) || fs.lstatSync(manifestPath).isSymbolicLink()) {
+if (
+ !fs.existsSync(manifestPath) ||
+ fs.lstatSync(manifestPath).isSymbolicLink()
+) {
fail('trusted capture manifest is missing or symbolic');
}
const manifest = readJSON(manifestPath);
@@ -128,7 +142,8 @@ const blocker = incomparable(baselineManifest, manifest);
if (blocker) fail(`baseline is not comparable: ${blocker}`);
const entries = Object.entries(manifest.shots);
-if (entries.length > MAX_SHOTS) fail(`trusted capture exceeds ${MAX_SHOTS} shots`);
+if (entries.length > MAX_SHOTS)
+ fail(`trusted capture exceeds ${MAX_SHOTS} shots`);
for (const [key, shot] of entries) {
if (
!KEY.test(key) ||
@@ -154,19 +169,30 @@ const sourceNames = fs.existsSync(sourceShots)
? fs.readdirSync(sourceShots, {withFileTypes: true})
: [];
const sourceKeys = sourceNames.map(entry => {
- if (!entry.isFile() || entry.isSymbolicLink() || !entry.name.endsWith('.png')) {
+ if (
+ !entry.isFile() ||
+ entry.isSymbolicLink() ||
+ !entry.name.endsWith('.png')
+ ) {
fail(`unexpected capture entry ${entry.name}`);
}
return entry.name.slice(0, -4);
});
-if (sourceKeys.length !== entries.length || sourceKeys.some(key => !manifest.shots[key])) {
+if (
+ sourceKeys.length !== entries.length ||
+ sourceKeys.some(key => !manifest.shots[key])
+) {
fail('capture PNG set does not match its manifest');
}
const trustedManifest = {...manifest, shots: {}};
for (const [key, shot] of entries) {
const target = path.join(output, 'current', `${key}.png`);
- const image = copyPng(path.join(sourceShots, `${key}.png`), target, `shots/${key}.png`);
+ const image = copyPng(
+ path.join(sourceShots, `${key}.png`),
+ target,
+ `shots/${key}.png`,
+ );
trustedManifest.shots[key] = {
...shot,
sha256: shaFile(target),
@@ -179,8 +205,10 @@ const baselineEntries = Object.entries(baselineManifest.shots ?? {});
const expected = scope.broadStableVisual
? baselineEntries.map(([key]) => key)
: baselineEntries
- .filter(([, shot]) =>
- scope.stableComponents.includes(shot.component) || scope.stableThemes.includes(shot.theme),
+ .filter(
+ ([, shot]) =>
+ scope.stableComponents.includes(shot.component) ||
+ scope.stableThemes.includes(shot.theme),
)
.map(([key]) => key);
if (entries.length === 0 && expected.length === 0) {
@@ -203,7 +231,11 @@ const verdict = buildVerdict({
comparison,
currentManifest: trustedManifest,
baselineManifest,
- targeting: {unexercisedOverrides: [], undeclaredTargets: [], uncoveredTargets: []},
+ targeting: {
+ unexercisedOverrides: [],
+ undeclaredTargets: [],
+ uncoveredTargets: [],
+ },
failures: [],
context: {...manifest.context, trustedScope: scope},
});
@@ -212,17 +244,31 @@ const beforeSha256 = {};
for (const change of verdict.changes) {
const key = change.key;
const baselineFile = path.join(baseline, 'shots', `${key}.png`);
- copyPng(baselineFile, path.join(output, 'before', `${key}.png`), `baseline/${key}.png`);
- fs.copyFileSync(path.join(output, 'current', `${key}.png`), path.join(output, 'after', `${key}.png`));
+ copyPng(
+ baselineFile,
+ path.join(output, 'before', `${key}.png`),
+ `baseline/${key}.png`,
+ );
+ fs.copyFileSync(
+ path.join(output, 'current', `${key}.png`),
+ path.join(output, 'after', `${key}.png`),
+ );
beforeSha256[key] = shaFile(baselineFile);
}
for (const key of verdict.added) {
- fs.copyFileSync(path.join(output, 'current', `${key}.png`), path.join(output, 'after', `${key}.png`));
+ fs.copyFileSync(
+ path.join(output, 'current', `${key}.png`),
+ path.join(output, 'after', `${key}.png`),
+ );
beforeSha256[key] = null;
}
for (const key of verdict.removed) {
const baselineFile = path.join(baseline, 'shots', `${key}.png`);
- copyPng(baselineFile, path.join(output, 'before', `${key}.png`), `baseline/${key}.png`);
+ copyPng(
+ baselineFile,
+ path.join(output, 'before', `${key}.png`),
+ `baseline/${key}.png`,
+ );
beforeSha256[key] = shaFile(baselineFile);
}
@@ -263,8 +309,14 @@ const evidence = {
};
fs.rmSync(path.join(output, 'current'), {recursive: true, force: true});
-fs.writeFileSync(path.join(output, 'evidence.json'), `${JSON.stringify(evidence, null, 2)}\n`);
-fs.writeFileSync(path.join(output, 'verdict.json'), `${JSON.stringify(verdict, null, 2)}\n`);
+fs.writeFileSync(
+ path.join(output, 'evidence.json'),
+ `${JSON.stringify(evidence, null, 2)}\n`,
+);
+fs.writeFileSync(
+ path.join(output, 'verdict.json'),
+ `${JSON.stringify(verdict, null, 2)}\n`,
+);
fs.writeFileSync(
path.join(output, 'index.html'),
renderReport(verdict, {
diff --git a/.github/scripts/visual-gate/publish-pr-report.test.mjs b/.github/scripts/visual-gate/publish-pr-report.test.mjs
index 2a99b05cbb..dfc22c5643 100644
--- a/.github/scripts/visual-gate/publish-pr-report.test.mjs
+++ b/.github/scripts/visual-gate/publish-pr-report.test.mjs
@@ -10,7 +10,16 @@ import {fileURLToPath} from 'node:url';
import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import {PNG} from 'pngjs';
-const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'publish-pr-report.mjs');
+import {canonicalizePng} from './lib/canonical-png.mjs';
+
+const SCRIPT = path.join(
+ path.dirname(fileURLToPath(import.meta.url)),
+ 'publish-pr-report.mjs',
+);
+const ACCEPTANCE_SCRIPT = path.join(
+ path.dirname(fileURLToPath(import.meta.url)),
+ 'visual-acceptance.mjs',
+);
const HEAD = 'a'.repeat(40);
const RUN = '123456';
const KEY = 'core-button--default__neutral-light';
@@ -52,7 +61,10 @@ function writeBaseline(shots = {[KEY]: {shot: SHOT, bytes: png()}}) {
const file = path.join(baseline, 'shots', `${key}.png`);
fs.mkdirSync(path.dirname(file), {recursive: true});
fs.writeFileSync(file, bytes);
- manifestShots[key] = {...shot, sha256: createHash('sha256').update(bytes).digest('hex')};
+ manifestShots[key] = {
+ ...shot,
+ sha256: createHash('sha256').update(bytes).digest('hex'),
+ };
}
writeJSON(path.join(baseline, 'manifest.json'), {
version: 1,
@@ -64,7 +76,10 @@ function writeBaseline(shots = {[KEY]: {shot: SHOT, bytes: png()}}) {
});
}
-function writeCapture(shots = {[KEY]: {shot: SHOT, bytes: png(0, 0, 255)}}, overrides = {}) {
+function writeCapture(
+ shots = {[KEY]: {shot: SHOT, bytes: png(0, 0, 255)}},
+ overrides = {},
+) {
fs.rmSync(input, {recursive: true, force: true});
const manifestShots = {};
const shotsDir = path.join(input, 'shots');
@@ -104,19 +119,35 @@ function run() {
process.execPath,
[
SCRIPT,
- '--input', input,
- '--output', output,
- '--baseline', baseline,
- '--scope', scope,
- '--pr', '42',
- '--head-sha', HEAD,
- '--run-id', RUN,
- '--run-attempt', '1',
+ '--input',
+ input,
+ '--output',
+ output,
+ '--baseline',
+ baseline,
+ '--scope',
+ scope,
+ '--pr',
+ '42',
+ '--head-sha',
+ HEAD,
+ '--run-id',
+ RUN,
+ '--run-attempt',
+ '1',
],
{encoding: 'utf8'},
);
}
+function runAcceptance(command, flags) {
+ const args = [ACCEPTANCE_SCRIPT, command];
+ for (const [name, value] of Object.entries(flags)) {
+ args.push(`--${name}`, String(value));
+ }
+ return execFileSync(process.execPath, args, {encoding: 'utf8'});
+}
+
beforeEach(() => {
root = fs.mkdtempSync(path.join(os.tmpdir(), 'trusted-visual-'));
input = path.join(root, 'input');
@@ -136,9 +167,119 @@ beforeEach(() => {
afterEach(() => fs.rmSync(root, {recursive: true, force: true}));
describe('trusted PR visual publisher', () => {
+ it('canonicalizes raw capture bytes through acceptance and promotion', () => {
+ const rawImage = PNG.sync.read(png(0, 0, 255));
+ rawImage.gamma = 0.45455;
+ const rawAfter = PNG.sync.write(rawImage, {
+ deflateLevel: 0,
+ deflateStrategy: 0,
+ filterType: 0,
+ });
+ writeCapture({[KEY]: {shot: SHOT, bytes: rawAfter}});
+ run();
+
+ const publishedAfter = fs.readFileSync(
+ path.join(output, 'after', `${KEY}.png`),
+ );
+ expect(publishedAfter).toEqual(canonicalizePng(rawAfter).bytes);
+ expect(publishedAfter).not.toEqual(rawAfter);
+ const evidence = JSON.parse(
+ fs.readFileSync(path.join(output, 'evidence.json'), 'utf8'),
+ );
+ expect(evidence.deltas[0].shot.sha256).toBe(
+ createHash('sha256').update(publishedAfter).digest('hex'),
+ );
+
+ const pages = path.join(root, 'pages');
+ fs.mkdirSync(path.join(pages, 'visual-gate'), {recursive: true});
+ fs.cpSync(baseline, path.join(pages, 'visual-gate', 'baseline'), {
+ recursive: true,
+ });
+ const evidenceDir = path.join(pages, 'pr', '42', 'visual', HEAD, RUN, '1');
+ fs.mkdirSync(path.dirname(evidenceDir), {recursive: true});
+ fs.cpSync(output, evidenceDir, {recursive: true});
+ execFileSync('git', ['init', '-q', '-b', 'gh-pages'], {cwd: pages});
+ execFileSync('git', ['config', 'user.name', 'Test'], {cwd: pages});
+ execFileSync('git', ['config', 'user.email', '[email protected]'], {
+ cwd: pages,
+ });
+ execFileSync('git', ['add', '.'], {cwd: pages});
+ execFileSync('git', ['commit', '-qm', 'trusted evidence'], {cwd: pages});
+
+ runAcceptance('accept', {
+ pages,
+ pr: 42,
+ head: HEAD,
+ 'run-id': RUN,
+ 'run-attempt': 1,
+ approver: 'maintainer',
+ 'approver-id': 99,
+ permission: 'maintain',
+ 'effective-permission': 'maintain',
+ 'comment-id': 1234,
+ reason: 'The changed frame matches the approved component design.',
+ });
+ const acceptance = path.join(
+ pages,
+ 'visual-gate',
+ 'acceptances',
+ '42',
+ HEAD,
+ RUN,
+ '1',
+ 'acceptance.json',
+ );
+ expect(
+ JSON.parse(fs.readFileSync(acceptance, 'utf8')).keys[0].afterSha256,
+ ).toBe(createHash('sha256').update(publishedAfter).digest('hex'));
+
+ const mergeImage = PNG.sync.read(rawAfter);
+ mergeImage.gamma = 0.8;
+ const rawMerged = PNG.sync.write(mergeImage, {
+ deflateLevel: 1,
+ deflateStrategy: 1,
+ filterType: 4,
+ });
+ expect(rawMerged).not.toEqual(rawAfter);
+ expect(canonicalizePng(rawMerged).bytes).toEqual(publishedAfter);
+ const merged = path.join(root, 'merged');
+ fs.mkdirSync(path.join(merged, 'shots'), {recursive: true});
+ fs.writeFileSync(path.join(merged, 'shots', `${KEY}.png`), rawMerged);
+ writeJSON(path.join(merged, 'manifest.json'), {
+ version: 1,
+ platform: 'linux-arm64',
+ browser: 'chromium-140.0',
+ viewport: {width: 1280, height: 900},
+ capturedAt: '2026-08-27T09:00:00.000Z',
+ context: {sha: 'd'.repeat(40)},
+ shots: {
+ [KEY]: {
+ ...SHOT,
+ sha256: createHash('sha256').update(rawMerged).digest('hex'),
+ width: 2,
+ height: 2,
+ },
+ },
+ });
+
+ runAcceptance('promote', {
+ pages,
+ acceptance,
+ capture: merged,
+ 'merge-sha': 'd'.repeat(40),
+ });
+ expect(
+ fs.readFileSync(
+ path.join(pages, 'visual-gate', 'baseline', 'shots', `${KEY}.png`),
+ ),
+ ).toEqual(publishedAfter);
+ });
+
it('derives a changed verdict even when PR data claims pass', () => {
expect(run()).toContain('trusted changed verdict');
- const verdict = JSON.parse(fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'));
+ const verdict = JSON.parse(
+ fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'),
+ );
expect(verdict).toMatchObject({status: 'changed', counts: {changed: 1}});
expect(fs.existsSync(path.join(output, 'before', `${KEY}.png`))).toBe(true);
expect(fs.existsSync(path.join(output, 'after', `${KEY}.png`))).toBe(true);
@@ -148,7 +289,9 @@ describe('trusted PR visual publisher', () => {
it('derives pass only from a trusted capture matching the baseline', () => {
writeCapture({[KEY]: {shot: SHOT, bytes: png()}});
run();
- const verdict = JSON.parse(fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'));
+ const verdict = JSON.parse(
+ fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'),
+ );
expect(verdict.status).toBe('pass');
});
@@ -164,7 +307,9 @@ describe('trusted PR visual publisher', () => {
});
writeCapture({[key]: {shot, bytes: png(0, 255, 0)}});
run();
- const verdict = JSON.parse(fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'));
+ const verdict = JSON.parse(
+ fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'),
+ );
expect(verdict).toMatchObject({status: 'changed', added: [key]});
expect(fs.existsSync(path.join(output, 'after', `${key}.png`))).toBe(true);
});
@@ -172,20 +317,26 @@ describe('trusted PR visual publisher', () => {
it('derives a removed baseline shot when trusted capture omits expected scope', () => {
writeCapture({});
run();
- const verdict = JSON.parse(fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'));
+ const verdict = JSON.parse(
+ fs.readFileSync(path.join(output, 'verdict.json'), 'utf8'),
+ );
expect(verdict).toMatchObject({status: 'changed', removed: [KEY]});
expect(fs.existsSync(path.join(output, 'before', `${KEY}.png`))).toBe(true);
});
it('rejects a trusted capture that claims another run', () => {
- const manifest = JSON.parse(fs.readFileSync(path.join(input, 'manifest.json'), 'utf8'));
+ const manifest = JSON.parse(
+ fs.readFileSync(path.join(input, 'manifest.json'), 'utf8'),
+ );
manifest.context.runId = '999';
writeJSON(path.join(input, 'manifest.json'), manifest);
expect(() => run()).toThrow(/identity mismatch/);
});
it('rejects traversal-shaped manifest keys', () => {
- writeCapture({'../bad': {shot: {...SHOT, storyId: '../bad'}, bytes: png()}});
+ writeCapture({
+ '../bad': {shot: {...SHOT, storyId: '../bad'}, bytes: png()},
+ });
expect(() => run()).toThrow(/metadata is invalid/);
});
diff --git a/.github/scripts/visual-gate/visual-acceptance.mjs b/.github/scripts/visual-gate/visual-acceptance.mjs
index de728b9610..faadcf14d1 100644
--- a/.github/scripts/visual-gate/visual-acceptance.mjs
+++ b/.github/scripts/visual-gate/visual-acceptance.mjs
@@ -11,13 +11,13 @@
import {execFileSync} from 'node:child_process';
import {createHash} from 'node:crypto';
import fs from 'node:fs';
-import {createRequire} from 'node:module';
import path from 'node:path';
import {
isVisualAcceptanceEndpointMaintainer,
isVisualAcceptanceRecordMaintainer,
} from './authorization.mjs';
+import {canonicalizePng} from './lib/canonical-png.mjs';
import {readStoryIndex, shotKey, storiesInPackages} from './lib/plan.mjs';
const args = process.argv.slice(2);
@@ -76,14 +76,25 @@ function evidenceRoot(pages, pr, head) {
}
function evidenceAt(pages, pr, head, run, attempt) {
- if (!Number.isSafeInteger(run) || run <= 0 || !Number.isSafeInteger(attempt) || attempt <= 0) {
+ if (
+ !Number.isSafeInteger(run) ||
+ run <= 0 ||
+ !Number.isSafeInteger(attempt) ||
+ attempt <= 0
+ ) {
fail('invalid evidence run/attempt');
}
- const dir = path.join(evidenceRoot(pages, pr, head), String(run), String(attempt));
- if (!fs.existsSync(dir)) fail(`no published evidence for run ${run}/${attempt}`);
+ const dir = path.join(
+ evidenceRoot(pages, pr, head),
+ String(run),
+ String(attempt),
+ );
+ if (!fs.existsSync(dir))
+ fail(`no published evidence for run ${run}/${attempt}`);
const evidence = readJSON(path.join(dir, 'evidence.json'));
validateEvidence(evidence, {pr, head, run});
- if (evidence.run.attempt !== attempt) fail('evidence attempt identity mismatch');
+ if (evidence.run.attempt !== attempt)
+ fail('evidence attempt identity mismatch');
return {dir, evidence};
}
@@ -109,7 +120,8 @@ function latestEvidence(pages, pr, head, {required = true} = {}) {
.filter(entry => entry.isDirectory() && /^\d+$/.test(entry.name))
.map(entry => Number(entry.name))
.sort((a, b) => b - a);
- const dir = attempts.length > 0 ? path.join(runDir, String(attempts[0])) : runDir;
+ const dir =
+ attempts.length > 0 ? path.join(runDir, String(attempts[0])) : runDir;
const evidence = readJSON(path.join(dir, 'evidence.json'));
validateEvidence(evidence, {pr, head, run});
if (attempts.length > 0 && evidence.run.attempt !== attempts[0]) {
@@ -268,7 +280,14 @@ function recordPath(pages, pr, head, run, attempt) {
}
function pointerPath(pages, pr, head) {
- return path.join(pages, 'visual-gate', 'acceptances', String(pr), head, 'current.json');
+ return path.join(
+ pages,
+ 'visual-gate',
+ 'acceptances',
+ String(pr),
+ head,
+ 'current.json',
+ );
}
function accept() {
@@ -294,7 +313,13 @@ function accept() {
if (!Number.isSafeInteger(commentId) || commentId <= 0)
fail('invalid comment id');
- const {dir: evidenceDir, evidence} = evidenceAt(pages, pr, head, runId, runAttempt);
+ const {dir: evidenceDir, evidence} = evidenceAt(
+ pages,
+ pr,
+ head,
+ runId,
+ runAttempt,
+ );
if (evidence.verdict.status !== 'changed' || evidence.deltas.length === 0) {
fail('current visual bundle has no delta to accept');
}
@@ -506,7 +531,10 @@ function validateAcceptance(value, expected = {}) {
validateShot(entry.shot, entry.key);
if (expected.dir) {
const archived = path.join(expected.dir, 'after', `${entry.key}.png`);
- if (!fs.existsSync(archived) || shaFile(archived) !== entry.afterSha256) {
+ if (
+ !fs.existsSync(archived) ||
+ shaFile(archived) !== entry.afterSha256
+ ) {
fail(`archived AFTER is missing or changed for ${entry.key}`);
}
}
@@ -522,7 +550,9 @@ function validateAcceptance(value, expected = {}) {
function trustedPlan() {
const scope = readJSON(path.resolve(flag('scope')));
- const baseline = readJSON(path.join(path.resolve(flag('baseline')), 'manifest.json'));
+ const baseline = readJSON(
+ path.join(path.resolve(flag('baseline')), 'manifest.json'),
+ );
const storybookDir = path.resolve(flag('storybook-dir'));
const output = path.resolve(flag('output'));
if (
@@ -535,15 +565,25 @@ function trustedPlan() {
}
const baselineEntries = Object.entries(baseline.shots ?? {});
- const baselineThemes = [...new Set(baselineEntries.map(([, shot]) => shot.theme))].filter(Boolean);
+ const baselineThemes = [
+ ...new Set(baselineEntries.map(([, shot]) => shot.theme)),
+ ].filter(Boolean);
const shots = scope.broadStableVisual
- ? baselineEntries.map(([key, shot]) => ({...shot, key, reasons: ['trusted:broad']}))
+ ? baselineEntries.map(([key, shot]) => ({
+ ...shot,
+ key,
+ reasons: ['trusted:broad'],
+ }))
: [];
if (scope.stableComponents.length > 0 || scope.stableThemes.length > 0) {
- const indexed = storiesInPackages(readStoryIndex(storybookDir, []), ['Core']);
+ const indexed = storiesInPackages(readStoryIndex(storybookDir, []), [
+ 'Core',
+ ]);
const stories = new Map();
- const newTheme = scope.stableThemes.some(theme => !baselineThemes.includes(theme));
+ const newTheme = scope.stableThemes.some(
+ theme => !baselineThemes.includes(theme),
+ );
for (const [, shot] of baselineEntries) {
if (
newTheme ||
@@ -554,9 +594,11 @@ function trustedPlan() {
}
}
for (const story of indexed) {
- if (scope.stableComponents.includes(story.component)) stories.set(story.id, story);
+ if (scope.stableComponents.includes(story.component))
+ stories.set(story.id, story);
}
- const themes = scope.stableThemes.length > 0 ? scope.stableThemes : baselineThemes;
+ const themes =
+ scope.stableThemes.length > 0 ? scope.stableThemes : baselineThemes;
for (const story of stories.values()) {
for (const theme of themes) {
for (const mode of ['light', 'dark']) {
@@ -579,7 +621,9 @@ function trustedPlan() {
fail(`trusted visual plan has invalid size ${unique.length}`);
}
writeJSON(output, unique);
- process.stdout.write(`Wrote ${unique.length} trusted PR shot(s) to ${output}.\n`);
+ process.stdout.write(
+ `Wrote ${unique.length} trusted PR shot(s) to ${output}.\n`,
+ );
}
function plan() {
@@ -596,19 +640,6 @@ function plan() {
);
}
-const require = createRequire(import.meta.url);
-
-function samePixels(first, second) {
- const {PNG} = require('pngjs');
- const a = PNG.sync.read(fs.readFileSync(first));
- const b = PNG.sync.read(fs.readFileSync(second));
- return (
- a.width === b.width &&
- a.height === b.height &&
- Buffer.compare(a.data, b.data) === 0
- );
-}
-
function sameViewport(first, second) {
return first?.width === second?.width && first?.height === second?.height;
}
@@ -686,9 +717,24 @@ function promote() {
if (!fs.existsSync(recaptured) || !capturedShot) {
fail(`post-merge capture is missing ${entry.key}`);
}
- if (capturedShot.sha256 !== shaFile(recaptured)) {
+ const rawRecapturedSha256 = shaFile(recaptured);
+ if (capturedShot.sha256 !== rawRecapturedSha256) {
fail(`post-merge manifest hash does not match ${entry.key}`);
}
+ let canonical;
+ try {
+ canonical = canonicalizePng(fs.readFileSync(recaptured));
+ } catch (error) {
+ fail(
+ `post-merge capture is not a valid PNG for ${entry.key}: ${error.message}`,
+ );
+ }
+ const canonicalSha256 = shaBytes(canonical.bytes);
+ if (canonicalSha256 !== entry.afterSha256) {
+ fail(
+ `canonical post-merge hash does not match accepted AFTER for ${entry.key}`,
+ );
+ }
for (const field of ['storyId', 'theme', 'mode']) {
if (capturedShot[field] !== entry.shot[field]) {
fail(
@@ -696,14 +742,24 @@ function promote() {
);
}
}
- if (!samePixels(acceptedAfter, recaptured)) {
- fail(`post-merge pixels do not match accepted AFTER for ${entry.key}`);
+ if (
+ capturedShot.width !== canonical.width ||
+ capturedShot.height !== canonical.height
+ ) {
+ fail(`post-merge dimensions do not match ${entry.key}`);
}
- actions.push({entry, baselineFile, recaptured, capturedShot});
+ actions.push({
+ entry,
+ baselineFile,
+ canonicalBytes: canonical.bytes,
+ capturedShot: {...capturedShot, sha256: canonicalSha256},
+ });
}
if (actions.every(action => action.alreadyPromoted)) {
- process.stdout.write(`Accepted visual bundle for PR #${acceptance.pr} was already promoted.\n`);
+ process.stdout.write(
+ `Accepted visual bundle for PR #${acceptance.pr} was already promoted.\n`,
+ );
return;
}
@@ -713,7 +769,7 @@ function promote() {
if (fs.existsSync(action.baselineFile)) fs.rmSync(action.baselineFile);
delete manifest.shots[action.entry.key];
} else {
- fs.copyFileSync(action.recaptured, action.baselineFile);
+ fs.writeFileSync(action.baselineFile, action.canonicalBytes);
manifest.shots[action.entry.key] = action.capturedShot;
}
}
@@ -763,5 +819,7 @@ switch (command) {
promote();
break;
default:
- fail('usage: visual-acceptance.mjs <accept|state|trusted-plan|plan|promote>');
+ fail(
+ 'usage: visual-acceptance.mjs <accept|state|trusted-plan|plan|promote>',
+ );
}
diff --git a/.github/scripts/visual-gate/visual-acceptance.test.mjs b/.github/scripts/visual-gate/visual-acceptance.test.mjs
index c14c8539f9..9229fcc280 100644
--- a/.github/scripts/visual-gate/visual-acceptance.test.mjs
+++ b/.github/scripts/visual-gate/visual-acceptance.test.mjs
@@ -10,6 +10,8 @@ import {fileURLToPath} from 'node:url';
import {afterEach, beforeEach, describe, expect, it} from 'vitest';
import {PNG} from 'pngjs';
+import {canonicalizePng} from './lib/canonical-png.mjs';
+
const SCRIPT = path.join(
path.dirname(fileURLToPath(import.meta.url)),
'visual-acceptance.mjs',
@@ -133,7 +135,15 @@ function writeEvidence({
attempt = 1,
status = 'changed',
} = {}) {
- const dir = path.join(pages, 'pr', '42', 'visual', HEAD, String(run), String(attempt));
+ const dir = path.join(
+ pages,
+ 'pr',
+ '42',
+ 'visual',
+ HEAD,
+ String(run),
+ String(attempt),
+ );
fs.mkdirSync(path.join(dir, 'after'), {recursive: true});
if (status === 'changed' && kind !== 'removed') {
fs.writeFileSync(path.join(dir, 'after', `${key}.png`), after);
@@ -295,7 +305,9 @@ describe('visual acceptance', () => {
delete record.decision.roleName;
delete record.decision.effectivePermission;
writeJSON(acceptanceFile(), record);
- expect(JSON.parse(run('state', {pages, pr: 42, head: HEAD}))).toMatchObject({
+ expect(
+ JSON.parse(run('state', {pages, pr: 42, head: HEAD})),
+ ).toMatchObject({
state: 'success',
reason: 'accepted',
});
@@ -383,10 +395,12 @@ describe('visual acceptance', () => {
it('returns success for a clean trusted capture without acceptance', () => {
writeEvidence({run: 124, status: 'pass'});
- expect(JSON.parse(run('state', {pages, pr: 42, head: HEAD}))).toMatchObject({
- state: 'success',
- reason: 'clean',
- });
+ expect(JSON.parse(run('state', {pages, pr: 42, head: HEAD}))).toMatchObject(
+ {
+ state: 'success',
+ reason: 'clean',
+ },
+ );
});
it('derives a trusted component plan from baseline themes and the Storybook index', () => {
@@ -417,7 +431,9 @@ describe('visual acceptance', () => {
'storybook-dir': storybook,
output,
});
- expect(JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key)).toEqual([
+ expect(
+ JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key),
+ ).toEqual([
'core-button--default__neutral-light',
'core-button--default__neutral-dark',
]);
@@ -441,7 +457,9 @@ describe('visual acceptance', () => {
'storybook-dir': storybook,
output,
});
- expect(JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key)).toEqual([
+ expect(
+ JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key),
+ ).toEqual([
'core-button--default__new-theme-light',
'core-button--default__new-theme-dark',
]);
@@ -462,7 +480,9 @@ describe('visual acceptance', () => {
'storybook-dir': root,
output,
});
- expect(JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key)).toEqual([KEY]);
+ expect(
+ JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key),
+ ).toEqual([KEY]);
});
it('allows the trusted 520-shot broad plan through the capture CLI', () => {
@@ -478,9 +498,13 @@ describe('visual acceptance', () => {
}));
const file = path.join(root, 'large-plan.json');
writeJSON(file, plan);
- const printed = execFileSync(process.execPath, [GATE, 'plan', '--plan-file', file], {
- encoding: 'utf8',
- });
+ const printed = execFileSync(
+ process.execPath,
+ [GATE, 'plan', '--plan-file', file],
+ {
+ encoding: 'utf8',
+ },
+ );
expect(printed).toContain('520 shots');
});
@@ -512,7 +536,9 @@ describe('visual acceptance', () => {
'storybook-dir': storybook,
output,
});
- expect(JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key)).toEqual([
+ expect(
+ JSON.parse(fs.readFileSync(output, 'utf8')).map(shot => shot.key),
+ ).toEqual([
KEY,
'core-new--default__neutral-light',
'core-new--default__neutral-dark',
@@ -521,7 +547,15 @@ describe('visual acceptance', () => {
it('accepts a trusted 520-delta broad bundle', () => {
const runId = 130;
- const dir = path.join(pages, 'pr', '42', 'visual', HEAD, String(runId), '1');
+ const dir = path.join(
+ pages,
+ 'pr',
+ '42',
+ 'visual',
+ HEAD,
+ String(runId),
+ '1',
+ );
const deltas = [];
fs.mkdirSync(path.join(dir, 'after'), {recursive: true});
for (let index = 0; index < 520; index += 1) {
@@ -631,7 +665,129 @@ describe('visual acceptance', () => {
});
});
- it('rejects changed post-merge pixels and a stale merge identity', () => {
+ it.each([
+ {kind: 'changed', key: KEY, runId: 123},
+ {kind: 'added', key: 'core-new--default__neutral-light', runId: 124},
+ ])(
+ 'canonicalizes equivalent raw PNG bytes when promoting a $kind shot',
+ ({kind, key, runId}) => {
+ if (kind === 'added') writeEvidence({kind, key, run: runId});
+ run('accept', acceptanceFlags({'run-id': runId}));
+ const record = acceptanceFile(runId);
+ const accepted = fs.readFileSync(
+ path.join(path.dirname(record), 'after', `${key}.png`),
+ );
+ const decoded = PNG.sync.read(accepted);
+ decoded.gamma = 0.45455;
+ const rawRecapture = PNG.sync.write(decoded, {deflateLevel: 0});
+ expect(rawRecapture).not.toEqual(accepted);
+ expect(PNG.sync.read(rawRecapture).data).toEqual(
+ PNG.sync.read(accepted).data,
+ );
+ expect(canonicalizePng(rawRecapture).bytes).toEqual(accepted);
+
+ const capture = path.join(root, `capture-${kind}`);
+ fs.mkdirSync(path.join(capture, 'shots'), {recursive: true});
+ fs.writeFileSync(path.join(capture, 'shots', `${key}.png`), rawRecapture);
+ writeJSON(path.join(capture, 'manifest.json'), {
+ version: 1,
+ platform: 'linux-arm64',
+ browser: 'chromium-140.0',
+ viewport: {width: 1280, height: 900},
+ capturedAt: '2026-08-26T22:00:00.000Z',
+ context: {sha: MERGE},
+ shots: {
+ [key]: {
+ ...SHOT,
+ sha256: digest(rawRecapture),
+ width: 2,
+ height: 2,
+ },
+ },
+ });
+
+ expect(
+ run('promote', {
+ pages,
+ acceptance: record,
+ capture,
+ 'merge-sha': MERGE,
+ }),
+ ).toContain('Promoted accepted visual bundle');
+ expect(
+ fs.readFileSync(
+ path.join(pages, 'visual-gate', 'baseline', 'shots', `${key}.png`),
+ ),
+ ).toEqual(accepted);
+ const baselineManifest = JSON.parse(
+ fs.readFileSync(
+ path.join(pages, 'visual-gate', 'baseline', 'manifest.json'),
+ 'utf8',
+ ),
+ );
+ expect(baselineManifest.shots[key].sha256).toBe(digest(accepted));
+ },
+ );
+
+ it('promotes a removed shot without an AFTER hash or recaptured file', () => {
+ writeEvidence({kind: 'removed', run: 125});
+ run('accept', acceptanceFlags({'run-id': 125}));
+ const capture = path.join(root, 'capture-removed');
+ fs.mkdirSync(capture);
+ writeJSON(path.join(capture, 'manifest.json'), {
+ version: 1,
+ platform: 'linux-arm64',
+ browser: 'chromium-140.0',
+ viewport: {width: 1280, height: 900},
+ capturedAt: '2026-08-26T22:00:00.000Z',
+ context: {sha: MERGE},
+ shots: {},
+ });
+
+ expect(
+ run('promote', {
+ pages,
+ acceptance: acceptanceFile(125),
+ capture,
+ 'merge-sha': MERGE,
+ }),
+ ).toContain('Promoted accepted visual bundle');
+ expect(
+ fs.existsSync(
+ path.join(pages, 'visual-gate', 'baseline', 'shots', `${KEY}.png`),
+ ),
+ ).toBe(false);
+ });
+
+ it('rejects a merged recapture whose canonical pixels changed', () => {
+ run('accept', acceptanceFlags());
+ const capture = path.join(root, 'capture-changed-pixels');
+ const changed = png(0, 255, 0);
+ fs.mkdirSync(path.join(capture, 'shots'), {recursive: true});
+ fs.writeFileSync(path.join(capture, 'shots', `${KEY}.png`), changed);
+ writeJSON(path.join(capture, 'manifest.json'), {
+ version: 1,
+ platform: 'linux-arm64',
+ browser: 'chromium-140.0',
+ viewport: {width: 1280, height: 900},
+ capturedAt: '2026-08-26T22:00:00.000Z',
+ context: {sha: MERGE},
+ shots: {
+ [KEY]: {...SHOT, sha256: digest(changed), width: 2, height: 2},
+ },
+ });
+
+ expect(
+ fail('promote', {
+ pages,
+ acceptance: acceptanceFile(),
+ capture,
+ 'merge-sha': MERGE,
+ }),
+ ).toMatch(/canonical post-merge hash does not match accepted AFTER/);
+ });
+
+ it('rejects a stale merge identity', () => {
run('accept', acceptanceFlags());
const capture = path.join(root, 'capture');
fs.mkdirSync(path.join(capture, 'shots'), {recursive: true});
diff --git a/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs b/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs
new file mode 100644
index 0000000000..bc6f117e35
--- /dev/null
+++ b/.github/scripts/visual-gate/visual-promotion-workflow.test.mjs
@@ -0,0 +1,401 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {execFileSync, spawnSync} from 'node:child_process';
+import {createHash} from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+import {afterEach, describe, expect, it} from 'vitest';
+import {PNG} from 'pngjs';
+
+const ROOT = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '../../..',
+);
+const SCRIPT = path.join(
+ ROOT,
+ '.github',
+ 'scripts',
+ 'visual-gate',
+ 'visual-acceptance.mjs',
+);
+const WORKFLOW = path.join(
+ ROOT,
+ '.github',
+ 'workflows',
+ 'visual-acceptance-promote.yml',
+);
+const HEAD = 'a'.repeat(40);
+const MERGE = 'c'.repeat(40);
+const KEY = 'core-button--default__neutral-light';
+const RECORD_REL = '123/1/acceptance.json';
+const SHOT = {
+ storyId: 'core-button--default',
+ title: 'Core/Button',
+ name: 'Default',
+ component: 'Button',
+ theme: 'neutral',
+ mode: 'light',
+ reasons: ['component:Button'],
+};
+
+const roots = [];
+
+afterEach(() => {
+ for (const root of roots.splice(0)) {
+ fs.rmSync(root, {recursive: true, force: true});
+ }
+});
+
+function png(red, green = 0, blue = 0) {
+ const image = new PNG({width: 2, height: 2});
+ for (let offset = 0; offset < image.data.length; offset += 4) {
+ image.data[offset] = red;
+ image.data[offset + 1] = green;
+ image.data[offset + 2] = blue;
+ image.data[offset + 3] = 255;
+ }
+ return PNG.sync.write(image);
+}
+
+function digest(bytes) {
+ return createHash('sha256').update(bytes).digest('hex');
+}
+
+function writeJSON(file, value) {
+ fs.mkdirSync(path.dirname(file), {recursive: true});
+ fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function git(cwd, ...args) {
+ return execFileSync('git', args, {cwd, encoding: 'utf8'}).trim();
+}
+
+function runAcceptance(command, flags) {
+ const args = [SCRIPT, command];
+ for (const [name, value] of Object.entries(flags)) {
+ args.push(`--${name}`, String(value));
+ }
+ return execFileSync(process.execPath, args, {encoding: 'utf8'});
+}
+
+function workflowStepScript(name) {
+ const workflow = fs.readFileSync(WORKFLOW, 'utf8');
+ const start = workflow.indexOf(` - name: ${name}\n`);
+ expect(start).toBeGreaterThan(-1);
+ const next = workflow.indexOf('\n - name:', start + 1);
+ const step = workflow.slice(start, next === -1 ? undefined : next);
+ const runMarker = ' run: |\n';
+ const runStart = step.indexOf(runMarker);
+ expect(runStart).toBeGreaterThan(-1);
+ return step
+ .slice(runStart + runMarker.length)
+ .split('\n')
+ .map(line => (line.startsWith(' ') ? line.slice(10) : line))
+ .join('\n');
+}
+
+function writeCommandShims(root) {
+ const bin = path.join(root, 'bin');
+ fs.mkdirSync(bin);
+ const gitShim = path.join(bin, 'git');
+ fs.writeFileSync(
+ gitShim,
+ [
+ '#!/bin/bash',
+ 'set -e',
+ 'REAL_GIT="$TEST_REAL_GIT"',
+ 'if [ "${1:-}" = "clone" ]; then',
+ ' args=("$@")',
+ ' for ((i = 0; i < ${#args[@]}; i += 1)); do',
+ ' case "${args[$i]}" in',
+ ' https://x-access-token:*) args[$i]="file://${TEST_REMOTE}" ;;',
+ ' esac',
+ ' done',
+ ' exec "$REAL_GIT" "${args[@]}"',
+ 'fi',
+ 'if [ "${1:-}" = "-C" ] && [ "${3:-}" = "push" ] && [ "${TEST_INJECT_RACE:-0}" = "1" ] && [ ! -e "$TEST_RACE_MARKER" ]; then',
+ ' CLEANUP="$TEST_ROOT/cleanup-clone"',
+ ' "$REAL_GIT" clone -q --branch gh-pages "file://${TEST_REMOTE}" "$CLEANUP"',
+ ' "$REAL_GIT" -C "$CLEANUP" config user.name Test',
+ ' "$REAL_GIT" -C "$CLEANUP" config user.email [email protected]',
+ ' rm -rf "$CLEANUP/pr/${PR_NUMBER}"',
+ ' "$REAL_GIT" -C "$CLEANUP" add -A',
+ ' "$REAL_GIT" -C "$CLEANUP" commit -qm "cleanup merged preview"',
+ ' "$REAL_GIT" -C "$CLEANUP" push -q origin gh-pages',
+ ' touch "$TEST_RACE_MARKER"',
+ 'fi',
+ 'exec "$REAL_GIT" "$@"',
+ '',
+ ].join('\n'),
+ );
+ fs.chmodSync(gitShim, 0o755);
+
+ const ghShim = path.join(bin, 'gh');
+ fs.writeFileSync(ghShim, '#!/bin/sh\nprintf "%b\\n" "$GH_LATEST"\n');
+ fs.chmodSync(ghShim, 0o755);
+
+ const sleepShim = path.join(bin, 'sleep');
+ fs.writeFileSync(sleepShim, '#!/bin/sh\nexit 0\n');
+ fs.chmodSync(sleepShim, 0o755);
+ return bin;
+}
+
+function makeFixture(mutate) {
+ const root = fs.mkdtempSync(
+ path.join(os.tmpdir(), 'visual-promotion-workflow-'),
+ );
+ roots.push(root);
+ const pages = path.join(root, 'pages');
+ fs.mkdirSync(pages);
+ git(pages, 'init', '-q', '-b', 'gh-pages');
+ git(pages, 'config', 'user.name', 'Test');
+ git(pages, 'config', 'user.email', '[email protected]');
+
+ const before = png(255);
+ const after = png(0, 0, 255);
+ const baselineShot = path.join(
+ pages,
+ 'visual-gate',
+ 'baseline',
+ 'shots',
+ `${KEY}.png`,
+ );
+ fs.mkdirSync(path.dirname(baselineShot), {recursive: true});
+ fs.writeFileSync(baselineShot, before);
+ writeJSON(path.join(pages, 'visual-gate', 'baseline', 'manifest.json'), {
+ version: 1,
+ platform: 'linux-arm64',
+ browser: 'chromium-140.0',
+ viewport: {width: 1280, height: 900},
+ shots: {
+ [KEY]: {...SHOT, key: KEY, sha256: digest(before), width: 2, height: 2},
+ },
+ decisions: [],
+ });
+
+ const evidence = path.join(pages, 'pr', '42', 'visual', HEAD, '123', '1');
+ fs.mkdirSync(path.join(evidence, 'after'), {recursive: true});
+ fs.writeFileSync(path.join(evidence, 'after', `${KEY}.png`), after);
+ writeJSON(path.join(evidence, 'evidence.json'), {
+ version: 1,
+ repo: 'facebook/astryx',
+ pr: 42,
+ headSha: HEAD,
+ testedSha: 'b'.repeat(40),
+ baseSha: 'd'.repeat(40),
+ run: {id: 123, attempt: 1},
+ capture: {
+ platform: 'linux-arm64',
+ browser: 'chromium-140.0',
+ viewport: {width: 1280, height: 900},
+ },
+ deltas: [
+ {
+ key: KEY,
+ kind: 'changed',
+ beforeSha256: digest(before),
+ shot: SHOT,
+ },
+ ],
+ verdict: {version: 1, status: 'changed'},
+ });
+ git(pages, 'add', '.');
+ git(pages, 'commit', '-qm', 'fixture');
+
+ runAcceptance('accept', {
+ pages,
+ pr: 42,
+ head: HEAD,
+ 'run-id': 123,
+ 'run-attempt': 1,
+ approver: 'maintainer',
+ 'approver-id': 99,
+ permission: 'maintain',
+ 'effective-permission': 'maintain',
+ 'comment-id': 1234,
+ reason: 'The new radius matches the approved component design.',
+ });
+
+ const acceptance = path.join(
+ pages,
+ 'visual-gate',
+ 'acceptances',
+ '42',
+ HEAD,
+ RECORD_REL,
+ );
+ const sandbox = path.join(root, 'sandbox');
+ fs.mkdirSync(path.join(sandbox, '.github', 'scripts'), {recursive: true});
+ fs.symlinkSync(
+ path.join(ROOT, '.github', 'scripts', 'visual-gate'),
+ path.join(sandbox, '.github', 'scripts', 'visual-gate'),
+ );
+ const plan = path.join(sandbox, 'accepted-plan.json');
+ runAcceptance('plan', {acceptance, output: plan});
+
+ const capture = path.join(sandbox, '.visual-merged');
+ fs.mkdirSync(path.join(capture, 'shots'), {recursive: true});
+ fs.writeFileSync(path.join(capture, 'shots', `${KEY}.png`), after);
+ writeJSON(path.join(capture, 'manifest.json'), {
+ version: 1,
+ platform: 'linux-arm64',
+ browser: 'chromium-140.0',
+ viewport: {width: 1280, height: 900},
+ capturedAt: '2026-08-27T08:00:00.000Z',
+ context: {sha: MERGE},
+ shots: {[KEY]: {...SHOT, sha256: digest(after), width: 2, height: 2}},
+ });
+
+ mutate?.({acceptance, baselineShot, pages});
+ git(pages, 'add', '.');
+ git(pages, 'commit', '-qm', 'record acceptance');
+
+ const remote = path.join(root, 'remote.git');
+ git(root, 'clone', '-q', '--bare', pages, remote);
+ const bin = writeCommandShims(root);
+ return {root, remote, sandbox, bin, after};
+}
+
+function runPromotion({fixture, latest = '123\\t1\\tcompleted', race = false}) {
+ const marker = path.join(fixture.root, 'race-injected');
+ const result = spawnSync(
+ '/bin/bash',
+ ['-c', workflowStepScript('Verify and promote the baseline')],
+ {
+ cwd: fixture.sandbox,
+ encoding: 'utf8',
+ env: {
+ ...process.env,
+ PATH: `${fixture.bin}:${process.env.PATH}`,
+ GH_TOKEN: 'test-token',
+ GITHUB_REPOSITORY: 'facebook/astryx',
+ PR_NUMBER: '42',
+ HEAD_SHA: HEAD,
+ MERGE_SHA: MERGE,
+ RECORD_REL,
+ RUNNER_TEMP: path.join(fixture.root, 'runner'),
+ GH_LATEST: latest,
+ TEST_INJECT_RACE: race ? '1' : '0',
+ TEST_RACE_MARKER: marker,
+ TEST_REAL_GIT: execFileSync('which', ['git'], {
+ encoding: 'utf8',
+ }).trim(),
+ TEST_REMOTE: fixture.remote,
+ TEST_ROOT: fixture.root,
+ },
+ },
+ );
+ return {...result, marker};
+}
+
+describe('visual acceptance promotion workflow', () => {
+ it('retries from the immutable record after cleanup wins the first push race', () => {
+ const fixture = makeFixture();
+ const result = runPromotion({fixture, race: true});
+ expect(result.status, `${result.stdout}\n${result.stderr}`).toBe(0);
+ expect(fs.existsSync(result.marker)).toBe(true);
+
+ const final = path.join(fixture.root, 'final');
+ git(
+ fixture.root,
+ 'clone',
+ '-q',
+ '--branch',
+ 'gh-pages',
+ fixture.remote,
+ final,
+ );
+ expect(fs.existsSync(path.join(final, 'pr', '42'))).toBe(false);
+ expect(
+ fs.readFileSync(
+ path.join(final, 'visual-gate', 'baseline', 'shots', `${KEY}.png`),
+ ),
+ ).toEqual(fixture.after);
+ const manifest = JSON.parse(
+ fs.readFileSync(
+ path.join(final, 'visual-gate', 'baseline', 'manifest.json'),
+ 'utf8',
+ ),
+ );
+ expect(manifest.decisions.at(-1)).toMatchObject({
+ pr: 42,
+ headSha: HEAD,
+ mergeSha: MERGE,
+ });
+ });
+
+ it.each([
+ {
+ name: 'a stale current pointer',
+ mutate: ({pages}) =>
+ writeJSON(
+ path.join(
+ pages,
+ 'visual-gate',
+ 'acceptances',
+ '42',
+ HEAD,
+ 'current.json',
+ ),
+ {version: 1, run: 124, attempt: 1, record: '124/1/acceptance.json'},
+ ),
+ error: /newer visual acceptance superseded/,
+ },
+ {
+ name: 'a superseded CI run',
+ latest: '124\\t1\\tcompleted',
+ error: /not from the latest completed CI attempt/,
+ },
+ {
+ name: 'the wrong head identity',
+ mutate: ({acceptance}) => {
+ const record = JSON.parse(fs.readFileSync(acceptance, 'utf8'));
+ record.headSha = 'e'.repeat(40);
+ writeJSON(acceptance, record);
+ },
+ error: /record identity does not match this merged head/,
+ },
+ {
+ name: 'a run identity that disagrees with the immutable path',
+ mutate: ({acceptance}) => {
+ const record = JSON.parse(fs.readFileSync(acceptance, 'utf8'));
+ record.run.id = 124;
+ writeJSON(acceptance, record);
+ },
+ latest: '124\\t1\\tcompleted',
+ error: /record identity does not match this merged head/,
+ },
+ {
+ name: 'tampered archived pixels',
+ mutate: ({acceptance}) =>
+ fs.writeFileSync(
+ path.join(path.dirname(acceptance), 'after', `${KEY}.png`),
+ png(0, 255, 0),
+ ),
+ error: /archived AFTER is missing or changed/,
+ },
+ {
+ name: 'a changed baseline preimage',
+ mutate: ({baselineShot}) =>
+ fs.writeFileSync(baselineShot, png(0, 255, 0)),
+ error: /baseline conflict/,
+ },
+ ])('fails closed for $name', ({mutate, latest, error}) => {
+ const fixture = makeFixture(mutate);
+ const result = runPromotion({fixture, latest});
+ expect(result.status).not.toBe(0);
+ expect(`${result.stdout}\n${result.stderr}`).toMatch(error);
+ });
+
+ it('does not consult ephemeral PR evidence during promotion', () => {
+ const script = workflowStepScript('Verify and promote the baseline');
+ expect(script).toContain('current.json');
+ expect(script).toContain('LATEST_STATUS');
+ expect(script).toContain('visual-acceptance.mjs promote');
+ expect(script).not.toContain('visual-acceptance.mjs state');
+ expect(script).not.toContain('/pr/');
+ });
+});
diff --git a/.github/workflows/visual-acceptance-promote.yml b/.github/workflows/visual-acceptance-promote.yml
index faa7053407..1e758d1077 100644
--- a/.github/workflows/visual-acceptance-promote.yml
+++ b/.github/workflows/visual-acceptance-promote.yml
@@ -120,24 +120,25 @@ jobs:
echo "::error::A newer visual acceptance superseded the reviewed record"
exit 1
fi
+ ACCEPTED_IDENTITY=$(jq -er '[.pr, .headSha, .run.id, .run.attempt] | @tsv' \
+ "$PAGES/$RECORD")
+ IFS=$'\t' read -r ACCEPTED_PR ACCEPTED_HEAD ACCEPTED_RUN ACCEPTED_ATTEMPT <<< "$ACCEPTED_IDENTITY"
+ if [ "$ACCEPTED_PR" != "$PR_NUMBER" ] || \
+ [ "$ACCEPTED_HEAD" != "$HEAD_SHA" ] || \
+ [ "$RECORD_REL" != "${ACCEPTED_RUN}/${ACCEPTED_ATTEMPT}/acceptance.json" ]; then
+ echo "::error::Visual acceptance record identity does not match this merged head"
+ exit 1
+ fi
LATEST=$(gh api \
"repos/${GITHUB_REPOSITORY}/actions/runs?event=pull_request&head_sha=${HEAD_SHA}&per_page=100" \
--jq '[.workflow_runs[] | select(.name == "CI")][0] | [.id, .run_attempt, .status] | @tsv')
IFS=$'\t' read -r LATEST_RUN LATEST_ATTEMPT LATEST_STATUS <<< "$LATEST"
- ACCEPTED_RUN=$(jq -r '.run.id' "$PAGES/$RECORD")
- ACCEPTED_ATTEMPT=$(jq -r '.run.attempt' "$PAGES/$RECORD")
if [ "$LATEST_RUN" != "$ACCEPTED_RUN" ] || \
[ "$LATEST_ATTEMPT" != "$ACCEPTED_ATTEMPT" ] || \
[ "$LATEST_STATUS" != "completed" ]; then
echo "::error::Accepted evidence is not from the latest completed CI attempt"
exit 1
fi
- node .github/scripts/visual-gate/visual-acceptance.mjs state \
- --pages "$PAGES" --pr "$PR_NUMBER" --head "$HEAD_SHA" > "$RUNNER_TEMP/promotion-state.json"
- if [ "$(jq -r '.state + ":" + .reason' "$RUNNER_TEMP/promotion-state.json")" != "success:accepted" ]; then
- echo "::error::Accepted evidence is no longer the latest visual result"
- exit 1
- fi
node .github/scripts/visual-gate/visual-acceptance.mjs promote \
--pages "$PAGES" \
--acceptance "$PAGES/$RECORD" \