Skip to content

Commit 6177112

Browse files
mcmiremcmire
committed
Update README
[ci skip]
1 parent 9b17e39 commit 6177112

File tree

1 file changed

+127
-95
lines changed

1 file changed

+127
-95
lines changed

‎README.md

Lines changed: 127 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -8,134 +8,166 @@
88
[hound-badge]: https://img.shields.io/badge/Reviewed_by-Hound-8E64B0.svg
99
[hound]: https://houndci.com
1010

11-
SuperDiff is a utility that helps you diff two complex data structures in Ruby,
11+
## Concept
12+
13+
SuperDiff is a utility that helps you diff two complex data structures in Ruby
1214
and gives you helpful output to show you exactly how the two data structures
1315
differ.
1416

15-
## Installation
16-
17-
Add the following line to your Gemfile:
18-
19-
gem "super_diff"
20-
21-
## Usage
22-
2317
Let's say you have two hashes and you want to compare them. Perhaps your first
2418
hash looks like this:
2519

26-
expected = {
27-
customer: {
28-
name: "Marty McFly",
29-
shipping_address: {
30-
line_1: "123 Main St.",
31-
city: "Hill Valley",
32-
state: "CA",
33-
zip: "90382",
34-
},
35-
},
36-
items: [
37-
{
38-
name: "Fender Stratocaster",
39-
cost: 100_000,
40-
options: ["red", "blue", "green"],
41-
},
42-
{ name: "Chevy 4x4" },
43-
],
44-
}
20+
``` ruby
21+
expected = {
22+
customer: {
23+
name: "Marty McFly",
24+
shipping_address: {
25+
line_1: "123 Main St.",
26+
city: "Hill Valley",
27+
state: "CA",
28+
zip: "90382",
29+
},
30+
},
31+
items: [
32+
{
33+
name: "Fender Stratocaster",
34+
cost: 100_000,
35+
options: ["red", "blue", "green"],
36+
},
37+
{ name: "Chevy 4x4" },
38+
],
39+
}
40+
```
4541

4642
and your second hash looks like this:
4743

48-
actual = {
49-
customer: {
50-
name: "Marty McFly, Jr.",
51-
shipping_address: {
52-
line_1: "456 Ponderosa Ct.",
53-
city: "Hill Valley",
54-
state: "CA",
55-
zip: "90382",
56-
},
57-
},
58-
items: [
59-
{
60-
name: "Fender Stratocaster",
61-
cost: 100_000,
62-
options: ["red", "blue", "green"],
63-
},
64-
{ name: "Mattel Hoverboard" },
65-
],
66-
}
44+
``` ruby
45+
actual = {
46+
customer: {
47+
name: "Marty McFly, Jr.",
48+
shipping_address: {
49+
line_1: "456 Ponderosa Ct.",
50+
city: "Hill Valley",
51+
state: "CA",
52+
zip: "90382",
53+
},
54+
},
55+
items: [
56+
{
57+
name: "Fender Stratocaster",
58+
cost: 100_000,
59+
options: ["red", "blue", "green"],
60+
},
61+
{ name: "Mattel Hoverboard" },
62+
],
63+
}
64+
```
6765

6866
If you want to know what the difference between them is, you could say:
6967

70-
require "super_diff"
71-
72-
puts SuperDiff::EqualityMatcher.call(expected, actual)
68+
``` ruby
69+
SuperDiff::EqualityMatcher.call(expected, actual)
70+
```
7371

74-
This will print out the following:
72+
This will give you the following string:
7573

