From 4378483f0844c3946146cdcd711406adf01e401d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A0=20Fontcuberta?= Date: Tue, 7 Jul 2020 17:55:02 +0200 Subject: [PATCH 1/8] docs: create section for installation docs --- docs/.vuepress/config.js | 1 + docs/README.md | 11 ++-- docs/guides/README.md | 5 -- docs/guides/getting-started.md | 51 +------------------ docs/installation/README.md | 7 +++ .../choosing-a-test-runner.md | 0 ...esting-single-file-components-with-jest.md | 2 +- ...sting-single-file-components-with-karma.md | 0 ...ngle-file-components-with-mocha-webpack.md | 0 .../usage-without-a-build-step-node.md | 8 +-- 10 files changed, 21 insertions(+), 64 deletions(-) create mode 100644 docs/installation/README.md rename docs/{guides => installation}/choosing-a-test-runner.md (100%) rename docs/{guides => installation}/testing-single-file-components-with-jest.md (99%) rename docs/{guides => installation}/testing-single-file-components-with-karma.md (100%) rename docs/{guides => installation}/testing-single-file-components-with-mocha-webpack.md (100%) rename docs/{guides => installation}/usage-without-a-build-step-node.md (95%) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 2e7034774..4782634df 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -57,6 +57,7 @@ module.exports = { ], sidebar: [ '/', + '/installation/', '/guides/', '/api/', '/api/wrapper/', diff --git a/docs/README.md b/docs/README.md index c85386834..8a7a1074f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,15 +4,16 @@ Vue Test Utils is the official unit testing utility library for Vue.js.
Learn how to test Vue.js components with Vue School
+- [Installation](./installation/) + - [Choosing a test runner](installation/choosing-a-test-runner.md) + - [Testing Single-File Components with Jest](installation/testing-single-file-components-with-jest.md) + - [Testing Single-File Components with Mocha + webpack](installation/testing-single-file-components-with-mocha-webpack.md) + - [Testing Single-File Components with Karma](installation/testing-single-file-components-with-karma.md) + - [Testing in Node.js Without a Build Step](installation/usage-without-a-build-step-node.md) - [Guides](./guides/) - [Getting Started](./guides/getting-started.md) - [Common Tips](guides/common-tips.md) - [Mouse, Key and other DOM Events](guides/dom-events.md) - - [Choosing a test runner](guides/choosing-a-test-runner.md) - - [Testing Single-File Components with Jest](guides/testing-single-file-components-with-jest.md) - - [Testing Single-File Components with Mocha + webpack](guides/testing-single-file-components-with-mocha-webpack.md) - - [Testing Single-File Components with Karma](guides/testing-single-file-components-with-karma.md) - - [Testing in Node.js Without a Build Step](guides/usage-without-a-build-step-node.md) - [Testing Asynchronous Behavior](guides/testing-async-components.md) - [Using with TypeScript](guides/using-with-typescript.md) - [Using with Vue Router](guides/using-with-vue-router.md) diff --git a/docs/guides/README.md b/docs/guides/README.md index 1792ea228..6953194d5 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -3,11 +3,6 @@ !!!include(docs/guides/getting-started.md)!!! !!!include(docs/guides/common-tips.md)!!! !!!include(docs/guides/dom-events.md)!!! -!!!include(docs/guides/choosing-a-test-runner.md)!!! -!!!include(docs/guides/testing-single-file-components-with-jest.md)!!! -!!!include(docs/guides/testing-single-file-components-with-mocha-webpack.md)!!! -!!!include(docs/guides/testing-single-file-components-with-karma.md)!!! -!!!include(docs/guides/usage-without-a-build-step-node.md)!!! !!!include(docs/guides/testing-async-components.md)!!! !!!include(docs/guides/using-with-typescript.md)!!! !!!include(docs/guides/using-with-vue-router.md)!!! diff --git a/docs/guides/getting-started.md b/docs/guides/getting-started.md index 96d37dfea..c4f69e49f 100644 --- a/docs/guides/getting-started.md +++ b/docs/guides/getting-started.md @@ -4,56 +4,9 @@ ### Setup -To get a quick taste of using Vue Test Utils, clone our demo repository with basic setup and install the dependencies: +If you already have a project that was created with the [Vue CLI](https://cli.vuejs.org/), you might want to add and configure the [core Jest plugin](https://cli.vuejs.org/core-plugins/unit-jest.html) or the [core Mocha plugin](https://cli.vuejs.org/core-plugins/unit-mocha.html). -```bash -git clone https://github.com/vuejs/vue-test-utils-getting-started -cd vue-test-utils-getting-started -npm install -``` - -If you already have a project that was created with the [Vue CLI](https://cli.vuejs.org/) and want to add testing capabilities you may run: - -```bash -# unit testing -vue add @vue/unit-jest - -# or: -vue add @vue/unit-mocha - -# end-to-end -vue add @vue/e2e-cypress - -# or: -vue add @vue/e2e-nightwatch -``` - -You will see that the project includes a simple component, `counter.js`: - -```js -// counter.js - -export default { - template: ` -
- {{ count }} - -
- `, - - data() { - return { - count: 0 - } - }, - - methods: { - increment() { - this.count++ - } - } -} -``` +If needed, check out the [Installation guides](../installation/README.md) for further details. ### Mounting Components diff --git a/docs/installation/README.md b/docs/installation/README.md new file mode 100644 index 000000000..fbe5f4674 --- /dev/null +++ b/docs/installation/README.md @@ -0,0 +1,7 @@ +# Installation + +!!!include(docs/installation/choosing-a-test-runner.md)!!! +!!!include(docs/installation/testing-single-file-components-with-jest.md)!!! +!!!include(docs/installation/testing-single-file-components-with-mocha-webpack.md)!!! +!!!include(docs/installation/testing-single-file-components-with-karma.md)!!! +!!!include(docs/installation/usage-without-a-build-step-node.md)!!! diff --git a/docs/guides/choosing-a-test-runner.md b/docs/installation/choosing-a-test-runner.md similarity index 100% rename from docs/guides/choosing-a-test-runner.md rename to docs/installation/choosing-a-test-runner.md diff --git a/docs/guides/testing-single-file-components-with-jest.md b/docs/installation/testing-single-file-components-with-jest.md similarity index 99% rename from docs/guides/testing-single-file-components-with-jest.md rename to docs/installation/testing-single-file-components-with-jest.md index 7c31a8cab..c84eb3d88 100644 --- a/docs/guides/testing-single-file-components-with-jest.md +++ b/docs/installation/testing-single-file-components-with-jest.md @@ -188,7 +188,7 @@ When you mount a component with Vue Test Utils, you get access to the root HTML ```js test('renders correctly', () => { const wrapper = mount(Component) - expect(wrapper.element).toMatchSnapshot() + expect(wrapper.html()).toMatchSnapshot() }) ``` diff --git a/docs/guides/testing-single-file-components-with-karma.md b/docs/installation/testing-single-file-components-with-karma.md similarity index 100% rename from docs/guides/testing-single-file-components-with-karma.md rename to docs/installation/testing-single-file-components-with-karma.md diff --git a/docs/guides/testing-single-file-components-with-mocha-webpack.md b/docs/installation/testing-single-file-components-with-mocha-webpack.md similarity index 100% rename from docs/guides/testing-single-file-components-with-mocha-webpack.md rename to docs/installation/testing-single-file-components-with-mocha-webpack.md diff --git a/docs/guides/usage-without-a-build-step-node.md b/docs/installation/usage-without-a-build-step-node.md similarity index 95% rename from docs/guides/usage-without-a-build-step-node.md rename to docs/installation/usage-without-a-build-step-node.md index 3613183ba..62a7f8266 100644 --- a/docs/guides/usage-without-a-build-step-node.md +++ b/docs/installation/usage-without-a-build-step-node.md @@ -8,11 +8,11 @@ While it is common to build Vue applications using tools [Webpack](https://webpa In this example, we will demonstrate how to write a simple test using nothing but the minimal dependencies described above. The final code can be found [here](https://github.com/lmiller1990/vue-test-utils-node-basic). -## Installing the Dependencies +### Installing the Dependencies We need to install some dependencies, as explained above: `npm install vue vue-template-compiler jsdom jsdom-global @vue/test-utils`. No test runner or bundler is needed for this example. -## Requiring the Libraries +### Requiring the Libraries Now we need to require the libraries. There is a slight caveat, explained in a comment, and in depth below the snippet. @@ -30,7 +30,7 @@ const VueTestUtils = require('@vue/test-utils') As the comment says, `jsdom-global` must be required before `@vue/test-utils`. This is because Vue Test Utils expects a DOM to be present to render the Vue components. If you are running the tests in a real browser, you will not need `jsdom` at all. `Vue` must also be required before `@vue/test-utils` for obvious reasons - Vue Test Utils expects to be available, as well. We also require `assert` from the node standard library. Normally we would use the matchers provided by a test runner, often in the format of an `expect(...).toEqual(...)` assertion, but `assert` will serve this purpose for this example. -## Writing a Test +### Writing a Test Now everything is set up, all we need is a component and a test. To keep things simple, we will just render some text and assert it is present in the rendered component. @@ -47,7 +47,7 @@ const App = Vue.component('app', { ` }) -const wrapper = VueTestUtils.shallowMount(App) +const wrapper = VueTestUtils.mount(App) assert.strictEqual('Hello Vue Test Utils', wrapper.text()) ``` From b069296e104795e6a4bf10890b3f27f98e0efa57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A0=20Fontcuberta?= Date: Tue, 7 Jul 2020 18:00:45 +0200 Subject: [PATCH 2/8] docs(ja): create section for installation docs --- docs/ja/README.md | 9 +++++---- docs/ja/guides/README.md | 4 ---- docs/ja/installation/README.md | 6 ++++++ .../{guides => installation}/choosing-a-test-runner.md | 0 .../testing-single-file-components-with-jest.md | 0 .../testing-single-file-components-with-karma.md | 0 .../testing-single-file-components-with-mocha-webpack.md | 0 7 files changed, 11 insertions(+), 8 deletions(-) create mode 100644 docs/ja/installation/README.md rename docs/ja/{guides => installation}/choosing-a-test-runner.md (100%) rename docs/ja/{guides => installation}/testing-single-file-components-with-jest.md (100%) rename docs/ja/{guides => installation}/testing-single-file-components-with-karma.md (100%) rename docs/ja/{guides => installation}/testing-single-file-components-with-mocha-webpack.md (100%) diff --git a/docs/ja/README.md b/docs/ja/README.md index d3d211078..7f001c06d 100644 --- a/docs/ja/README.md +++ b/docs/ja/README.md @@ -2,14 +2,15 @@ `vue-test-utils`は Vue.js 向けの公式単体テストライブラリです。 +- [インスト](installation/) + - [テストランナを選ぶ](installation/choosing-a-test-runner.md) + - [Jest による単一ファイルコンポーネントのテスト](installation/testing-single-file-components-with-jest.md) + - [Mocha + webpack による単一ファイルコンポーネントのテスト](installation/testing-single-file-components-with-mocha-webpack.md) + - [Karma による単一ファイルコンポーネントのテスト](installation/testing-single-file-components-with-karma.md) - [ガイド](guides/) - [はじめる](guides/getting-started.md) - [一般的なヒント](guides/common-tips.md) - [キー、マウス、その他の DOM イベントのテスト](guides/dom-events.md) - - [テストランナを選ぶ](guides/choosing-a-test-runner.md) - - [Jest による単一ファイルコンポーネントのテスト](guides/testing-single-file-components-with-jest.md) - - [Mocha + webpack による単一ファイルコンポーネントのテスト](guides/testing-single-file-components-with-mocha-webpack.md) - - [Karma による単一ファイルコンポーネントのテスト](guides/testing-single-file-components-with-karma.md) - [非同期動作のテスト](guides/testing-async-components.md) - [TypeScript と一緒に使う](guides/using-with-typescript.md) - [Vue Router と一緒に使う](guides/using-with-vue-router.md) diff --git a/docs/ja/guides/README.md b/docs/ja/guides/README.md index 1ae3bf2a1..5897f1978 100644 --- a/docs/ja/guides/README.md +++ b/docs/ja/guides/README.md @@ -3,10 +3,6 @@ !!!include(docs/ja/guides/getting-started.md)!!! !!!include(docs/ja/guides/common-tips.md)!!! !!!include(docs/ja/guides/dom-events.md)!!! -!!!include(docs/ja/guides/choosing-a-test-runner.md)!!! -!!!include(docs/ja/guides/testing-single-file-components-with-jest.md)!!! -!!!include(docs/ja/guides/testing-single-file-components-with-mocha-webpack.md)!!! -!!!include(docs/ja/guides/testing-single-file-components-with-karma.md)!!! !!!include(docs/ja/guides/testing-async-components.md)!!! !!!include(docs/ja/guides/using-with-typescript.md)!!! !!!include(docs/ja/guides/using-with-vue-router.md)!!! diff --git a/docs/ja/installation/README.md b/docs/ja/installation/README.md new file mode 100644 index 000000000..bbdba38ac --- /dev/null +++ b/docs/ja/installation/README.md @@ -0,0 +1,6 @@ +# インスト + +!!!include(docs/ja/guides/choosing-a-test-runner.md)!!! +!!!include(docs/ja/guides/testing-single-file-components-with-jest.md)!!! +!!!include(docs/ja/guides/testing-single-file-components-with-mocha-webpack.md)!!! +!!!include(docs/ja/guides/testing-single-file-components-with-karma.md)!!! diff --git a/docs/ja/guides/choosing-a-test-runner.md b/docs/ja/installation/choosing-a-test-runner.md similarity index 100% rename from docs/ja/guides/choosing-a-test-runner.md rename to docs/ja/installation/choosing-a-test-runner.md diff --git a/docs/ja/guides/testing-single-file-components-with-jest.md b/docs/ja/installation/testing-single-file-components-with-jest.md similarity index 100% rename from docs/ja/guides/testing-single-file-components-with-jest.md rename to docs/ja/installation/testing-single-file-components-with-jest.md diff --git a/docs/ja/guides/testing-single-file-components-with-karma.md b/docs/ja/installation/testing-single-file-components-with-karma.md similarity index 100% rename from docs/ja/guides/testing-single-file-components-with-karma.md rename to docs/ja/installation/testing-single-file-components-with-karma.md diff --git a/docs/ja/guides/testing-single-file-components-with-mocha-webpack.md b/docs/ja/installation/testing-single-file-components-with-mocha-webpack.md similarity index 100% rename from docs/ja/guides/testing-single-file-components-with-mocha-webpack.md rename to docs/ja/installation/testing-single-file-components-with-mocha-webpack.md From 85189314e2ad4bd2f9fdc14b830c41c74ce17870 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A0=20Fontcuberta?= Date: Tue, 7 Jul 2020 18:03:34 +0200 Subject: [PATCH 3/8] docs(ru): create section for installation docs --- docs/ru/README.md | 9 +++++---- docs/ru/guides/README.md | 4 ---- docs/ru/installation/README.md | 6 ++++++ .../{guides => installation}/choosing-a-test-runner.md | 0 .../testing-single-file-components-with-jest.md | 0 .../testing-single-file-components-with-karma.md | 0 .../testing-single-file-components-with-mocha-webpack.md | 0 7 files changed, 11 insertions(+), 8 deletions(-) create mode 100644 docs/ru/installation/README.md rename docs/ru/{guides => installation}/choosing-a-test-runner.md (100%) rename docs/ru/{guides => installation}/testing-single-file-components-with-jest.md (100%) rename docs/ru/{guides => installation}/testing-single-file-components-with-karma.md (100%) rename docs/ru/{guides => installation}/testing-single-file-components-with-mocha-webpack.md (100%) diff --git a/docs/ru/README.md b/docs/ru/README.md index de346d0b3..0f42207b8 100644 --- a/docs/ru/README.md +++ b/docs/ru/README.md @@ -2,14 +2,15 @@ Vue Test Utils — официальная библиотека модульного тестирования для Vue.js. +- [сборка](installation/) + - [Чем запускать тесты](installation/choosing-a-test-runner.md) + - [Тестирование однофайловых компонентов с Jest](installation/testing-single-file-components-with-jest.md) + - [Тестирование однофайловых компонентов с Mocha + webpack](installation/testing-single-file-components-with-mocha-webpack.md) + - [Testing однофайловых компонентов с Karma](installation/testing-single-file-components-with-karma.md) - [Руководства](guides/) - [Введение](guides/getting-started.md) - [Общие советы](guides/common-tips.md) - [Мышь, клавиши и другие события DOM](guides/dom-events.md) - - [Чем запускать тесты](guides/choosing-a-test-runner.md) - - [Тестирование однофайловых компонентов с Jest](guides/testing-single-file-components-with-jest.md) - - [Тестирование однофайловых компонентов с Mocha + webpack](guides/testing-single-file-components-with-mocha-webpack.md) - - [Testing однофайловых компонентов с Karma](guides/testing-single-file-components-with-karma.md) - [Тестирование асинхронной логики](guides/testing-async-components.md) - [Использование с TypeScript](guides/using-with-typescript.md) - [Использование с Vue Router](guides/using-with-vue-router.md) diff --git a/docs/ru/guides/README.md b/docs/ru/guides/README.md index e932b55e8..303697e0b 100644 --- a/docs/ru/guides/README.md +++ b/docs/ru/guides/README.md @@ -3,10 +3,6 @@ !!!include(docs/ru/guides/getting-started.md)!!! !!!include(docs/ru/guides/common-tips.md)!!! !!!include(docs/ru/guides/dom-events.md)!!! -!!!include(docs/ru/guides/choosing-a-test-runner.md)!!! -!!!include(docs/ru/guides/testing-single-file-components-with-jest.md)!!! -!!!include(docs/ru/guides/testing-single-file-components-with-mocha-webpack.md)!!! -!!!include(docs/ru/guides/testing-single-file-components-with-karma.md)!!! !!!include(docs/ru/guides/testing-async-components.md)!!! !!!include(docs/guides/using-with-typescript.md)!!! !!!include(docs/ru/guides/using-with-vue-router.md)!!! diff --git a/docs/ru/installation/README.md b/docs/ru/installation/README.md new file mode 100644 index 000000000..f99f871b6 --- /dev/null +++ b/docs/ru/installation/README.md @@ -0,0 +1,6 @@ +# сборка + +!!!include(docs/ru/guides/choosing-a-test-runner.md)!!! +!!!include(docs/ru/guides/testing-single-file-components-with-jest.md)!!! +!!!include(docs/ru/guides/testing-single-file-components-with-mocha-webpack.md)!!! +!!!include(docs/ru/guides/testing-single-file-components-with-karma.md)!!! diff --git a/docs/ru/guides/choosing-a-test-runner.md b/docs/ru/installation/choosing-a-test-runner.md similarity index 100% rename from docs/ru/guides/choosing-a-test-runner.md rename to docs/ru/installation/choosing-a-test-runner.md diff --git a/docs/ru/guides/testing-single-file-components-with-jest.md b/docs/ru/installation/testing-single-file-components-with-jest.md similarity index 100% rename from docs/ru/guides/testing-single-file-components-with-jest.md rename to docs/ru/installation/testing-single-file-components-with-jest.md diff --git a/docs/ru/guides/testing-single-file-components-with-karma.md b/docs/ru/installation/testing-single-file-components-with-karma.md similarity index 100% rename from docs/ru/guides/testing-single-file-components-with-karma.md rename to docs/ru/installation/testing-single-file-components-with-karma.md diff --git a/docs/ru/guides/testing-single-file-components-with-mocha-webpack.md b/docs/ru/installation/testing-single-file-components-with-mocha-webpack.md similarity index 100% rename from docs/ru/guides/testing-single-file-components-with-mocha-webpack.md rename to docs/ru/installation/testing-single-file-components-with-mocha-webpack.md From fd255c77dd15677496519f569f45640f3f09a744 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A0=20Fontcuberta?= Date: Tue, 7 Jul 2020 18:06:20 +0200 Subject: [PATCH 4/8] docs(zh): create section for installation docs --- docs/zh/README.md | 11 ++++++----- docs/zh/guides/README.md | 5 ----- docs/zh/installation/README.md | 7 +++++++ .../choosing-a-test-runner.md | 0 .../testing-single-file-components-with-jest.md | 0 .../testing-single-file-components-with-karma.md | 0 ...sting-single-file-components-with-mocha-webpack.md | 0 .../usage-without-a-build-step-node.md | 0 8 files changed, 13 insertions(+), 10 deletions(-) create mode 100644 docs/zh/installation/README.md rename docs/zh/{guides => installation}/choosing-a-test-runner.md (100%) rename docs/zh/{guides => installation}/testing-single-file-components-with-jest.md (100%) rename docs/zh/{guides => installation}/testing-single-file-components-with-karma.md (100%) rename docs/zh/{guides => installation}/testing-single-file-components-with-mocha-webpack.md (100%) rename docs/zh/{guides => installation}/usage-without-a-build-step-node.md (100%) diff --git a/docs/zh/README.md b/docs/zh/README.md index 5982924b9..edd46eb1b 100644 --- a/docs/zh/README.md +++ b/docs/zh/README.md @@ -4,15 +4,16 @@ Vue Test Utils 是 Vue.js 官方的单元测试实用工具库。
在 Vue School 学习如何测试 Vue.js 组件
+- [安装](installation/) + - [选择一个测试运行器](installation/choosing-a-test-runner.md) + - [用 Jest 测试单文件组件](installation/testing-single-file-components-with-jest.md) + - [用 Mocha 和 webpack 测试单文件组件](installation/testing-single-file-components-with-mocha-webpack.md) + - [用 Karma 测试单文件组件](installation/testing-single-file-components-with-karma.md) + - [无需构建在 Node.js 中测试](installation/usage-without-a-build-step-node.md) - [教程](guides/) - [起步](guides/getting-started.md) - [常用技巧](guides/common-tips.md) - [鼠标、键盘以及其它 DOM 事件](guides/dom-events.md) - - [选择一个测试运行器](guides/choosing-a-test-runner.md) - - [用 Jest 测试单文件组件](guides/testing-single-file-components-with-jest.md) - - [用 Mocha 和 webpack 测试单文件组件](guides/testing-single-file-components-with-mocha-webpack.md) - - [用 Karma 测试单文件组件](guides/testing-single-file-components-with-karma.md) - - [无需构建在 Node.js 中测试](guides/usage-without-a-build-step-node.md) - [测试异步行为](guides/testing-async-components.md) - [配合 TypeScript 使用](guides/using-with-typescript.md) - [配合 Vue Router 使用](guides/using-with-vue-router.md) diff --git a/docs/zh/guides/README.md b/docs/zh/guides/README.md index 585044f3b..a1521e9a3 100644 --- a/docs/zh/guides/README.md +++ b/docs/zh/guides/README.md @@ -3,11 +3,6 @@ !!!include(docs/zh/guides/getting-started.md)!!! !!!include(docs/zh/guides/common-tips.md)!!! !!!include(docs/zh/guides/dom-events.md)!!! -!!!include(docs/zh/guides/choosing-a-test-runner.md)!!! -!!!include(docs/zh/guides/testing-single-file-components-with-jest.md)!!! -!!!include(docs/zh/guides/testing-single-file-components-with-mocha-webpack.md)!!! -!!!include(docs/zh/guides/testing-single-file-components-with-karma.md)!!! -!!!include(docs/zh/guides/usage-without-a-build-step-node.md)!!! !!!include(docs/zh/guides/testing-async-components.md)!!! !!!include(docs/zh/guides/using-with-typescript.md)!!! !!!include(docs/zh/guides/using-with-vue-router.md)!!! diff --git a/docs/zh/installation/README.md b/docs/zh/installation/README.md new file mode 100644 index 000000000..f2034cad4 --- /dev/null +++ b/docs/zh/installation/README.md @@ -0,0 +1,7 @@ +# 安装 + +!!!include(docs/zh/guides/choosing-a-test-runner.md)!!! +!!!include(docs/zh/guides/testing-single-file-components-with-jest.md)!!! +!!!include(docs/zh/guides/testing-single-file-components-with-mocha-webpack.md)!!! +!!!include(docs/zh/guides/testing-single-file-components-with-karma.md)!!! +!!!include(docs/zh/guides/usage-without-a-build-step-node.md)!!! diff --git a/docs/zh/guides/choosing-a-test-runner.md b/docs/zh/installation/choosing-a-test-runner.md similarity index 100% rename from docs/zh/guides/choosing-a-test-runner.md rename to docs/zh/installation/choosing-a-test-runner.md diff --git a/docs/zh/guides/testing-single-file-components-with-jest.md b/docs/zh/installation/testing-single-file-components-with-jest.md similarity index 100% rename from docs/zh/guides/testing-single-file-components-with-jest.md rename to docs/zh/installation/testing-single-file-components-with-jest.md diff --git a/docs/zh/guides/testing-single-file-components-with-karma.md b/docs/zh/installation/testing-single-file-components-with-karma.md similarity index 100% rename from docs/zh/guides/testing-single-file-components-with-karma.md rename to docs/zh/installation/testing-single-file-components-with-karma.md diff --git a/docs/zh/guides/testing-single-file-components-with-mocha-webpack.md b/docs/zh/installation/testing-single-file-components-with-mocha-webpack.md similarity index 100% rename from docs/zh/guides/testing-single-file-components-with-mocha-webpack.md rename to docs/zh/installation/testing-single-file-components-with-mocha-webpack.md diff --git a/docs/zh/guides/usage-without-a-build-step-node.md b/docs/zh/installation/usage-without-a-build-step-node.md similarity index 100% rename from docs/zh/guides/usage-without-a-build-step-node.md rename to docs/zh/installation/usage-without-a-build-step-node.md From 4f1b888c798c5f26dcceed3d511d3ecef2431e5a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A0=20Fontcuberta?= Date: Tue, 7 Jul 2020 18:10:08 +0200 Subject: [PATCH 5/8] docs: add links to Installation section --- docs/.vuepress/config.js | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 4782634df..6516b35c3 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -82,6 +82,7 @@ module.exports = { ], sidebar: [ '/zh/', + '/zh/installation/', '/zh/guides/', '/zh/api/', '/zh/api/wrapper/', @@ -106,6 +107,7 @@ module.exports = { ], sidebar: [ '/ja/', + '/ja/installation/', '/ja/guides/', '/ja/api/', '/ja/api/wrapper/', @@ -130,6 +132,7 @@ module.exports = { ], sidebar: [ '/ru/', + '/ru/installation/', '/ru/guides/', '/ru/api/', '/ru/api/wrapper/', From f865e9e95611a11e32056dd0b7899b44a885229f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A0=20Fontcuberta?= Date: Tue, 7 Jul 2020 18:13:21 +0200 Subject: [PATCH 6/8] docs: fix internal links --- docs/ja/guides/getting-started.md | 2 +- docs/ja/installation/README.md | 8 ++++---- docs/ru/guides/getting-started.md | 2 +- docs/ru/installation/README.md | 8 ++++---- docs/zh/installation/README.md | 10 +++++----- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/ja/guides/getting-started.md b/docs/ja/guides/getting-started.md index 3c69d5ac9..d085eb9c7 100644 --- a/docs/ja/guides/getting-started.md +++ b/docs/ja/guides/getting-started.md @@ -139,5 +139,5 @@ it('will catch the error using a promise', () => { ### 次は何をするのか -- [テストランナを選ぶ](./choosing-a-test-runner.md)で `vue-test-utils` をプロジェクトに組み込む +- [**テストランナを選ぶ**](../installation/choosing-a-test-runner.md)で `vue-test-utils` をプロジェクトに組み込む - [テストを書くときの一般的なヒント](./common-tips.md)についてもっと知る diff --git a/docs/ja/installation/README.md b/docs/ja/installation/README.md index bbdba38ac..9d239a6cc 100644 --- a/docs/ja/installation/README.md +++ b/docs/ja/installation/README.md @@ -1,6 +1,6 @@ # インスト -!!!include(docs/ja/guides/choosing-a-test-runner.md)!!! -!!!include(docs/ja/guides/testing-single-file-components-with-jest.md)!!! -!!!include(docs/ja/guides/testing-single-file-components-with-mocha-webpack.md)!!! -!!!include(docs/ja/guides/testing-single-file-components-with-karma.md)!!! +!!!include(docs/ja/installation/choosing-a-test-runner.md)!!! +!!!include(docs/ja/installation/testing-single-file-components-with-jest.md)!!! +!!!include(docs/ja/installation/testing-single-file-components-with-mocha-webpack.md)!!! +!!!include(docs/ja/installation/testing-single-file-components-with-karma.md)!!! diff --git a/docs/ru/guides/getting-started.md b/docs/ru/guides/getting-started.md index b216b7921..77b324fa2 100644 --- a/docs/ru/guides/getting-started.md +++ b/docs/ru/guides/getting-started.md @@ -139,5 +139,5 @@ it('должен отлавливать ошибку с использовани ### Что дальше -- Интегрируйте `vue-test-utils` в ваш проект выбрав [программу для запуска тестов](./choosing-a-test-runner.md). +- Интегрируйте `vue-test-utils` в ваш проект выбрав [программу для запуска тестов](../installation/choosing-a-test-runner.md). - Прочитайте больше об [общих техниках и советах при написании тестов](./common-tips.md). diff --git a/docs/ru/installation/README.md b/docs/ru/installation/README.md index f99f871b6..208121471 100644 --- a/docs/ru/installation/README.md +++ b/docs/ru/installation/README.md @@ -1,6 +1,6 @@ # сборка -!!!include(docs/ru/guides/choosing-a-test-runner.md)!!! -!!!include(docs/ru/guides/testing-single-file-components-with-jest.md)!!! -!!!include(docs/ru/guides/testing-single-file-components-with-mocha-webpack.md)!!! -!!!include(docs/ru/guides/testing-single-file-components-with-karma.md)!!! +!!!include(docs/ru/installation/choosing-a-test-runner.md)!!! +!!!include(docs/ru/installation/testing-single-file-components-with-jest.md)!!! +!!!include(docs/ru/installation/testing-single-file-components-with-mocha-webpack.md)!!! +!!!include(docs/ru/installation/testing-single-file-components-with-karma.md)!!! diff --git a/docs/zh/installation/README.md b/docs/zh/installation/README.md index f2034cad4..1fa7566c3 100644 --- a/docs/zh/installation/README.md +++ b/docs/zh/installation/README.md @@ -1,7 +1,7 @@ # 安装 -!!!include(docs/zh/guides/choosing-a-test-runner.md)!!! -!!!include(docs/zh/guides/testing-single-file-components-with-jest.md)!!! -!!!include(docs/zh/guides/testing-single-file-components-with-mocha-webpack.md)!!! -!!!include(docs/zh/guides/testing-single-file-components-with-karma.md)!!! -!!!include(docs/zh/guides/usage-without-a-build-step-node.md)!!! +!!!include(docs/zh/installation/choosing-a-test-runner.md)!!! +!!!include(docs/zh/installation/testing-single-file-components-with-jest.md)!!! +!!!include(docs/zh/installation/testing-single-file-components-with-mocha-webpack.md)!!! +!!!include(docs/zh/installation/testing-single-file-components-with-karma.md)!!! +!!!include(docs/zh/installation/usage-without-a-build-step-node.md)!!! From 1657b6be3e050bcfaf62a996ba91f34a5c174c03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A0=20Fontcuberta?= Date: Tue, 7 Jul 2020 18:14:12 +0200 Subject: [PATCH 7/8] docs: fix headings --- docs/zh/installation/usage-without-a-build-step-node.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/zh/installation/usage-without-a-build-step-node.md b/docs/zh/installation/usage-without-a-build-step-node.md index 436d10cd2..2abc4a15c 100644 --- a/docs/zh/installation/usage-without-a-build-step-node.md +++ b/docs/zh/installation/usage-without-a-build-step-node.md @@ -8,11 +8,11 @@ 在这个示例中，我们会展示如何仅使用上述最小化的依赖撰写一个简单的测试。最终的代码可以在[这里](https://github.com/lmiller1990/vue-test-utils-node-basic)找到。 -## 安装依赖 +### 安装依赖 我们需要安装一些依赖，如上所述：`npm install vue vue-template-compiler jsdom jsdom-global @vue/test-utils`。该示例不需要测试运行器或打包工具。 -## 引入库 +### 引入库 现在我们需要引入这些库。这里有一些轻微的注意事项并解释在了如下代码片段的注释中。 @@ -29,7 +29,7 @@ const VueTestUtils = require('@vue/test-utils') 如注释中所述，`jsdom-global` 必须优先于 `@vue/test-utils` 被引入。因为 Vue Test Utils 需要一个 DOM 环境来渲染 Vue 组件。如果你在一个真实的浏览器中运行测试，你就完全不需要 `jsdom` 了。`Vue` 也必须在 `@vue/test-utils` 之前被引入，原因很明显——Vue Test Utils 也需要可以正常工作。我们还从 Node 标准库中引入了 `assert`。一般我们会使用测试运行器提供的方法，通常形如 `expect(...).toEqual(...)`，但在这个示例中 `assert` 就可以用来做这件事。 -## 撰写一个测试 +### 撰写一个测试 现在万事俱备，我们需要一个待测试的组件。为了保持简介，我们之渲染一些文本并断言该组件的渲染结果。 From 0e1ef71fa7d6b9762cc99d1713062952158797fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adri=C3=A0=20Fontcuberta?= Date: Wed, 8 Jul 2020 09:26:22 +0200 Subject: [PATCH 8/8] docs(en): reduce and simplify content on Installation --- docs/README.md | 5 - docs/installation/README.md | 8 +- docs/installation/choosing-a-test-runner.md | 48 ---- docs/installation/semantic-versioning.md | 3 + ...esting-single-file-components-with-jest.md | 219 ------------------ ...sting-single-file-components-with-karma.md | 194 ---------------- ...ngle-file-components-with-mocha-webpack.md | 183 --------------- .../usage-without-a-build-step-node.md | 55 ----- docs/installation/using-other-test-runners.md | 60 +++++ docs/installation/using-with-jest.md | 66 ++++++ 10 files changed, 132 insertions(+), 709 deletions(-) delete mode 100644 docs/installation/choosing-a-test-runner.md create mode 100644 docs/installation/semantic-versioning.md delete mode 100644 docs/installation/testing-single-file-components-with-jest.md delete mode 100644 docs/installation/testing-single-file-components-with-karma.md delete mode 100644 docs/installation/testing-single-file-components-with-mocha-webpack.md delete mode 100644 docs/installation/usage-without-a-build-step-node.md create mode 100644 docs/installation/using-other-test-runners.md create mode 100644 docs/installation/using-with-jest.md diff --git a/docs/README.md b/docs/README.md index 8a7a1074f..b2d02340f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,11 +5,6 @@ Vue Test Utils is the official unit testing utility library for Vue.js.
Learn how to test Vue.js components with Vue School
- [Installation](./installation/) - - [Choosing a test runner](installation/choosing-a-test-runner.md) - - [Testing Single-File Components with Jest](installation/testing-single-file-components-with-jest.md) - - [Testing Single-File Components with Mocha + webpack](installation/testing-single-file-components-with-mocha-webpack.md) - - [Testing Single-File Components with Karma](installation/testing-single-file-components-with-karma.md) - - [Testing in Node.js Without a Build Step](installation/usage-without-a-build-step-node.md) - [Guides](./guides/) - [Getting Started](./guides/getting-started.md) - [Common Tips](guides/common-tips.md) diff --git a/docs/installation/README.md b/docs/installation/README.md index fbe5f4674..4000e8e1e 100644 --- a/docs/installation/README.md +++ b/docs/installation/README.md @@ -1,7 +1,5 @@ # Installation -!!!include(docs/installation/choosing-a-test-runner.md)!!! -!!!include(docs/installation/testing-single-file-components-with-jest.md)!!! -!!!include(docs/installation/testing-single-file-components-with-mocha-webpack.md)!!! -!!!include(docs/installation/testing-single-file-components-with-karma.md)!!! -!!!include(docs/installation/usage-without-a-build-step-node.md)!!! +!!!include(docs/installation/semantic-versioning.md)!!! +!!!include(docs/installation/using-with-jest.md)!!! +!!!include(docs/installation/using-other-test-runners.md)!!! diff --git a/docs/installation/choosing-a-test-runner.md b/docs/installation/choosing-a-test-runner.md deleted file mode 100644 index a3b8d5497..000000000 --- a/docs/installation/choosing-a-test-runner.md +++ /dev/null @@ -1,48 +0,0 @@ -## Choosing a test runner - -A test runner is a program that runs tests. - -There are many popular JavaScript test runners, and Vue Test Utils works with all of them. It's test runner agnostic. - -There are a few things to consider when choosing a test runner though: feature set, performance, and support for single-file component (SFC) pre-compilation. After carefully comparing existing libraries, here are two test runners that we recommend: - -- [Jest](https://jestjs.io/docs/en/getting-started#content) is the most fully featured test runner. It requires the least configuration, sets up JSDOM by default, provides built-in assertions, and has a great command line user experience. However, you will need a preprocessor to be able to import SFC components in your tests. We have created the `vue-jest` preprocessor which can handle most common SFC features, but it currently does not have 100% feature parity with `vue-loader`. Jest also supports watch mode and watchAll. - -- [mocha-webpack](https://github.com/zinserjan/mocha-webpack) is a wrapper around webpack + Mocha, but with a more streamlined interface and watch mode. The benefits of this setup is that we can get complete SFC support via webpack + `vue-loader`, but it requires more configuration upfront. - -### 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 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 Single-File Components - -Single-file Vue components (SFCs) require pre-compilation before they can be run in Node or in the browser. There are two recommended ways to perform the compilation: with a Jest preprocessor, or directly use webpack. - -The `vue-jest` preprocessor supports basic SFC functionalities, but currently does not handle style blocks or custom blocks, which are only supported in `vue-loader`. If you rely on these features or other webpack-specific configurations, you will need to use a webpack + `vue-loader` based setup. - -Read the following guides for different setups: - -- [Testing Single-File Components with Jest](./testing-single-file-components-with-jest.md) -- [Testing Single-File Components with Mocha + webpack](./testing-single-file-components-with-mocha-webpack.md) - -### Resources - -- [Test runner performance comparison](https://github.com/eddyerburgh/vue-unit-test-perf-comparison) -- [Example project with Jest](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-jest) -- [Example project with Mocha](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-mocha) -- [Example project with tape](https://github.com/eddyerburgh/vue-test-utils-tape-example) -- [Example project with AVA](https://github.com/eddyerburgh/vue-test-utils-ava-example) -- [tyu - Delightful web testing by egoist](https://github.com/egoist/tyu) diff --git a/docs/installation/semantic-versioning.md b/docs/installation/semantic-versioning.md new file mode 100644 index 000000000..b1e756d23 --- /dev/null +++ b/docs/installation/semantic-versioning.md @@ -0,0 +1,3 @@ +## Semantic versioning + +Vue Test Utils follows [Semantic Versioning](https://semver.org/) in all its official projects for documented features and behavior. For undocumented behavior or exposed internals, changes are described in [release notes](https://github.com/vuejs/vue-test-utils/releases). diff --git a/docs/installation/testing-single-file-components-with-jest.md b/docs/installation/testing-single-file-components-with-jest.md deleted file mode 100644 index c84eb3d88..000000000 --- a/docs/installation/testing-single-file-components-with-jest.md +++ /dev/null @@ -1,219 +0,0 @@ -## Testing Single-File Components with Jest - -> An example project for this setup is available on [GitHub](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-jest). - -Jest is a test runner developed by Facebook, aiming to deliver a battery-included unit testing solution. You can learn more about Jest on its [official documentation](https://jestjs.io/). - -
Learn how to use Jest to test Single File Components with Vue School
- -#### Setting up Jest - -We will assume you are starting with a setup that already has webpack, vue-loader and Babel properly configured - e.g. the `webpack-simple` template scaffolded by `vue-cli`. - -> Alternatively, if you are using the Vue CLI to build your project, you can use the plugin [cli-plugin-unit-jest](https://cli.vuejs.org/core-plugins/unit-jest.html#injected-commands) to run Jest tests. -> -> Skip to and then follow the instructions from [Processing Single-File Components in Jest](#processing-single-file-components-in-jest) to process your Vue Single-File Components. -> -> If you are transpiling with Babel (the default configuration when creating a new project), you will also need to add the JavaScript transform to the Jest config in your package.json as described in the section [Configuring Babel for Jest](#configuring-babel-for-fest), but then you should skip the rest of that section. - -The first thing to do is install Jest and Vue Test Utils: - -```bash -$ npm install --save-dev jest @vue/test-utils -``` - -Next we need to define a test script in our `package.json`. - -```json -// package.json -{ - "scripts": { - "test": "jest" - } -} -``` - -### Processing Single-File Components in Jest - -To teach Jest how to process `*.vue` files, we will need to install and configure the `vue-jest` preprocessor: - -```bash -npm install --save-dev vue-jest -``` - -Next, create a `jest` block in `package.json`: - -```json -{ - // ... - "jest": { - "moduleFileExtensions": [ - "js", - "json", - // tell Jest to handle `*.vue` files - "vue" - ], - "transform": { - // process `*.vue` files with `vue-jest` - ".*\\.(vue)$": "vue-jest" - } - } -} -``` - -> **Note:** `vue-jest` currently does not support all the features of `vue-loader`, for example custom block support and style loading. In addition, some webpack-specific features such as code-splitting are not supported either. To use these unsupported features, you need to use Mocha instead of Jest to run your tests, and webpack to compile your components. To get started, read the guide on [testing SFCs with Mocha + webpack](./testing-single-file-components-with-mocha-webpack.md). - -> **Note:** If you are using Babel 7 or higher, you will need to add [babel-bridge](https://github.com/babel/babel-bridge) to your devDependencies (`$ npm install --save-dev babel-core@^7.0.0-bridge.0`). - -### Handling webpack Aliases - -If you use a resolve alias in the webpack config, e.g. aliasing `@` to `/src`, you need to add a matching config for Jest as well, using the `moduleNameMapper` option: - -```json -{ - // ... - "jest": { - // ... - // support the same @ -> src alias mapping in source code - "moduleNameMapper": { - "^@/(.*)$": "/src/$1" - } - } -} -``` - -### Configuring Babel for Jest - - - -Although latest versions of Node already supports most ES2015 features, you may still want to use ES modules syntax and stage-x features in your tests. For that we need to install `babel-jest`: - -```bash -npm install --save-dev babel-jest -``` - -Next, we need to tell Jest to process JavaScript test files with `babel-jest` by adding an entry under `jest.transform` in `package.json`: - -```json -{ - // ... - "jest": { - // ... - "transform": { - // ... - // process js with `babel-jest` - "^.+\\.js$": "/node_modules/babel-jest" - } - // ... - } -} -``` - -> By default, `babel-jest` automatically configures itself as long as it's installed. However, because we have explicitly added a transform for `*.vue` files, we now need to explicitly configure `babel-jest` as well. - -Assuming using `babel-preset-env` with webpack, the default Babel config disables ES modules transpilation because webpack already knows how to handle ES modules. However, we do need to enable it for our tests because Jest tests run directly in Node. - -Also, we can tell `babel-preset-env` to target the Node version we are using. This skips transpiling unnecessary features and makes our tests boot faster. - -To apply these options only for tests, put them in a separate config under `env.test` (this will be automatically picked up by `babel-jest`). - -Example `.babelrc`: - -```json -{ - "presets": [["env", { "modules": false }]], - "env": { - "test": { - "presets": [["env", { "targets": { "node": "current" } }]] - } - } -} -``` - -### Placing Test Files - -By default, Jest will recursively pick up all files that have a `.spec.js` or `.test.js` extension in the entire project. If this does not fit your needs, it's possible [to change the `testRegex`](https://jestjs.io/docs/en/configuration#testregex-string-array-string) in the config section in the `package.json` file. - -Jest recommends creating a `__tests__` directory right next to the code being tested, but feel free to structure your tests as you see fit. Just beware that Jest would create a `__snapshots__` directory next to test files that performs snapshot testing. - -### Coverage - -Jest can be used to generate coverage reports in multiple formats. The following is a simple example to get started with: - -Extend your `jest` config (usually in `package.json` or `jest.config.js`) with the [`collectCoverage`](https://jestjs.io/docs/en/configuration#collectcoverage-boolean) option, and then add the [`collectCoverageFrom`](https://jestjs.io/docs/en/configuration#collectcoveragefrom-array) array to define the files for which coverage information should be collected. - -```json -{ - "jest": { - // ... - "collectCoverage": true, - "collectCoverageFrom": ["**/*.{js,vue}", "!**/node_modules/**"] - } -} -``` - -This will enable coverage reports with the [default coverage reporters](https://jestjs.io/docs/en/configuration#coveragereporters-array-string). You can customise these with the `coverageReporters` option: - -```json -{ - "jest": { - // ... - "coverageReporters": ["html", "text-summary"] - } -} -``` - -Further documentation can be found in the [Jest configuration documentation](https://jestjs.io/docs/en/configuration#collectcoverage-boolean), where you can find options for coverage thresholds, target output directories, etc. - -### Example Spec - -If you are familiar with Jasmine, you should feel right at home with Jest's [assertion API](https://jestjs.io/docs/en/expect#content): - -```js -import { mount } from '@vue/test-utils' -import Component from './component' - -describe('Component', () => { - test('is a Vue instance', () => { - const wrapper = mount(Component) - expect(wrapper.isVueInstance()).toBeTruthy() - }) -}) -``` - -### Snapshot Testing - -When you mount a component with Vue Test Utils, you get access to the root HTML element. This can be saved as a snapshot for [Jest snapshot testing](https://jestjs.io/docs/en/snapshot-testing): - -```js -test('renders correctly', () => { - const wrapper = mount(Component) - expect(wrapper.html()).toMatchSnapshot() -}) -``` - -We can improve the saved snapshot with a custom serializer: - -```bash -npm install --save-dev jest-serializer-vue -``` - -Then configure it in `package.json`: - -```json -{ - // ... - "jest": { - // ... - // serializer for snapshots - "snapshotSerializers": ["jest-serializer-vue"] - } -} -``` - -### Resources - -- [Example project for this setup](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-unit-jest) -- [Examples and slides from Vue Conf 2017](https://github.com/codebryo/vue-testing-with-jest-conf17) -- [Jest](https://jestjs.io/) -- [Babel preset env](https://github.com/babel/babel-preset-env) diff --git a/docs/installation/testing-single-file-components-with-karma.md b/docs/installation/testing-single-file-components-with-karma.md deleted file mode 100644 index fafbc1145..000000000 --- a/docs/installation/testing-single-file-components-with-karma.md +++ /dev/null @@ -1,194 +0,0 @@ -## Testing Single-File Components with Karma - -> An example project for this setup is available on [GitHub](https://github.com/eddyerburgh/vue-test-utils-karma-example). - -Karma is a test runner that launches browsers, runs tests, and reports them back to us. We're going to use the Mocha framework to write the tests. We'll use the chai library for test assertions. - -### Setting up Mocha - -We will assume you are starting with a setup that already has webpack, vue-loader and Babel properly configured - e.g. the `webpack-simple` template scaffolded by `vue-cli`. - -The first thing to do is install the test dependencies: - -```bash -npm install --save-dev @vue/test-utils karma karma-chrome-launcher karma-mocha karma-sourcemap-loader karma-spec-reporter karma-webpack mocha -``` - -Next we need to define a test script in our `package.json`. - -```json -// package.json -{ - "scripts": { - "test": "karma start --single-run" - } -} -``` - -- The `--single-run` flag tells Karma to run the test suite once. - -### Karma Configuration - -Create a `karma.conf.js` file in the index of the project: - -```js -// karma.conf.js - -var webpackConfig = require('./webpack.config.js') - -module.exports = function(config) { - config.set({ - frameworks: ['mocha'], - - files: ['test/**/*.spec.js'], - - preprocessors: { - '**/*.spec.js': ['webpack', 'sourcemap'] - }, - - webpack: webpackConfig, - - reporters: ['spec'], - - browsers: ['Chrome'] - }) -} -``` - -This file is used to configure Karma. - -We need to preprocess our files with webpack. to do that, we add webpack as a preprocessor, and include our webpack config. We can use the webpack config file in the base of the project without changing anything. - -In our configuration, we run the tests in Chrome. To add extra browsers, see [the Browsers section in the Karma docs](http://karma-runner.github.io/3.0/config/browsers.html). - -### Picking an Assertion Library - -[Chai](http://chaijs.com/) is a popular assertion library that is commonly used alongside Mocha. You may also want to check out [Sinon](http://sinonjs.org/) for creating spies and stubs. - -We can install the `karma-chai` plugin to use `chai` in our tests. - -```bash -npm install --save-dev karma-chai -``` - -### Adding a test - -Create a file in `src` named `Counter.vue`: - -```html - - - -``` - -And create a test file named `test/Counter.spec.js` with the following code: - -```js -import { expect } from 'chai' -import { shallowMount } from '@vue/test-utils' -import Counter from '../src/Counter.vue' - -describe('Counter.vue', () => { - it('increments count when button is clicked', () => { - const wrapper = shallowMount(Counter) - wrapper.find('button').trigger('click') - expect(wrapper.find('div').text()).contains('1') - }) -}) -``` - -And now we can run the tests: - -``` -npm run test -``` - -Woohoo, we got our tests running! - -### Coverage - -To setup code coverage to Karma, we can use the `karma-coverage` plugin. - -By default, `karma-coverage` won't use source maps to map the coverage reports. So we need to use `babel-plugin-istanbul` to make sure the coverage is mapped correctly. - -Install `karma-coverage`, `babel-plugin-istanbul`, and `cross-env`: - -``` -npm install --save-dev karma-coverage cross-env -``` - -We're going to use `cross-env` to set a `NODE_ENV` environment variable. This way we can use `babel-plugin-istanbul` when we're compiling for our tests—we don't want to include `babel-plugin-istanbul` when we compile our production code: - -``` -npm install --save-dev babel-plugin-istanbul -``` - -Update your `.babelrc` file to use `babel-plugin-istanbul` when `NODE_ENV` is set to test: - -```json -{ - "presets": [["env", { "modules": false }], "stage-3"], - "env": { - "test": { - "plugins": ["istanbul"] - } - } -} -``` - -Now update the `karma.conf.js` file to use coverage. Add `coverage` to the `reporters` array, and add a `coverageReporter` field: - -```js -// karma.conf.js - -module.exports = function(config) { - config.set({ - // ... - - reporters: ['spec', 'coverage'], - - coverageReporter: { - dir: './coverage', - reporters: [{ type: 'lcov', subdir: '.' }, { type: 'text-summary' }] - } - }) -} -``` - -And update the `test` script to set the `NODE_ENV`: - -```json -// package.json -{ - "scripts": { - "test": "cross-env NODE_ENV=test karma start --single-run" - } -} -``` - -### Resources - -- [Example project for this setup](https://github.com/eddyerburgh/vue-test-utils-karma-example) -- [Karma](http://karma-runner.github.io/) -- [Mocha](https://mochajs.org/) -- [Chai](http://chaijs.com/) -- [Sinon](http://sinonjs.org/) diff --git a/docs/installation/testing-single-file-components-with-mocha-webpack.md b/docs/installation/testing-single-file-components-with-mocha-webpack.md deleted file mode 100644 index cee57d924..000000000 --- a/docs/installation/testing-single-file-components-with-mocha-webpack.md +++ /dev/null @@ -1,183 +0,0 @@ -## Testing Single-File Components with Mocha + webpack - -Another strategy for testing SFCs is compiling all our tests via webpack and then run it in a test runner. The advantage of this approach is that it gives us full support for all webpack and `vue-loader` features, so we don't have to make compromises in our source code. - -You can technically use any test runner you like and manually wire things together, but we've found [`mochapack`](https://github.com/sysgears/mochapack) to provide a very streamlined experience for this particular task. - -### Setting Up `mochapack` - -We will assume you are starting with a setup that already has webpack, vue-loader and Babel properly configured - e.g. the `webpack-simple` template scaffolded by `vue-cli`. - -The first thing to do is installing test dependencies: - -```bash -npm install --save-dev @vue/test-utils mocha mochapack -``` - -Next we need to define a test script in our `package.json`. - -```json -// package.json -{ - "scripts": { - "test": "mochapack --webpack-config webpack.config.js --require test/setup.js test/**/*.spec.js" - } -} -``` - -A few things to note here: - -- The `--webpack-config` flag specifies the webpack config file to use for the tests. In most cases, this would be identical to the config you use for the actual project with one small tweak. We will talk about this later. - -- The `--require` flag ensures the file `test/setup.js` is run before any tests, in which we can setup the global environment for our tests to be run in. - -- The final argument is a glob for the test files to be included in the test bundle. - -### Extra webpack Configuration - -#### Externalizing NPM Dependencies - -In our tests we will likely import a number of NPM dependencies - some of these modules may be written without browser usage in mind and simply cannot be bundled properly by webpack. Another consideration is externalizing dependencies greatly improves test boot up speed. We can externalize all NPM dependencies with `webpack-node-externals`: - -```js -// webpack.config.js -const nodeExternals = require('webpack-node-externals') - -module.exports = { - // ... - externals: [nodeExternals()] -} -``` - -#### Source Maps - -Source maps need to be inlined to be picked up by `mochapack`. The recommended config is: - -```js -module.exports = { - // ... - devtool: 'inline-cheap-module-source-map' -} -``` - -If debugging via IDE, it's also recommended to add the following: - -```js -module.exports = { - // ... - output: { - // ... - // use absolute paths in sourcemaps (important for debugging via IDE) - devtoolModuleFilenameTemplate: '[absolute-resource-path]', - devtoolFallbackModuleFilenameTemplate: '[absolute-resource-path]?[hash]' - } -} -``` - -### Setting Up Browser Environment - -Vue Test Utils requires a browser environment to run. We can simulate it in Node using `jsdom-global`: - -```bash -npm install --save-dev jsdom jsdom-global -``` - -Then in `test/setup.js`: - -```js -require('jsdom-global')() -``` - -This adds a browser environment to Node, so that Vue Test Utils can run correctly. - -### Picking an Assertion Library - -[Chai](http://chaijs.com/) is a popular assertion library that is commonly used alongside Mocha. You may also want to check out [Sinon](http://sinonjs.org/) for creating spies and stubs. - -Alternatively you can use `expect` which is now part of Jest, and exposes [the exact same API](https://jestjs.io/docs/en/expect#content) in Jest docs. - -We will be using `expect` here and make it globally available so that we don't have to import it in every test: - -```bash -npm install --save-dev expect -``` - -Then in `test/setup.js`: - -```js -require('jsdom-global')() - -global.expect = require('expect') -``` - -### Optimizing Babel for Tests - -Notice that we are using `babel-loader` to handle JavaScript. You should already have Babel configured if you are using it in your app via a `.babelrc` file. Here `babel-loader` will automatically use the same config file. - -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.). - -### Adding a test - -Create a file in `src` named `Counter.vue`: - -```html - - - -``` - -And create a test file named `test/Counter.spec.js` with the following code: - -```js -import Vue from 'vue' -import { shallowMount } from '@vue/test-utils' -import Counter from '../src/Counter.vue' - -describe('Counter.vue', () => { - it('increments count when button is clicked', async () => { - const wrapper = shallowMount(Counter) - wrapper.find('button').trigger('click') - await Vue.nextTick() - expect(wrapper.find('div').text()).toMatch('1') - }) -}) -``` - -And now we can run the test: - -``` -npm run test -``` - -Woohoo, we got our tests running! - -### Coverage - -To setup code coverage to `mochapack`, follow [the `mochapack` code coverage guide](https://github.com/sysgears/mochapack/blob/master/docs/guides/code-coverage.md). - -### Resources - -- [Mocha](https://mochajs.org/) -- [mochapack](https://github.com/sysgears/mochapack/) -- [Chai](http://chaijs.com/) -- [Sinon](http://sinonjs.org/) -- [jest/expect](https://jestjs.io/docs/en/expect#content) diff --git a/docs/installation/usage-without-a-build-step-node.md b/docs/installation/usage-without-a-build-step-node.md deleted file mode 100644 index 62a7f8266..000000000 --- a/docs/installation/usage-without-a-build-step-node.md +++ /dev/null @@ -1,55 +0,0 @@ -## Usage Without a Build Step - -While it is common to build Vue applications using tools [Webpack](https://webpack.js.org/) to bundle the application, `vue-loader` to leverage Single File Components, and [Jest](https://jestjs.io/) to write expressive tests, it is possible to use Vue Test Utils with much less. The minimal requirements for Vue Test Utils, aside from the library itself are: - -- Vue -- vue-template-compiler -- a DOM (be it [jsdom](https://github.com/jsdom/jsdom) in a Node environment, or the DOM in a real browser) - -In this example, we will demonstrate how to write a simple test using nothing but the minimal dependencies described above. The final code can be found [here](https://github.com/lmiller1990/vue-test-utils-node-basic). - -### Installing the Dependencies - -We need to install some dependencies, as explained above: `npm install vue vue-template-compiler jsdom jsdom-global @vue/test-utils`. No test runner or bundler is needed for this example. - -### Requiring the Libraries - -Now we need to require the libraries. There is a slight caveat, explained in a comment, and in depth below the snippet. - -```js -// jsdom-global must be required before vue-test-utils, -// because vue-test-utils expects a DOM (real DOM, or JSDOM) -// to exist. -require('jsdom-global')() - -const assert = require('assert') - -const Vue = require('vue') -const VueTestUtils = require('@vue/test-utils') -``` - -As the comment says, `jsdom-global` must be required before `@vue/test-utils`. This is because Vue Test Utils expects a DOM to be present to render the Vue components. If you are running the tests in a real browser, you will not need `jsdom` at all. `Vue` must also be required before `@vue/test-utils` for obvious reasons - Vue Test Utils expects to be available, as well. We also require `assert` from the node standard library. Normally we would use the matchers provided by a test runner, often in the format of an `expect(...).toEqual(...)` assertion, but `assert` will serve this purpose for this example. - -### Writing a Test - -Now everything is set up, all we need is a component and a test. To keep things simple, we will just render some text and assert it is present in the rendered component. - -```js -const App = Vue.component('app', { - data() { - return { - msg: 'Hello Vue Test Utils' - } - }, - - template: ` -
{{ msg }}
- ` -}) - -const wrapper = VueTestUtils.mount(App) - -assert.strictEqual('Hello Vue Test Utils', wrapper.text()) -``` - -It's as simple as it looks. Since we do not have a build step, we cannot use Single File Components. There is nothing to stop us using Vue in the same style you would when including it from a CDN via a `