Jest Vue Transformer (Legacy)

Common errors

• Cannot find module 'vue-template-compiler' from 'node_modules/vue-jest/lib/transformers/template.js'

  cause `vue-template-compiler` is a required peer dependency but is not installed or its version is mismatched with `vue`.
  fix `npm install vue-template-compiler@<vue-version>` or `yarn add vue-template-compiler@<vue-version>`. Ensure the version matches your installed `vue` package.

• Jest encountered an unexpected token. This usually means that you are trying to import a file which Jest cannot process, e.g. a .vue file, without a proper transformer.

  cause `vue-jest` is not correctly configured in `jest.config.js`'s `transform` section for `.vue` files, or `babel-jest` isn't configured for `.js` files in `node_modules`.
  fix Check your `jest.config.js` `transform` entry for `vue-jest`: `{'^.+\.vue$': 'vue-jest'}`. Also, ensure `babel-jest` is configured for JavaScript files and `transformIgnorePatterns` allows transformation of relevant modules if needed.

• SyntaxError: Cannot use import statement outside a module

  cause CommonJS vs. ES Module conflict. Vue SFCs often use ESM syntax, but Jest (depending on configuration and Node.js version) might be running in CommonJS mode. `babel-jest` or `ts-jest` need to correctly transpile ESM `import`/`export` statements.
  fix Ensure `babel-jest` (or `ts-jest` for TypeScript) is correctly configured in `jest.config.js` to transpile ES modules. For Babel, verify your `.babelrc` or `babel.config.js` includes `@babel/preset-env` with `modules: 'commonjs'` (or `auto` if Babel 7.x).

Warnings

• breaking The `vue-jest` package (v3.x and earlier) has been superseded. For Jest 28 and 29, and for distinct Vue 2 or Vue 3 projects, developers must migrate to `@vue/vue2-jest` or `@vue/vue3-jest` respectively. These new packages have different installation and configuration paths.
  Fix: Install `@vue/vue2-jest` or `@vue/vue3-jest` and update `jest.config.js` transform entry to `'@vue/vue2-jest'` or `'@vue/vue3-jest'`. Ensure compatibility with your Jest and Vue versions.
• gotcha `vue-jest@3.x` requires `vue-template-compiler` to be explicitly installed as a peer dependency, matching your `vue` version. Mismatched versions can lead to compilation errors or unexpected behavior.
  Fix: Ensure `vue-template-compiler` is installed with the exact same version as `vue`. For example, `npm install vue-template-compiler@<vue-version>`.
• gotcha When using TypeScript in Vue SFCs, `vue-jest@3.x` typically relies on `babel-jest` or `ts-jest` for script block transformation. Incorrect configuration of these can lead to "unexpected token" errors or TypeScript compilation failures.
  Fix: Verify your `jest.config.js` includes `ts-jest` or `babel-jest` for `.ts` files and that your `tsconfig.json` is correctly configured to transpile for your target environment. Ensure `tsconfig.json` includes `vue` types if necessary.
• deprecated The `vue-jest` package itself (versions 3.x and earlier) is considered deprecated by the Vue team in favor of the scoped `@vue/vue2-jest` and `@vue/vue3-jest` packages. While still functional, it receives minimal maintenance.
  Fix: Plan to migrate to the appropriate scoped `@vue` package to receive active development, bug fixes, and Jest 28/29+ compatibility.

Install

• npm install vue-jest npm
• yarn add vue-jest yarn
• pnpm add vue-jest pnpm

Imports

• Transformer Configuration
  wrong:

  import vueJest from 'vue-jest';

  correct:

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

  vue-jest is a Jest transformer, not a library meant for direct JavaScript imports. Its usage is solely within Jest configuration files (`jest.config.js` or similar).

Quickstart

This quickstart demonstrates how to configure `vue-jest` in `jest.config.js` for testing a basic Vue 2 component, including an example component and its corresponding unit test using `@vue/test-utils`.

/* jest.config.js */
module.exports = {
  moduleFileExtensions: ['js', 'json', 'vue'],
  transform: {
    '^.+\.vue$': 'vue-jest',
    '^.+\.js$': 'babel-jest',
    // If using TypeScript, you might need 'ts-jest'
    // '^.+\.ts$': 'ts-jest',
  },
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
  },
  testEnvironment: 'jsdom',
  snapshotSerializers: ['jest-serializer-vue'],
};

/* src/components/HelloWorld.vue */
<template>
  <div class="hello">
    <h1>{{ msg }}</h1>
  </div>
</template>

<script>
export default {
  name: 'HelloWorld',
  props: {
    msg: String
  }
};
</script>

<style scoped>
h3 {
  margin: 40px 0 0;
}
</style>

/* tests/unit/HelloWorld.spec.js */
import { shallowMount } from '@vue/test-utils';
import HelloWorld from '@/components/HelloWorld.vue';

describe('HelloWorld.vue', () => {
  it('renders props.msg when passed', () => {
    const msg = 'new message';
    const wrapper = shallowMount(HelloWorld, {
      propsData: { msg }
    });
    expect(wrapper.text()).toMatch(msg);
  });
});