Vue 3 中 Jest 单元测试正确集成 vue-i18n 的完整实践指南-js教程-PHP中文网

Vue 3 中 Jest 单元测试正确集成 vue-i18n 的完整实践指南

本文详解如何在 Vue 3（Composition API）项目中为 Jest 单元测试正确配置 vue-i18n，解决 $t is not a function 等核心报错，涵盖插件注入、类型声明、模拟策略及常见陷阱。

本文详解如何在 vue 3（composition api）项目中为 jest 单元测试正确配置 vue-i18n，解决 `$t is not a function` 等核心报错，涵盖插件注入、类型声明、模拟策略及常见陷阱。

在 Vue 3 + TypeScript 项目中集成 vue-i18n 后，单元测试常因 $t 方法缺失而崩溃——典型错误如 TypeError: _ctx.$t is not a function。这并非代码逻辑问题，而是测试环境未正确提供 i18n 实例所致。与开发时自动挂载不同，Jest 测试需显式将 i18n 插件注入 mount 配置的 global.plugins 中，否则组件无法访问 $t、$i18n 等全局属性。

✅ 正确做法：在 `mount()` 中注入 i18n 实例

首先确保你已创建并导出 i18n 实例（推荐使用 Composition API 模式，即 legacy: false）：

// src/i18n/index.ts
import { createI18n } from 'vue-i18n';
import { de, en } from './locales';

export const i18n = createI18n({
  legacy: false, // 关键！禁用 Vue 2 兼容模式
  locale: 'de',
  messages: { de, en }
});

接着，在测试文件中导入该实例，并将其传入 mount 的 global.plugins：

// DudDialog.spec.js
import { mount } from '@vue/test-utils';
import { createPinia } from 'pinia';
import { i18n } from '@/i18n'; // ✅ 导入真实 i18n 实例
import DudDialog from '@/components/DudsView/DudDialog.vue';

describe('DudDialog.vue', () => {
  const pinia = createPinia();

  it('displays the form fields correctly', () => {
    const wrapper = mount(DudDialog, {
      global: {
        plugins: [pinia, i18n], // ✅ 关键：将 i18n 加入 plugins 数组
        stubs: ['v-app', 'v-dialog', /* ... */],
      },
      props: { dud: new Dud('Test') }
    });

    // 此时 $t 可正常使用，模板渲染无报错
    expect(wrapper.find('[label="Typ"]').exists()).toBe(true);
  });
});

⚠️ 注意：plugins 是数组，必须包含 i18n（而非字符串 'vue-i18n'），且顺序无关；但务必确保 i18n 实例已初始化（不为 undefined）。

? 补充：TypeScript 类型支持（防 `TS2339` 报错）

若在 .spec.ts 中使用 wrapper.vm.$t(...) 仍遇 TS 错误，需补充类型声明：

Vue

避免 Vue 常见错误——响应式陷阱、ref 与 reactive 区别、计算属性时机及 Composition API 陷阱。

下载

// src/types/shims-vue-i18n.d.ts
import 'vue-i18n';
import type { ComponentCustomProperties } from 'vue';
import type { I18n } from 'vue-i18n';

declare module 'vue' {
  interface ComponentCustomProperties {
    $t: I18n['t'];
  }
}

并在 tsconfig.json 的 include 中加入该文件路径：

{
  "include": ["src/**/*", "src/types/shims-vue-i18n.d.ts"]
}

? 替代方案：轻量 Mock（适用于无真实翻译需求场景）

若仅需通过测试、无需真实翻译逻辑，可快速 mock $t：

const wrapper = mount(DudDialog, {
  global: {
    mocks: {
      $t: (key: string) => `{{${key}}}` // 返回占位符，避免报错
    },
    stubs: [...],
  },
  props: { dud: new Dud('Test') }
});

但注意：mocks 在 Vue Test Utils v2+ 中已被标记为 deprecated，官方推荐优先使用 plugins 注入真实实例，以保障测试真实性与可维护性。