{"action":"created","comment":{"url":"https://api.github.com/repos/rspec/rspec.github.io/pulls/comments/29941487","id":29941487,"diff_hunk":"@@ -0,0 +1,216 @@\n+---\n+title: How RSpec 3.0 composable matchers work\n+author: Sam Phippen\n+---\n+\n+##Warmup: the `===` protocol\n+\n+In Ruby, a number of objects implement the `===` protocol. Some of the objects\n+that implement this protocol include:\n+\n+* all class objects\n+* lambdas\n+* regexes\n+* ranges\n+\n+Conceptually, this protocol represents a \"match\". That is, the object that\n+implements the `===` declares whether or not it \"matches\" the other object.\n+For example, `Array === []` returns `true`. This is because an empty array is a\n+subclass of the array class. `Array === {}` returns false because a hash is not\n+a subclass of array. For regexes, `===` returns true if the passed string\n+matches the regex, and false if it does not.\n+\n+The `===` method is used in Ruby case statements to decide if a branch should\n+be taken. For example\n+\n+```\n+case 3\n+when (1...18)\n+    puts \"hello\"\n+end\n+```\n+\n+will print hello, because `(1...18) === 3` returns `true`.\n+\n+The new RSpec matchers make heavy use of `===` internally, if you'd like to get\n+more of an understanding of `===`, I'd heavily suggest you pop open IRB and\n+play around with it a little before moving on.\n+\n+## RSpec matchers\n+\n+In an RSpec expectation expression like `expect(object_1).to eq(object_2)`\n+there are two primary objects at play, the **target** and the **matcher**. The\n+**target** object is created by \"expect\" and basically wraps the passed object\n+to it in a class called `ExpectationTarget`. The primary methods on the\n+`ExpectationTarget` that users see are `to` and `not_to`/`to_not`. Let's focus\n+on `to`.\n+\n+The `to` method is basically responsible for invoking the `matches?` method on the\n+passed matcher. It's possible to see this happening quite easily in an IRB session.\n+\n+```\n+>> require \"rspec/expectations\"\n+=> true\n+>> o = Object.new\n+=> #<Object:0x007fa20d221490>\n+>> o.extend(RSpec::Matchers)\n+=> #<Object:0x007fa20d221490>\n+>> o.expect(3).to Object.new\n+NoMethodError: undefined method `matches?' for #<Object:0x007fa20d1f4e68>\n+    from /Users/sam/.gem/ruby/2.1.5/gems/rspec-expectations-3.2.1/lib/rspec/expectations/handler.rb:50:in `block in handle_matcher'\n+    from /Users/sam/.gem/ruby/2.1.5/gems/rspec-expectations-3.2.1/lib/rspec/expectations/handler.rb:27:in `with_matcher'\n+    from /Users/sam/.gem/ruby/2.1.5/gems/rspec-expectations-3.2.1/lib/rspec/expectations/handler.rb:48:in `handle_matcher'\n+    from /Users/sam/.gem/ruby/2.1.5/gems/rspec-expectations-3.2.1/lib/rspec/expectations/expectation_target.rb:54:in `to'\n+    from (irb):4\n+    from /Users/sam/.rubies/ruby-2.1.5/bin/irb:11:in `<main>'\n+>>\n+```\n+\n+In this session, we extend the RSpec DSL on to a blank object and then call\n+`o.expect(3).to Object.new`. This blows up because our new object does not implement\n+the `matches?` method.\n+\n+In RSpec expectations, most matchers inherit from a class called `BaseMatcher`\n+which causes `matches?` to delegate to a method called `match`. Some matchers have\n+a very simple definition of `match`. For example, here's the definition of `match`\n+for the `eq` matcher:\n+\n+```ruby\n+def match(expected, actual)\n+  actual == expected\n+end\n+```\n+\n+Some matchers, however, have a more complicated match protocol. This more complicated\n+protocol is called the **composable** matcher protocol, which is what we'll discuss next.\n+\n+## Composable RSpec matchers\n+\n+A composable RSpec matcher is one which expects other RSpec matchers for some/all of it's\n+arguments. The `match` matcher is perhaps an obvious place to start. In RSpec 2.xx the match\n+matcher was really only used match regexes, and its match definition looked thus:\n+\n+```ruby\n+def match(expected, actual)\n+  actual.match expected\n+end\n+```\n+\n+Now obviously, one could extend the capabilites by providing other objects that provided a\n+definition of match, but that's besides the point.\n+\n+The new definition of the match matcher's match method is thus:\n+\n+```ruby\n+def match(expected, actual)\n+  return true if values_match?(expected, actual)\n+  return false unless can_safely_call_match?(expected, actual)\n+  actual.match(expected)\n+end\n+```\n+\n+The key important difference is that call to `values_match?` which is the core implementation\n+of the new matching protocol in RSpec. The list of matchers which now reference the values_match?\n+method are (as of RSpec expectations 3.3.0 development, not including mocks):\n+\n+* `change`\n+* `contain_exactly`\n+* `have_attributes`\n+* `include`\n+* `match`\n+* `output`\n+* `raise_error`\n+* `start_or_end_with`\n+* `throw_symbol`\n+* `yield`\n+\n+Let's take a look at what `values_match?` does.\n+\n+`values_match?` is the RSpec match definition that allows matchers, and other objects, to compose.\n+The implementation looks like this:\n+\n+```ruby\n+def self.values_match?(expected, actual)\n+  if Hash === actual\n+    return hashes_match?(expected, actual) if Hash === expected\n+  elsif Array === expected && Enumerable === actual && !(Struct === actual)\n+    return arrays_match?(expected, actual.to_a)\n+  end\n+\n+  return true if expected == actual\n+\n+  begin\n+    expected === actual\n+  rescue ArgumentError\n+    # Some objects, like 0-arg lambdas on 1.9+, raise\n+    # ArgumentError for `expected === actual`.\n+    false\n+  end\n+end\n+```\n+\n+The first thing to note is the special casing for Hashes and Arrays. Basically,\n+what those methods do is recursively apply `values_match?` to each of the\n+elements in the various collection types as you'd expect. Arrays by scanning\n+elements and hashes by matching keys and values.\n+\n+The next thing the method does is return `true` if expected === actual. An easy\n+way to demonstrate this is back in our IRB session:\n+\n+```\n+>> o.expect(3).to o.match(3)\n+=> true\n+```\n+\n+What we've done here is we've constructed a both a target and match matcher with the value 3.\n+When the match matcher hits `values_match?` it sees that 3 is not an array or a hash, and so\n+checks `expected == actual`, which in this case is `3 == 3`, which is true.\n+\n+The next line checks `expected === actual`. This is where the power of RSpec's new composability\n+really kicks in. The reason for this is that the `BaseMatcher` class includes a module called\n+`Composable`. The composable matcher defines `===` on matchers thusly:\n+\n+```rspec\n+def ===(value)\n+  matches?(value)\n+end\n+```\n+\n+This means that `expected` in the expression `expected === actual` can be another RSpec matcher,\n+a regex, or any other object that responds to `===`. This means, for example, that one can trivially\n+match a lambda by doing `expect(obj).to match(lambda { |actual| ... })`. Given that all RSpec matchers\n+implement `===` we are able to compose them arbitrarily with other \"matching\" values in the Ruby system.\n+\n+An example I've given in the past is matching nesting hashes like so:\n+\n+```\n+expect({:data => {... complex hash ...}).to include(:data => a_hash_including(:response => \"success\"))\n+```\n+\n+The reason we're able to pass the `a_hash_including` matcher inside the\n+`include` matcher is that `values_match?` will dilligently call `===` on the\n+inner, `a_hash_including` matcher, which will invoke its `matches?` method, which","path":"source/blog/2015-05-08-rspec-compsable-matchers.md","position":192,"original_position":192,"commit_id":"aa99cdd04b6b9be505d5538f9ad24b082079d117","original_commit_id":"aa99cdd04b6b9be505d5538f9ad24b082079d117","user":{"login":"xaviershay","id":1714,"avatar_url":"https://avatars.githubusercontent.com/u/1714?v=3","gravatar_id":"","url":"https://api.github.com/users/xaviershay","html_url":"https://github.com/xaviershay","followers_url":"https://api.github.com/users/xaviershay/followers","following_url":"https://api.github.com/users/xaviershay/following{/other_user}","gists_url":"https://api.github.com/users/xaviershay/gists{/gist_id}","starred_url":"https://api.github.com/users/xaviershay/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/xaviershay/subscriptions","organizations_url":"https://api.github.com/users/xaviershay/orgs","repos_url":"https://api.github.com/users/xaviershay/repos","events_url":"https://api.github.com/users/xaviershay/events{/privacy}","received_events_url":"https://api.github.com/users/xaviershay/received_events","type":"User","site_admin":false},"body":"comma after \"inner\"?","created_at":"2015-05-08T14:00:46Z","updated_at":"2015-05-08T14:00:46Z","html_url":"https://github.com/rspec/rspec.github.io/pull/69#discussion_r29941487","pull_request_url":"https://api.github.com/repos/rspec/rspec.github.io/pulls/69","_links":{"self":{"href":"https://api.github.com/repos/rspec/rspec.github.io/pulls/comments/29941487"},"html":{"href":"https://github.com/rspec/rspec.github.io/pull/69#discussion_r29941487"},"pull_request":{"href":"https://api.github.com/repos/rspec/rspec.github.io/pulls/69"}}},"pull_request":{"url":"https://api.github.com/repos/rspec/rspec.github.io/pulls/69","id":34995115,"html_url":"https://github.com/rspec/rspec.github.io/pull/69","diff_url":"https://github.com/rspec/rspec.github.io/pull/69.diff","patch_url":"https://github.com/rspec/rspec.github.io/pull/69.patch","issue_url":"https://api.github.com/repos/rspec/rspec.github.io/issues/69","number":69,"state":"open","locked":false,"title":"Add a post on how the composable matchers work.","user":{"login":"samphippen","id":96662,"avatar_url":"https://avatars.githubusercontent.com/u/96662?v=3","gravatar_id":"","url":"https://api.github.com/users/samphippen","html_url":"https://github.com/samphippen","followers_url":"https://api.github.com/users/samphippen/followers","following_url":"https://api.github.com/users/samphippen/following{/other_user}","gists_url":"https://api.github.com/users/samphippen/gists{/gist_id}","starred_url":"https://api.github.com/users/samphippen/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/samphippen/subscriptions","organizations_url":"https://api.github.com/users/samphippen/orgs","repos_url":"https://api.github.com/users/samphippen/repos","events_url":"https://api.github.com/users/samphippen/events{/privacy}","received_events_url":"https://api.github.com/users/samphippen/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-05-08T09:57:11Z","updated_at":"2015-05-08T14:00:46Z","closed_at":null,"merged_at":null,"merge_commit_sha":"c248f3d5678ddd04151fb90726b33ddc4e7e534a","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/rspec/rspec.github.io/pulls/69/commits","review_comments_url":"https://api.github.com/repos/rspec/rspec.github.io/pulls/69/comments","review_comment_url":"https://api.github.com/repos/rspec/rspec.github.io/pulls/comments{/number}","comments_url":"https://api.github.com/repos/rspec/rspec.github.io/issues/69/comments","statuses_url":"https://api.github.com/repos/rspec/rspec.github.io/statuses/aa99cdd04b6b9be505d5538f9ad24b082079d117","head":{"label":"rspec:composable-matchers-post","ref":"composable-matchers-post","sha":"aa99cdd04b6b9be505d5538f9ad24b082079d117","user":{"login":"rspec","id":22388,"avatar_url":"https://avatars.githubusercontent.com/u/22388?v=3","gravatar_id":"","url":"https://api.github.com/users/rspec","html_url":"https://github.com/rspec","followers_url":"https://api.github.com/users/rspec/followers","following_url":"https://api.github.com/users/rspec/following{/other_user}","gists_url":"https://api.github.com/users/rspec/gists{/gist_id}","starred_url":"https://api.github.com/users/rspec/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rspec/subscriptions","organizations_url":"https://api.github.com/users/rspec/orgs","repos_url":"https://api.github.com/users/rspec/repos","events_url":"https://api.github.com/users/rspec/events{/privacy}","received_events_url":"https://api.github.com/users/rspec/received_events","type":"Organization","site_admin":false},"repo":{"id":2544146,"name":"rspec.github.io","full_name":"rspec/rspec.github.io","owner":{"login":"rspec","id":22388,"avatar_url":"https://avatars.githubusercontent.com/u/22388?v=3","gravatar_id":"","url":"https://api.github.com/users/rspec","html_url":"https://github.com/rspec","followers_url":"https://api.github.com/users/rspec/followers","following_url":"https://api.github.com/users/rspec/following{/other_user}","gists_url":"https://api.github.com/users/rspec/gists{/gist_id}","starred_url":"https://api.github.com/users/rspec/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rspec/subscriptions","organizations_url":"https://api.github.com/users/rspec/orgs","repos_url":"https://api.github.com/users/rspec/repos","events_url":"https://api.github.com/users/rspec/events{/privacy}","received_events_url":"https://api.github.com/users/rspec/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/rspec/rspec.github.io","description":"source for rspec.info","fork":false,"url":"https://api.github.com/repos/rspec/rspec.github.io","forks_url":"https://api.github.com/repos/rspec/rspec.github.io/forks","keys_url":"https://api.github.com/repos/rspec/rspec.github.io/keys{/key_id}","collaborators_url":"https://api.github.com/repos/rspec/rspec.github.io/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/rspec/rspec.github.io/teams","hooks_url":"https://api.github.com/repos/rspec/rspec.github.io/hooks","issue_events_url":"https://api.github.com/repos/rspec/rspec.github.io/issues/events{/number}","events_url":"https://api.github.com/repos/rspec/rspec.github.io/events","assignees_url":"https://api.github.com/repos/rspec/rspec.github.io/assignees{/user}","branches_url":"https://api.github.com/repos/rspec/rspec.github.io/branches{/branch}","tags_url":"https://api.github.com/repos/rspec/rspec.github.io/tags","blobs_url":"https://api.github.com/repos/rspec/rspec.github.io/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/rspec/rspec.github.io/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/rspec/rspec.github.io/git/refs{/sha}","trees_url":"https://api.github.com/repos/rspec/rspec.github.io/git/trees{/sha}","statuses_url":"https://api.github.com/repos/rspec/rspec.github.io/statuses/{sha}","languages_url":"https://api.github.com/repos/rspec/rspec.github.io/languages","stargazers_url":"https://api.github.com/repos/rspec/rspec.github.io/stargazers","contributors_url":"https://api.github.com/repos/rspec/rspec.github.io/contributors","subscribers_url":"https://api.github.com/repos/rspec/rspec.github.io/subscribers","subscription_url":"https://api.github.com/repos/rspec/rspec.github.io/subscription","commits_url":"https://api.github.com/repos/rspec/rspec.github.io/commits{/sha}","git_commits_url":"https://api.github.com/repos/rspec/rspec.github.io/git/commits{/sha}","comments_url":"https://api.github.com/repos/rspec/rspec.github.io/comments{/number}","issue_comment_url":"https://api.github.com/repos/rspec/rspec.github.io/issues/comments{/number}","contents_url":"https://api.github.com/repos/rspec/rspec.github.io/contents/{+path}","compare_url":"https://api.github.com/repos/rspec/rspec.github.io/compare/{base}...{head}","merges_url":"https://api.github.com/repos/rspec/rspec.github.io/merges","archive_url":"https://api.github.com/repos/rspec/rspec.github.io/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/rspec/rspec.github.io/downloads","issues_url":"https://api.github.com/repos/rspec/rspec.github.io/issues{/number}","pulls_url":"https://api.github.com/repos/rspec/rspec.github.io/pulls{/number}","milestones_url":"https://api.github.com/repos/rspec/rspec.github.io/milestones{/number}","notifications_url":"https://api.github.com/repos/rspec/rspec.github.io/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/rspec/rspec.github.io/labels{/name}","releases_url":"https://api.github.com/repos/rspec/rspec.github.io/releases{/id}","created_at":"2011-10-09T19:44:45Z","updated_at":"2015-04-26T17:58:55Z","pushed_at":"2015-05-08T09:57:11Z","git_url":"git://github.com/rspec/rspec.github.io.git","ssh_url":"git@github.com:rspec/rspec.github.io.git","clone_url":"https://github.com/rspec/rspec.github.io.git","svn_url":"https://github.com/rspec/rspec.github.io","homepage":"","size":7493,"stargazers_count":10,"watchers_count":10,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":15,"mirror_url":null,"open_issues_count":7,"forks":15,"open_issues":7,"watchers":10,"default_branch":"source"}},"base":{"label":"rspec:source","ref":"source","sha":"a512ef03615870bc8d4b97367775f295654266e8","user":{"login":"rspec","id":22388,"avatar_url":"https://avatars.githubusercontent.com/u/22388?v=3","gravatar_id":"","url":"https://api.github.com/users/rspec","html_url":"https://github.com/rspec","followers_url":"https://api.github.com/users/rspec/followers","following_url":"https://api.github.com/users/rspec/following{/other_user}","gists_url":"https://api.github.com/users/rspec/gists{/gist_id}","starred_url":"https://api.github.com/users/rspec/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rspec/subscriptions","organizations_url":"https://api.github.com/users/rspec/orgs","repos_url":"https://api.github.com/users/rspec/repos","events_url":"https://api.github.com/users/rspec/events{/privacy}","received_events_url":"https://api.github.com/users/rspec/received_events","type":"Organization","site_admin":false},"repo":{"id":2544146,"name":"rspec.github.io","full_name":"rspec/rspec.github.io","owner":{"login":"rspec","id":22388,"avatar_url":"https://avatars.githubusercontent.com/u/22388?v=3","gravatar_id":"","url":"https://api.github.com/users/rspec","html_url":"https://github.com/rspec","followers_url":"https://api.github.com/users/rspec/followers","following_url":"https://api.github.com/users/rspec/following{/other_user}","gists_url":"https://api.github.com/users/rspec/gists{/gist_id}","starred_url":"https://api.github.com/users/rspec/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/rspec/subscriptions","organizations_url":"https://api.github.com/users/rspec/orgs","repos_url":"https://api.github.com/users/rspec/repos","events_url":"https://api.github.com/users/rspec/events{/privacy}","received_events_url":"https://api.github.com/users/rspec/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/rspec/rspec.github.io","description":"source for rspec.info","fork":false,"url":"https://api.github.com/repos/rspec/rspec.github.io","forks_url":"https://api.github.com/repos/rspec/rspec.github.io/forks","keys_url":"https://api.github.com/repos/rspec/rspec.github.io/keys{/key_id}","collaborators_url":"https://api.github.com/repos/rspec/rspec.github.io/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/rspec/rspec.github.io/teams","hooks_url":"https://api.github.com/repos/rspec/rspec.github.io/hooks","issue_events_url":"https://api.github.com/repos/rspec/rspec.github.io/issues/events{/number}","events_url":"https://api.github.com/repos/rspec/rspec.github.io/events","assignees_url":"https://api.github.com/repos/rspec/rspec.github.io/assignees{/user}","branches_url":"https://api.github.com/repos/rspec/rspec.github.io/branches{/branch}","tags_url":"https://api.github.com/repos/rspec/rspec.github.io/tags","blobs_url":"https://api.github.com/repos/rspec/rspec.github.io/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/rspec/rspec.github.io/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/rspec/rspec.github.io/git/refs{/sha}","trees_url":"https://api.github.com/repos/rspec/rspec.github.io/git/trees{/sha}","statuses_url":"https://api.github.com/repos/rspec/rspec.github.io/statuses/{sha}","languages_url":"https://api.github.com/repos/rspec/rspec.github.io/languages","stargazers_url":"https://api.github.com/repos/rspec/rspec.github.io/stargazers","contributors_url":"https://api.github.com/repos/rspec/rspec.github.io/contributors","subscribers_url":"https://api.github.com/repos/rspec/rspec.github.io/subscribers","subscription_url":"https://api.github.com/repos/rspec/rspec.github.io/subscription","commits_url":"https://api.github.com/repos/rspec/rspec.github.io/commits{/sha}","git_commits_url":"https://api.github.com/repos/rspec/rspec.github.io/git/commits{/sha}","comments_url":"https://api.github.com/repos/rspec/rspec.github.io/comments{/number}","issue_comment_url":"https://api.github.com/repos/rspec/rspec.github.io/issues/comments{/number}","contents_url":"https://api.github.com/repos/rspec/rspec.github.io/contents/{+path}","compare_url":"https://api.github.com/repos/rspec/rspec.github.io/compare/{base}...{head}","merges_url":"https://api.github.com/repos/rspec/rspec.github.io/merges","archive_url":"https://api.github.com/repos/rspec/rspec.github.io/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/rspec/rspec.github.io/downloads","issues_url":"https://api.github.com/repos/rspec/rspec.github.io/issues{/number}","pulls_url":"https://api.github.com/repos/rspec/rspec.github.io/pulls{/number}","milestones_url":"https://api.github.com/repos/rspec/rspec.github.io/milestones{/number}","notifications_url":"https://api.github.com/repos/rspec/rspec.github.io/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/rspec/rspec.github.io/labels{/name}","releases_url":"https://api.github.com/repos/rspec/rspec.github.io/releases{/id}","created_at":"2011-10-09T19:44:45Z","updated_at":"2015-04-26T17:58:55Z","pushed_at":"2015-05-08T09:57:11Z","git_url":"git://github.com/rspec/rspec.github.io.git","ssh_url":"git@github.com:rspec/rspec.github.io.git","clone_url":"https://github.com/rspec/rspec.github.io.git","svn_url":"https://github.com/rspec/rspec.github.io","homepage":"","size":7493,"stargazers_count":10,"watchers_count":10,"language":"CSS","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":15,"mirror_url":null,"open_issues_count":7,"forks":15,"open_issues":7,"watchers":10,"default_branch":"source"}},"_links":{"self":{"href":"https://api.github.com/repos/rspec/rspec.github.io/pulls/69"},"html":{"href":"https://github.com/rspec/rspec.github.io/pull/69"},"issue":{"href":"https://api.github.com/repos/rspec/rspec.github.io/issues/69"},"comments":{"href":"https://api.github.com/repos/rspec/rspec.github.io/issues/69/comments"},"review_comments":{"href":"https://api.github.com/repos/rspec/rspec.github.io/pulls/69/comments"},"review_comment":{"href":"https://api.github.com/repos/rspec/rspec.github.io/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/rspec/rspec.github.io/pulls/69/commits"},"statuses":{"href":"https://api.github.com/repos/rspec/rspec.github.io/statuses/aa99cdd04b6b9be505d5538f9ad24b082079d117"}}}}