Merge branch 'master' into 2146-pretty-jsdom

.eslintrc

@@ -2,7 +2,10 @@
   "extends": "./packages/eslint-config-fb-strict/index.js",
   "parser": "babel-eslint",
   "rules": {
-    "no-multiple-empty-lines": 1
+    "no-multiple-empty-lines": 1,
+    "flowtype/require-valid-file-annotation": 2,
+    "flowtype/boolean-style": 2,
+    "flowtype/no-primitive-constructor-types": 2
   },
   "plugins": [
     "markdown"

.flowconfig

@@ -11,4 +11,4 @@ module.name_mapper='^types/\(.*\)$' -> '<PROJECT_ROOT>/types/\1.js'
 module.name_mapper='\(jest-[^/]*\)' -> '<PROJECT_ROOT>/packages/\1/src/index.js'
 
 [version]
-^0.41.0
+^0.43.0

README.md

@@ -102,10 +102,10 @@ Jest can be used in projects that use [webpack](https://webpack.github.io/) to m
 
 ### Using TypeScript
 
-To use TypeScript in your tests, install the `ts-jest` package:
+To use TypeScript in your tests, install the `ts-jest` package and the types for Jest.
 
 ```
-npm install --save-dev ts-jest
+npm install --save-dev ts-jest @types/jest
 ```
 
 then modify your `package.json` so the `jest` section looks something like:

docs/Configuration.md

@@ -249,6 +249,8 @@ If enabled, the module registry for every test file will be reset before running
 ### `resolver` [string]
 Default: `undefined`
 
+##### available in Jest **20.0.0+**
+
 This option allows the use of a custom resolver. This resolver must be a node module that exports a function expecting a string as the first argument for the path to resolve and an object with the following structure as the second argument:
 
 ```

docs/ExpectAPI.md

@@ -286,6 +286,58 @@ test('the best flavor is not coconut', () => {
 });
 ```
 
+### `.resolves`
+
+##### available in Jest **20.0.0+**
+
+If your code uses Promises, use the `.resolves` keyword, and Jest will wait for the Promise to resolve and then run an assertion on the resulting value.
+
+For example, this code tests that the Promise returned by `fetchData()` resolves and that the resulting value is peanut butter:
+
+```js
+test('fetchData() resolves and is peanut butter', () => {
+  // make sure to add a return statement
+  return expect(fetchData()).resolves.toBe('peanut butter');
+});
+```
+
+Alternatively, you can use `async/await` in combination with `.resolves`:
+
+```js
+test('fetchData() resolves and is peanut butter', async () => {
+  await expect(fetchData()).resolves.toBe('peanut butter');
+  await expect(fetchData()).resolves.not.toBe('coconut');
+});
+```
+
+### `.rejects`
+
+##### available in Jest **20.0.0+**
+
+If your code uses Promises, use the `.rejects` keyword, and Jest will wait for that Promise to reject and then run an assertion on the resulting value.
+
+For example, this code tests that the Promise returned by `fetchData()` rejects and that the resulting value is an error:
+
+```js
+test('fetchData() rejects to be error', () => {
+  // make sure to add a return statement
+  return expect(fetchData()).rejects.toEqual({
+    error: 'User not found',
+  });
+});
+```
+
+Alternatively, you can use `async/await` in combination with `.rejects`:
+
+```js
+test('fetchData() rejects to be error', async () => {
+  await expect(fetchData()).rejects.toEqual({
+    error: 'User not found',
+  });
+  await expect(fetchData()).rejects.not.toBe('Mark');
+});
+```
+
 ### `.toBe(value)`
 
 `toBe` just checks that a value is what you expect. It uses `===` to check
@@ -566,7 +618,7 @@ describe('my beverage', () => {
 
 ### `.toEqual(value)`
 
-Use `.toEqual` when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity. For example, `toEqual` and `toBe` behave differently in this test suite, so all the tests pass:
+Use `.toEqual` when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity—this is also known as "deep equal". For example, `toEqual` and `toBe` behave differently in this test suite, so all the tests pass:
 
 ```js
 const can1 = {

docs/GettingStarted.md

@@ -35,8 +35,10 @@ test('adds 1 + 2 to equal 3', () => {
 Add the following section to your `package.json`:
 
 ```json
-"scripts": {
-  "test": "jest"
+{
+  "scripts": {
+    "test": "jest"
+  }
 }
 ```
 

docs/ManualMocks.md

@@ -10,18 +10,13 @@ next: webpack
 
 Manual mocks are used to stub out functionality with mock data. For example, instead of accessing a remote resource like a website or a database, you might want to create a manual mock that allows you to use fake data. This ensures your tests will be fast and not flaky.
 
-Manual mocks are defined by writing a module in a `__mocks__/` subdirectory
-immediately adjacent to the module. For example, to mock a module called
-``user`` in the ``models`` directory, create a file called ``user.js`` and
-put it in the ``models/__mocks__`` directory. If the module you are mocking is
-a node module (eg: `fs`), the mock should be placed in the same parent
-directory as the ``node_modules`` folder. Eg:
+Manual mocks are defined by writing a module in a `__mocks__/` subdirectory immediately adjacent to the module. For example, to mock a module called `user` in the `models` directory, create a file called `user.js` and put it in the `models/__mocks__` directory. If the module you are mocking is a node module (eg: `fs`), the mock should be placed in the `__mocks__` directory adjacent to `node_modules`. Eg:
 
 ```bash
 .
 ├── config
-├── fs.js
 ├── __mocks__
+│   └── fs.js
 ├── models
 │   ├── __mocks__
 │   │   └── user.js

docs/MigrationGuide.md

@@ -5,7 +5,7 @@ layout: docs
 category: Guides
 permalink: docs/migration-guide.html
 previous: webpack
-next: troubleshooting
+next: testing-frameworks
 ---
 
 If you'd like to try out Jest with an existing codebase, there are a number of ways to convert to Jest:

docs/SnapshotTesting.md

@@ -42,7 +42,7 @@ exports[`Link renders correctly 1`] = `
 `;
 ```
 
-The snapshot artifact should be committed alongside code changes. Jest uses [pretty-format](https://github.com/facebook/jest/tree/master/packages/pretty-format) to make snapshots human-readable during code review. On subsequent test runs Jest will simply compare the rendered output with the previous snapshot. If they match, the test will pass. If they don't match, either the test runner found a bug in your code that should be fixed, or the implementation has changed and the snapshot needs to be updated.
+The snapshot artifact should be committed alongside code changes, and reviewed as part of your code review process. Jest uses [pretty-format](https://github.com/facebook/jest/tree/master/packages/pretty-format) to make snapshots human-readable during code review. On subsequent test runs Jest will simply compare the rendered output with the previous snapshot. If they match, the test will pass. If they don't match, either the test runner found a bug in your code that should be fixed, or the implementation has changed and the snapshot needs to be updated.
 
 More information on how snapshot testing works and why we built it can be found on the [release blog post](https://facebook.github.io/jest/blog/2016/07/27/jest-14.html). We recommend reading [this blog post](http://benmccormick.org/2016/09/19/testing-with-jest-snapshots-first-impressions/) to get a good sense of when you should use snapshot testing. We also recommend watching this [this egghead video](https://egghead.io/lessons/javascript-use-jest-s-snapshot-testing-feature?pl=testing-javascript-with-jest-a36c4074) on Snapshot Testing with Jest.
 

docs/TestingAsyncCode.md

@@ -62,14 +62,25 @@ test('the data is peanut butter', () => {
 
 Be sure to return the promise - if you omit this `return` statement, your test will complete before `fetchData` completes.
 
+##### available in Jest **20.0.0+**
+
+You can also use the `resolves` keyword in your expect statement, and Jest will wait for that promise to resolve. If the promise is rejected, the test will automatically fail.
+
+```js
+test('the data is peanut butter', () => {
+  return expect(fetchData()).resolves.toBe('peanut butter');
+});
+```
+
+Be sure to return the promise - if you omit this `return` statement, your test will complete before `fetchData` completes.
+
 ### Async/Await
 
 If your code uses `async` and `await`, you can use these in your tests as well. To write an async test, just use the `async` keyword in front of the function passed to `test`. For example, the same `fetchData` scenario can be tested with:
 
 ```js
 test('the data is peanut butter', async () => {
-  const data = await fetchData();
-  expect(data).toBe('peanut butter');
+  await expect(fetchData()).resolves.toBe('peanut butter');
 });
 ```
 

docs/TestingFrameworks.md

@@ -0,0 +1,31 @@
+---
+id: testing-frameworks
+title: Testing other frameworks
+layout: docs
+category: Guides
+permalink: docs/testing-frameworks.html
+previous: migration-guide
+next: troubleshooting
+---
+
+Although Jest may be considered React-specific test runner, in fact it is a universal testing platform, with the ability to adapt to any JavaScript library or framework. In this section we'd like to link to community posts and articles about integrating Jest into other popular JS libraries.
+
+## Vue.js
+
+* [Jest for all: Episode 1 — Vue.js](https://medium.com/@kentaromiura_the_js_guy/jest-for-all-episode-1-vue-js-d616bccbe186#.d573vrce2) by Cristian Carlesso ([@kentaromiura](https://twitter.com/kentaromiura))
+
+## AngularJS
+
+* [Testing an AngularJS app with Jest](https://medium.com/aya-experience/testing-an-angularjs-app-with-jest-3029a613251) by Matthieu Lux ([@Swiip](https://twitter.com/Swiip))
+
+## Angular
+
+* [Testing Angular faster with Jest](https://www.xfive.co/blog/testing-angular-faster-jest/) by Michał Pierzchała ([@thymikee](https://twitter.com/thymikee))
+
+## MobX
+
+* [How to Test React and MobX with Jest](https://semaphoreci.com/community/tutorials/how-to-test-react-and-mobx-with-jest) by Will Stern ([@willsterndev](https://twitter.com/willsterndev))
+
+## Redux
+
+* [Writing Tests](http://redux.js.org/docs/recipes/WritingTests.html) by Redux docs

docs/Troubleshooting.md

@@ -4,7 +4,7 @@ title: Troubleshooting
 layout: docs
 category: Guides
 permalink: docs/troubleshooting.html
-previous: migration-guide
+previous: testing-frameworks
 ---
 
 Uh oh, something went wrong? Use this guide to resolve issues with Jest.

docs/TutorialAsync.md

@@ -68,7 +68,7 @@ export default function request(url) {
 }
 ```
 
-Now let's write a test for our async functionality.
+Now let's write a test for our async functionality. Using the `resolves` keyword (available in Jest **20.0.0+**)
 ```js
 // __tests__/user-test.js
 jest.mock('../request');
@@ -77,8 +77,7 @@ import * as user from '../user';
 
 // The promise that is being tested should be returned.
 it('works with promises', () => {
-  return user.getUserName(5)
-    .then(name => expect(name).toEqual('Paul'));
+  return expect(user.getUserName(5)).resolves.toEqual('Paul');
 });
 ```
 
@@ -94,8 +93,7 @@ how you'd write the same example from before:
 ```js
 // async/await can also be used.
 it('works with async/await', async () => {
-  const userName = await user.getUserName(4);
-  expect(userName).toEqual('Mark');
+  await expect(user.getUserName(4)).resolves.toEqual('Mark');
 });
 ```
 
@@ -106,32 +104,21 @@ and enable the feature in your `.babelrc` file.
 
 ### Error handling
 
-Errors can be handled in the standard JavaScript way: Either using `.catch()`
-directly on a Promise or through `try-catch` when using async/await. Note that
-if a Promise throws and the error is not handled, the test will fail. `expect.assertion(1)` makes sure that expectation was checked once. In this example it will fail if promise was resolved without throwing.
+Errors can be handled using the keyword `rejects` in your expect statement. This will verify that the promise rejects and perform an assertion on the resulting error.
 
 ```js
 // Testing for async errors can be done using `catch`.
 it('tests error with promises', () => {
-  // to be sure that `Promise` rejected and `expect` has been called once
-  expect.assertions(1); 
-
-  return user.getUserName(3)
-    .catch(e => expect(e).toEqual({
-      error: 'User with 3 not found.',
-    }));
+  return expect(user.getUserName(3)).rejects.toEqual({
+    error: 'User with 3 not found.',
+  });
 });
 
 // Or try-catch.
 it('tests error with async/await', async () => {
-  // to be sure that `await` throws error and `expect` has been called once
-  expect.assertions(1); 
-
-  try {
-    await user.getUserName(2);
-  } catch (object) {
-    expect(object.error).toEqual('User with 2 not found.');
-  }
+  await expect(user.getUserName(3)).rejects.toEqual({
+    error: 'User with 3 not found.',
+  });
 });
 ```
 

integration_tests/__tests__/__snapshots__/globals-test.js.snap

@@ -48,10 +48,10 @@ Ran all test suites.
 
 exports[`only with expand arg 1`] = `
 " PASS  __tests__/only-constructs-test.js
+  ○ it
   ✓ test.only
   ✓ it.only
   ✓ fit
-  ○ it
   fdescribe
     ✓ it
     ✓ test

integration_tests/__tests__/coverage-remapping-test.js

@@ -18,7 +18,7 @@ skipOnWindows.suite();
 
 it('maps code coverage against original source', () => {
   const dir = path.resolve(__dirname, '../coverage-remapping');
-  run('npm install', dir);
+  run('yarn --no-lockfile', dir);
   runJest(dir, ['--coverage', '--mapCoverage', '--no-cache']);
 
   const coverageMapFile = path.join(

integration_tests/__tests__/failures-test.js

@@ -17,14 +17,22 @@ const dir = path.resolve(__dirname, '../failures');
 
 skipOnWindows.suite();
 
+// Some node versions add an extra line to the error stack trace. This makes
+// snapshot tests fail on different machines. This function makes sure
+// this extra line is always removed.
+const stripInconsistentStackLines = summary => {
+  summary.rest = summary.rest.replace(/\n^.*process\._tickCallback.*$/gm, '');
+  return summary;
+};
+
 test('throwing not Error objects', () => {
   let stderr;
   stderr = runJest(dir, ['throw-number-test.js']).stderr;
-  expect(extractSummary(stderr)).toMatchSnapshot();
+  expect(stripInconsistentStackLines(extractSummary(stderr))).toMatchSnapshot();
   stderr = runJest(dir, ['throw-string-test.js']).stderr;
-  expect(extractSummary(stderr)).toMatchSnapshot();
+  expect(stripInconsistentStackLines(extractSummary(stderr))).toMatchSnapshot();
   stderr = runJest(dir, ['throw-object-test.js']).stderr;
-  expect(extractSummary(stderr)).toMatchSnapshot();
+  expect(stripInconsistentStackLines(extractSummary(stderr))).toMatchSnapshot();
   stderr = runJest(dir, ['assertion-count-test.js']).stderr;
-  expect(extractSummary(stderr)).toMatchSnapshot();
+  expect(stripInconsistentStackLines(extractSummary(stderr))).toMatchSnapshot();
 });

integration_tests/__tests__/native-async-mock-test.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ */
+
+'use strict';
+
+const {linkJestPackage, run} = require('../utils');
+const {extractSummary} = require('../utils');
+const path = require('path');
+const runJest = require('../runJest');
+const skipOnWindows = require('skipOnWindows');
+
+skipOnWindows.suite();
+const dir = path.resolve(__dirname, '..', 'native-async-mock');
+
+test('mocks async functions', () => {
+  if (process.versions.node < '7.6.0') {
+    return;
+  }
+  if (process.platform !== 'win32') {
+    run('yarn --no-lockfile', dir);
+    linkJestPackage('babel-jest', dir);
+  }
+  // --no-cache because babel can cache stuff and result in false green
+  const {stderr} = runJest(dir, ['--no-cache']);
+  expect(extractSummary(stderr).summary).toMatch(
+    'Test Suites: 1 passed, 1 total',
+  );
+});

integration_tests/__tests__/transform-test.js

@@ -19,7 +19,7 @@ describe('babel-jest', () => {
 
   beforeEach(() => {
     if (process.platform !== 'win32') {
-      run('npm install', dir);
+      run('yarn --no-lockfile', dir);
       linkJestPackage('babel-jest', dir);
     }
   });
@@ -88,7 +88,7 @@ describe('multiple-transformers', () => {
 
   beforeEach(() => {
     if (process.platform !== 'win32') {
-      run('npm install', dir);
+      run('yarn --no-lockfile', dir);
       linkJestPackage('babel-jest', dir);
     }
   });