Add Define A Custom Jest Matcher as a javascript til

Author: jbranchaud

README.md

@@ -9,7 +9,7 @@ and pairing with smart people at Hashrocket.
 
 For a steady stream of TILs, [sign up for my newsletter](https://tinyletter.com/jbranchaud).
 
-_898 TILs and counting..._
+_899 TILs and counting..._
 
 ---
 
@@ -300,6 +300,7 @@ _898 TILs and counting..._
 - [Create Bootstrapped Apps With Yarn](javascript/create-bootstrapped-apps-with-yarn.md)
 - [Custom Type Checking Error Messages With Yup](javascript/custom-type-checking-error-messages-with-yup.md)
 - [Default And Named Exports From The Same Module](javascript/default-and-named-exports-from-the-same-module.md)
+- [Define A Custom Jest Matcher](javascript/define-a-custom-jest-matcher.md)
 - [Destructure With Access To Nested Value And Parent Value](javascript/destructure-with-access-to-nested-value-and-parent-value.md);
 - [Destructuring The Rest Of An Array](javascript/destructuring-the-rest-of-an-array.md)
 - [Enable ES7 Transforms With react-rails](javascript/enable-es7-transforms-with-react-rails.md)

javascript/define-a-custom-jest-matcher.md

@@ -0,0 +1,46 @@
+# Define A Custom Jest Matcher
+
+Though [Jest's built-in
+matchers](https://jestjs.io/docs/en/expect) will get you pretty
+far in most testing scenarios, you may find yourself in a testing situation
+better served by a custom matcher. Custom matchers can be defined using the
+[`expect.extend()`
+function](https://jestjs.io/docs/en/expect#expectextendmatchers).
+
+Here is an example of a matcher that can check equality of two objects based
+solely on their `id` property.
+
+```javascript
+expect.extend({
+  toHaveMatchingId(recieved, expected) {
+    const pass = recieved.id === expected.id;
+
+    if (pass) {
+      return {
+        pass: true,
+        message: `Actual ${recieved.id} matches expected ${expected.id}`
+      };
+    } else {
+      return {
+        pass: false,
+        message: `Actual ${recieved.id} does not match expected ${expected.id}`
+      };
+    }
+  }
+});
+```
+
+This defines the name of the matcher (`toHaveMatchingId`), contains some logic
+to figure out whether `received` and `expected` pass the matcher, and then two
+return conditions (`pass: true` and `pass: false`) with accompanying messages.
+
+It can then be used like any other Jest matcher:
+
+```javascript
+test("compare objects", () => {
+  expect({ id: "001" }).toHaveMatchingId({ id: "001" });
+  expect({ id: "001" }).toHaveMatchingId({ id: "002" });
+});
+```
+
+Check out a [live example](https://codesandbox.io/s/focused-bush-vw2s5).