Vue Test Utils Compatibility Layer

Common errors

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

  cause 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

  cause 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

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

Warnings

• breaking Before 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.
• gotcha The `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.
• breaking Many `@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.
• gotcha The 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.

Install

• npm install vue-test-utils-compat npm
• yarn add vue-test-utils-compat yarn
• pnpm add vue-test-utils-compat pnpm

Imports

• installCompat
  wrong:

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

  correct:

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

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

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

  correct:

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

  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.

Quickstart

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