Add toBeDateString matcher

README.md

@@ -103,6 +103,7 @@ If you've come here to help contribute - Thanks! Take a look at the [contributin
   - [String](#string)
     - [.toBeString()](#tobestring)
     - [.toBeHexadecimal(string)](#tobehexadecimal)
+    - [.toBeDateString(string)](#tobedatestringstring)
     - [.toEqualCaseInsensitive(string)](#toequalcaseinsensitivestring)
     - [.toStartWith(prefix)](#tostartwithprefix)
     - [.toEndWith(suffix)](#toendwithsuffix)
@@ -880,6 +881,18 @@ test('passes when value is a valid hexadecimal', () => {
 });
 ```
 
+#### .toBeDateString(string)
+
+Use `.toBeDateString` when checking if a value is a valid date string.
+
+```js
+test('passes when value is a valid toBeDateString', () => {
+  expect('2019-11-27T14:05:07.520Z').toBeDateString();
+  expect('11/12/21').toBeDateString();
+  expect('not a date').not.toBeDateString();
+});
+```
+
 #### .toEqualCaseInsensitive(string)
 
 Use `.toEqualCaseInsensitive` when checking if a string is equal (===) to another ignoring the casing of both strings.

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

@@ -0,0 +1,15 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.not.toBeDateString fails when given a date string 1`] = `
+"<dim>expect(</><red>received</><dim>).not.toBeDateString()</>
+
+Expected value to not be a date string received:
+  <red>\\"2018-01-01T13:00:00.000Z\\"</>"
+`;
+
+exports[`.toBeDateString fails when not given a date string 1`] = `
+"<dim>expect(</><red>received</><dim>).toBeDateString()</>
+
+Expected value to be a date string received:
+  <red>\\"not a date\\"</>"
+`;

src/matchers/toBeDateString/index.js

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

src/matchers/toBeDateString/index.test.js

@@ -0,0 +1,23 @@
+import matcher from './';
+
+expect.extend(matcher);
+
+describe('.toBeDateString', () => {
+  test('passes when given a date string', () => {
+    expect(new Date().toISOString()).toBeDateString();
+  });
+
+  test('fails when not given a date string', () => {
+    expect(() => expect('not a date').toBeDateString()).toThrowErrorMatchingSnapshot();
+  });
+});
+
+describe('.not.toBeDateString', () => {
+  test('passes when not given a date string', () => {
+    expect('not a date').not.toBeDateString();
+  });
+
+  test('fails when given a date string', () => {
+    expect(() => expect('2018-01-01T13:00:00.000Z').not.toBeDateString()).toThrowErrorMatchingSnapshot();
+  });
+});

src/matchers/toBeDateString/predicate.js

@@ -0,0 +1,3 @@
+const isDateString = value => !isNaN(Date.parse(value));
+
+export default isDateString;

src/matchers/toBeDateString/predicate.test.js

@@ -0,0 +1,11 @@
+import predicate from './predicate';
+
+describe('toBeDateString Predicate', () => {
+  test('returns true when given a date string', () => {
+    expect(predicate(new Date().toISOString())).toBe(true);
+  });
+
+  test('returns false when given a non date string', () => {
+    expect(predicate('not a date')).toBe(false);
+  });
+});

types/index.d.ts

@@ -118,6 +118,13 @@ declare namespace jest {
      */
     toBeFunction(): R;
 
+    /**
+    * Use `.toBeDateString` when checking if a value is a valid date string.
+    *
+    * @param {String} string
+    */
+    toBeDateString(string: string): R;
+
     /**
      * Use `.toBeHexadecimal` when checking if a value is a valid HTML hex color.
      *
@@ -479,6 +486,13 @@ declare namespace jest {
      */
     toBeFunction(): any;
 
+    /**
+    * Use `.toBeDateString` when checking if a value is a valid date string.
+    *
+    * @param {String} string
+    */
+    toBeDateString(string: string): any;
+
     /**
      * Use `.toBeHexadecimal` when checking if a value is a valid HTML hex color.
      *