docs: update docs/ja

docs/ja/README.md

@@ -9,6 +9,7 @@
   * [テストランナを選ぶ](guides/choosing-a-test-runner.md)
   * [Jest による単一ファイルコンポーネントのテスト](guides/testing-SFCs-with-jest.md)
   * [Mocha + webpack による単一ファイルコンポーネントのテスト](guides/testing-SFCs-with-mocha-webpack.md)
+  * [非同期動作のテスト](guides/testing-async-components.md)
   * [Vue Router と一緒に使う](guides/using-with-vue-router.md)
   * [Vuex と一緒に使う](guides/using-with-vuex.md)
 * [API](api/README.md)

docs/ja/SUMMARY.md

@@ -7,6 +7,7 @@
   * [テストランナを選ぶ](guides/choosing-a-test-runner.md)
   * [Jest による単一ファイルコンポーネントのテスト](guides/testing-SFCs-with-jest.md)
   * [Mocha + webpack による単一ファイルコンポーネントのテスト](guides/testing-SFCs-with-mocha-webpack.md)
+  * [非同期動作のテスト](guides/testing-async-components.md)
   * [Vue Router と一緒に使う](guides/using-with-vue-router.md)
   * [Vuex と一緒に使う](guides/using-with-vuex.md)
 * [API](api/README.md)

docs/ja/api/config.md

@@ -21,5 +21,5 @@ vue-test-utils にはオプションを定義するための `config` オプシ
 ```js
 import VueTestUtils from '@vue/test-utils'
 
-VueTestUtils.config.stubs['my-compomnent'] = '<div />'
+VueTestUtils.config.stubs['my-component'] = '<div />'
 ```

docs/ja/api/mount.md

@@ -13,9 +13,7 @@
 
 - **使い方:**
 
-最初の DOM ノードまたは Vue コンポーネント一致セレクタの [`Wrapper`](./wrapper/README.md) を返します。
-
-有効な[セレクタ](./selectors.md)を使用してください。
+マウントされて描画された Vue コンポーネントを含む [`Wrapper`](./wrapper/README.md) を生成します。
 
 **オプションなし:**
 

docs/ja/api/selectors.md

@@ -23,8 +23,6 @@
 
 Vue コンポーネントもセレクタとして有効です。
 
-vue-test-utils は `name` プロパティを使用して、一致する Vue コンポーネントのインスタンスツリーを検索します。
-
 ```js
 // Foo.vue
 
@@ -44,9 +42,18 @@ expect(wrapper.is(Foo)).toBe(true)
 
 ## find メソッドのオプションオブジェクト
 
+### name
+
+find メソッドのオプションオブジェクトを使用すると、Wrapper コンポーネント内にあるコンポーネントの `name` に一致する要素を取得することができます。
+
+```js
+const buttonWrapper = wrapper.find({ name: 'my-button' })
+buttonWrapper.trigger('click')
+```
+
 ### ref
 
-find メソッドのオプションオブジェクトを使用すると、`Wrapper` コンポーネントの `$ref` プロパティに一致する要素を取得することができます。
+find メソッドのオプションオブジェクトを使用すると、Wrapper コンポーネントの `$ref` プロパティに一致する要素を取得することができます。
 
 ```js
 const buttonWrapper = wrapper.find({ ref: 'myButton' })

docs/ja/api/shallow.md

@@ -22,11 +22,8 @@
 
 - **使い方:**
 
-最初の DOM ノードまたは Vue コンポーネント一致セレクタの [`Wrapper`](./wrapper/) を返します。
-
-全ての子コンポーネントをスタブします。
-
-有効な[セレクタ](./selectors.md)を使用してください。
+[`mount`](mount.md)のようにマウントされて描画された Vue コンポーネントを含む [`Wrapper`](./wrapper/README.md) を生成しますが、  
+子コンポーネントはスタブされたコンポーネントです。
 
 **オプションなし:**
 

