Add a "errorOnDeprecated" mode that errors when calling deprecated APIs

CHANGELOG.md

@@ -3,6 +3,7 @@
 ### Features
 
 * `[jest-watch]` create new package `jest-watch` to ease custom watch plugin development ([#6318](https://github.com/facebook/jest/pull/6318))
+* Add a config/CLI option `errorOnDeprecated` which makes calling deprecated APIs throw hepful error messages.
 
 ### Fixes
 

TestUtils.js

@@ -24,6 +24,7 @@ const DEFAULT_GLOBAL_CONFIG: GlobalConfig = {
   detectLeaks: false,
   detectOpenHandles: false,
   enabledTestsMap: null,
+  errorOnDeprecated: false,
   expand: false,
   filter: null,
   findRelatedTests: false,
@@ -75,6 +76,7 @@ const DEFAULT_PROJECT_CONFIG: ProjectConfig = {
   detectLeaks: false,
   detectOpenHandles: false,
   displayName: undefined,
+  errorOnDeprecated: false,
   filter: null,
   forceCoverageMatch: [],
   globals: {},

docs/CLI.md

@@ -149,6 +149,10 @@ Attempt to collect and print open handles preventing Jest from exiting cleanly.
 
 The test environment used for all tests. This can point to any file or node module. Examples: `jsdom`, `node` or `path/to/my-environment.js`.
 
+### `--errorOnDeprecated`
+
+Make calling deprecated APIs throw helpful error messages. Useful for easing the upgrade process.
+
 ### `--expand`
 
 Alias: `-e`. Use this flag to show full diffs and errors instead of a patch.

docs/Configuration.md

@@ -664,6 +664,12 @@ Pretty foo: Object {
 
 To make a dependency explicit instead of implicit, you can call [`expect.addSnapshotSerializer`](ExpectAPI.md#expectaddsnapshotserializerserializer) to add a module for an individual test file instead of adding its path to `snapshotSerializers` in Jest configuration.
 
+### `errorOnDeprecated` [boolean]
+
+Default: `false`
+
+Make calling deprecated APIs throw helpful error messages. Useful for easing the upgrade process.
+
 ### `testEnvironment` [string]
 
 Default: `"jsdom"`

e2e/__tests__/__snapshots__/error-on-deprecated.test.js.snap

@@ -0,0 +1,226 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`fail.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/fail.test.js
+  ✕ fail
+
+  ● fail
+
+    Illegal usage of global \`fail\`, prefer throwing an error, or the \`done.fail\` callback.
+
+      11 | test('fail', () => {
+      12 |   if (true) {
+    > 13 |     fail('The truth hurts!');
+         |     ^
+      14 |   }
+      15 | });
+      16 | 
+
+      at __tests__/fail.test.js:13:5
+
+"
+`;
+
+exports[`jasmine.addMatchers.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/jasmine.addMatchers.test.js
+  ● Test suite failed to run
+
+    Illegal usage of \`jasmine.addMatchers\`, prefer \`expect.extends\`.
+
+       7 | 'use strict';
+       8 | 
+    >  9 | jasmine.addMatchers({
+         |         ^
+      10 |   theSpanishInquisition: () => ({
+      11 |     compare: (actual, expected) => ({
+      12 |       message: 'Nobdy expects the Spanish Inquisition!',
+
+      at __tests__/jasmine.addMatchers.test.js:9:9
+
+"
+`;
+
+exports[`jasmine.any.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/jasmine.any.test.js
+  ✕ jasmine.any
+
+  ● jasmine.any
+
+    Illegal usage of \`jasmine.any\`, prefer \`expect.any\`.
+
+       8 | 
+       9 | test('jasmine.any', () => {
+    > 10 |   expect({name: 'Jessie'}).toEqual({name: jasmine.any(String)});
+         |                                                   ^
+      11 | });
+      12 | 
+
+      at __tests__/jasmine.any.test.js:10:51
+
+"
+`;
+
+exports[`jasmine.anything.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/jasmine.anything.test.js
+  ✕ jasmine.anything
+
+  ● jasmine.anything
+
+    Illegal usage of \`jasmine.anything\`, prefer \`expect.anything\`.
+
+       8 | 
+       9 | test('jasmine.anything', () => {
+    > 10 |   expect({input: ['some', 'stuff']}).toEqual({input: jasmine.anything()});
+         |                                                              ^
+      11 | });
+      12 | 
+
+      at __tests__/jasmine.anything.test.js:10:62
+
+"
+`;
+
+exports[`jasmine.arrayContaining.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/jasmine.arrayContaining.test.js
+  ✕ jasmine.arrayContaining
+
+  ● jasmine.arrayContaining
+
+    Illegal usage of \`jasmine.arrayContaining\`, prefer \`expect.arrayContaining\`.
+
+       8 | 
+       9 | test('jasmine.arrayContaining', () => {
+    > 10 |   expect(['some', 'stuff']).toEqual(jasmine.arrayContaining(['stuff']));
+         |                                             ^
+      11 | });
+      12 | 
+
+      at __tests__/jasmine.arrayContaining.test.js:10:45
+
+"
+`;
+
+exports[`jasmine.createSpy.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/jasmine.createSpy.test.js
+  ✕ jasmine.createSpy
+
+  ● jasmine.createSpy
+
+    Illegal usage of \`jasmine.createSpy\`, prefer \`jest.fn\`.
+
+       8 | 
+       9 | test('jasmine.createSpy', () => {
+    > 10 |   const mySpy = jasmine.createSpy();
+         |                         ^
+      11 |   mySpy('hello?');
+      12 |   expect(mySpy).toHaveBeenCalledWith('hello?');
+      13 | });
+
+      at __tests__/jasmine.createSpy.test.js:10:25
+
+"
+`;
+
+exports[`jasmine.objectContaining.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/jasmine.objectContaining.test.js
+  ✕ jasmine.objectContaining
+
+  ● jasmine.objectContaining
+
+    Illegal usage of \`jasmine.objectContaining\`, prefer \`expect.objectContaining\`.
+
+       9 | test('jasmine.objectContaining', () => {
+      10 |   expect({input: 'trash', output: 'trash'}).toEqual(
+    > 11 |     jasmine.objectContaining({output: 'trash'})
+         |             ^
+      12 |   );
+      13 | });
+      14 | 
+
+      at __tests__/jasmine.objectContaining.test.js:11:13
+
+"
+`;
+
+exports[`jasmine.stringMatching.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/jasmine.stringMatching.test.js
+  ✕ jasmine.stringMatching
+
+  ● jasmine.stringMatching
+
+    Illegal usage of \`jasmine.stringMatching\`, prefer \`expect.stringMatching\`.
+
+       8 | 
+       9 | test('jasmine.stringMatching', () => {
+    > 10 |   expect('Greetings Earthling!').toEqual(jasmine.stringMatching(/^Greetings/));
+         |                                                  ^
+      11 | });
+      12 | 
+
+      at __tests__/jasmine.stringMatching.test.js:10:50
+
+"
+`;
+
+exports[`pending.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/pending.test.js
+  ✕ pending
+
+  ● pending
+
+    Illegal usage of global \`pending\`, prefer explicitly skipping a test using \`test.skip\`
+
+       9 | test('pending', () => {
+      10 |   if (true) {
+    > 11 |     pending('This test is pending.');
+         |     ^
+      12 |   }
+      13 |   expect(false).toBe(true);
+      14 | });
+
+      at __tests__/pending.test.js:11:5
+
+"
+`;
+
+exports[`spyOn.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/spyOn.test.js
+  ✕ spyOn
+
+  ● spyOn
+
+    Illegal usage of global \`spyOn\`, prefer \`jest.spyOn\`.
+
+      15 | 
+      16 | test('spyOn', () => {
+    > 17 |   spyOn(subject, 'func').and.returnValue('bar');
+         |   ^
+      18 |   expect(subject.func()).toBe('bar');
+      19 | });
+      20 | 
+
+      at __tests__/spyOn.test.js:17:3
+
+"
+`;
+
+exports[`spyOnProperty.test.js errors in errorOnDeprecated mode 1`] = `
+"FAIL __tests__/spyOnProperty.test.js
+  ✕ spyOnProperty
+
+  ● spyOnProperty
+
+    Illegal usage of global \`spyOnProperty\`, prefer \`jest.spyOn\`.
+
+      22 |   };
+      23 | 
+    > 24 |   const spy = spyOnProperty(obj, 'method', 'get');
+         |               ^
+      25 | 
+      26 |   obj.method();
+      27 | 
+
+      at __tests__/spyOnProperty.test.js:24:15
+
+"
+`;

e2e/__tests__/__snapshots__/show_config.test.js.snap

@@ -14,6 +14,7 @@ exports[`--showConfig outputs config info and exits 1`] = `
       ],
       \\"detectLeaks\\": false,
       \\"detectOpenHandles\\": false,
+      \\"errorOnDeprecated\\": false,
       \\"filter\\": null,
       \\"forceCoverageMatch\\": [],
       \\"globals\\": {},
@@ -81,6 +82,7 @@ exports[`--showConfig outputs config info and exits 1`] = `
     ],
     \\"detectLeaks\\": false,
     \\"detectOpenHandles\\": false,
+    \\"errorOnDeprecated\\": false,
     \\"expand\\": false,
     \\"filter\\": null,
     \\"globalSetup\\": null,

e2e/__tests__/error-on-deprecated.test.js

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+'use strict';
+
+const runJest = require('../runJest');
+const {extractSummary} = require('../Utils');
+const ConditionalTest = require('../../scripts/ConditionalTest');
+
+ConditionalTest.skipSuiteOnJestCircus();
+
+const testFiles = [
+  'fail.test.js',
+  'jasmine.addMatchers.test.js',
+  'jasmine.any.test.js',
+  'jasmine.anything.test.js',
+  'jasmine.arrayContaining.test.js',
+  'jasmine.createSpy.test.js',
+  'jasmine.objectContaining.test.js',
+  'jasmine.stringMatching.test.js',
+  'pending.test.js',
+  'spyOn.test.js',
+  'spyOnProperty.test.js',
+];
+
+const SHOULD_NOT_PASS_IN_JEST = new Set([
+  'fail.test.js',
+  'spyOnProperty.test.js',
+]);
+
+testFiles.forEach(testFile => {
+  test(`${testFile} errors in errorOnDeprecated mode`, () => {
+    const result = runJest('error-on-deprecated', [
+      testFile,
+      '--errorOnDeprecated',
+    ]);
+    expect(result.status).toBe(1);
+    const {rest} = extractSummary(result.stderr);
+    expect(rest).toMatchSnapshot();
+  });
+});
+
+testFiles.forEach(testFile => {
+  const shouldPass = SHOULD_NOT_PASS_IN_JEST.has(testFile);
+
+  const expectation = `${testFile} ${shouldPass ? 'errors' : 'passes'}`;
+  const testName = `${expectation} when not in errorOnDeprecated mode`;
+
+  test(testName, () => {
+    const result = runJest('error-on-deprecated', [testFile]);
+    expect(result.status).toBe(shouldPass ? 1 : 0);
+  });
+});

e2e/error-on-deprecated/__tests__/fail.test.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+'use strict';
+
+/* globals fail */
+
+test('fail', () => {
+  if (true) {
+    fail('The truth hurts!');
+  }
+});

e2e/error-on-deprecated/__tests__/jasmine.addMatchers.test.js

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+'use strict';
+
+jasmine.addMatchers({
+  theSpanishInquisition: () => ({
+    compare: (actual, expected) => ({
+      message: 'Nobdy expects the Spanish Inquisition!',
+      pass: false,
+    }),
+  }),
+});
+
+test('jasmine.addMatchers', () => {
+  expect('Anybody').not.theSpanishInquisition();
+});

e2e/error-on-deprecated/__tests__/jasmine.any.test.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+'use strict';
+
+test('jasmine.any', () => {
+  expect({name: 'Jessie'}).toEqual({name: jasmine.any(String)});
+});