如何在Vitest/Vue Test Utils中解决vueuse/head测试注入报错

@vueuse/head 依赖Vue的依赖注入机制提供useHead方法，实际项目运行时会在入口文件通过app.use(head)完成插件注册，但Vue Test Utils的测试挂载环境默认是无额外插件的干净Vue实例，没有注册该插件，组件执行setup调用useHead时拿不到注入的head实例，就会抛出对应错误。

根据你的测试场景，选下面任意一种配置方式即可：

单测试文件/单用例配置 #

只需要在挂载组件时，通过VTU提供的global.plugins配置项，把初始化好的head实例注册到测试应用实例上即可，修改后的测试代码如下：

import { describe, it, expect } from 'vitest';
import { mount } from '@vue/test-utils';
// 引入createHead方法用于创建head实例
import { createHead } from '@vueuse/head';
import Login from './Login.vue';

describe('Login.spec.js', () => {
    it('mounts correctly', () => {
        // 初始化head实例
        const head = createHead();
        const wrapper = mount(Login, {
            global: {
                // 注册插件，和实际项目入口app.use逻辑一致
                plugins: [head]
            }
        });
        expect(wrapper.isVisible()).toBe(true);
    });
});

如果同个文件下有多个测试用例，可以把公共初始化逻辑抽到beforeEach钩子中避免重复代码：

import { describe, it, expect, beforeEach } from 'vitest';
import { mount } from '@vue/test-utils';
import { createHead } from '@vueuse/head';
import Login from './Login.vue';

describe('Login.spec.js', () => {
    let wrapper;
    beforeEach(() => {
        const head = createHead();
        wrapper = mount(Login, {
            global: {
                plugins: [head]
            }
        });
    })

    it('mounts correctly', () => {
        expect(wrapper.isVisible()).toBe(true);
    });
});

全局配置（所有测试文件生效） #

如果项目中大量组件都用到了useHead，可以配置Vitest全局初始化逻辑，一次配置后所有测试文件自动生效，不需要重复引入注册：

1. 首先修改Vitest配置文件（vitest.config.js/vite.config.js中test配置段），指定全局setup文件：

import { defineConfig } from 'vitest/config';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [vue()],
    test: {
        globals: true,
        // 指向你自己的全局测试初始化文件路径
        setupFiles: './tests/setup.js'
    }
});

2. 创建对应的setup文件，配置VTU全局插件：

import { config } from '@vue/test-utils';
import { createHead } from '@vueuse/head';

// 初始化head实例并注册为全局插件
const head = createHead();
config.global.plugins = [head];

补充说明 #

• 上述写法同时兼容Vue3版本的@vueuse/head以及旧版Vue2适配版本，不需要额外调整API
• 如果测试中需要校验useHead配置的标题、meta标签等内容是否正确，可以直接通过创建的head实例读取内部状态做断言，不需要额外操作DOM
• 项目中其他全局依赖（比如vue-router、pinia、自定义全局组件），都可以通过相同的global.plugins/global.components配置项注入到测试环境，和实际项目入口的注册逻辑保持一致即可

内容的提问来源于stack exchange，提问作者agm1984