ruact 0.0.1 → 0.0.3

data/spec/support/matchers/flight_fixture_matcher.rb

@@ -1,5 +1,278 @@
 # frozen_string_literal: true
 
+require_relative "../flight_wire_parser"
+
+module Ruact
+  module Spec
+    # Internal helpers shared by the structural Flight matchers. Lives under
+    # `Ruact::Spec` (test-only namespace) — no top-level constants leak into
+    # the gem's public API surface.
+    # rubocop:disable Metrics/ClassLength -- single cohesive helper for matcher diffing/formatting; splitting would scatter related logic across files.
+    class FlightStructureDiff
+      # Keys the parser produces on every row. Predicates and expected rows
+      # may only reference these keys; unknown keys raise upfront so typos
+      # like `payloed:` don't silently match every row via `nil == nil`.
+      KNOWN_ROW_KEYS = %i[id class payload raw].freeze
+
+      # Keys that must be present in every expected-row hash passed to
+      # `match_flight_structure`. Excludes `:raw` because expected rows are
+      # authored as semantic descriptions, not byte-level snapshots.
+      REQUIRED_EXPECTED_KEYS = %i[id class payload].freeze
+
+      # Compute the set of differences between actual parsed rows and the
+      # expected structure. Import rows are matched as a multiset (their
+      # relative order among each other is not significant per AC1);
+      # everything else compares positionally.
+      def self.compute(actual_rows, expected_rows)
+        validate_expected_rows!(expected_rows)
+        return diffs_for_length_mismatch(actual_rows, expected_rows) if actual_rows.length != expected_rows.length
+
+        diffs = []
+        pending_actual_imports = []
+        pending_expected_imports = []
+
+        actual_rows.zip(expected_rows).each_with_index do |(actual, expected), i|
+          if actual[:class] == :import && expected[:class] == :import
+            pending_actual_imports << [i, actual]
+            pending_expected_imports << [i, expected]
+            next
+          end
+
+          next if rows_equal?(actual, expected)
+
+          diffs << build_field_diff(i, actual, expected)
+        end
+
+        diffs.concat(diff_imports_unordered(pending_actual_imports, pending_expected_imports))
+        diffs.sort_by { |d| d[:idx] }
+      end
+
+      # Imports are an unordered multiset within their class (AC1). Sort both
+      # sides by `:id` (always unique per render) and any leftover diffs come
+      # from semantic mismatch in the same-position-after-sort pair.
+      def self.diff_imports_unordered(actual_pairs, expected_pairs)
+        return [] if actual_pairs.empty? && expected_pairs.empty?
+
+        sort_key = ->(pair) { [pair[1][:id].to_i, pair[1][:payload].to_s] }
+        sorted_actual = actual_pairs.sort_by(&sort_key)
+        sorted_expected = expected_pairs.sort_by(&sort_key)
+
+        sorted_actual.zip(sorted_expected).filter_map do |(act_idx, act_row), (_exp_idx, exp_row)|
+          next if rows_equal?(act_row, exp_row)
+
+          build_field_diff(act_idx, act_row, exp_row)
+        end
+      end
+
+      def self.diffs_for_length_mismatch(actual_rows, expected_rows)
+        diffs = []
+        [actual_rows.length, expected_rows.length].max.times do |i|
+          actual = actual_rows[i]
+          expected = expected_rows[i]
+          if actual.nil?
+            diffs << { kind: :missing, idx: i, expected_row: expected }
+          elsif expected.nil?
+            diffs << { kind: :extra, idx: i, actual_row: actual }
+          elsif !rows_equal?(actual, expected)
+            diffs << build_field_diff(i, actual, expected)
+          end
+        end
+        diffs
+      end
+
+      def self.rows_equal?(actual, expected)
+        REQUIRED_EXPECTED_KEYS.all? { |k| actual[k] == expected[k] }
+      end
+
+      def self.build_field_diff(idx, actual, expected)
+        field_diff = nil
+        REQUIRED_EXPECTED_KEYS.each do |key|
+          next if actual[key] == expected[key]
+
+          path, sub_expected, sub_actual = first_difference(expected[key], actual[key], ".#{key}")
+          field_diff = { path: path, expected: sub_expected, got: sub_actual }
+          break
+        end
+
+        {
+          kind: :differs,
+          idx: idx,
+          row_class: actual[:class],
+          path: field_diff[:path],
+          expected: field_diff[:expected],
+          got: field_diff[:got],
+          expected_row: expected,
+          got_row: actual
+        }
+      end
+
+      # Walks parallel structures (Hash/Array/scalar) and returns the path,
+      # expected leaf, and actual leaf at the first differing position.
+      def self.first_difference(expected, actual, path)
+        return [path, expected, actual] if expected.class != actual.class
+        return [path, expected, actual] unless expected.is_a?(Array) || expected.is_a?(Hash)
+
+        return diff_in_array(expected, actual, path) if expected.is_a?(Array)
+
+        diff_in_hash(expected, actual, path)
+      end
+
+      def self.diff_in_array(expected, actual, path)
+        [expected.length, actual.length].max.times do |i|
+          return ["#{path}[#{i}]", expected[i], actual[i]] if i >= expected.length || i >= actual.length
+          next if expected[i] == actual[i]
+
+          return first_difference(expected[i], actual[i], "#{path}[#{i}]")
+        end
+        [path, expected, actual]
+      end
+
+      def self.diff_in_hash(expected, actual, path)
+        (expected.keys | actual.keys).each do |key|
+          return ["#{path}[#{key.inspect}]", expected[key], actual[key]] if !expected.key?(key) || !actual.key?(key)
+          next if expected[key] == actual[key]
+
+          return first_difference(expected[key], actual[key], "#{path}[#{key.inspect}]")
+        end
+        [path, expected, actual]
+      end
+
+      # Validates each expected row carries the required `:id`, `:class`,
+      # `:payload` keys. Without this, an expected row of `{ id: 0, class:
+      # :model }` would silently pass against any actual row whose payload
+      # was nil — because the `==` check reads `expected[:payload]` as nil.
+      def self.validate_expected_rows!(expected_rows)
+        expected_rows.each_with_index do |row, i|
+          unless row.is_a?(Hash)
+            raise ArgumentError,
+                  "match_flight_structure: expected row #{i} must be a Hash, got #{row.class}: #{row.inspect}"
+          end
+
+          missing = REQUIRED_EXPECTED_KEYS.reject { |k| row.key?(k) }
+          next if missing.empty?
+
+          raise ArgumentError,
+                "match_flight_structure: expected row #{i} is missing required keys: #{missing.inspect}. " \
+                "Each expected row must include :id, :class, and :payload."
+        end
+      end
+
+      # Validates a predicate hash for `include_flight_row`. Unknown keys
+      # (typos like `payloed:` or `clas:`) raise immediately so they don't
+      # silently match any row via `row[:payloed]` returning nil.
+      def self.validate_predicate!(predicate)
+        unless predicate.is_a?(Hash)
+          raise ArgumentError,
+                "include_flight_row: predicate must be a Hash, got #{predicate.class}: #{predicate.inspect}"
+        end
+        raise ArgumentError, "include_flight_row: predicate cannot be empty" if predicate.empty?
+
+        unknown = predicate.keys - KNOWN_ROW_KEYS
+        return if unknown.empty?
+
+        raise ArgumentError,
+              "include_flight_row: predicate has unknown keys: #{unknown.inspect}. " \
+              "Allowed keys: #{KNOWN_ROW_KEYS.inspect}."
+      end
+
+      def self.format_single(diff)
+        case diff[:kind]
+        when :missing
+          row = diff[:expected_row]
+          "Expected row #{diff[:idx]} (#{row[:class]}) was not produced.\n  expected: #{row.inspect}"
+        when :extra
+          row = diff[:actual_row]
+          "Got unexpected row #{diff[:idx]} (#{row[:class]}): #{row.inspect}"
+        else
+          format_field_diff(diff)
+        end
+      end
+
+      def self.format_field_diff(diff)
+        <<~MSG.strip
+          Expected Flight output to match structure.
+
+          Row #{diff[:idx]} (#{diff[:row_class]}) differs at #{diff[:path]}:
+            expected: #{diff[:expected].inspect}
+            got:      #{diff[:got].inspect}
+
+          Row #{diff[:idx]} (#{diff[:row_class]}) full diff:
+            expected: #{diff[:expected_row][:payload].inspect}
+            got:      #{diff[:got_row][:payload].inspect}
+        MSG
+      end
+
+      # Builds the multi-row failure message: header naming the diff count,
+      # AC3-specified wording for missing / extra / differing rows, and a
+      # `Row N (<class>): ✓` summary line for every matching row so the
+      # reader can see what passed.
+      def self.format_multi(diffs, actual_rows, expected_rows)
+        header = "Expected Flight output to match structure. #{diffs.length} rows differ:"
+        total = [actual_rows.length, expected_rows.length].max
+        diff_by_idx = diffs.to_h { |d| [d[:idx], d] }
+
+        body = (0...total).map do |i|
+          diff = diff_by_idx[i]
+          if diff
+            format_entry(diff)
+          else
+            row_class = (actual_rows[i] || expected_rows[i])[:class]
+            "Row #{i} (#{row_class}): ✓"
+          end
+        end
+
+        ([header, ""] + body).join("\n")
+      end
+
+      def self.format_entry(diff)
+        case diff[:kind]
+        when :missing
+          row = diff[:expected_row]
+          "Expected row #{diff[:idx]} (#{row[:class]}) was not produced.\n  expected: #{row.inspect}"
+        when :extra
+          row = diff[:actual_row]
+          "Got unexpected row #{diff[:idx]} (#{row[:class]}): #{row.inspect}"
+        else
+          <<~ENTRY.strip
+            Row #{diff[:idx]} (#{diff[:row_class]}) differs at #{diff[:path]}:
+              expected: #{diff[:expected].inspect}
+              got:      #{diff[:got].inspect}
+          ENTRY
+        end
+      end
+
+      # Subset / case-equality match used by `include_flight_row`. Plain
+      # values use `==`; richer matchers (`hash_including`, `array_including`,
+      # `kind_of`, regexes) use `===` which delegates to their custom logic.
+      # Predicate keys are validated upfront by `validate_predicate!`, so
+      # this method can assume every key is one of the known row keys.
+      def self.row_matches?(row, predicate)
+        predicate.all? do |key, expected_value|
+          actual_value = row[key]
+          case expected_value
+          when Symbol, Numeric, NilClass, TrueClass, FalseClass
+            expected_value == actual_value
+          else
+            # rubocop:disable Style/CaseEquality -- intentional: lets RSpec mock argument matchers
+            # (hash_including, array_including, kind_of, etc.) drive predicate semantics via #===.
+            expected_value === actual_value
+            # rubocop:enable Style/CaseEquality
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end
+
+# `match_flight_fixture(name)` — Phase 1 byte-exact snapshot matcher.
+#
+# Reads `spec/fixtures/flight/<name>.txt` and compares the actual wire bytes
+# to the file contents via `==`. Used when the wire format itself is the
+# contract (escape rules, ordering invariants, payload framing).
+#
+# @example
+#   expect(serializer.serialize_value("$danger")).to match_flight_fixture("string_dollar_escape")
 RSpec::Matchers.define :match_flight_fixture do |name|
   match do |actual|
     fixtures_dir = File.expand_path("../../fixtures/flight", __dir__)