76-
Differing hashes.
74+
```
75+
Differing hashes.
7776
78-
Expected: { customer: { name: "Marty McFly", shipping_address: { line_1: "123 Main St.", city: "Hill Valley", state: "CA", zip: "90382" } }, items: [{ name: "Fender Stratocaster", cost: 100000, options: ["red", "blue", "green"] }, { name: "Chevy 4x4" }] }
79-
Got: { customer: { name: "Marty McFly, Jr.", shipping_address: { line_1: "456 Ponderosa Ct.", city: "Hill Valley", state: "CA", zip: "90382" } }, items: [{ name: "Fender Stratocaster", cost: 100000, options: ["red", "blue", "green"] }, { name: "Mattel Hoverboard" }] }
80-
81-
Diff:
77+
Expected: { customer: { name: "Marty McFly", shipping_address: { line_1: "123 Main St.", city: "Hill Valley", state: "CA", zip: "90382" } }, items: [{ name: "Fender Stratocaster", cost: 100000, options: ["red", "blue", "green"] }, { name: "Chevy 4x4" }] }
78+
Got: { customer: { name: "Marty McFly, Jr.", shipping_address: { line_1: "456 Ponderosa Ct.", city: "Hill Valley", state: "CA", zip: "90382" } }, items: [{ name: "Fender Stratocaster", cost: 100000, options: ["red", "blue", "green"] }, { name: "Mattel Hoverboard" }] }
8279
80+
Diff:
8381
82+
{
83+
customer: {
84+
- name: "Marty McFly",
85+
+ name: "Marty McFly, Jr.",
86+
shipping_address: {
87+
- line_1: "123 Main St.",
88+
+ line_1: "456 Ponderosa Ct.",
89+
city: "Hill Valley",
90+
state: "CA",
91+
zip: "90382"
92+
}
93+
},
94+
items: [
8495
{
85-
customer: {
86-
- name: "Marty McFly",
87-
+ name: "Marty McFly, Jr.",
88-
shipping_address: {
89-
- line_1: "123 Main St.",
90-
+ line_1: "456 Ponderosa Ct.",
91-
city: "Hill Valley",
92-
state: "CA",
93-
zip: "90382"
94-
}
95-
},
96-
items: [
97-
{
98-
name: "Fender Stratocaster",
99-
cost: 100000,
100-
options: ["red", "blue", "green"]
101-
},
102-
{
103-
- name: "Chevy 4x4"
104-
+ name: "Mattel Hoverboard"
105-
}
106-
]
96+
name: "Fender Stratocaster",
97+
cost: 100000,
98+
options: ["red", "blue", "green"]
99+
},
100+
{
101+
- name: "Chevy 4x4"
102+
+ name: "Mattel Hoverboard"
107103
}
104+
]
105+
}
106+
```
107+
108+
When printed to a terminal, this will display in color, so the "expected" value
109+
in the summary and deleted lines in the diff will appear in red, while the
110+
"actual" value in the summary and inserted lines in the diff will appear in
111+
green.
112+
113+
By the way, SuperDiff doesn't just work with hashes, but arrays as well as other
114+
objects, too!
115+
116+
## Usage
108117

109-
This works with arrays, too!
118+
There are two ways to use this gem. One way is to use the API methods that this
119+
gem provides, such as the method presented above.
110120

111-
## Usage with RSpec
121+
However, this gem was really designed for use specifically with RSpec. In recent
122+
years, RSpec has added a feature where if you're comparing two objects in a test
123+
and your test fails, you will see a diff between those objects (provided the
124+
objects are large enough). However, this diff is not always the most helpful.
125+
It's very common when writing tests for API endpoints to work with giant JSON
126+
hashes, and RSpec's diffs are not sufficient in highlighting changes between
127+
such structures. Therefore, this gem provides an integration layer where you can
128+
replace RSpec's differ with SuperDiff.
112129

113-
This gem was specifically designed for use with RSpec. RSpec has this great
114-
feature where if you're using `eq` or some other built-in matcher to compare two
115-
objects, and your test fails, you may see a diff between those objects. However,
116-
this diff is not always the most helpful. It's very common when writing tests
117-
for API endpoints to work with large data structures, and these diffs are not
118-
sufficient in highlighting changes between such structures.
130+
To get started, add the gem to your Gemfile under the `test` group:
119131

120-
To fix this, this gem replaces the default differ in RSpec with SuperDiff so
121-
that you get diffs such as the example provided above. To make use of this,
122-
simply add this line to your `spec_helper`:
132+
``` ruby
133+
gem "super_diff"
134+
```
123135

124-
require "super_diff/rspec"
136+
Then, open up `spec_helper` and add this line somewhere:
137+
138+
``` ruby
139+
require "super_diff/rspec"
140+
```
141+
142+
Now try writing a test using `eq` to compare two large data structures, and you
143+
should see a diff similar to the one given above.
125144

126145
## Contributing
127146

128147
If you encounter a bug or have an idea for how this could be better, I'm all
129-
ears! Feel free to create an issue or post a PR and I'll take a look at it when
130-
I get a chance.
148+
ears! Feel free to create an issue.
131149

132-
To get set up locally, clone this repo and then run:
150+
If you'd like to submit a PR instead, here's how to get started. First, fork
151+
this repo and then run:
133152

134-
bundle install
153+
```
154+
bundle install
155+
```
135156

136157
This will install dependencies. From here you can run all of the tests:
137158

138-
bundle exec rake
159+
```
160+
bundle exec rake
161+
```
162+
163+
Or a single test:
164+
165+
```
166+
bundle exec rspec spec/acceptance/...
167+
bundle exec rspec spec/unit/...
168+
```
169+
170+
Finally, submit your PR and I'll take a look at it when I get a chance.
139171

140172
## Copyright/License
141173

0 commit comments

Comments
 (0)