From c5f6ce6c65cb2ac9256246bd3aabf95754f89487 Mon Sep 17 00:00:00 2001
From: Elliot Winkler <elliot.winkler@gmail.com>
Date: Sat, 10 Feb 2024 15:26:26 -0700
Subject: [PATCH] Use correct terminology for RSpec matchers (#220)

There are four kinds of matchers which are referred to within the RSpec
source code:

- **(Built-in) matchers:** Also simply shortened to "matcher", these are
instances of RSpec::Matchers::BuiltIn::Base and are created via
convenience methods which are available in all RSpec example groups
(e.g. `eq` for RSpec::Matchers::BuiltIn::Eq, `include` for
RSpec::Matchers::BuiltIn::Include, etc.).
- **Custom matchers:** These are matchers that end users can create via
`RSpec::Matchers.define`. They are not instances of
RSpec::Matchers::BuiltIn::Base, but rather
RSpec::Matchers::DSL::Matcher.
- **Aliased matchers:** These are matchers which act just like other
matchers but are created via a different method name and hence have a
different description to match. For instance, `include` has four
aliases: `a_collection_including`, `a_string_including`,
`a_hash_including`, and `including`. The objects that such methods
return are actually an instance of RSpec::Matchers::AliasedMatcher and
wrap the original matcher object.
- **Describable matchers:** These are matchers which satisfy a minimal
matcher interface including `description`, so they effectively match
both built-in and custom matchers. More formally, they are objects which
pass the check that `RSpec::Matchers.is_a_describable_matcher?` makes:
that is, they are either instances of RSpec::Matchers::BuiltIn::Base, or
they respond to `matches?` and `description` and either
`failure_message` or `failure_message_when_negated`.

So far in the SuperDiff code we have been using the phrase "fuzzy
object" to describe an aliased matcher. That was derived from
`rspec-support`'s FuzzyMatcher class, which compares two objects with
the consideration that either could be an RSpec matcher object. But
that's not an official term, and so it could be confusing if we use
that.

This commit corrects this term to simply "RSpec matcher object", except
in the case where it was being used to test whether a value was an
aliased matcher, in which case that term is now used.
---
 lib/super_diff/rspec.rb                          | 16 ++++++++--------
 .../rspec/contain_exactly_matcher_spec.rb        |  2 +-
 .../rspec/have_attributes_matcher_spec.rb        |  4 ++--
 .../rspec/match_array_matcher_spec.rb            |  2 +-
 .../rspec/raise_error_matcher_spec.rb            |  8 ++++----
 spec/unit/rspec/matchers/raise_error_spec.rb     |  8 ++++----
 spec/unit/rspec/object_inspection_spec.rb        |  4 ++--
 7 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/lib/super_diff/rspec.rb b/lib/super_diff/rspec.rb
index 8a2c9dd6..e9a09692 100644
--- a/lib/super_diff/rspec.rb
+++ b/lib/super_diff/rspec.rb
@@ -20,7 +20,7 @@ def self.configuration
     end
 
     def self.a_hash_including_something?(value)
-      fuzzy_object?(value) && value.respond_to?(:expecteds) &&
+      aliased_matcher?(value) && value.respond_to?(:expecteds) &&
         value.expecteds.one? && value.expecteds.first.is_a?(::Hash)
     end
 
@@ -31,7 +31,7 @@ def self.hash_including_something?(value)
     end
 
     def self.a_collection_including_something?(value)
-      fuzzy_object?(value) && value.respond_to?(:expecteds) &&
+      aliased_matcher?(value) && value.respond_to?(:expecteds) &&
         !(value.expecteds.one? && value.expecteds.first.is_a?(::Hash))
     end
 
@@ -40,17 +40,17 @@ def self.array_including_something?(value)
     end
 
     def self.an_object_having_some_attributes?(value)
-      fuzzy_object?(value) &&
+      aliased_matcher?(value) &&
         value.base_matcher.is_a?(::RSpec::Matchers::BuiltIn::HaveAttributes)
     end
 
     def self.a_collection_containing_exactly_something?(value)
-      fuzzy_object?(value) &&
+      aliased_matcher?(value) &&
         value.base_matcher.is_a?(::RSpec::Matchers::BuiltIn::ContainExactly)
     end
 
     def self.a_kind_of_something?(value)
-      fuzzy_object?(value) &&
+      aliased_matcher?(value) &&
         value.base_matcher.is_a?(::RSpec::Matchers::BuiltIn::BeAKindOf)
     end
 
@@ -61,7 +61,7 @@ def self.kind_of_something?(value)
     end
 
     def self.an_instance_of_something?(value)
-      fuzzy_object?(value) &&
+      aliased_matcher?(value) &&
         value.base_matcher.is_a?(::RSpec::Matchers::BuiltIn::BeAnInstanceOf)
     end
 
@@ -72,11 +72,11 @@ def self.instance_of_something?(value)
     end
 
     def self.a_value_within_something?(value)
-      fuzzy_object?(value) &&
+      aliased_matcher?(value) &&
         value.base_matcher.is_a?(::RSpec::Matchers::BuiltIn::BeWithin)
     end
 
-    def self.fuzzy_object?(value)
+    def self.aliased_matcher?(value)
       value.is_a?(::RSpec::Matchers::AliasedMatcher)
     end
 
diff --git a/spec/integration/rspec/contain_exactly_matcher_spec.rb b/spec/integration/rspec/contain_exactly_matcher_spec.rb
index 5b08ffc1..c9f45c3f 100644
--- a/spec/integration/rspec/contain_exactly_matcher_spec.rb
+++ b/spec/integration/rspec/contain_exactly_matcher_spec.rb
@@ -308,7 +308,7 @@
       end
     end
 
-    context "and some of them are fuzzy objects" do
+    context "and some of them are RSpec matchers" do
       it "produces the correct failure message" do
         as_both_colored_and_uncolored do |color_enabled|
           snippet = <<~TEST.strip
diff --git a/spec/integration/rspec/have_attributes_matcher_spec.rb b/spec/integration/rspec/have_attributes_matcher_spec.rb
index f06cc0b0..02fa673e 100644
--- a/spec/integration/rspec/have_attributes_matcher_spec.rb
+++ b/spec/integration/rspec/have_attributes_matcher_spec.rb
@@ -347,8 +347,8 @@
       end
     end
 
-    # TODO: Add as many fuzzy matchers as we can here
-    context "that contains fuzzy matcher objects instead of an object" do
+    # TODO: Add as many RSpec matchers as we can here
+    context "that contains RSpec matchers" do
       it "displays the hash correctly" do
         as_both_colored_and_uncolored do |color_enabled|
           snippet = <<~TEST.strip
diff --git a/spec/integration/rspec/match_array_matcher_spec.rb b/spec/integration/rspec/match_array_matcher_spec.rb
index 24ce7c0d..9383e825 100644
--- a/spec/integration/rspec/match_array_matcher_spec.rb
+++ b/spec/integration/rspec/match_array_matcher_spec.rb
@@ -310,7 +310,7 @@
       end
     end
 
-    context "and some of them are fuzzy objects" do
+    context "and some of them are RSpec matchers" do
       it "produces the correct failure message" do
         as_both_colored_and_uncolored do |color_enabled|
           snippet = <<~TEST.strip
diff --git a/spec/integration/rspec/raise_error_matcher_spec.rb b/spec/integration/rspec/raise_error_matcher_spec.rb
index 7c65cfee..cc801a3c 100644
--- a/spec/integration/rspec/raise_error_matcher_spec.rb
+++ b/spec/integration/rspec/raise_error_matcher_spec.rb
@@ -1006,7 +1006,7 @@
     end
   end
 
-  context "given a simple RSpec fuzzy object" do
+  context "given a simple RSpec matcher" do
     context "when used in the positive" do
       context "when the block raises a different error than what is given" do
         context "when the expected error and/or actual message is short" do
@@ -1184,7 +1184,7 @@
     end
   end
 
-  context "given only a simple RSpec fuzzy object and string message" do
+  context "given only a simple RSpec matcher and string message" do
     context "when used in the positive" do
       context "when the block raises a different error than what is given" do
         it "produces the correct failure message" do
@@ -1260,7 +1260,7 @@
     end
   end
 
-  context "given only a simple RSpec fuzzy object and regexp message" do
+  context "given only a simple RSpec matcher and regexp message" do
     context "when used in the positive" do
       context "when the block raises a different error than what is given" do
         it "produces the correct failure message" do
@@ -1338,7 +1338,7 @@
 
   # NOTE: No need to test this using a string or regexp message — we've tested
   # it enough above
-  context "given a compound RSpec fuzzy object" do
+  context "given a compound RSpec matcher" do
     context "when used in the positive" do
       context "when the block raises a different error than what is given" do
         context "when the expected error and/or actual message is short" do
diff --git a/spec/unit/rspec/matchers/raise_error_spec.rb b/spec/unit/rspec/matchers/raise_error_spec.rb
index e809ace3..4c33e266 100644
--- a/spec/unit/rspec/matchers/raise_error_spec.rb
+++ b/spec/unit/rspec/matchers/raise_error_spec.rb
@@ -42,7 +42,7 @@
       end
     end
 
-    context "given a simple RSpec fuzzy object" do
+    context "given a simple RSpec matcher" do
       it "returns the correct output" do
         expect(raise_error(a_kind_of(RuntimeError)).description).to eq(
           "raise #<a kind of RuntimeError>"
@@ -50,7 +50,7 @@
       end
     end
 
-    context "given a simple RSpec fuzzy object and string message" do
+    context "given a simple RSpec matcher and string message" do
       it "returns the correct output" do
         expect(raise_error(a_kind_of(RuntimeError), "boo").description).to eq(
           'raise #<a kind of RuntimeError> with message "boo"'
@@ -58,7 +58,7 @@
       end
     end
 
-    context "given a simple RSpec fuzzy object and regexp message" do
+    context "given a simple RSpec matcher and regexp message" do
       it "returns the correct output" do
         expect(raise_error(a_kind_of(RuntimeError), /boo/i).description).to eq(
           "raise #<a kind of RuntimeError> with message matching /boo/i"
@@ -66,7 +66,7 @@
       end
     end
 
-    context "given a compound RSpec fuzzy object" do
+    context "given a compound RSpec matcher" do
       it "returns the correct output" do
         expect(raise_error(a_kind_of(Array).or eq(true)).description).to eq(
           "raise #<a kind of Array or eq true>"
diff --git a/spec/unit/rspec/object_inspection_spec.rb b/spec/unit/rspec/object_inspection_spec.rb
index ff985e0d..cd71dc7d 100644
--- a/spec/unit/rspec/object_inspection_spec.rb
+++ b/spec/unit/rspec/object_inspection_spec.rb
@@ -1,7 +1,7 @@
 require "spec_helper"
 
 RSpec.describe SuperDiff, type: :unit do
-  describe ".inspect_object", "for RSpec objects" do
+  describe ".inspect_object", "for RSpec aliased matchers" do
     context "given a hash-including-<something>" do
       context "given as_lines: false" do
         it "returns an inspected version of the object" do
@@ -116,7 +116,7 @@
       end
     end
 
-    context "given a fuzzy object" do
+    context "given an object-having-<something>" do
       context "given as_lines: false" do
         it "returns an inspected version of the object" do
           string =