From 27fc2ac0f9c2495c6da4128b1e95c405dec52c7b Mon Sep 17 00:00:00 2001 From: cpojer Date: Sat, 6 Jan 2018 10:51:43 +0000 Subject: [PATCH] Update README.md --- README.md | 112 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 68 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 2edda037793d..2b52e9aa1b65 100644 --- a/README.md +++ b/README.md @@ -5,22 +5,30 @@ 🃏 Delightful JavaScript Testing -- **👩🏻‍💻 Easy Setup**: Jest is a complete and easy to set up JavaScript testing solution. In fact, Jest works out of the box for any React project. +- **👩🏻‍💻 Easy Setup**: Complete and easy to set-up JavaScript testing solution. Works out of the box for any React project. -- **🏃🏽 Instant Feedback**: Failed tests run first. Fast interactive mode can switch between running all tests or only test files related to changed files. +- **🏃🏽 Instant Feedback**: Fast interactive watch mode runs only test files related to changed files and is optimized to give signal quickly. -- **📸 Snapshot Testing**: Jest can [capture snapshots](http://facebook.github.io/jest/docs/en/snapshot-testing.html) of React trees or other serializable values to simplify testing. +- **📸 Snapshot Testing**: Capture snapshots of React trees or other serializable values to simplify testing and to analyze how state changes over time. ## Getting Started -Install Jest using `npm`: + +Install Jest using [`npm`](https://www.npmjs.com/): ``` npm install --save-dev jest ``` -Let's get started by writing a test for a hypothetical function that adds two numbers. First, create a `sum.js` file: +Or via [`yarn`](https://yarnpkg.com/en/package/jest): + +``` +yarn add --dev jest +``` + +Let's get started by writing a test for a hypothetical function that adds two +numbers. First, create a `sum.js` file: ```javascript function sum(a, b) { @@ -58,33 +66,51 @@ PASS ./sum.test.js **You just successfully wrote your first test using Jest!** -This test used `expect` and `toBe` to test that two values were exactly identical. To learn about the other things that Jest can test, see [Using Matchers](https://facebook.github.io/jest/docs/en/using-matchers.html). +This test used `expect` and `toBe` to test that two values were exactly +identical. To learn about the other things that Jest can test, see +[Using Matchers](UsingMatchers.md). ## Running from command line -You can run Jest directly from the CLI (if it's globally available in your `PATH`, e.g. by `npm install -g jest`) with variety of useful options. +You can run Jest directly from the CLI (if it's globally available in your +`PATH`, e.g. by `npm install -g jest`) with variety of useful options. -Here's how to run Jest on files matching `my-test`, using `config.json` as a configuration file and display a native OS notification after the run: +Here's how to run Jest on files matching `my-test`, using `config.json` as a +configuration file and display a native OS notification after the run: ```bash jest my-test --notify --config=config.json ``` -If you'd like to learn more about running `jest` through the command line, take a look at the [Jest CLI Options](https://facebook.github.io/jest/docs/en/cli.html) page. +If you'd like to learn more about running `jest` through the command line, take +a look at the [Jest CLI Options](CLI.md) page. ## Additional Configuration ### Using Babel -To use [Babel](http://babeljs.io/), install the `babel-jest` and `regenerator-runtime` packages: +To use [Babel](http://babeljs.io/), install the `babel-jest` and +`regenerator-runtime` packages: ``` -npm install --save-dev jest babel-jest regenerator-runtime +npm install --save-dev babel-jest babel-core regenerator-runtime ``` -*Note: Explicitly installing `regenerator-runtime` is not needed if you use `npm` 3 or 4 or Yarn* +> Note: If you are using a babel version 7 then you need to install `babel-jest` +> with the following command: +> +> ``` +> npm install --save-dev babel-jest 'babel-core@^7.0.0-0' @babel/core regenerator-runtime +> ``` + +_Note: Explicitly installing `regenerator-runtime` is not needed if you use +`npm` 3 or 4 or Yarn_ -Don't forget to add a [`.babelrc`](https://babeljs.io/docs/usage/babelrc/) file in your project's root folder. For example, if you are using ES6 and [React.js](https://facebook.github.io/react/) with the [`babel-preset-es2015`](https://babeljs.io/docs/plugins/preset-es2015/) and [`babel-preset-react`](https://babeljs.io/docs/plugins/preset-react/) presets: +Don't forget to add a [`.babelrc`](https://babeljs.io/docs/usage/babelrc/) file +in your project's root folder. For example, if you are using ES6 and +[React.js](https://facebook.github.io/react/) with the +[`babel-preset-es2015`](https://babeljs.io/docs/plugins/preset-es2015/) and +[`babel-preset-react`](https://babeljs.io/docs/plugins/preset-react/) presets: ```json { @@ -94,11 +120,30 @@ Don't forget to add a [`.babelrc`](https://babeljs.io/docs/usage/babelrc/) file You are now set up to use all ES6 features and React specific syntax. -> Note: If you are using a more complicated Babel configuration, using Babel's `env` option, -keep in mind that Jest will automatically define `NODE_ENV` as `test`. -It will not use `development` section like Babel does by default when no `NODE_ENV` is set. +> Note: If you are using a more complicated Babel configuration, using Babel's +> `env` option, keep in mind that Jest will automatically define `NODE_ENV` as +> `test`. It will not use `development` section like Babel does by default when +> no `NODE_ENV` is set. + +> Note: If you've turned off transpilation of ES2015 modules with the option +> `{ "modules": false }`, you have to make sure to turn this on in your test +> environment. + +```json +{ + "presets": [["es2015", {"modules": false}], "react"], + "env": { + "test": { + "presets": [["es2015"], "react"] + } + } +} +``` -> Note: `babel-jest` is automatically installed when installing Jest and will automatically transform files if a babel configuration exists in your project. To avoid this behavior, you can explicitly reset the `transform` configuration option: +> Note: `babel-jest` is automatically installed when installing Jest and will +> automatically transform files if a babel configuration exists in your project. +> To avoid this behavior, you can explicitly reset the `transform` configuration +> option: ```json // package.json @@ -111,36 +156,15 @@ It will not use `development` section like Babel does by default when no `NODE_E ### Using webpack -Jest can be used in projects that use [webpack](https://webpack.github.io/) to manage assets, styles, and compilation. webpack does offer some unique challenges over other tools. Refer to the [webpack guide](https://facebook.github.io/jest/docs/en/webpack.html) to get started. +Jest can be used in projects that use [webpack](https://webpack.github.io/) to +manage assets, styles, and compilation. webpack does offer some unique +challenges over other tools. Refer to the [webpack guide](Webpack.md) to get +started. ### Using TypeScript -To use TypeScript in your tests, install the `ts-jest` package and the types for Jest. - -``` -npm install --save-dev jest ts-jest @types/jest -``` - -then modify your `package.json` so the `jest` section looks something like: - -```json -{ - "jest": { - "transform": { - "^.+\\.tsx?$": "ts-jest" - }, - "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$", - "moduleFileExtensions": [ - "ts", - "tsx", - "js", - "jsx", - "json", - "node" - ] - } -} -``` +To use TypeScript in your tests you can use +[ts-jest](https://github.com/kulshekhar/ts-jest). ## Documentation