Registry / testing / vue-test-utils-compat

vue-test-utils-compat

library0.0.15jsnpmunverified

vue-test-utils-compat provides a critical compatibility layer for migrating existing Vue 2 test suites written with `@vue/test-utils` v1 to run seamlessly on `@vue/test-utils` v2 and Vue 3. This package, currently at version 0.0.15, is designed to ease the transition burden by allowing developers to upgrade their Vue components to Vue 3 first, and then address test migrations, leveraging Vue 3's migration build. It achieves this by providing numerous compatibility flags that can be configured to mimic v1 behavior, addressing differences in mounting options, wrapper APIs, and event handling. Its release cadence is tied to the needs of the Vue 2 to Vue 3 migration process. A key differentiator is its extensive configuration options, allowing granular control over which v1 behaviors are re-enabled, facilitating a gradual and less disruptive migration path.

testing web-framework

npm install vue-test-utils-compat

package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-TEST-UTILS-COM

vue-test-utils-compat

testingjavascriptv0.0.15

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.

installCompat

✓ import { installCompat } from 'vue-test-utils-compat'

✗ const { installCompat } = require('vue-test-utils-compat')

While the quickstart uses `require`, ESM imports are the modern standard for Node.js modules. The package supports both.

fullCompatConfig

✓ import { fullCompatConfig } from 'vue-test-utils-compat'

✗ const fullCompatConfig = require('vue-test-utils-compat').fullCompatConfig

Used to apply a comprehensive set of v1 compatibility flags to `@vue/test-utils` v2.

installCompat (CommonJS)

✓ const { installCompat } = require('vue-test-utils-compat')

This pattern is explicitly shown in the documentation and is valid for CommonJS environments, especially older Node.js projects.

Demonstrates how to install the compatibility layer for `@vue/test-utils` v2 in a Vue 3 project and provides a basic example of testing a component with v1-style APIs.

import { h } from 'vue'; import * as VueTestUtils from '@vue/test-utils'; import { installCompat, fullCompatConfig } from 'vue-test-utils-compat'; // Assuming Vue 3 without migration build // If using 'vue/compat', the 'h' function might need to be retrieved from a mounted app instance. installCompat(VueTestUtils, fullCompatConfig, h); // Example test using the compat layer describe('MyComponent with VTU v1 compat', () => { const MyComponent = { template: '<div><p>{{ message }}</p><button @click="increment">Click me</button></div>', data: () => ({ message: 'Hello', count: 0 }), methods: { increment() { this.count++; } } }; it('renders the message', () => { const wrapper = VueTestUtils.mount(MyComponent); expect(wrapper.find('p').text()).toBe('Hello'); }); it('increments count on button click (v1 style)', async () => { const wrapper = VueTestUtils.mount(MyComponent); await wrapper.find('button').trigger('click'); // In v1, wrapper.vm would directly expose the component instance // With compat, this attempts to bridge that gap. expect(wrapper.vm.count).toBe(1); }); });

Debug

Known issues

breakingBefore applying `vue-test-utils-compat`, ensure all deprecations from `@vue/test-utils` v1 are addressed and fixed in your existing test suite. This ensures the baseline v1 tests are stable before introducing the compatibility layer.

fix

Run your existing v1 test suite with the latest `@vue/test-utils` v1 and resolve all reported deprecation warnings and errors. Consult the `@vue/test-utils` v1 documentation for specific deprecation fixes.

affects: >=0.0.1

gotchaThe `h` function (render function) is a required argument for `installCompat`. If using the Vue 3 migration build (Vue 2 mode), you must correctly retrieve the `h` function from a mounted Vue application instance, which can be non-trivial.

fix

For Vue 3 (full mode), import `h` directly from 'vue'. For Vue 3 migration build (Vue 2 mode), ensure you mount a temporary app to capture the `h` function, as shown in the package's documentation. Incorrect `h` will lead to runtime errors during test execution.

affects: >=0.0.1

breakingMany `@vue/test-utils` v1 APIs, such as direct access to `wrapper.vm`, `wrapper.attributes()`, and event handling (`wrapper.trigger`), behave differently or are removed in v2. The compatibility layer attempts to bridge these gaps, but subtle differences or edge cases may still exist.

fix

Review the list of compatibility flags in the `vue-test-utils-compat` documentation and enable/disable specific flags as needed. Debug tests thoroughly after migration, focusing on interactions that rely heavily on v1-specific APIs. Be prepared to gradually refactor problematic tests to native VTU v2 APIs where full compatibility is not achievable.

affects: >=0.0.1

gotchaThe compatibility layer introduces some overhead and potential for unexpected behavior due to the translation of v1 APIs to v2. It is an interim solution, and tests should ideally be refactored to native `@vue/test-utils` v2 APIs over time.

fix

Plan for a phased migration where `vue-test-utils-compat` is used temporarily, followed by a dedicated effort to rewrite tests using `@vue/test-utils` v2 and Vue 3's native testing patterns for long-term maintainability and performance.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'config')

The `@vue/test-utils` instance passed to `installCompat` is undefined or incorrect.

fix

Ensure `@vue/test-utils` is correctly installed and imported, and that `installCompat` receives the actual `VueTestUtils` object (e.g., `import * as VueTestUtils from '@vue/test-utils'`).

Error: [vue-compat] h is not defined

The `h` (render function) argument was not provided or was incorrect during `installCompat`.

fix

Pass the `h` function imported from 'vue' (for Vue 3) or correctly retrieved from a Vue 3 migration build instance to `installCompat`.

TypeError: wrapper.find(...).text is not a function

This error often indicates that `wrapper.find` is returning a `WrapperArray` or a component wrapper instead of a DOM wrapper, and `text()` is called on an unexpected type, or the element was not found.

fix

Ensure you are targeting a DOM element (`wrapper.find('p')`) and not a component (`wrapper.findComponent(MyComponent)`) when expecting DOM-specific methods like `text()`. Also verify the selector correctly matches an element present in the rendered output.

Upgrade

Version history

0.0.15latest on npm

Audit

Dependencies

vuerequiredPeer dependency, required for component rendering and framework utilities.

@vue/test-utilsrequiredPeer dependency, this package provides a compatibility layer on top of VTU v2.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/vue-test-utils-compat ↗

homepagehttps://gitlab.com/xanf/vue-test-utils-compat#readme ↗