Add toBeSymbol matcher (#217)

README.md

@@ -111,6 +111,8 @@ If you've come here to help contribute - Thanks! Take a look at the [contributin
     - [.toInclude(substring)](#toincludesubstring)
     - [.toIncludeRepeated(substring, times)](#toincluderepeatedsubstring-times)
     - [.toIncludeMultiple([substring])](#toincludemultiplesubstring)
+  - [Symbol](#symbol)
+    - [.toBeSymbol()](#tobesymbol)
 - [LICENSE](#license)
 
 ## Installation
@@ -1003,6 +1005,19 @@ test('passes when value includes all substrings', () => {
 });
 ```
 
+### Symbol
+
+#### .toBeSymbol()
+
+Use `.toBeSymbol` when checking if a value is a `Symbol`.
+
+```js
+test('passes when value is a symbol', () => {
+  expect(Symbol()).toBeSymbol();
+  expect(true).not.toBeSymbol();
+});
+```
+
 ## LICENSE
 
 [MIT](/LICENSE)

src/matchers/index.js

@@ -27,6 +27,7 @@ import toBeOneOfMatcher from './toBeOneOf';
 import toBePositiveMatcher from './toBePositive';
 import toBeSealedMatcher from './toBeSealed';
 import toBeStringMatcher from './toBeString';
+import toBeSymbolMatcher from './toBeSymbol';
 import toBeTrueMatcher from './toBeTrue';
 import toBeValidDateMatcher from './toBeValidDate';
 import toBeWithinMatcher from './toBeWithin';
@@ -91,6 +92,7 @@ export const toBeOneOf = toBeOneOfMatcher.toBeOneOf;
 export const toBePositive = toBePositiveMatcher.toBePositive;
 export const toBeSealed = toBeSealedMatcher.toBeSealed;
 export const toBeString = toBeStringMatcher.toBeString;
+export const toBeSymbol = toBeSymbolMatcher.toBeSymbol;
 export const toBeTrue = toBeTrueMatcher.toBeTrue;
 export const toBeValidDate = toBeValidDateMatcher.toBeValidDate;
 export const toBeWithin = toBeWithinMatcher.toBeWithin;

src/matchers/toBeSymbol/__snapshots__/index.test.js.snap

@@ -0,0 +1,15 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.not.toBeSymbol fails when given a symbol 1`] = `
+"<dim>expect(</><red>received</><dim>).not.toBeSymbol()</>
+
+Expected value to not be a symbol, received:
+  <red>Symbol()</>"
+`;
+
+exports[`.toBeSymbol fails when not given a symbol 1`] = `
+"<dim>expect(</><red>received</><dim>).toBeSymbol()</>
+
+Expected to receive a symbol, received:
+  <red>false</>"
+`;

src/matchers/toBeSymbol/index.js

@@ -0,0 +1,26 @@
+import { matcherHint, printReceived } from 'jest-matcher-utils';
+
+import predicate from './predicate';
+
+const passMessage = received => () =>
+  matcherHint('.not.toBeSymbol', 'received', '') +
+  '\n\n' +
+  'Expected value to not be a symbol, received:\n' +
+  `  ${printReceived(received)}`;
+
+const failMessage = received => () =>
+  matcherHint('.toBeSymbol', 'received', '') +
+  '\n\n' +
+  'Expected to receive a symbol, received:\n' +
+  `  ${printReceived(received)}`;
+
+export default {
+  toBeSymbol: expected => {
+    const pass = predicate(expected);
+    if (pass) {
+      return { pass: true, message: passMessage(expected) };
+    }
+
+    return { pass: false, message: failMessage(expected) };
+  },
+};

src/matchers/toBeSymbol/index.test.js

@@ -0,0 +1,26 @@
+import matcher from './';
+
+expect.extend(matcher);
+
+describe('.toBeSymbol', () => {
+  test('passes when given a symbol', () => {
+    expect(Symbol()).toBeSymbol();
+  });
+
+  test('fails when not given a symbol', () => {
+    expect(() => expect(false).toBeSymbol()).toThrowErrorMatchingSnapshot();
+  });
+});
+
+describe('.not.toBeSymbol', () => {
+  test.each([[false], [''], [0], [{}], [[]], [undefined], [null], [NaN], [() => {}]])(
+    'passes when not given a symbol: %s',
+    given => {
+      expect(given).not.toBeSymbol();
+    },
+  );
+
+  test('fails when given a symbol', () => {
+    expect(() => expect(Symbol()).not.toBeSymbol()).toThrowErrorMatchingSnapshot();
+  });
+});

src/matchers/toBeSymbol/predicate.js

@@ -0,0 +1 @@
+export default expected => typeof expected === 'symbol';

src/matchers/toBeSymbol/predicate.test.js

@@ -0,0 +1,14 @@
+import predicate from './predicate';
+
+describe('toBeSymbol Predicate', () => {
+  test('returns true when given a symbol', () => {
+    expect(predicate(Symbol())).toBe(true);
+  });
+
+  test.each([[false], [''], [0], [{}], [[]], [undefined], [null], [NaN], [() => {}]])(
+    'returns false when given: %s',
+    given => {
+      expect(predicate(given)).toBe(false);
+    },
+  );
+});

types/index.d.ts

@@ -373,6 +373,11 @@ declare namespace jest {
      * @param {String | RegExp} message
      */
     toThrowWithMessage(type: Function, message: string | RegExp): R;
+
+    /**
+     * Use `.toBeSymbol` when checking if a value is a `Symbol`.
+     */
+    toBeSymbol(): R;
   }
 
   // noinspection JSUnusedGlobalSymbols
@@ -746,6 +751,11 @@ declare namespace jest {
     /**
      * Use `.toBeEmptyObject` when checking if a value is an empty `Object`.
      */
-    toBeEmptyObject(): R;
+    toBeEmptyObject(): any;
+
+    /**
+     * Use `.toBeSymbol` when checking if a value is a `Symbol`.
+     */
+    toBeSymbol(): any;
   }
 }