{"id":15282,"library":"vue-test-utils-compat","title":"Vue Test Utils Compatibility Layer","description":"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.","status":"active","version":"0.0.15","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","vue-test-utils","vue-compat","vue"],"install":[{"cmd":"npm install vue-test-utils-compat","lang":"bash","label":"npm"},{"cmd":"yarn add vue-test-utils-compat","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-test-utils-compat","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required for component rendering and framework utilities.","package":"vue","optional":false},{"reason":"Peer dependency, this package provides a compatibility layer on top of VTU v2.","package":"@vue/test-utils","optional":false}],"imports":[{"note":"While the quickstart uses `require`, ESM imports are the modern standard for Node.js modules. The package supports both.","wrong":"const { installCompat } = require('vue-test-utils-compat')","symbol":"installCompat","correct":"import { installCompat } from 'vue-test-utils-compat'"},{"note":"Used to apply a comprehensive set of v1 compatibility flags to `@vue/test-utils` v2.","wrong":"const fullCompatConfig = require('vue-test-utils-compat').fullCompatConfig","symbol":"fullCompatConfig","correct":"import { fullCompatConfig } from 'vue-test-utils-compat'"},{"note":"This pattern is explicitly shown in the documentation and is valid for CommonJS environments, especially older Node.js projects.","symbol":"installCompat (CommonJS)","correct":"const { installCompat } = require('vue-test-utils-compat')"}],"quickstart":{"code":"import { h } from 'vue';\nimport * as VueTestUtils from '@vue/test-utils';\nimport { installCompat, fullCompatConfig } from 'vue-test-utils-compat';\n\n// Assuming Vue 3 without migration build\n// If using 'vue/compat', the 'h' function might need to be retrieved from a mounted app instance.\n\ninstallCompat(VueTestUtils, fullCompatConfig, h);\n\n// Example test using the compat layer\ndescribe('MyComponent with VTU v1 compat', () => {\n  const MyComponent = {\n    template: '<div><p>{{ message }}</p><button @click=\"increment\">Click me</button></div>',\n    data: () => ({ message: 'Hello', count: 0 }),\n    methods: { increment() { this.count++; } }\n  };\n\n  it('renders the message', () => {\n    const wrapper = VueTestUtils.mount(MyComponent);\n    expect(wrapper.find('p').text()).toBe('Hello');\n  });\n\n  it('increments count on button click (v1 style)', async () => {\n    const wrapper = VueTestUtils.mount(MyComponent);\n    await wrapper.find('button').trigger('click');\n    // In v1, wrapper.vm would directly expose the component instance\n    // With compat, this attempts to bridge that gap.\n    expect(wrapper.vm.count).toBe(1);\n  });\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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'`).","cause":"The `@vue/test-utils` instance passed to `installCompat` is undefined or incorrect.","error":"TypeError: Cannot read properties of undefined (reading 'config')"},{"fix":"Pass the `h` function imported from 'vue' (for Vue 3) or correctly retrieved from a Vue 3 migration build instance to `installCompat`.","cause":"The `h` (render function) argument was not provided or was incorrect during `installCompat`.","error":"Error: [vue-compat] h is not defined"},{"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.","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.","error":"TypeError: wrapper.find(...).text is not a function"}],"ecosystem":"npm"}