run-goldens-rebaseline

Re-baselines Flutter golden test reference images through a manual, ordered blessing workflow.

Updated Aug 22, 2026
One-click install
npx skills add https://github.com/zakariaf/NearlyStop --skill run-goldens-rebaseline-zakariaf
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: run-goldens-rebaseline
Source: https://github.com/zakariaf/NearlyStop/tree/main/.claude/skills/run-goldens-rebaseline
Command: npx skills add https://github.com/zakariaf/NearlyStop --skill run-goldens-rebaseline-zakariaf

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Golden tests fail whenever an intentional visual change lands, and the reflex response — running flutter test --update-goldens — silently destroys the only record of what the UI used to look like. This Skill enforces the one sanctioned ritual for overwriting committed reference images so a re-baseline never hides a regression, a flaky test, or host-specific rendering noise. ## Core Features & Use Cases - Ordered blessing workflow: Green the non-golden geometry, contrast, and a11y assertions first, then re-baseline only in the pinned OS/Flutter environment with loadAppFonts() active, via flutter test --update-goldens --tags golden. - Review and cleanup gates: Inspect every changed PNG by eye, delete orphan goldens left by renamed tests, remove failures/ artifacts, and commit images as their own commit naming the cause. - Verification before merge: Re-run flutter test --tags golden twice without the flag to prove the new baselines reproduce, and confirm --update-goldens appears nowhere in CI. - Use Case: A design review raises a row height from 40 to 48 pixels and dozens of matchesGoldenFile tests go red. Follow the ritual to confirm the change is intentional, bless the full affected set in the pinned environment, and land the images as a standalone commit. ## Quick Start A deliberate visual change broke my golden tests — walk me through the sanctioned re-baselining ritual and verify the new baselines reproduce without the update flag.

Frequently Asked Questions about run-goldens-rebaseline

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I update Flutter golden test images after an intentional UI change?

Run flutter test --update-goldens --tags golden only after the non-golden geometry, contrast, and a11y tests are green. Then inspect every changed PNG by eye, delete orphans, and re-run the suite without the flag to prove the baselines reproduce.

Why do Flutter golden tests fail on a different machine or CI runner?

Font rasterization differs by host OS and Flutter version, so images blessed elsewhere never match. Re-baseline only in the pinned environment that produced the committed images, and never run --update-goldens in CI.

What is loadAppFonts() and why do golden tests need it?

loadAppFonts() loads the real application fonts into the test environment. Without it, every glyph renders as an Ahem rectangle, and blessing in that state commits a wall of boxes that passes forever while asserting nothing.

Should I use --update-goldens to fix a failing golden test in CI?

No. A gate that rewrites the reference it checks asserts nothing permanently. A golden failure is a question: confirm the pixel change was intended, fix the code if it was not, and bless only as a local, human-reviewed act.

What should I do when a golden test keeps changing without code changes?

That is a flaky golden, not a baseline to update. Pump to a settled frame, remove time-dependent values, or delete the golden — re-blessing only hides the flake until the next run.