shed-goldens-rebaseline

Regenerates Flutter golden test reference images with font loading, visual inspection, and isolated commits.

Updated Jul 27, 2026
One-click install
npx skills add https://github.com/zakariaf/Shed-Book --skill shed-goldens-rebaseline-zakariaf
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: shed-goldens-rebaseline
Source: https://github.com/zakariaf/Shed-Book/tree/main/.claude/skills/shed-goldens-rebaseline
Command: npx skills add https://github.com/zakariaf/Shed-Book --skill shed-goldens-rebaseline-zakariaf

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Golden image tests in Flutter fail whenever rendering legitimately changes, and blindly regenerating reference PNGs destroys the visual evidence needed to review whether the change is acceptable. This Skill provides a controlled, manual-only runbook for re-baselining Shed Book's eight golden images without losing the diff evidence or corrupting baselines with wrong fonts or platforms. ## Core Features & Use Cases - Verify-before-regenerate workflow: Runs make goldens first to produce four failure images per changed golden (master, test, isolated diff, masked diff) before any regeneration, since --update-goldens overwrites unconditionally. - Environment precondition checks: Confirms macOS host, exact Flutter version from .fvmrc, real bundled font loading via FontLoader in test/flutter_test_config.dart, and the TolerantFileComparator at 0.005 tolerance. - Review and commit discipline: Requires inspecting every changed image for legibility (no Ahem boxes, readable tag numbers), deleting test/features/failures/, and landing the PNGs alone in their own commit and PR. - Use Case: After a design-system change moves several golden images, use this Skill to verify the diffs are intended, regenerate the baselines on the pinned Flutter version, and ship the new PNGs as a standalone reviewed commit. ## Quick Start Ask the agent to re-baseline the golden images after confirming which intended change moved them, and it will verify, inspect, regenerate, and commit the PNGs separately.

Frequently Asked Questions about shed-goldens-rebaseline

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

FAQPage Schema
How do I update Flutter golden test images safely?▼

Run `make goldens` first to verify against committed PNGs and generate failure images, inspect all four diff images per changed golden, then run `make goldens-update` through the Makefile target. Never pass `--update-goldens` directly, since a PreToolUse hook blocks that flag.

Why do Flutter golden tests render text as black boxes?▼

Black boxes mean glyphs rendered in the Ahem fallback font because real fonts were not loaded. The test configuration must load every font family listed in pubspec.yaml via FontLoader after TestWidgetsFlutterBinding.ensureInitialized, otherwise baselines assert the opposite of legibility.

Can I re-baseline golden images on Linux or CI?▼

No. Goldens are OS-, font-, and Flutter-version-sensitive, so regenerating on Linux or a different Flutter version rewrites all images to bytes the pinned macOS runner rejects. Regeneration is a local, reviewed act on macOS with the exact version from .fvmrc.

Why does a golden test stay green after a small visual change?▼

The TolerantFileComparator uses a 0.005 tolerance, so drift under half a percent never turns red. A green run proves nothing moved by more than 0.5%, not that baselines are current.

Should golden image updates go in the same PR as the code change?▼

No. Re-baselined PNGs must land in their own commit and their own PR with a one-line body explaining what changed and why. A re-baseline bundled into a feature PR is one nobody reviewed.