add inverse expect asymmetric matchers (#5517)

* add inverse expect helpers

* linting

* switch to expect.not.* format, fix string validation in asymmetric matcher

* add back mistakenly removed test

* lint docs

* add changelog entry

Author: quantizor

CHANGELOG.md

@@ -14,6 +14,8 @@
   promises ([#5670](https://github.com/facebook/jest/pull/5670))
 * `[expect]` Add isError to utils
   ([#5670](https://github.com/facebook/jest/pull/5670))
+* `[expect]` Add inverse matchers (`expect.not.arrayContaining`, etc.,
+  [#5517](https://github.com/facebook/jest/pull/5517))
 
 ### Fixes
 

docs/ExpectAPI.md

@@ -273,6 +273,37 @@ test('prepareState prepares a valid state', () => {
 The `expect.hasAssertions()` call ensures that the `prepareState` callback
 actually gets called.
 
+### `expect.not.arrayContaining(array)`
+
+`expect.not.arrayContaining(array)` matches a received array which contains none
+of the elements in the expected array. That is, the expected array **is not a
+subset** of the received array.
+
+It is the inverse of `expect.arrayContaining`.
+
+### `expect.not.objectContaining(object)`
+
+`expect.not.objectContaining(object)` matches any received object that does not
+recursively match the expected properties. That is, the expected object **is not
+a subset** of the received object. Therefore, it matches a received object which
+contains properties that are **not** in the expected object.
+
+It is the inverse of `expect.objectContaining`.
+
+### `expect.not.stringContaining(string)`
+
+`expect.not.stringContaining(string)` matches any received string that does not
+contain the exact expected string.
+
+It is the inverse of `expect.stringContaining`.
+
+### `expect.not.stringMatching(regexp)`
+
+`expect.not.stringMatching(regexp)` matches any received string that does not
+match the expected regexp.
+
+It is the inverse of `expect.stringMatching`.
+
 ### `expect.objectContaining(object)`
 
 `expect.objectContaining(object)` matches any received object that recursively
@@ -302,8 +333,6 @@ test('onPress gets called with the right thing', () => {
 
 ### `expect.stringContaining(string)`
 
-##### available in Jest **19.0.0+**
-
 `expect.stringContaining(string)` matches any received string that contains the
 exact expected string.
 

packages/expect/src/__tests__/asymmetric_matchers.test.js

@@ -13,9 +13,13 @@ const {
   any,
   anything,
   arrayContaining,
+  arrayNotContaining,
   objectContaining,
+  objectNotContaining,
   stringContaining,
+  stringNotContaining,
   stringMatching,
+  stringNotMatching,
 } = require('../asymmetric_matchers');
 
 test('Any.asymmetricMatch()', () => {
@@ -89,6 +93,27 @@ test('ArrayContaining throws for non-arrays', () => {
   }).toThrow();
 });
 
+test('ArrayNotContaining matches', () => {
+  jestExpect(arrayNotContaining(['foo']).asymmetricMatch(['bar'])).toBe(true);
+});
+
+test('ArrayNotContaining does not match', () => {
+  [
+    arrayNotContaining([]).asymmetricMatch('jest'),
+    arrayNotContaining(['foo']).asymmetricMatch(['foo']),
+    arrayNotContaining(['foo']).asymmetricMatch(['foo', 'bar']),
+    arrayNotContaining([]).asymmetricMatch({}),
+  ].forEach(test => {
+    jestExpect(test).toEqual(false);
+  });
+});
+
+test('ArrayNotContaining throws for non-arrays', () => {
+  jestExpect(() => {
+    arrayNotContaining('foo').asymmetricMatch([]);
+  }).toThrow();
+});
+
 test('ObjectContaining matches', () => {
   [
     objectContaining({}).asymmetricMatch('jest'),
@@ -139,32 +164,106 @@ test('ObjectContaining throws for non-objects', () => {
   jestExpect(() => objectContaining(1337).asymmetricMatch()).toThrow();
 });
 
+test('ObjectNotContaining matches', () => {
+  [
+    objectNotContaining({}).asymmetricMatch('jest'),
+    objectNotContaining({foo: 'foo'}).asymmetricMatch({bar: 'bar'}),
+    objectNotContaining({foo: 'foo'}).asymmetricMatch({foo: 'foox'}),
+    objectNotContaining({foo: undefined}).asymmetricMatch({}),
+  ].forEach(test => {
+    jestExpect(test).toEqual(true);
+  });
+});
+
+test('ObjectNotContaining does not match', () => {
+  [
+    objectNotContaining({foo: 'foo'}).asymmetricMatch({
+      foo: 'foo',
+      jest: 'jest',
+    }),
+    objectNotContaining({foo: undefined}).asymmetricMatch({foo: undefined}),
+    objectNotContaining({
+      first: objectNotContaining({second: {}}),
+    }).asymmetricMatch({first: {second: {}}}),
+  ].forEach(test => {
+    jestExpect(test).toEqual(false);
+  });
+});
+
+test('ObjectNotContaining throws for non-objects', () => {
+  jestExpect(() => objectNotContaining(1337).asymmetricMatch()).toThrow();
+});
+
 test('StringContaining matches string against string', () => {
   jestExpect(stringContaining('en*').asymmetricMatch('queen*')).toBe(true);
   jestExpect(stringContaining('en').asymmetricMatch('queue')).toBe(false);
-  jestExpect(stringContaining('en').asymmetricMatch({})).toBe(false);
 });
 
 test('StringContaining throws for non-strings', () => {
   jestExpect(() => {
     stringContaining([1]).asymmetricMatch('queen');
   }).toThrow();
+
+  jestExpect(() => {
+    stringContaining('en*').asymmetricMatch(1);
+  }).toThrow();
+});
+
+test('StringNotContaining matches string against string', () => {
+  jestExpect(stringNotContaining('en*').asymmetricMatch('queen*')).toBe(false);
+  jestExpect(stringNotContaining('en').asymmetricMatch('queue')).toBe(true);
+});
+
+test('StringNotContaining throws for non-strings', () => {
+  jestExpect(() => {
+    stringNotContaining([1]).asymmetricMatch('queen');
+  }).toThrow();
+
+  jestExpect(() => {
+    stringNotContaining('en*').asymmetricMatch(1);
+  }).toThrow();
 });
 
 test('StringMatching matches string against regexp', () => {
   jestExpect(stringMatching(/en/).asymmetricMatch('queen')).toBe(true);
   jestExpect(stringMatching(/en/).asymmetricMatch('queue')).toBe(false);
-  jestExpect(stringMatching(/en/).asymmetricMatch({})).toBe(false);
 });
 
 test('StringMatching matches string against string', () => {
   jestExpect(stringMatching('en').asymmetricMatch('queen')).toBe(true);
   jestExpect(stringMatching('en').asymmetricMatch('queue')).toBe(false);
-  jestExpect(stringMatching('en').asymmetricMatch({})).toBe(false);
 });
 
 test('StringMatching throws for non-strings and non-regexps', () => {
   jestExpect(() => {
     stringMatching([1]).asymmetricMatch('queen');
   }).toThrow();
 });
+
+test('StringMatching throws for non-string actual values', () => {
+  jestExpect(() => {
+    stringMatching('en').asymmetricMatch(1);
+  }).toThrow();
+});
+
+test('StringNotMatching matches string against regexp', () => {
+  jestExpect(stringNotMatching(/en/).asymmetricMatch('queen')).toBe(false);
+  jestExpect(stringNotMatching(/en/).asymmetricMatch('queue')).toBe(true);
+});
+
+test('StringNotMatching matches string against string', () => {
+  jestExpect(stringNotMatching('en').asymmetricMatch('queen')).toBe(false);
+  jestExpect(stringNotMatching('en').asymmetricMatch('queue')).toBe(true);
+});
+
+test('StringNotMatching throws for non-strings and non-regexps', () => {
+  jestExpect(() => {
+    stringNotMatching([1]).asymmetricMatch('queen');
+  }).toThrow();
+});
+
+test('StringNotMatching throws for non-string actual values', () => {
+  jestExpect(() => {
+    stringNotMatching('en').asymmetricMatch(1);
+  }).toThrow();
+});

packages/expect/src/__tests__/utils.test.js

@@ -9,7 +9,7 @@
 'use strict';
 
 const {stringify} = require('jest-matcher-utils');
-const {getObjectSubset, getPath} = require('../utils');
+const {emptyObject, getObjectSubset, getPath} = require('../utils');
 
 describe('getPath()', () => {
   test('property exists', () => {
@@ -107,3 +107,18 @@ describe('getObjectSubset()', () => {
     );
   });
 });
+
+describe('emptyObject()', () => {
+  test('matches an empty object', () => {
+    expect(emptyObject({})).toBe(true);
+  });
+
+  test('does not match an object with keys', () => {
+    expect(emptyObject({foo: undefined})).toBe(false);
+  });
+
+  test('does not match a non-object', () => {
+    expect(emptyObject(null)).toBe(false);
+    expect(emptyObject(34)).toBe(false);
+  });
+});