minitest-hashdiff 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 62ffed814bbebbcf613fa11125780d0b09fd1c02959718115b203cdd66fcc436
+  data.tar.gz: 5555f3146e81cd840b5559c9d18ee0db1055810d64a6acf359647a3823f16fa3
+SHA512:
+  metadata.gz: 5ebbf349e05b283ea574c0673e8696ef6a9501bb516186a9da54a858215e2fbf2d7660b0b29d77c5b50edd97be0d18ad7f58e3a135c34c9549a0b935ecc530e4
+  data.tar.gz: 94382db83217c19236e4eeccce4f98404767efa7e617ba68d75a6592a707026282cfdcee13a06f50243d4444d1af0cf7be7c5af3a496e912d159917fbc1d236d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lachlan Young
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,49 @@
+# minitest-hashdiff
+
+When a Minitest assertion fails on two hashes, the default output is two nearly identical walls of `inspect` text, and the one value that changed is somewhere in there. This gem replaces that with a report of exactly what changed.
+
+Before:
+
+```
+Expected: {"uid"=>"user@example.test", "active"=>true, "role"=>"admin", "last_login"=>nil}
+  Actual: {"uid"=>"user@example.test", "active"=>true, "role"=>"editor", "last_login"=>"2026-07-10"}
+```
+
+After:
+
+```
+Hash diff (expected => actual):
+  changed "last_login": nil => "2026-07-10" (nil -> String)
+  changed "role": "admin" => "editor"
+```
+
+Type changes are flagged explicitly because they are the differences most likely to cause a downstream bug and the easiest to miss: `nil` to `String`, `Integer` to `Float`, and symbol keys versus string keys (which are different keys in Ruby, even though they look almost the same).
+
+## Install
+
+```ruby
+# Gemfile
+group :test do
+  gem "minitest-hashdiff"
+end
+```
+
+That's it for almost everyone: Rails and any app using `Bundler.require` loads the gem automatically, and on minitest 5 the plugin also self-discovers with no Bundler involved. The one exception: minitest 6 made plugin loading opt-in, so if you are on minitest 6 *and* not using `Bundler.require`, add `require "minitest/hashdiff"` to your test helper.
+
+Only `assert_equal` failures where both sides are hashes are affected; every other assertion behaves exactly as before.
+
+## What the report covers
+
+- Changed values, with before and after
+- Added and removed keys
+- Explicit type changes
+- Nested hashes and arrays, with the path to each difference
+- Keys sorted, so ordering noise never masquerades as a real change
+
+## Prefer a visual diff?
+
+This gem's output is built for terminals. For a side-by-side visual comparison of two large hashes, paste your failing test output into [rubyhash.dev](https://rubyhash.dev), which does the same parsing and type detection in your browser, with nothing uploaded.
+
+## License
+
+MIT.

data/lib/minitest/hashdiff/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Minitest
+  module HashDiff
+    VERSION = "0.1.1"
+  end
+end

data/lib/minitest/hashdiff.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "minitest"
+require "minitest/test"
+require_relative "hashdiff/version"
+
+module Minitest
+  # Formats the difference between two hashes as a readable, sorted,
+  # type-aware report instead of two walls of inspect output.
+  module HashDiff
+    module_function
+
+    def display_type(value)
+      case value
+      when nil then "nil"
+      when true, false then "Boolean"
+      when Integer then "Integer"
+      when Float then "Float"
+      when String then "String"
+      when Symbol then "Symbol"
+      when Hash then "Hash"
+      when Array then "Array"
+      else value.class.name
+      end
+    end
+
+    # Returns a readable diff report, or nil when nothing differs.
+    def format(expected, actual)
+      lines = []
+      walk(expected, actual, nil, lines)
+      return nil if lines.empty?
+
+      "Hash diff (expected => actual):\n#{lines.join("\n")}"
+    end
+
+    def walk(expected, actual, path, lines)
+      if expected.is_a?(Hash) && actual.is_a?(Hash)
+        keys = (expected.keys | actual.keys).sort_by(&:inspect)
+        keys.each do |key|
+          key_path = path ? "#{path} > #{key.inspect}" : key.inspect
+          if !expected.key?(key)
+            lines << "  added   #{key_path}: #{actual[key].inspect}"
+          elsif !actual.key?(key)
+            lines << "  removed #{key_path}: #{expected[key].inspect}"
+          elsif expected[key] != actual[key]
+            walk(expected[key], actual[key], key_path, lines)
+          end
+        end
+      elsif expected.is_a?(Array) && actual.is_a?(Array)
+        [expected.size, actual.size].max.times do |i|
+          item_path = "#{path}[#{i}]"
+          if i >= expected.size
+            lines << "  added   #{item_path}: #{actual[i].inspect}"
+          elsif i >= actual.size
+            lines << "  removed #{item_path}: #{expected[i].inspect}"
+          elsif expected[i] != actual[i]
+            walk(expected[i], actual[i], item_path, lines)
+          end
+        end
+      else
+        expected_type = display_type(expected)
+        actual_type = display_type(actual)
+        note = expected_type == actual_type ? "" : " (#{expected_type} -> #{actual_type})"
+        lines << "  changed #{path}: #{expected.inspect} => #{actual.inspect}#{note}"
+      end
+    end
+  end
+
+  # Prepended so assert_equal failures on two hashes show the readable
+  # report instead of the default diff.
+  module HashDiffAssertions
+    def diff(exp, act)
+      if exp.is_a?(Hash) && act.is_a?(Hash) && exp != act
+        Minitest::HashDiff.format(exp, act) || super
+      else
+        super
+      end
+    end
+  end
+
+  # Prepend into the class, not just the Assertions module: before Ruby 3.0,
+  # prepending into an already-included module does not propagate to its
+  # includers, so Assertions alone silently misses on Ruby 2.7.
+  Test.prepend(HashDiffAssertions)
+  Assertions.prepend(HashDiffAssertions)
+end

data/lib/minitest/hashdiff_plugin.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Minitest auto-discovers minitest/*_plugin.rb files across installed gems,
+# so simply having this gem in the bundle activates readable hash diffs.
+# No require needed in your test helper.
+require "minitest/hashdiff"
+
+module Minitest
+  def self.plugin_hashdiff_init(_options); end
+end

data/lib/minitest-hashdiff.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name, so Bundler.require (the default in
+# Rails and most apps) activates the gem even where Minitest's plugin
+# autodiscovery does not run. Requiring twice is harmless.
+require "minitest/hashdiff"

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: minitest-hashdiff
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Lachlan Young
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: 'When assert_equal fails on two hashes, show exactly what changed: added,
+  removed, and changed keys with type-change detection (nil to String, Integer to
+  Float, symbol vs string keys), instead of two walls of inspect output. Zero configuration,
+  Minitest loads it automatically. From the maker of rubyhash.dev.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/minitest-hashdiff.rb
+- lib/minitest/hashdiff.rb
+- lib/minitest/hashdiff/version.rb
+- lib/minitest/hashdiff_plugin.rb
+homepage: https://rubyhash.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://rubyhash.dev
+  documentation_uri: https://rubyhash.dev/blog/minitest-hash-diff-hard-to-read
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Readable hash diffs for failing Minitest assertions
+test_files: []