Skip to content
View differences between complex data structures in RSpec.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
LICENSE Update README, add LICENSE Oct 2, 2018

SuperDiff Gem Version Build Status Downloads Hound

SuperDiff is a gem that hooks into RSpec to intelligently display the differences between two data structures of any type.

📢 See what's changed in the latest version (0.2.0).


The primary motivation behind this gem is to vastly improve upon RSpec's built-in diffing capabilities.

Sometimes, 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 — nested data structures (arrays, hashes, and full-scale objects), such as what you might work with when developing API endpoints or testing methods that make database calls and return a set of model objects — 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: "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: ["red", "blue", "green"]
    { name: "Mattel Hoverboard" }

expected = {
  customer: {
    person: "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: ["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


Want to try out this gem for yourself? As with most development-related gems, there are a couple ways depending on your type of project:

Rails apps

If you're developing a Rails app, add the following to your Gemfile:

gem "super_diff"

After running bundle install, add the following to your rails_helper:

require "super_diff/rspec-rails"

You're done!


If you're developing a library, add the following to your gemspec:

spec.add_development_dependency "super_diff"

Now add the following to your spec_helper:

require "super_diff/rspec"

You're done!


As capable as this library is, it doesn't know how to deal with every kind of object out there. You might find it necessary to instruct the gem on how to diff your object. To do this, you can use a configuration block. Simply add this to your test helper file (rails_helper or spec_helper):

SuperDiff::RSpec.configure do |config|

(More info here in the future on adding a custom differ, operational sequencer, and diff formatter. Also explanations on what these are.)


If you encounter a bug or have an idea for how this could be better, feel free to create an issue.

If you'd like to submit a PR instead, here's how to get started. First, fork this repo. Then, when you've cloned your fork, run:


This will install various dependencies. After this, you can run all of the tests:

bundle exec rake

If you update one of the tests, you can run it like so:

bin/rspec spec/integration/...
bin/rspec spec/unit/...

Finally, submit your PR and I'll take a look at it when I get a chance.


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


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

Thank you so much!


© 2018-2019 Elliot Winkler, released under the MIT license.

You can’t perform that action at this time.