vue-jest

library3.0.7jsnpmunverified

vue-jest is a Jest transformer designed to enable testing of Vue Single File Components (SFCs) within a Jest environment. Version 3.0.7 is part of the legacy branch primarily supporting Vue 2.x applications and compatible with Jest versions up to Jest 27. This package transpiles Vue SFCs, including script, template, and style blocks, into a format Jest can understand. While still functional for older projects, it has been largely superseded by the `@vue/vue2-jest` and `@vue/vue3-jest` packages, which offer dedicated support for Vue 2 and Vue 3 respectively, alongside Jest 28 and 29. Developers working on new projects or upgrading Jest should use the scoped `@vue` packages. The release cadence for `vue-jest@3.x` is now minimal, focused mainly on critical fixes for existing users, as active development has shifted to the scoped packages. Its key differentiator was being the official Vue team's solution for Jest testing before the package split.

testing

npm install vue-jest

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-JEST

vue-jest

testingjavascriptv3.0.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Transformer Configuration

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

✗ import vueJest from '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).

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); }); });

Debug

Known issues

breakingThe `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.

affects: >=3.0.0

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>`.

affects: <=3.x

gotchaWhen 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.

affects: <=3.x

deprecatedThe `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.

affects: <=3.x

Errors

Common errors & fixes

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

`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.

`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

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).

Upgrade

Version history

3.0.7latest on npm

Audit

Dependencies

babel-corerequiredRequired for transpiling JavaScript/TypeScript within Vue SFCs. Supports Babel 6 and 7.

vuerequiredRequired peer dependency for Vue 2.x component logic.

vue-template-compilerrequiredRequired peer dependency for Vue 2.x template compilation.

jestrequiredImplicit peer dependency as it's a Jest transformer. `vue-jest@3` typically works with Jest 26-27.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/vuejs/vue-jest ↗

packagehttps://www.npmjs.com/package/vue-jest ↗

homepagehttps://vue-test-utils.vuejs.org ↗