@@ -23,3 +296,86 @@ RSpec::Matchers.define :match_flight_fixture do |name|
     "match Flight wire fixture '#{name}'"
   end
 end
+
+# `match_flight_structure(expected)` — Phase 2 structural matcher (Story 7.5).
+#
+# Parses the actual Flight wire output via `Ruact::Spec::FlightWireParser`,
+# then compares the resulting array of row records against `expected`. Hash
+# payloads are compared structurally (key insertion order is ignored), so
+# cosmetic JSON re-ordering does not break specs that assert on semantics.
+# Import rows are matched as a multiset; non-import rows are compared
+# positionally because Flight semantics depend on their order.
+#
+# Failure messages name the row index and the differing field — bytes are
+# only printed when no narrower diff is available.
+#
+# @example
+#   expect(wire).to match_flight_structure([
+#     { id: 1, class: :import, payload: ["/L.jsx", "L", ["/L.jsx"]] },
+#     { id: 0, class: :model,  payload: ["$", "$L1", nil, {}] }
+#   ])
+RSpec::Matchers.define :match_flight_structure do |expected|
+  match do |actual|
+    @parsed = Ruact::Spec::FlightWireParser.parse(actual)
+    @expected_rows = expected
+    @diffs = Ruact::Spec::FlightStructureDiff.compute(@parsed, expected)
+    @diffs.empty?
+  end
+
+  failure_message do |_actual|
+    if @diffs.length == 1
+      Ruact::Spec::FlightStructureDiff.format_single(@diffs.first)
+    else
+      Ruact::Spec::FlightStructureDiff.format_multi(@diffs, @parsed, @expected_rows)
+    end
+  end
+
+  failure_message_when_negated do |_actual|
+    "Expected output NOT to match the given Flight wire structure, but it did."
+  end
+
+  description do
+    "match Flight wire structure (#{expected.length} row(s))"
+  end
+end
+
+# `include_flight_row(predicate)` — Phase 2 ordering-independent presence matcher (Story 7.5).
+#
+# Parses the actual Flight wire output, then asserts at least one parsed row
+# satisfies the predicate hash. Subset semantics: only the keys present in
+# `predicate` are compared. Predicate keys must be one of `:id`, `:class`,
+# `:payload`, `:raw` — unknown keys raise upfront so typos don't silently
+# match every row. Values may be plain Ruby values (compared with `==`) or
+# RSpec argument matchers like `hash_including(...)` (compared with `===`).
+# Negation (`not_to`) is supported.
+#
+# @example
+#   expect(wire).to include_flight_row(class: :model, payload: hash_including("postId" => 42))
+RSpec::Matchers.define :include_flight_row do |predicate|
+  match do |actual|
+    Ruact::Spec::FlightStructureDiff.validate_predicate!(predicate)
+    @parsed = Ruact::Spec::FlightWireParser.parse(actual)
+    @predicate = predicate
+    @matched_idx = @parsed.find_index { |row| Ruact::Spec::FlightStructureDiff.row_matches?(row, predicate) }
+    !@matched_idx.nil?
+  end
+
+  failure_message do |_actual|
+    summary = @parsed.each_with_index.map do |row, i|
+      payload_snippet = row[:payload].inspect
+      payload_snippet = "#{payload_snippet[0, 80]}…" if payload_snippet.length > 80
+      "  [#{i}] id=#{row[:id].inspect}, class=#{row[:class]}, payload=#{payload_snippet}"
+    end.join("\n")
+    summary = "  (no rows parsed)" if @parsed.empty?
+
+    "Expected Flight output to include a row matching: #{predicate.inspect}.\nParsed rows:\n#{summary}"
+  end
+
+  failure_message_when_negated do |_actual|
+    "Expected Flight output NOT to include a row matching: #{predicate.inspect}, but row #{@matched_idx} matched."
+  end
+
+  description do
+    "include a Flight row matching #{predicate.inspect}"
+  end
+end

