super_diff

A more helpful way to view differences between complex data structures in RSpec.

612
29
Ruby

SuperDiff Gem Version Build Status Downloads IssueHunt

SuperDiff is a Ruby gem
which is designed to display the differences between two objects of any type
in a familiar and intelligent fashion.

šŸ“¢ See whatā€™s changed in recent versions.

Introduction

The primary motivation behind this gem
is to vastly improve upon RSpecā€™s built-in diffing capabilities.
RSpec has many nice features,
and one of them is that whenever you use a matcher such as eq, match, include, or have_attributes,
you will get a diff of the two data structures you are trying to match against.
This is great if all you want to do is compare multi-line strings.
But if you want to compare other, more ā€œreal worldā€ kinds of values such as API or database data,
then you are out of luck.
Since RSpec merely runs your expected and actual values through Rubyā€™s PrettyPrinter library
and then performs a diff of these strings,
the output it produces leaves much to be desired.

For instance, letā€™s say you wanted to compare these two hashes:

actual = {
  customer: {
    person: SuperDiff::Test::Person.new(name: "Marty McFly, Jr.", age: 17),
    shipping_address: {
      line_1: "456 Ponderosa Ct.",
      city: "Hill Valley",
      state: "CA",
      zip: "90382"
    }
  },
  items: [
    { name: "Fender Stratocaster", cost: 100_000, options: %w[red blue green] },
    { name: "Mattel Hoverboard" }
  ]
}

expected = {
  customer: {
    person: SuperDiff::Test::Person.new(name: "Marty McFly", age: 17),
    shipping_address: {
      line_1: "123 Main St.",
      city: "Hill Valley",
      state: "CA",
      zip: "90382"
    }
  },
  items: [
    { name: "Fender Stratocaster", cost: 100_000, options: %w[red blue green] },
    { name: "Chevy 4x4" }
  ]
}

If, somewhere in a test, you were to say:

expect(actual).to eq(expected)

You would get output that looks like this:

Before super_diff

What this library does
is to provide a diff engine
that knows how to figure out the differences between any two data structures
and display them in a sensible way.
So, using the example above,
youā€™d get this instead:

After super_diff

Installation & Usage

šŸ“˜ For more on how to install and use SuperDiff,
read the user documentation.

Support

My goal for this library is to improve your development experience.
If this is not the case,
and you encounter a bug or have a suggestion,
feel free to create an issue.
Iā€™ll try to respond to it as soon as I can!

Contributing

Any code contributions to improve this library are welcome!
Please see the contributing document
for more on how to do that.

Sponsoring

If thereā€™s a change you want implemented, you can choose to sponsor that change!
super_diff is set up on IssueHunt,
so feel free to search for an existing issue (or make your own)
and add a bounty.
Iā€™ll get notified right away!

Compatibility

super_diff is tested to work with
Ruby >= 3.x,
RSpec 3.x,
and Rails >= 6.x.

Inspiration/Thanks

In developing this gem
I made use of or was heavily inspired by these libraries:

Thank you to the authors of these libraries!

Author/License

SuperDiff was created and is maintained by Elliot Winkler.
It is released under the MIT license.