docs/ja/guides/README.md

@@ -6,5 +6,6 @@
 * [テストランナを選ぶ](./choosing-a-test-runner.md)
 * [Jest による単一ファイルコンポーネントのテスト](./testing-SFCs-with-jest.md)
 * [Mocha + webpack による単一ファイルコンポーネントのテスト](./testing-SFCs-with-mocha-webpack.md)
+* [非同期動作のテスト](./testing-async-components.md)
 * [Vue Router と一緒に使う](./using-with-vue-router.md)
 * [Vuex と一緒に使う](./using-with-vuex.md)

docs/ja/guides/common-tips.md

@@ -109,6 +109,9 @@ mount(Component, {
 })
 ```
 
+**Vue Router のようなプラグインはグローバルの Vue コンストラクタに read-only なプロパティを追加します。  
+これは localVue コンストラクタにそのプラグインを再びインストールすることや read-only なプロパティに対するモックを追加することを不可能にします。**
+
 ## モックの注入
 
 単純なモックを注入するための別の戦略として `mocks` オプションで行うことができます:

docs/ja/guides/dom-events.md

@@ -22,6 +22,8 @@ wrapper.find('button').trigger('click')
 
 `trigger` メソッドはオプションで `options` オブジェクトを引数として取ります。`options` オブジェクトのプロパティはイベントオブジェクトのプロパティに追加されます。
 
+target を `options` オブジェクトに追加することができないことに注意してください。
+
 ```js
 const wrapper = mount(MyButton)
 

docs/ja/guides/testing-SFCs-with-jest.md

@@ -123,7 +123,7 @@ webpack で `babel-preset-env` を使用するとした場合、webpack は ES M
 }
 ```
 
-### スナップショットテスト
+## スナップショットテスト
 
 [`vue-server-renderer`](https://github.com/vuejs/vue/tree/dev/packages/vue-server-renderer) を使ってコンポーネントを文字列に描画して保存することができます。[Jest のスナップショットテスト](https://facebook.github.io/jest/docs/en/snapshot-testing.html) のスナップショットとして表示されます。 
 
@@ -148,13 +148,47 @@ npm install --save-dev jest-serializer-vue
 }
 ```
 
