[Feature] Golden HTML suite: the 1.6 parity ruler

Closed
CI
22d ago
+7392-6

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 to FormField's controller and to empty: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 on v2-herb and the recording against main — which is what
    validates the ruler.
  • ContextMenuLabel bug 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 applied pl-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.rb lists candidate spots; the
    decision it informs — an inventory, not a bound — and the observations from
    the whole-branch review are in design/v2/decisions.md.
  • gem/Gemfile.lock gains the x86_64-linux platform 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::Base subclass, 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:update re-records snapshots; nokogiri is a development dependency only.
  • rake golden also runs the ruler's own tests.

Bug Fixes

  • Fixes ContextMenuLabel so inset: applies pl-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 lets golden:update run after golden in the same rake process.
  • Fixes the custom-keybindings command scenario to use keydown.ctrl+p@window so the snapshot pins a keybinding that actually fires.