data/spec/support/matchers/flight_fixture_matcher_spec.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Specs for the three Flight wire matcher modes added in Story 7.5
+# (`match_flight_fixture`, `match_flight_structure`, `include_flight_row`).
+RSpec.describe "Flight wire matchers" do
+  # Captures an `ExpectationNotMetError` raised by the inner block so the
+  # spec can make multiple assertions on its message without resorting to a
+  # multi-line block chained off `raise_error`.
+  def capture_failure
+    yield
+    nil
+  rescue RSpec::Expectations::ExpectationNotMetError => e
+    e
+  end
+
+  describe "match_flight_fixture (existing snapshot mode)" do
+    let(:nil_wire) { "0:null\n" }
+
+    it "passes against canonical fixture content (regression check)" do
+      expect(nil_wire).to match_flight_fixture("nil")
+    end
+  end
+
+  describe "match_flight_structure" do
+    let(:simple_wire) { %(0:{"className":"box"}\n) }
+    let(:two_row_wire) { %(1:I["/L.jsx","L",["/L.jsx"]]\n0:["$","$L1",null,{}]\n) }
+
+    it "passes when the actual wire matches a single-row expected structure" do
+      expect(simple_wire).to match_flight_structure([
+                                                      { id: 0, class: :model, payload: { "className" => "box" } }
+                                                    ])
+    end
+
+    it "passes for a two-row mixed import + model sequence" do
+      expect(two_row_wire).to match_flight_structure([
+                                                       { id: 1, class: :import, payload: ["/L.jsx", "L", ["/L.jsx"]] },
+                                                       { id: 0, class: :model, payload: ["$", "$L1", nil, {}] }
+                                                     ])
+    end
+
+    it "fails with a missing-row message when actual has fewer rows than expected" do
+      err = capture_failure do
+        expect(simple_wire).to match_flight_structure([
+                                                        { id: 0, class: :model, payload: { "className" => "box" } },
+                                                        { id: 1, class: :import, payload: [] }
+                                                      ])
+      end
+
+      expect(err.message).to include("Expected row 1 (import) was not produced.")
+      expect(err.message).to include("expected: {")
+    end
+
+    it "produces the AC3 verbatim row-indexed diff for a single-field semantic regression" do
+      broken_wire = %(0:["$X","div",null,{"className":"box","children":"hi"}]\n)
+      expected_payload = ["$", "div", nil, { "className" => "box", "children" => "hi" }]
+      got_payload      = ["$X", "div", nil, { "className" => "box", "children" => "hi" }]
+      expected_structure = [{ id: 0, class: :model, payload: expected_payload }]
+
+      # Hash#inspect changed between Ruby 3.3 (`{"a"=>"b"}`) and Ruby 3.4
+      # (`{"a" => "b"}`). The AC3 contract is "values shown via .inspect" —
+      # so we render the expected message with the same .inspect the matcher
+      # uses at runtime, keeping the spec stable across the CI Ruby matrix.
+      expected_message = <<~MSG.strip
+        Expected Flight output to match structure.
+
+        Row 0 (model) differs at .payload[0]:
+          expected: "$"
+          got:      "$X"
+
+        Row 0 (model) full diff:
+          expected: #{expected_payload.inspect}
+          got:      #{got_payload.inspect}
+      MSG
+
+      expect do
+        expect(broken_wire).to match_flight_structure(expected_structure)
+      end.to raise_error(RSpec::Expectations::ExpectationNotMetError, expected_message)
+    end
+
+    it "fails with an unexpected-row message when actual has extra rows" do
+      err = capture_failure do
+        expect(two_row_wire).to match_flight_structure([
+                                                         { id: 1, class: :import,
+                                                           payload: ["/L.jsx", "L", ["/L.jsx"]] }
+                                                       ])
+      end
+
+      expect(err.message).to include("Got unexpected row 1 (model)")
+    end
+
+    it "tolerates cosmetic JSON key reordering in payload hashes (AC4)" do
+      canonical = %(0:{"a":1,"b":2}\n)
+      perturbed = %(0:{"b":2,"a":1}\n)
+      expected_structure = [{ id: 0, class: :model, payload: { "a" => 1, "b" => 2 } }]
+
+      expect(canonical).to match_flight_structure(expected_structure)
+      expect(perturbed).to match_flight_structure(expected_structure)
+    end
+
+    it "passes negation when the structure does not match" do
+      expect(simple_wire).not_to match_flight_structure([
+                                                          { id: 0, class: :model, payload: { "className" => "circle" } }
+                                                        ])
+    end
+
+    # AC1: "multiple I rows are an unordered set". The expected list below
+    # reverses the import order vs the wire — the structural matcher must
+    # still consider this a match because import-row ordering is not
+    # protocol-significant within the import class.
+    it "treats import rows as an unordered set (AC1)" do
+      wire = %(1:I["/A.jsx","A",["/A.jsx"]]\n2:I["/B.jsx","B",["/B.jsx"]]\n0:["$","$L1",null,{}]\n)
+
+      expect(wire).to match_flight_structure([
+                                               { id: 2, class: :import, payload: ["/B.jsx", "B", ["/B.jsx"]] },
+                                               { id: 1, class: :import, payload: ["/A.jsx", "A", ["/A.jsx"]] },
+                                               { id: 0, class: :model, payload: ["$", "$L1", nil, {}] }
+                                             ])
+    end
+
+    # Defends against incomplete expected rows silently passing when actual
+    # payload happens to be nil (e.g. `{ id: 0, class: :model }` without
+    # `:payload` would otherwise satisfy any row whose payload is nil).
+    it "raises ArgumentError when an expected row is missing :payload" do
+      expect do
+        expect(simple_wire).to match_flight_structure([{ id: 0, class: :model }])
+      end.to raise_error(ArgumentError, /missing required keys.*:payload/)
+    end
+
+    it "raises ArgumentError when an expected row is missing :class" do
+      expect do
+        expect(simple_wire).to match_flight_structure([{ id: 0, payload: {} }])
+      end.to raise_error(ArgumentError, /missing required keys.*:class/)
+    end
+
+    # Multi-row failure message: the count, AC3 wording for missing/extra,
+    # plus a "✓" line for every matching row so the reader can confirm
+    # which rows passed (AC3 — "Other rows that match are summarized as
+    # `Row N (<class>): ✓`").
+    it "shows matching-row checkmarks alongside multi-row diffs" do
+      wire = %(1:I["/A.jsx","A",["/A.jsx"]]\n0:["$X","div",null,{}]\n)
+
+      err = capture_failure do
+        expect(wire).to match_flight_structure([
+                                                 { id: 1, class: :import, payload: ["/A.jsx", "A", ["/A.jsx"]] },
+                                                 { id: 0, class: :model, payload: ["$", "div", nil, {}] },
+                                                 { id: 2, class: :model, payload: ["$", "span", nil, {}] }
+                                               ])
+      end
+
+      expect(err.message).to include("Expected Flight output to match structure. 2 rows differ:")
+      expect(err.message).to include("Row 0 (import): ✓")
+      expect(err.message).to include("Row 1 (model) differs at .payload[0]:")
+      expect(err.message).to include("Expected row 2 (model) was not produced.")
+    end
+  end
+
+  describe "include_flight_row" do
+    let(:wire_with_post_id) do
+      %(1:I["/L.jsx","L",["/L.jsx"]]\n0:["$","$L1",null,{"postId":42}]\n)
+    end
+
+    it "matches when at least one row satisfies a hash_including payload predicate" do
+      expect(wire_with_post_id).to include_flight_row(
+        class: :model,
+        payload: include("postId" => 42)
+      )
+    end
+
+    it "fails listing parsed rows when no row matches the predicate" do
+      err = capture_failure do
+        expect(wire_with_post_id).to include_flight_row(
+          class: :model,
+          payload: include("postId" => 999)
+        )
+      end
+
+      expect(err.message).to include("Expected Flight output to include a row matching")
+      expect(err.message).to include("[0] id=1, class=import")
+      expect(err.message).to include("[1] id=0, class=model")
+    end
+
+    it "supports negation with not_to" do
+      expect(wire_with_post_id).not_to include_flight_row(class: :error)
+    end
+
+    it "fails negation when a row matches, naming the offending row index" do
+      expect do
+        expect(wire_with_post_id).not_to include_flight_row(class: :import)
+      end.to raise_error(RSpec::Expectations::ExpectationNotMetError, /but row 0 matched/)
+    end
+
+    it "supports array_including for the payload key" do
+      expect(wire_with_post_id).to include_flight_row(
+        class: :import,
+        payload: include("/L.jsx")
+      )
+    end
+
+    # AC4 fixture-mode failure proof. The structural matcher tolerates the
+    # cosmetic perturbation; the fixture matcher fails *positively* with the
+    # expected-vs-got diff visible — confirming fixture mode is the wire-
+    # format contract guard. This spec verifies the failure message rather
+    # than relying on a `not_to` shortcut (which would prove only that the
+    # matcher returned false, not that the failure is loud and informative).
+    it "demonstrates cosmetic-vs-fixture asymmetry — structure tolerates re-ordering, fixture fails loudly (AC4)" do
+      canonical_wire = %(0:{"debug":true,"count":5,"label":"x"}\n)
+      perturbed_wire = %(0:{"label":"x","count":5,"debug":true}\n)
+      expected_structure = [
+        { id: 0, class: :model, payload: { "debug" => true, "count" => 5, "label" => "x" } }
+      ]
+
+      err = capture_failure do
+        expect(perturbed_wire).to match_flight_fixture("hash")
+      end
+
+      aggregate_failures do
+        # Structural mode: both pass — JSON key reordering is cosmetic.
+        expect(canonical_wire).to match_flight_structure(expected_structure)
+        expect(perturbed_wire).to match_flight_structure(expected_structure)
+
+        # Fixture mode: canonical passes — the fixture file is the canonical
+        # wire bytes.
+        expect(canonical_wire).to match_flight_fixture("hash")
+
+        # Fixture mode against the perturbed wire fails *loudly* with the
+        # bytes-for-bytes diff so a human reviewer can see the cosmetic drift.
+        expect(err).to be_a(RSpec::Expectations::ExpectationNotMetError)
+        expect(err.message).to include("Expected output to match fixture at", "hash.txt", "Expected:", "Got:")
+        expect(err.message).to include(perturbed_wire.inspect)
+      end
+    end
+
+    # Predicate validation: an unknown key (typo) must raise immediately.
+    # Otherwise `row[:payloed]` returns nil and `nil == nil` would silently
+    # match every row, hiding broken specs.
+    it "raises ArgumentError when the predicate has an unknown key" do
+      expect do
+        expect(wire_with_post_id).to include_flight_row(payloed: { "postId" => 42 })
+      end.to raise_error(ArgumentError, /unknown keys.*:payloed/)
+    end
+
+    it "raises ArgumentError when given an empty predicate" do
+      expect do
+        expect(wire_with_post_id).to include_flight_row({})
+      end.to raise_error(ArgumentError, /predicate cannot be empty/)
+    end
+  end
+end