[Feature] Golden HTML suite: the 1.6 parity ruler
What
Adds the golden HTML suite: every component in the catalog is rendered, reduced
to a canonical form by an HTML5-spec parser, and compared byte-for-byte against
a committed snapshot. 188 snapshots over 54 component directories.
Three coverage tests stop the ruler from quietly shrinking: every component
directory must have a scenario, every RubyUI::Base subclass must actually
render in one (recorded at before_template, not at initialize), and no
snapshot may exist without a scenario. The normalizer is asserted to be
idempotent over every snapshot on every run, which is what makes the final byte
comparison a structural comparison rather than a string one, and every scenario
is rendered twice to catch unpinned randomness.
rake golden is reached by rake test, so CI covers it on Ruby 3.3 and 3.4
with no workflow change. nokogiri is added as a development dependency; the
gem still ships with no runtime dependencies.
Why now
This is Phase 1 of design/2026-09-19-rubyui-2-0-design.md, which this PR
also carries along with its implementation plan. The 2.0 migration replaces
Phlex with plain Ruby classes and ERB templates, and it needs an executable
definition of "the HTML did not change" before the first component moves. A
ruler written after the thing it measures is not a ruler.
It also earns its place on main on its own: it catches markup regressions in
ordinary bug-fix PRs today.
Also in this PR
- The ruler is hardened against five false equivalences found in review,
each with a test that failed before its fix: a stray</template>silently
truncated the input; an empty element and a whitespace-only element compared
equal (they are different toFormField's controller and toempty:hidden);
class tokens and text collapsed on Ruby's\s, which includes U+000B, rather
than HTML's whitespace; and the LF the parser drops after<pre>/
<textarea>was never re-emitted, so a preserved block starting with a blank
line could not be pinned. No recorded snapshot changed. - HoverCard snapshots re-recorded. #530 changed its markup after the
snapshots were first taken. Those two files are the only difference between
the recording onv2-herband the recording againstmainā which is what
validates the ruler. ContextMenuLabelbug fix.class: [..., inset?: "pl-8"]is an Array
whose second element is a Hash, so every label shipped a literal
{inset?: "pl-8"}class token,inset:never appliedpl-8, and the
output differed between Ruby 3.3 and 3.4. Fixing it pins the last two
unpinned scenarios. The MCP registry is rebuilt to match.- A whitespace inventory. The canonical form is, by design, blind to
whitespace between element siblings and at text boundaries.
gem/test/golden/tools/inline_adjacency.rblists candidate spots; the
decision it informs ā an inventory, not a bound ā and the observations from
the whole-branch review are indesign/v2/decisions.md. gem/Gemfile.lockgains thex86_64-linuxplatform so CI installs the
prebuilt nokogiri instead of compiling it per job.
Test steps
cd gem
bundle exec rake golden # the suite plus the ruler's own tests
bundle exec rake # unit tests + golden + standardrb
Both green, zero skips. To see the ruler work, change a class in any component
and re-run rake golden. To see the hardening, feed
Golden::CanonicalHtml.call a <div>\n</div> and a <div></div>.
š¤ Generated with Claude Code
Summary by cubic
Adds the golden HTML suite that renders every component, normalizes the output with an HTML5 parser, and compares it byte-for-byte against committed snapshots, giving the RubyUI 2.0 migration an executable definition of "the HTML did not change." rake golden runs under rake test, so CI covers all 188 snapshots on Ruby 3.3 and 3.4 with no workflow change. The PR also carries the RubyUI 2.0 design doc and Phase 1 plan, defers follow-up issues #537ā#543 to the 2.0 line, and keeps the docs generator in 2.0.
New Features
- Coverage tests require every component directory, every
RubyUI::Basesubclass, and every snapshot to have a matching scenario; scenarios render twice to catch unpinned randomness, and the normalizer is checked for idempotence on every snapshot on every run. rake golden:updatere-records snapshots;nokogiriis a development dependency only.rake goldenalso runs the ruler's own tests.
Bug Fixes
- Fixes
ContextMenuLabelsoinset:appliespl-8; it previously emitted a literal{inset?: "pl-8"}class token. - Hardens the normalizer against a stray
</template>truncating output, empty vs whitespace-only elements, non-HTML whitespace, and lost newlines after<pre>/<textarea>. - Keeps the canonical form a fixed point for nested preserved and raw-text elements; the normalizer hardening changes no snapshot.
- Re-records HoverCard snapshots and 47 snapshots carrying
xmlns:xmlns; the harness bounds pinned ranges before materialising them, proves the same value returns on every render, and letsgolden:updaterun aftergoldenin the same rake process. - Fixes the custom-keybindings command scenario to use
keydown.ctrl+p@windowso the snapshot pins a keybinding that actually fires.