Installation

Semantic versioning

Vue Test Utils follows Semantic Versioning in all its official projects for documented features and behavior. For undocumented behavior or exposed internals, changes are described in release notes.

Using Vue Test Utils with Jest (recommended)

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.

Learn how to use Jest to test Single File Components with Vue School

Installation with Vue CLI (recommended)

If you are using the Vue CLI to build your project, you can use the plugin cli-plugin-unit-jest to run Jest tests.

$ vue add unit-jest

The plugin pulls all required dependencies (including jest), creates a jest.config.js file with sensible defaults, and generates a sample test suite.

After that, all you need to do is to install Vue Test Utils.

$ npm install --save-dev @vue/test-utils@legacy

Manual installation

After setting up Jest, the first thing to do is to install Vue Test Utils and vue-jest to process Single-File Components:

$ npm install --save-dev @vue/test-utils@legacy vue-jest

Then, you need to tell Jest to transform .vue files using vue-jest. You can do so by adding the following configuration in package.json or in a standalone Jest config file:

{
  "jest": {
    "moduleFileExtensions": [
      "js",
      "json",
      // tell Jest to handle `*.vue` files
      "vue"
    ],
    "transform": {
      // process `*.vue` files with `vue-jest`
      ".*\\.(vue)$": "vue-jest"
    }
  }
}

Using with Babel

If you are going to use babel and import vue single file components with .vue extension inside your tests, you will need to install babel and transform .js files with babel-jest .

npm install --save-dev babel-jest @babel/core @babel/preset-env babel-core@^7.0.0-bridge.0

Then, you need to tell Jest to transform .js files using babel-jest. You can do so by adding the following configuration in package.json or in a standalone Jest config file:

{
  "jest": {
    "transform": {
      // process `*.js` files with `babel-jest`
      ".*\\.(js)$": "babel-jest"
    }
  }
}

Then you need to create babel config using babel.config.json or .babelrc.json config files:

{
  "presets": ["@babel/preset-env"]
}

You can also add these options to package.json:

{
  "babel": {
    "presets": ["@babel/preset-env"]
  }
}

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:

{
  "jest": {
    // support the same @ -> src alias mapping in source code
    "moduleNameMapper": {
      "^@/(.*)$": "<rootDir>/src/$1"
    }
  }
}

Code Coverage

Jest can be used to generate coverage reports in multiple formats. This is disabled by default (both for a vue-cli installation and for a manual one). The following is a simple example to get started with:

Extend your jest config with the collectCoverage option, and then add the collectCoverageFrom array to define the files for which coverage information should be collected.

{
  "jest": {
    "collectCoverage": true,
    "collectCoverageFrom": ["**/*.{js,vue}", "!**/node_modules/**"]
  }
}

This will enable coverage reports with the default coverage reporters. Further documentation can be found in the Jest configuration documentation, where you can find options for coverage thresholds, target output directories, etc.

Using other Test runners

Running Vue Test Utils with Karma

Karma is a test runner that launches browsers, runs tests, and reports them back to us.

In addition to Karma, you might want to use the Mocha framework to write the tests, and the Chai library for test assertions. Also, you may also want to check out Sinon for creating spies and stubs.

Following is a basic Karma config for Vue Test Utils:

// karma.conf.js
var webpackConfig = require('./webpack.config.js')

module.exports = function (config) {
  config.set({
    frameworks: ['mocha'],
    files: ['test/**/*.spec.js'],
    webpack: webpackConfig,
    reporters: ['spec'],
    browsers: ['Chrome'],
    preprocessors: {
      '**/*.spec.js': ['webpack', 'sourcemap']
    }
  })
}

Running Vue Test Utils 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.

We've found mochapack to provide a very streamlined experience for this particular task.

The first thing to do is installing test dependencies:

npm install --save-dev @vue/test-utils mocha mochapack

After installing Vue Test Utils and mochapack, you will need to define a test script in your package.json:

// package.json
{
  "scripts": {
    "test": "mochapack --webpack-config webpack.config.js --require test/setup.js test/**/*.spec.js"
  }
}

Running Vue Test Utils without a build step

While it is common to build Vue applications using tools such as webpack to bundle the application, vue-loader to leverage Single File Components, 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 in a Node environment, or the DOM in a real browser)

Notice that jsdom(or any other DOM implementation) must be required before Vue Test Utils, because it expects a DOM (real DOM, or JSDOM) to exist.