docs: further brush up

yyx990803 · yyx990803 · commit 32857f2d369e · 2017-09-28T16:19:19.000-04:00
diff --git a/docs/LANGS.md b/docs/LANGS.md
@@ -1 +1 @@
-* [0.0.1 - English](en/)
+* [English](en/)
diff --git a/docs/en/README.md b/docs/en/README.md
@@ -88,17 +88,14 @@ Read the following guides for different setups:
 - [Testing SFCs with Jest](./guides/testing-SFCs-with-jest.md)
 - [Testing SFCs with Mocha + webpack](./guides/testing-SFCs-with-mocha-webpack.md)
 
-## Knowing what to test
+### Knowing What to Test
 
-It's difficult to generalize what you should test and what you shouldn't, because it's a trade-off that has to do with your development requirements and time constraints. However, there are some general rules you can follow.
+For UI components, we don't recommend aiming for complete line-based coverage, because it leads to too much focus on the internal implementation details of the components and could result in brittle tests.
 
-You should write tests to assert your component's logic, not implementation details. The best way to test the logic of component is to make sure an input (user interaction or change of props) creates the expected output.
+Instead, we recommend writing tests that assert your component's public interface, and treat its internals as a black box. A single test case would assert that some input (user interaction or change of props) provided to the component results in the expected output (render result or emitted custom events).
 
-For example, imagine we have a `Counter` component that increments a display counter by 1 each time a button is clicked. The test should perform the click and assert that the counter increased by 1. This ensures that your test is not implementation specific. You can rewrite the logic of the test, and as long as clicking a button still updates the counter text, the test will pass.
+For example, imagine we have a `Counter` component that increments a display counter by 1 each time a button is clicked. Its test case would simulate the click and assert that the rendered output has increased by 1. The test doesn't care about how the Counter increments the value, it only cares about the input and the output.
 
-## Example projects
+The benefit of this approach is that as long as your component's public interface remains the same, your tests will pass no matter how the component's internal implementation changes over time.
 