-### テストファイルの配置
+## テストファイルの配置
 
 デフォルトでは、Jest はプロジェクト全体で `.spec.js` または `.test.js` 拡張子を持つすべてのファイルを再帰的に取得します。これがあなたのニーズに合わない場合は、`package.json` ファイルの config セクションで[testRegex を変更する](https://facebook.github.io/jest/docs/en/configuration.html#testregex-string)ことが可能です。
 
 Jestは、テスト対象のコードのすぐ隣に`__tests__`ディレクトリを作成することを推奨していますが、適切にテストを構造化することは自由です。 Jestがスナップショットテストを実行するテストファイルの隣に`__snapshots__`ディレクトリを作成することに注意してください。
 
-### Spec の例
+## カバレッジ
+
+Jest は複数のフォーマットでカバレッジを取ることができます。 以下はそれをするための簡単な例です。
+
+`jest` の設定 (普通は `package.json` か `jest.config.js`) に [collectCoverage](https://facebook.github.io/jest/docs/en/configuration.html#collectcoverage-boolean) オプションを加えます。それから、カバレッジを収集する対象のファイルを [collectCoverageFrom](https://facebook.github.io/jest/docs/en/configuration.html#collectcoveragefrom-array) に配列で定義します。 正確なカバレッジデータのために [mapCoverage](https://facebook.github.io/jest/docs/en/configuration.html#mapcoverage-boolean) を `true` にします。
+
+```json
+{
+  "jest": {
+    // ...
+    "collectCoverage": true,
+    "collectCoverageFrom": [
+      "**/*.{js,vue}",
+      "!**/node_modules/**"
+    ],
+    "mapCoverage": true
+  }
+}
+```
+
+[デフォルトのカバレッジレポーター](https://facebook.github.io/jest/docs/en/configuration.html#coveragereporters-array-string)のカバレッジレポートは有効になります。 `coverageReporters` オプションでそれらをカスタマイズすることができます。
+
+```json
+{
+  "jest": {
+    // ...
+    "coverageReporters": ["html", "text-summary"]
+  }
+}
+```
+
+より詳しい情報は [Jest configuration documentation](https://facebook.github.io/jest/docs/en/configuration.html#collectcoverage-boolean) にあります。 カバレッジの閾値やターゲットを出力するディレクトリなどのオプションが記載されています。
+
+
+## Spec の例
 
 あなたが Jasmine をよく知っているなら、Jest の [assertion API](https://facebook.github.io/jest/docs/en/expect.html#content)は自宅のように感じるはずです。
 
@@ -170,7 +204,7 @@ describe('Component', () => {
 })
 ```
 
-### リソース
+## リソース
 
 - [このセットアップのプロジェクト例](https://github.com/vuejs/vue-test-utils-jest-example)
 - [Vue Conf 2017のスライド](https://github.com/codebryo/vue-testing-with-jest-conf17)

docs/ja/guides/testing-SFCs-with-mocha-webpack.md

@@ -170,6 +170,10 @@ npm run unit
 
 やったー！テストを実行している!
 
+### カバレッジ
+
+mocha-webpack にコードカバレッジをセットしたい場合は、 [the mocha-webpack code coverage guide](https://github.com/zinserjan/mocha-webpack/blob/master/docs/guides/code-coverage.md) に従ってください。
+
 ### リソース
 
 - [この設定のプロジェクトの例](https://github.com/vuejs/vue-test-utils-mocha-webpack-example)

docs/ja/guides/testing-async-components.md

@@ -0,0 +1,97 @@
+# 非同期動作のテスト
+
+テストをシンプルにするために、 `vue-test-utils` はDOMの更新を同期的に適用します。しかし、コールバックや Promise のようなコンポーネントの非同期動作をテストする場合、いくつかのテクニックを知っておく必要があります。
+
+よくある非同期動作の1つとして API 呼び出しと Vuex の action があります。以下の例は API 呼び出しをするメソッドをテストする方法を示しています。この例は HTTP のライブラリである `axios` をモックしてテストを実行するために Jest を使っています。Jestのモックの詳細は[ここ](https://facebook.github.io/jest/docs/en/manual-mocks.html#content)にあります。
+
+`axios` のモックの実装はこのようにします。
+
+``` js
+export default {
+  get: () => new Promise(resolve => {
+    resolve({ data: 'value' })
+  })
+}
+```
+
+ボタンをクリックすると以下のコンポーネントは API 呼び出しをします。そして、レスポンスを `value` に代入します。
+
+``` html
+<template>
+  <button @click="fetchResults" />
+</template>
+
+<script>
+  import axios from 'axios'
+
+  export default {
+    data () {
+      return {
+        value: null
+      }
+    },
+
+    methods: {
+      async fetchResults () {
+        const response = await axios.get('mock/service')
+        this.value = response.data
+      }
+    }
+  }
+</script>
+```
+
+テストはこのように書くことができます。
+
+``` js
+import { shallow } from '@vue/test-utils'
+import Foo from './Foo'
+jest.mock('axios')
+
+test('Foo', () => {
+  it('fetches async when a button is clicked', () => {
+    const wrapper = shallow(Foo)
+    wrapper.find('button').trigger('click')
+    expect(wrapper.vm.value).toEqual('value')
+  })
+})
+```
+
+`fetchResults` 内の Promise が resolve する前にアサーションが呼ばれるので、このテストは現時点では失敗します。ほとんどのユニットテストライブラリはテストが完了したことをテストランナーに知らせるためのコールバック関数を提供します。Jest と Mocha は両方とも `done` を使います。アサーションが行われる前に確実に各 Promise が resolve するために `done` を `$nextTick` や `setTimeout` と組み合わせて使うことができます。
+
+``` js
+test('Foo', () => {
+  it('fetches async when a button is clicked', (done) => {
+    const wrapper = shallow(Foo)
+    wrapper.find('button').trigger('click')
+    wrapper.vm.$nextTick(() => {
+      expect(wrapper.vm.value).toEqual('value')
+      done()
+    })
+  })
+})
+```
+
+`$nextTick` と `setTimeout` がテストをパスする理由は `$nextTick` と `setTimeout` を処理するタスクキュー前に Promise のコールバック関数を処理するマイクロタスクキューが実行されるからです。つまり、`$nextTick` と `setTimeout` が実行される前に、マイクロタスクキュー上にあるすべての Promise のコールバック関数が実行されます。より詳しい説明は[ここ](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/)を見てください。
+
+もう1つの解決策は `async` function と npm パッケージの `flush-promises` を使用することです。`flush-promises` は堰き止められている resolve された Promise ハンドラを流します。堰き止められている Promise を流すこととテストの可読性を改善するために `await` を `flushPromises` の呼び出しの前に置きます。
+
+反映されたテストはこのようになります。
+
+``` js
+import { shallow } from '@vue/test-utils'
+import flushPromises from 'flush-promises'
+import Foo from './Foo'
+jest.mock('axios')
+
+test('Foo', () => {
+  it('fetches async when a button is clicked', async () => {
+    const wrapper = shallow(Foo)
+    wrapper.find('button').trigger('click')
+    await flushPromises()
+    expect(wrapper.vm.value).toEqual('value')
+  })
+})
+```
+
+同じテクニックをデフォルトで Promise を返す Vuex の action に適用することができます。

docs/ja/guides/using-with-vue-router.md

@@ -7,9 +7,10 @@
 これを回避するために、localeVue を作成し、その上に Vue Router をインストールすることができます。
 
 ```js
+import { shallow, createLocalVue } from '@vue/test-utils'
 import VueRouter from 'vue-router'
-const localVue = createLocalVue()
 
+const localVue = createLocalVue()
 localVue.use(VueRouter)
 
 shallow(Component, {
@@ -26,6 +27,8 @@ Vue Router をインストールする時、`router-link` と `router-view` コ
 ### スタブを使用する
 
 ```js
+import { shallow } from '@vue/test-utils'
+
 shallow(Component, {
   stubs: ['router-link', 'router-view']
 })
@@ -34,9 +37,10 @@ shallow(Component, {
 ### localVue による Vue Router のインストール
 
 ```js
+import { shallow, createLocalVue } from '@vue/test-utils'
 import VueRouter from 'vue-router'
-const localVue = createLocalVue()
 
+const localVue = createLocalVue()
 localVue.use(VueRouter)
 
 shallow(Component, {
@@ -49,6 +53,8 @@ shallow(Component, {
 時々、コンポーネントが `$route` と `$router` オブジェクトから引数によって何かをするテストをしたいときがあります。これをするためには、Vue インスタンスにカスタムモックを渡すことができます。
 
 ```js
+import { shallow } from '@vue/test-utils'
+
 const $route = {
   path: '/some/path'
 }
@@ -59,7 +65,7 @@ const wrapper = shallow(Component, {
   }
 })
 
-wrapper.vm.$router // /some/path
+wrapper.vm.$route.path // /some/path
 ```
 
 ## よくある落とし穴
@@ -68,4 +74,5 @@ Vue Router をインストールすると Vue のプロトタイプに読み取
 
 これは、`$route` または `$router` をモックを試みるテストが将来失敗することを意味します。
 
-これを回避するために、テストを実行するときに、Vue Router をインストールしないでください。
+これを回避するために、テストを実行するときに、Vue Router をグローバルにインストールしないでください。  
+上記のように localVue を使用してください。