vue-jest

What is vue-jest?

vue-jest is a Jest transformer for Vue single-file components (SFCs). It allows you to use Jest to test Vue components by transforming the .vue files into a format that Jest can understand.

What are vue-jest's main functionalities?

Transform Vue SFCs

This feature allows Jest to transform Vue single-file components (.vue files) so that they can be tested. The code sample shows how to configure Jest to use vue-jest for transforming .vue files.

module.exports = { transform: { '^.+\.vue$': 'vue-jest' } };

Mocking Vue Components

This feature allows you to mock Vue components and their dependencies during testing. The code sample demonstrates how to use vue-jest with @vue/test-utils to shallow mount a component and mock a translation function.

import { shallowMount } from '@vue/test-utils';
import MyComponent from '@/components/MyComponent.vue';

test('renders a message', () => {
  const wrapper = shallowMount(MyComponent, {
    mocks: {
      $t: msg => msg
    }
  });
  expect(wrapper.text()).toContain('Hello World');
});

Snapshot Testing

This feature allows you to perform snapshot testing on Vue components. The code sample shows how to use vue-jest with @vue/test-utils to create a snapshot of a component's rendered HTML and compare it to a saved snapshot.

import { shallowMount } from '@vue/test-utils';
import MyComponent from '@/components/MyComponent.vue';

test('matches snapshot', () => {
  const wrapper = shallowMount(MyComponent);
  expect(wrapper.html()).toMatchSnapshot();
});

Other packages similar to vue-jest

vue-test-utils

vue-test-utils is the official testing utility library for Vue.js. It provides methods to mount and interact with Vue components in tests. While vue-jest focuses on transforming .vue files for Jest, vue-test-utils provides a more comprehensive set of utilities for testing Vue components.

jest-vue-preprocessor

jest-vue-preprocessor is another Jest transformer for Vue single-file components. It is similar to vue-jest in that it transforms .vue files for Jest, but it is less commonly used and lacks some of the additional features and community support that vue-jest offers.

babel-jest

babel-jest is a Jest transformer that uses Babel to transform JavaScript files. While it is not specific to Vue, it can be used in conjunction with other tools to transform Vue components. It is more general-purpose compared to vue-jest, which is specifically designed for Vue SFCs.

README

vue-jest

Jest transformer for Vue single file components

NOTE: This is documentation for vue-jest@4.x. View the vue-jest@3.x documentation

Usage

npm install --save-dev vue-jest
yarn add vue-jest --dev

Usage with Babel 7

If you use jest > 24.0.0 and babel-jest make sure to install babel-core@bridge

npm install --save-dev babel-core@bridge
yarn add babel-core@bridge --dev

Setup

To use vue-jest as a transformer for your .vue files, map them to the vue-jest module:

{
  "jest": {
    "transform": {
      "^.+\\.vue$": "vue-jest"
    }
  }
}

A full config will look like this.

{
  "jest": {
    "moduleFileExtensions": ["js", "json", "vue"],
    "transform": {
      "^.+\\.js$": "babel-jest",
      "^.+\\.vue$": "vue-jest"
    }
  }
}

Examples

Example repositories testing Vue components with jest and vue-jest:

• Vue Test Utils with Jest

Supported langs

vue-jest compiles <script />, <template />, and <style /> blocks with supported lang attributes into JavaScript that Jest can run.

Supported script languages

• typescript (lang="ts", lang="typescript")
• coffeescript (lang="coffee", lang="coffeescript")

Global Jest options

You can change the behavior of vue-jest by using jest.globals.

Supporting custom blocks

A great feature of the Vue SFC compiler is that it can support custom blocks. You might want to use those blocks in your tests. To render out custom blocks for testing purposes, you'll need to write a transformer. Once you have your transformer, you'll add an entry to vue-jest's transform map. This is how vue-i18n's <i18n> custom blocks are supported in unit tests.

A package.json Example

{
  "jest": {
    "moduleFileExtensions": ["js", "json", "vue"],
    "transform": {
      "^.+\\.js$": "babel-jest",
      "^.+\\.vue$": "vue-jest"
    },
    "globals": {
      "vue-jest": {
        "transform": {
          "your-custom-block": "./custom-block-processor.js"
        }
      }
    }
  }
}

Tip: Need programmatic configuration? Use the --config option in Jest CLI, and export a .js file

A jest.config.js Example - If you're using a dedicated configuration file like you can reference and require your processor in the config file instead of using a file reference.

module.exports = {
  globals: {
    'vue-jest': {
      transform: {
        'your-custom-block': require('./custom-block-processor')
      }
    }
  }
}

Writing a processor

Processors must return an object with a "process" method, like so...

