Add snapshot property matchers

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ### Features
 
+* `[expect]` Expose `getObjectSubset`, `iterableEquality`, and `subsetEquality`
+  ([#6210](https://github.com/facebook/jest/pull/6210))
+* `[jest-snapshot]` Add snapshot property matchers
+  ([#6210](https://github.com/facebook/jest/pull/6210))
 * `[jest-cli]` Add `--detectOpenHandles` flag which enables Jest to potentially
   track down handles keeping it open after tests are complete.
   ([#6130](https://github.com/facebook/jest/pull/6130))

docs/ExpectAPI.md

@@ -1192,13 +1192,16 @@ test('this house has my desired features', () => {
 });
 ```
 
-### `.toMatchSnapshot(optionalString)`
+### `.toMatchSnapshot(propertyMatchers, snapshotName)`
 
 This ensures that a value matches the most recent snapshot. Check out
 [the Snapshot Testing guide](SnapshotTesting.md) for more information.
 
-You can also specify an optional snapshot name. Otherwise, the name is inferred
-from the test.
+The optional propertyMatchers argument allows you to specify asymmetric matchers
+which are verified instead of the exact values.
+
+The last argument allows you option to specify a snapshot name. Otherwise, the
+name is inferred from the test.
 
 _Note: While snapshot testing is most commonly used with React components, any
 serializable value can be used as a snapshot._

docs/SnapshotTesting.md

@@ -140,6 +140,61 @@ watch mode:
 
 ![](/jest/img/content/interactiveSnapshotDone.png)
 
+### Property Matchers
+
+Often there are fields in the object you want to snapshot which are generated
+(like IDs and Dates). If you try to snapshot these objects, they will force the
+snapshot to fail on every run:
+
+```javascript
+it('will fail every time', () => {
+  const user = {
+    createdAt: new Date(),
+    id: Math.floor(Math.random() * 20),
+    name: 'LeBron James',
+  };
+
+  expect(user).toMatchSnapshot();
+});
+
+// Snapshot
+exports[`will fail every time 1`] = `
+Object {
+  "createdAt": 2018-05-19T23:36:09.816Z,
+  "id": 3,
+  "name": "LeBron James",
+}
+`;
+```
+
+For these cases, Jest allows providing an asymmetric matcher for any property.
+These matchers are checked before the snapshot is written or tested, and then
+saved to the snapshot file instead of the received value:
+
+```javascript
+it('will check the matchers and pass', () => {
+  const user = {
+    createdAt: new Date(),
+    id: Math.floor(Math.random() * 20),
+    name: 'LeBron James',
+  };
+
+  expect(user).toMatchSnapshot({
+    createdAt: expect.any(Date),
+    id: expect.any(Number),
+  });
+});
+
+// Snapshot
+exports[`will check the matchers and pass 1`] = `
+Object {
+  "createdAt": Any<Date>,
+  "id": Any<Number>,
+  "name": "LeBron James",
+}
+`;
+```
+
 ## Best Practices
 
 Snapshots are a fantastic tool for identifying unexpected interface changes

integration-tests/__tests__/to_match_snapshot.test.js

@@ -159,3 +159,65 @@ test('accepts custom snapshot name', () => {
     expect(status).toBe(0);
   }
 });
+
+test('handles property matchers', () => {
+  const filename = 'handle-property-matchers.test.js';
+  const template = makeTemplate(`test('handles property matchers', () => {
+      expect({createdAt: $1}).toMatchSnapshot({createdAt: expect.any(Date)});
+    });
+    `);
+
+  {
+    writeFiles(TESTS_DIR, {[filename]: template(['new Date()'])});
+    const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
+    expect(stderr).toMatch('1 snapshot written from 1 test suite.');
+    expect(status).toBe(0);
+  }
+
+  {
+    const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
+    expect(stderr).toMatch('Snapshots:   1 passed, 1 total');
+    expect(status).toBe(0);
+  }
+
+  {
+    writeFiles(TESTS_DIR, {[filename]: template(['"string"'])});
+    const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
+    expect(stderr).toMatch(
+      'Received value does not match snapshot properties for "handles property matchers 1".',
+    );
+    expect(stderr).toMatch('Snapshots:   1 failed, 1 total');
+    expect(status).toBe(1);
+  }
+});
+
+test('handles property matchers with custom name', () => {
+  const filename = 'handle-property-matchers-with-name.test.js';
+  const template = makeTemplate(`test('handles property matchers with name', () => {
+      expect({createdAt: $1}).toMatchSnapshot({createdAt: expect.any(Date)}, 'custom-name');
+    });
+    `);
+
+  {
+    writeFiles(TESTS_DIR, {[filename]: template(['new Date()'])});
+    const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
+    expect(stderr).toMatch('1 snapshot written from 1 test suite.');
+    expect(status).toBe(0);
+  }
+
+  {
+    const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
+    expect(stderr).toMatch('Snapshots:   1 passed, 1 total');
+    expect(status).toBe(0);
+  }
+
+  {
+    writeFiles(TESTS_DIR, {[filename]: template(['"string"'])});
+    const {stderr, status} = runJest(DIR, ['-w=1', '--ci=false', filename]);
+    expect(stderr).toMatch(
+      'Received value does not match snapshot properties for "handles property matchers with name: custom-name 1".',
+    );
+    expect(stderr).toMatch('Snapshots:   1 failed, 1 total');
+    expect(status).toBe(1);
+  }
+});

packages/expect/src/index.js

@@ -21,6 +21,7 @@ import type {
 } from 'types/Matchers';
 
 import * as utils from 'jest-matcher-utils';
+import {iterableEquality, subsetEquality, getObjectSubset} from './utils';
 import matchers from './matchers';
 import spyMatchers from './spy_matchers';
 import toThrowMatchers, {
@@ -223,7 +224,10 @@ const makeThrowingMatcher = (
       getState(),
       {
         equals,
+        getObjectSubset,
         isNot,
+        iterableEquality,
+        subsetEquality,
         utils,
       },
     );

packages/jest-snapshot/src/State.js

@@ -190,4 +190,17 @@ export default class SnapshotState {
       }
     }
   }
+
+  fail(testName: string, received: any, key?: string) {
+    this._counters.set(testName, (this._counters.get(testName) || 0) + 1);
+    const count = Number(this._counters.get(testName));
+
+    if (!key) {
+      key = testNameToKey(testName, count);
+    }
+
+    this._uncheckedKeys.delete(key);
+    this.unmatched++;
+    return key;
+  }
 }

packages/jest-snapshot/src/index.js

@@ -48,8 +48,13 @@ const cleanup = (hasteFS: HasteFS, update: SnapshotUpdateState) => {
   };
 };
 
-const toMatchSnapshot = function(received: any, testName?: string) {
+const toMatchSnapshot = function(
+  received: any,
+  propertyMatchers?: any,
+  testName?: string,
+) {
   this.dontThrow && this.dontThrow();
+  testName = typeof propertyMatchers === 'string' ? propertyMatchers : testName;
 
   const {currentTestName, isNot, snapshotState}: MatcherState = this;
 
@@ -61,12 +66,43 @@ const toMatchSnapshot = function(received: any, testName?: string) {
     throw new Error('Jest: snapshot state must be initialized.');
   }
 
-  const result = snapshotState.match(
+  const fullTestName =
     testName && currentTestName
       ? `${currentTestName}: ${testName}`
-      : currentTestName || '',
-    received,
-  );
+      : currentTestName || '';
+
+  if (typeof propertyMatchers === 'object') {
+    const propertyPass = this.equals(received, propertyMatchers, [
+      this.iterableEquality,
+      this.subsetEquality,
+    ]);
+
+    if (!propertyPass) {
+      const key = snapshotState.fail(fullTestName, received);
+
+      const report = () =>
+        `${RECEIVED_COLOR('Received value')} does not match ` +
+        `${EXPECTED_COLOR(`snapshot properties for "${key}"`)}.\n\n` +
+        `Expected snapshot to match properties:\n` +
+        `  ${this.utils.printExpected(propertyMatchers)}` +
+        `\nReceived:\n` +
+        `  ${this.utils.printReceived(received)}`;
+
+      return {
+        message: () =>
+          matcherHint('.toMatchSnapshot', 'value', 'properties') +
+          '\n\n' +
+          report(),
+        name: 'toMatchSnapshot',
+        pass: false,
+        report,
+      };
+    } else {
+      Object.assign(received, propertyMatchers);
+    }
+  }
+
+  const result = snapshotState.match(fullTestName, received);
   const {pass} = result;
   let {actual, expected} = result;
 

packages/jest-snapshot/src/plugins.js

@@ -18,6 +18,7 @@ const {
   Immutable,
   ReactElement,
   ReactTestComponent,
+  AsymmetricMatcher,
 } = prettyFormat.plugins;
 
 let PLUGINS: Array<Plugin> = [
@@ -27,6 +28,7 @@ let PLUGINS: Array<Plugin> = [
   DOMCollection,
   Immutable,
   jestMockSerializer,
+  AsymmetricMatcher,
 ];
 
 // Prepend to list so the last added is the first tested.

website/i18n/en.json

@@ -80,7 +80,6 @@
     "Watch more videos|no description given": "Watch more videos",
     "Who's using Jest?|no description given": "Who's using Jest?",
     "Jest is used by teams of all sizes to test web applications, node.js services, mobile apps, and APIs.|no description given": "Jest is used by teams of all sizes to test web applications, node.js services, mobile apps, and APIs.",
-    "More Jest Users|no description given": "More Jest Users",
     "Talks & Videos|no description given": "Talks & Videos",
     "We understand that reading through docs can be boring sometimes. Here is a community curated list of talks & videos around Jest.|no description given": "We understand that reading through docs can be boring sometimes. Here is a community curated list of talks & videos around Jest.",
     "Add your favorite talk|no description given": "Add your favorite talk",