Skip to content

Use correct terminology for RSpec matchers #220

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 10, 2024

Conversation

mcmire
Copy link
Collaborator

@mcmire mcmire commented Feb 10, 2024

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.

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.
@mcmire mcmire merged commit c5f6ce6 into main Feb 10, 2024
@mcmire mcmire deleted the use-correct-rspec-terminology branch February 10, 2024 22:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant