README.md

rspec-difftastic

This gem allows you to use difftastic-ruby in place of RSpec's default differ.

This is a quick patch implementation and may not cover edge cases.

Motivation

When an RSpec test fails, the output includes so much red text that reading the diff takes more time than it should.

A few attempts have been made to improve the developer experience with RSpec failures (e.g., super_diff and a new default differ).

Integrating difftastic-ruby with RSpec makes another attempt at outputting diffs that are easier to read upon RSpec failures.

Diff Examples for Comparison

RSpec (default differ)

ruby example-rspec-diff.rb

So much red to scan.

RSpec with super_diff

ruby example-rspec-diff-with-super_diff.rb

Red is replaced with white, magenta, and yellow - easily readible!

RSpec with difftastic

ruby example-rspec-diff-with-rspec-difftastic.rb

Red and green is side-by-side. Word-level diff to highlight that the last name is different.

Matchers

Here are two example that use matchers for comparison.

    it do
      expect(
        unknown: 'any value is acceptable',
        number: 1,
      ).to match(
        unknown: anything,
        number: '1',
      )
    end

    it do
      expect(
        nested_hash: { some_key: :some_value },
        number: 1,
      ).to match(
        nested_hash: hash_including(:some_key),
        number: '1',
      )
    end

RSpec (default differ)

The lack of emphasis on the problem ("1" vs 1) may have some developers wondering if they're incorrectly using matchers.

RSpec with super_diff

In the first diff, super_diff arguably makes the diff worse by outputting the matcher's class name. In the second diff, the matcher is cleanly left out of the diff.

RSpec with difftastic

In the first diff rspec-difftastic diff strings and objects, so the matcher class name is shown, and can lead to being a distracting red herring especially if the reader is accustomed to relying on the +/- notation of RSpec diffs.

Development & Contributing

Install the development dependencies:

bundle install

Confirm the spec suite is passing:

bundle exec rspec

Make your modifications and submit a PR.