module.exports = {
  /**
   * Process the content inside of a custom block and prepare it for execution in a testing environment
   * @param {SFCCustomBlock[]} blocks All of the blocks matching your type, returned from `@vue/component-compiler-utils`
   * @param {string} vueOptionsNamespace The internal namespace for a component's Vue Options in vue-jest
   * @param {string} filename The SFC file being processed
   * @param {Object} config The full Jest config
   * @returns {string} The code to be output after processing all of the blocks matched by this type
   */
  process({ blocks, vueOptionsNamepsace, filename, config }) {}
}

babelConfig

Provide babelConfig in one of the following formats:

• <Boolean>
• <Object>
• <String>

Boolean

• true - Enable Babel processing. vue-jest will try to find Babel configuration using find-babel-config.

This is the default behavior if babelConfig is not defined.

• false - Skip Babel processing entirely:

{
  "jest": {
    "globals": {
      "vue-jest": {
        "babelConfig": false
      }
    }
  }
}

Object

Provide inline Babel options:

{
  "jest": {
    "globals": {
      "vue-jest": {
        "babelConfig": {
          "presets": [
            [
              "env",
              {
                "useBuiltIns": "entry",
                "shippedProposals": true
              }
            ]
          ],
          "plugins": ["syntax-dynamic-import"],
          "env": {
            "test": {
              "plugins": ["dynamic-import-node"]
            }
          }
        }
      }
    }
  }
}

String

If a string is provided, it will be an assumed path to a babel configuration file (e.g. .babelrc, .babelrc.js).

• Config file should export a Babel configuration object.
• Should not point to a project-wide configuration file (babel.config.js), which exports a function.

{
  "jest": {
    "globals": {
      "vue-jest": {
        "babelConfig": "path/to/.babelrc.js"
      }
    }
  }
}

To use the Config Function API, use inline options instead. i.e.:

{
  "jest": {
    "globals": {
      "vue-jest": {
        "babelConfig": {
          "configFile": "path/to/babel.config.js"
        }
      }
    }
  }
}

tsConfig

Provide tsConfig in one of the following formats:

• <Boolean>
• <Object>
• <String>

Boolean

• true - Process TypeScript files using custom configuration. vue-jest will try to find TypeScript configuration using tsconfig.loadSync.

This is the default behavior if tsConfig is not defined.

• false - Process TypeScript files using the default configuration provided by vue-jest.

Object

Provide inline TypeScript compiler options:

{
  "jest": {
    "globals": {
      "vue-jest": {
        "tsConfig": {
          "importHelpers": true
        }
      }
    }
  }
}

String

If a string is provided, it will be an assumed path to a TypeScript configuration file:

{
  "jest": {
    "globals": {
      "vue-jest": {
        "tsConfig": "path/to/tsconfig.json"
      }
    }
  }
}

Supported template languages

• pug (lang="pug")

  • To give options for the Pug compiler, enter them into the Jest configuration. The options will be passed to pug.compile().

  {
    "jest": {
      "globals": {
        "vue-jest": {
          "pug": {
            "basedir": "mybasedir"
          }
        }
      }
    }
  }
  

• jade (lang="jade")

• haml (lang="haml")

Supported style languages

• stylus (lang="stylus", lang="styl")

• sass (lang="sass"), and

• scss (lang="scss")

  • The Sass compiler supports Jest's moduleNameMapper which is the suggested way of dealing with Webpack aliases. Webpack's sass-loader uses a special syntax for indicating non-relative imports, so you'll likely need to copy this syntax into your moduleNameMapper entries if you make use of it. For aliases of bare imports (imports that require node module resolution), the aliased value must also be prepended with this ~ or vue-jest's custom resolver won't recognize it.

    {
      "jest": {
        "moduleNameMapper": {
          "^~foo/(.*)": "<rootDir>/foo/$1",
          // @import '~foo'; -> @import 'path/to/project/foo';
          "^~bar/(.*)": "~baz/lib/$1"
          // @import '~bar/qux'; -> @import 'path/to/project/node_modules/baz/lib/qux';
          // Notice how the tilde (~) was needed on the bare import to baz.
        }
      }
    }
    

  • To import globally included files (ie. variables, mixins, etc.), include them in the Jest configuration at jest.globals['vue-jest'].resources.scss:

    {
      "jest": {
        "globals": {
          "vue-jest": {
            "resources": {
              "scss": [
                "./node_modules/package/_mixins.scss",
                "./src/assets/css/globals.scss"
              ]
            }
          }
        }
      }
    }
    

CSS options

experimentalCSSCompile: Boolean Default true. Turn off CSS compilation hideStyleWarn: Boolean Default false. Hide warnings about CSS compilation resources:

{
  "jest": {
    "globals": {
      "vue-jest": {
        "hideStyleWarn": true,
        "experimentalCSSCompile": true
      }
    }
  }
}