feat: Add .toLog() matcher

README.md

@@ -56,6 +56,8 @@ If you've come here to help contribute - Thanks! Take a look at the [contributin
     - [.toBeBoolean()](#tobeboolean)
     - [.toBeTrue()](#tobetrue)
     - [.toBeFalse()](#tobefalse)
+  - [Console](#console)
+    - [.toLog()](#tolog)
   - [Date](#date)
     - [.toBeDate()](#tobedate)
     - [.toBeValidDate()](#tobevaliddate)
@@ -356,6 +358,21 @@ test('returns false', () => {
 });
 ```
 
+### Console
+
+#### .toLog()
+
+Use `.toLog` when checking if a callback function outputs a message to the console. The specified console method is mocked during execution so nothing will be printed to the console.
+
+```js
+expect(() => {
+  console.log('a message');
+}).toLog('a message');
+
+expect(someFunction).toLog('some deprecation warning', 'warn')
+expect(someOtherFunction).not.toLog('an error message', 'error')
+```
+
 ### ~~Date~~
 
 Proposal in #117 (*under development*)

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

@@ -0,0 +1,140 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`.not.toLog fails when the callback function outputs the expected message 1`] = `
+"<dim>expect(</><red>received</><dim>).not.toLog(</><green>expected</><dim>)</>
+
+Expected console.log not to have been called with:
+  <green>\\"console-log\\"</>
+But it was called with:
+  <red>[[\\"console-log\\"]]</>"
+`;
+
+exports[`.not.toLog fails when the callback function outputs the expected message 2`] = `
+"<dim>expect(</><red>received</><dim>).not.toLog(</><green>expected</><dim>)</>
+
+Expected console.warn not to have been called with:
+  <green>\\"console-warn\\"</>
+But it was called with:
+  <red>[[\\"console-warn\\"]]</>"
+`;
+
+exports[`.not.toLog fails when the callback function outputs the expected message 3`] = `
+"<dim>expect(</><red>received</><dim>).not.toLog(</><green>expected</><dim>)</>
+
+Expected console.error not to have been called with:
+  <green>\\"console-error\\"</>
+But it was called with:
+  <red>[[\\"console-error\\"]]</>"
+`;
+
+exports[`.not.toLog fails when the callback function outputs the expected message 4`] = `
+"<dim>expect(</><red>received</><dim>).not.toLog(</><green>expected</><dim>)</>
+
+Expected console.info not to have been called with:
+  <green>\\"console-info\\"</>
+But it was called with:
+  <red>[[\\"console-info\\"]]</>"
+`;
+
+exports[`.not.toLog fails when the callback function outputs the expected message 5`] = `
+"<dim>expect(</><red>received</><dim>).not.toLog(</><green>expected</><dim>)</>
+
+Expected console.assert not to have been called with:
+  <green>\\"console-assert\\"</>
+But it was called with:
+  <red>[[\\"console-assert\\"]]</>"
+`;
+
+exports[`.toLog fails when the callback function does not output any message 1`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.log to have been called with:
+  <green>\\"something\\"</>
+But it was not called"
+`;
+
+exports[`.toLog fails when the callback function does not output any message 2`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.warn to have been called with:
+  <green>\\"something\\"</>
+But it was not called"
+`;
+
+exports[`.toLog fails when the callback function does not output any message 3`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.error to have been called with:
+  <green>\\"something\\"</>
+But it was not called"
+`;
+
+exports[`.toLog fails when the callback function does not output any message 4`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.info to have been called with:
+  <green>\\"something\\"</>
+But it was not called"
+`;
+
+exports[`.toLog fails when the callback function does not output any message 5`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.assert to have been called with:
+  <green>\\"something\\"</>
+But it was not called"
+`;
+
+exports[`.toLog fails when the callback function does not output the expected message 1`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.log to have been called with:
+  <green>\\"something\\"</>
+But it was called with:
+  <red>[[\\"console-log\\"]]</>"
+`;
+
+exports[`.toLog fails when the callback function does not output the expected message 2`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.warn to have been called with:
+  <green>\\"something\\"</>
+But it was called with:
+  <red>[[\\"console-warn\\"]]</>"
+`;
+
+exports[`.toLog fails when the callback function does not output the expected message 3`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.error to have been called with:
+  <green>\\"something\\"</>
+But it was called with:
+  <red>[[\\"console-error\\"]]</>"
+`;
+
+exports[`.toLog fails when the callback function does not output the expected message 4`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.info to have been called with:
+  <green>\\"something\\"</>
+But it was called with:
+  <red>[[\\"console-info\\"]]</>"
+`;
+
+exports[`.toLog fails when the callback function does not output the expected message 5`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.assert to have been called with:
+  <green>\\"something\\"</>
+But it was called with:
+  <red>[[\\"console-assert\\"]]</>"
+`;
+
+exports[`.toLog fails when the callback function does not output the expected message 6`] = `
+"<dim>expect(</><red>received</><dim>).toLog(</><green>expected</><dim>)</>
+
+Expected console.log to have been called with:
+  <green>\\"something\\"</>
+But it was called with:
+  <red>[[\\"a\\", \\"b\\", \\"c\\"], [\\"console-log\\"]]</>"
+`;

src/matchers/toLog/index.js

@@ -0,0 +1,30 @@
+import { matcherHint, printExpected, printReceived } from 'jest-matcher-utils';
+
+import predicate from './predicate';
+
+const calledWith = actual =>
+  actual ? 'But it was called with:\n' + `  ${printReceived(actual)}` : 'But it was not called';
+
+const passMessage = (actual, expected, consoleMethod) => () =>
+  matcherHint('.not.toLog') +
+  '\n\n' +
+  `Expected console.${consoleMethod} not to have been called with:\n` +
+  `  ${printExpected(expected)}\n` +
+  calledWith(actual);
+
+const failMessage = (actual, expected, consoleMethod) => () =>
+  matcherHint('.toLog') +
+  '\n\n' +
+  `Expected console.${consoleMethod} to have been called with:\n` +
+  `  ${printExpected(expected)}\n` +
+  calledWith(actual);
+
+export default {
+  toLog: (fn, expected, consoleMethod = 'log') => {
+    const { actual, pass } = predicate(fn, expected, consoleMethod);
+    if (pass) {
+      return { pass: true, message: passMessage(actual, expected, consoleMethod) };
+    }
+    return { pass: false, message: failMessage(actual, expected, consoleMethod) };
+  }
+};

src/matchers/toLog/index.test.js

@@ -0,0 +1,73 @@
+import matcher from './';
+
+expect.extend(matcher);
+
+const log = () => console.log('console-log'); // eslint-disable-line
+const warn = () => console.warn('console-warn'); // eslint-disable-line
+const error = () => console.error('console-error'); // eslint-disable-line
+const info = () => console.info('console-info'); // eslint-disable-line
+const assert = () => console.assert('console-assert'); // eslint-disable-line
+const noop = () => {};
+
+describe('.toLog', () => {
+  test('passes when the callback function outputs the expected message to the console', () => {
+    expect(log).toLog('console-log');
+    expect(warn).toLog('console-warn', 'warn');
+    expect(error).toLog('console-error', 'error');
+    expect(info).toLog('console-info', 'info');
+    expect(assert).toLog('console-assert', 'assert');
+    expect(() => console.log(1)).toLog(1); // eslint-disable-line
+    expect(() => console.log([1, 2])).toLog([1, 2]); // eslint-disable-line
+    expect(() => console.log({ a: 1, b: 2 })).toLog({ a: 1, b: 2 }); // eslint-disable-line
+  });
+  test('fails when the callback function does not output any message', () => {
+    expect(() => expect(noop).toLog('something')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(noop).toLog('something', 'warn')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(noop).toLog('something', 'error')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(noop).toLog('something', 'info')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(noop).toLog('something', 'assert')).toThrowErrorMatchingSnapshot();
+  });
+  test('fails when the callback function does not output the expected message', () => {
+    expect(() => expect(log).toLog('something')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(warn).toLog('something', 'warn')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(error).toLog('something', 'error')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(info).toLog('something', 'info')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(assert).toLog('something', 'assert')).toThrowErrorMatchingSnapshot();
+    expect(() =>
+      expect(() => {
+        console.log('a', 'b', 'c'); // eslint-disable-line
+        log();
+      }).toLog('something')
+    ).toThrowErrorMatchingSnapshot();
+  });
+  test('passes when the callback function outputs the expected message among others', () => {
+    expect(() => {
+      console.log('something'); // eslint-disable-line
+      log();
+    }).toLog('console-log');
+  });
+});
+
+describe('.not.toLog', () => {
+  test('passes when the callback function does not output anything', () => {
+    expect(noop).not.toLog('something');
+    expect(noop).not.toLog('something', 'warn');
+    expect(noop).not.toLog('something', 'error');
+    expect(noop).not.toLog('something', 'info');
+    expect(noop).not.toLog('something', 'assert');
+  });
+  test('passes when the callback function does not output the expected message', () => {
+    expect(log).not.toLog('something');
+    expect(warn).not.toLog('something', 'warn');
+    expect(error).not.toLog('something', 'error');
+    expect(info).not.toLog('something', 'info');
+    expect(assert).not.toLog('something', 'assert');
+  });
+  test('fails when the callback function outputs the expected message', () => {
+    expect(() => expect(log).not.toLog('console-log')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(warn).not.toLog('console-warn', 'warn')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(error).not.toLog('console-error', 'error')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(info).not.toLog('console-info', 'info')).toThrowErrorMatchingSnapshot();
+    expect(() => expect(assert).not.toLog('console-assert', 'assert')).toThrowErrorMatchingSnapshot();
+  });
+});

src/matchers/toLog/predicate.js

@@ -0,0 +1,21 @@
+import { equals } from 'expect/build/jasmine_utils';
+
+export default (fn, expected, consoleMethod) => {
+  const spy = jest.spyOn(console, consoleMethod);
+  spy.mockImplementation(() => {});
+  fn();
+  spy.mockRestore();
+  if (spy.mock.calls.length === 0) {
+    return { pass: false };
+  }
+  const actual = spy.mock.calls;
+  let pass = false;
+  actual.forEach(call => {
+    call.forEach(arg => {
+      if (equals(arg, expected)) {
+        pass = true;
+      }
+    });
+  });
+  return { actual, pass };
+};

src/matchers/toLog/predicate.test.js

@@ -0,0 +1,20 @@
+import predicate from './predicate';
+
+const fn = () => console.log('console-log'); // eslint-disable-line
+
+describe('Predicate > .toLog', () => {
+  test('returns an object with pass status and the actual output', () => {
+    const expected = 'console-log';
+    const consoleMethod = 'log';
+    const { pass, actual } = predicate(fn, expected, consoleMethod);
+    expect(pass).toEqual(true);
+    expect(actual).toEqual([['console-log']]);
+  });
+  it('returns an object with fail status and the actual output', () => {
+    const expected = 'something';
+    const consoleMethod = 'log';
+    const { pass, actual } = predicate(fn, expected, consoleMethod);
+    expect(pass).toEqual(false);
+    expect(actual).toEqual([['console-log']]);
+  });
+});

types/index.d.ts

@@ -355,6 +355,15 @@ declare namespace jest {
      * @param {String | RegExp} message
      */
     toThrowWithMessage(type: Function, message: string | RegExp): R;
+
+    /**
+     * Use `.toLog` when checking if a callback function outputs a message to the console. 
+     * The specified console method is mocked during execution so nothing will be printed to the console.
+     * 
+     * @param {*} logOutput
+     * @param {String} [consoleMethod=log]
+     */
+    toLog(logOutput: any, consoleMethod?: string): R;
   }
 
   // noinspection JSUnusedGlobalSymbols