-- [example with Jest](https://github.com/eddyerburgh/vue-test-utils-jest-example)
-- [example with Mocha](https://github.com/eddyerburgh/vue-test-utils-mocha-example)
-- [example with tape](https://github.com/eddyerburgh/vue-test-utils-tape-example)
-- [example with AVA](https://github.com/eddyerburgh/vue-test-utils-ava-example)
+This topic is discussed with more details in a [great presentation by Matt O'Connell](http://slides.com/mattoconnell/deck#/).
diff --git a/docs/en/SUMMARY.md b/docs/en/SUMMARY.md
@@ -1,12 +1,13 @@
 ## Table of Contents
 
-* Guides
+* [Guides](guides/README.md)
   * [Choosing a test runner](guides/choosing-a-test-runner.md)
   * [Using with Jest](guides/using-with-jest.md)
   * [Testing SFCs with Jest](guides/testing-SFCs-with-jest.md)
   * [Testing SFCs with Mocha + webpack](guides/testing-SFCs-with-mocha-webpack.md)
   * [Using with Vuex](guides/using-with-vuex.md)
-* API
+  * [General Tips](guides/general-tips.md)
+* [API](api/README.md)
   * [createLocalVue](api/createLocalVue.md)
   * [mount](api/mount.md)
   * [shallow](api/shallow.md)
@@ -43,4 +44,3 @@
     * [setProps](api/wrapper-array/setProps.md)
     * [trigger](api/wrapper-array/trigger.md)
   * [Selectors](api/selectors.md)
-  * [Common gotchas](common-gotchas.md)
diff --git a/docs/en/api/createLocalVue.md b/docs/en/api/createLocalVue.md
@@ -5,7 +5,7 @@
 
 - **Usage:**
 
-createLocalVue returns a Vue class for you to add components, mixins and install plugins without polluting the global Vue class.
+`createLocalVue` returns a Vue class for you to add components, mixins and install plugins without polluting the global Vue class.
 
 Use it with `options.localVue`
 
@@ -25,4 +25,4 @@ const freshWrapper = shallow(Foo)
 expect(freshWrapper.vm.foo).to.equal(false)
 ```
 
-- **See also:** [Common Gotchas](common-gotchas.md)
+- **See also:** [General Tips](../guides/general-tips.md)
diff --git a/docs/en/common-gotchas.md b/docs/en/common-gotchas.md
diff --git a/docs/en/guides/README.md b/docs/en/guides/README.md
@@ -5,3 +5,4 @@
 * [Testing SFCs with Jest](./testing-SFCs-with-jest.md)
 * [Testing SFCs with Mocha + webpack](./testing-SFCs-with-mocha-webpack.md)
 * [Using with Vuex](./using-with-vuex.md)
+* [General Tips](./general-tips.md)
diff --git a/docs/en/guides/general-tips.md b/docs/en/guides/general-tips.md
@@ -0,0 +1,37 @@
+# General Tips
+
+## Browser Environment
+
+`vue-test-utils` relies on a browser environment. Technically you can run it in a real browser, but it's not recommended due to the complexity of launching real browsers on different platforms. Instead, we recommend running the tests in Node.js with a virtual browser environment using [JSDOM](https://github.com/tmpvar/jsdom).
+
+The Jest test runner sets up JSDOM automatically. For other test runners, you can manually set up JSDOM for the tests using [jsdom-global](https://github.com/rstacruz/jsdom-global) in the entry for your tests:
+
+``` bash
+npm install --save-dev jsdom jsdom-global
+```
+---
+``` js
+// in test setup / entry
+require('jsdom-global')()
+```
+
+## Testing Components that Rely on Global Plugins and Mixins
+
+Some of the components may rely on features injected by a global plugin or mixin, for example `vuex` and `vue-router`.
+
+If you are writing tests for components in a specific app, you can setup the same global plugins and mixins once in the entry of your tests. But in some cases, for example testing a generic component suite that may get shared across different apps, it's better to test your components in a more isolated setup, without polluting the global `Vue` constructor. We can use the [createLocalVue](../api/createLocalVue.md) method to achieve that:
+
+``` js
+import createLocalVue from 'vue-test-utils'
+
+// create an extended Vue constructor
+const localVue = createLocalVue()
+
+// install plugins as normal
+localVue.use(MyPlugin)
+
+// pass the localVue to the mount options
+mount(Component, {
+  localVue
+})
+```
diff --git a/docs/en/guides/testing-SFCs-with-jest.md b/docs/en/guides/testing-SFCs-with-jest.md
@@ -42,13 +42,14 @@ We need to add a `.babelrc` file, to tell babel to use the env preset:
 }
 ```
 
-By default, Jest doesn't recognize .vue files. So we need to tell Jest how to handle them. To do that we need to install jest-vue, which preprocesses .vue files:
+By default, Jest doesn't recognize `.vue` files. So we need to tell Jest how to handle them. To do that we need to install jest-vue, which preprocesses `.vue` files:
 
 ```
 npm install --sav-dev jest-vue
 ```
 
 In our `package.json`, we need to add a field to tell Jest how to treat .vue files:
+
 ```json
 // package.json
 {
diff --git a/docs/en/guides/testing-SFCs-with-mocha-webpack.md b/docs/en/guides/testing-SFCs-with-mocha-webpack.md
@@ -23,44 +23,35 @@ Next we need to define a unit script in our `package.json`.
 }
 ```
 
-This script tells mocha-webpack to get the webpack config from build/webpack.conf.js, run all test files in the test directory and run test/setup.js before the tests.
+This script tells `mocha-webpack` to get the webpack config from `build/webpack.conf.js`, run all test files in the test directory and run `test/setup.js` before the tests.
+
+### Setting Up Browser Environment
 
 Let's create the setup.js script first.
 
-`vue-test-utils` requires a browser environment to run. We can set one up using browser-env (a wrapper around JSDOM).
+`vue-test-utils` requires a browser environment to run. We can set one up using `jsdom-global`, which setups a JSDOM instance and attaches necessary globals to the Node process.
 
-Let's install that:
+Let's install the dependencies:
 
-```
-npm install --save-dev browser-env
+```bash
+npm install --save-dev jsdom jsdom-global
 ```
 
-Create a test/setup.js file and paste the following code in:
+Create a `test/setup.js` file and paste the following code in:
 
-```
-require('browser-env')();
+``` js
+require('jsdom-global')()
 ```
 
 This adds a browser environment to node, so that `vue-test-utils` can run correctly.
 
-Next, we need to install babel and configure it so we can use ES6 features in our JavaScript:
+### Configuring webpack
 
-```bash
-npm install --save-dev babel-core babel-preset-env
-```
+Now we need to create a webpack config file. In most cases your test config should use the same `module` rules with your projects existing webpack config. We recommend extracting the common config options into a base file and extend it separately for build and testing.
 
-and create a .babelrc file in the root of the project, that tells babel to use the env preset:
+One specific tweak needed for the test config is that we should externalize Node dependencies with `webpack-node-externals`. This significantly speeds up the bundling process.
 
-```json
-// .babelrc
-{
-  "presets": ["env"]
-}
-```
-
-*babel-preset-env allows compiling the JS based on the browsers you plan to support. Get more info here: [babel-preset-env](https://github.com/babel/babel-preset-env)*
-
-Now we need to create a webpack config file. Create a build/webpack.conf.js file, and add the following code:
+For our example project, the config looks like this:
 
 ```js
 const nodeExternals = require('webpack-node-externals')
@@ -84,17 +75,17 @@ module.exports = {
 }
 ```
 
-That's the setup done. Now to add a test.
-
+### Configuring Babel
 
-## Adding a test
+Notice that we are using `babel-loader` to handle JavaScript. You should already have Babel configured if you are using it in your app, e.g. via a `.babelrc` file. Here `babel-loader` will automatically use the same config file.
 
-Create a file in src named Counter.vue.
+One thing to note is that if you are using Node 6+, which already supports the majority of ES2015 features, you can configure a separate Babel [env option](https://babeljs.io/docs/usage/babelrc/#env-option) that only transpiles features that are not already supported in the Node version you are using (e.g. `stage-2` or flow syntax support, etc.)
 
-Paste the following code in src/Counter.vue:
+### Adding a test
 
+Create a file in `src` named `Counter.vue`:
 
-```vue
+``` html
 <template>
 	<div>
 	  {{ count }}
@@ -119,7 +110,7 @@ export default {
 </script>
 ```
 
-And create a test file—`test/Counter.spec.js`. Paste the code below into the file:
+And create a test file named `test/Counter.spec.js` with the following code:
 
 ```js
 import { shallow } from 'vue-test-utils'
@@ -135,7 +126,7 @@ describe('Counter.vue', () => {
 })
 ```
 
-Notice we're using expect from chai to make our assertion. We need to install chai before running the tests:
+Notice we're using `expect` from `chai` to make our assertion. We need to install chai before running the tests:
 
 ```
 npm install --save-dev chai
@@ -147,7 +138,7 @@ And now we can run the test:
 npm run unit
 ```
 
-Great, the tests are running!
+Woohoo, we got our tests running!
 
 ### Resources
 
diff --git a/docs/en/guides/using-with-vuex.md b/docs/en/guides/using-with-vuex.md

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-* [0.0.1 - English](en/)`
	`1`	`+* [English](en/)`
Original file line number	Diff line number	Diff line change
@@ -42,13 +42,14 @@ We need to add a `.babelrc` file, to tell babel to use the env preset:
`42`	`42`	`}`
`43`	`43`	```
`44`	`44`
`45`		`-By default, Jest doesn't recognize .vue files. So we need to tell Jest how to handle them. To do that we need to install jest-vue, which preprocesses .vue files:`
	`45`	+By default, Jest doesn't recognize `.vue` files. So we need to tell Jest how to handle them. To do that we need to install jest-vue, which preprocesses `.vue` files:
`46`	`46`
`47`	`47`	```
`48`	`48`	`npm install --sav-dev jest-vue`
`49`	`49`	```
`50`	`50`
`51`	`51`	In our `package.json`, we need to add a field to tell Jest how to treat .vue files:
	`52`	`+`
`52`	`53`	```json
`53`	`54`	`// package.json`
`54`	`55`	`{`