@blueking/bkui-knowledge 0.0.1-beta.13 → 0.0.1-beta.15

package/knowledge/skills/chat-x-unit-test/references/test-qa.md

@@ -0,0 +1,463 @@
+# 单元测试常见问题与解决方案 (Q&A)
+
+本文档总结了在 Chat-X 组件库开发过程中遇到的单元测试问题及解决方案。
+
+## Mock 相关问题
+
+### Q1: Mock 路径与组件 import 路径不匹配导致 Mock 失效
+
+**问题描述**：
+Mock 了组件但测试中找不到 mock 的元素，Mock 没有生效。
+
+**错误示例**：
+
+```typescript
+// 组件中的 import
+import ScrollBtn from '../../ai-buttons/scroll-btn/scroll-btn.vue';
+
+// 错误的 Mock 路径
+vi.mock('../ai-buttons/scroll-btn/scroll-btn.vue', () => ({ ... }));  // ❌
+```
+
+**解决方案**：
+Mock 路径必须与组件中的 import 路径完全一致（相对于测试文件位置）。
+
+```typescript
+// 正确的 Mock 路径
+vi.mock('../../ai-buttons/scroll-btn/scroll-btn.vue', () => ({ ... }));  // ✅
+```
+
+**调试技巧**：
+
+1. 检查被测试组件的 import 语句
+2. 根据测试文件位置计算正确的相对路径
+3. 使用 `console.log` 或断点确认 Mock 是否生效
+
+---
+
+### Q2: vi.mock 中使用外部变量导致 ReferenceError
+
+**问题描述**：
+在 `vi.mock` 工厂函数中引用外部定义的变量，导致 `ReferenceError: Cannot access 'xxx' before initialization`。
+
+**错误示例**：
+
+```typescript
+const mockFn = vi.fn(); // ❌ 在 mock 之前定义
+
+vi.mock('./module', () => ({
+  myFunction: mockFn, // 引用错误
+}));
+```
+
+**解决方案**：
+在 `vi.mock` 内部定义所有需要的 mock 函数，或使用 `vi.hoisted`。
+
+```typescript
+// 方式 1：内部定义
+vi.mock('./module', () => ({
+  myFunction: vi.fn(),
+}));
+
+// 方式 2：使用 vi.hoisted（推荐）
+const { mockFn } = vi.hoisted(() => ({
+  mockFn: vi.fn(),
+}));
+
+vi.mock('./module', () => ({
+  myFunction: mockFn,
+}));
+```
+
+---
+
+### Q3: bkui-vue 导入失败
+
+**问题描述**：
+运行测试时报错 `Failed to resolve import "bkui-vue"`。
+
+**解决方案**：
+在 `vitest.config.ts` 中配置 alias：
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  resolve: {
+    alias: {
+      'bkui-vue': path.resolve(__dirname, './node_modules/bkui-vue/lib/index.js'),
+    },
+  },
+});
+```
+
+或在测试文件中 mock 整个模块：
+
+```typescript
+vi.mock('bkui-vue', () => ({
+  Button: defineComponent({ ... }),
+  Input: defineComponent({ ... }),
+  Message: { success: vi.fn(), error: vi.fn() },
+}));
+```
+
+---
+
+## v-model 与响应式问题
+
+### Q4: defineModel 折叠状态测试失败
+
+**问题描述**：
+使用 `defineModel` 的组件，点击触发折叠后直接检查 DOM 可见性失败。
+
+**错误示例**：
+
+```typescript
+// ❌ 可能失败
+await wrapper.find('.title').trigger('click');
+expect(wrapper.find('.content').isVisible()).toBe(false);
+```
+
+**原因分析**：
+`defineModel` 生成的是双向绑定，组件内部修改值后需要父组件响应才能真正更新状态。
+
+**解决方案**：
+验证事件是否正确触发，而非直接检查 DOM 状态。
+
+```typescript
+// ✅ 正确方式
+it('点击标题应该触发折叠状态变化', async () => {
+  wrapper = mount(Component, {
+    props: {
+      collapsed: false,
+      'onUpdate:collapsed': (val: boolean) => wrapper.setProps({ collapsed: val }),
+    },
+  });
+
+  await wrapper.find('.title').trigger('click');
+  expect(wrapper.emitted('update:collapsed')).toBeTruthy();
+  expect(wrapper.emitted('update:collapsed')?.[0]).toEqual([true]);
+});
+
+// 如需验证 DOM 状态，确保 props 同步更新
+it('collapsed 为 true 时内容应该隐藏', () => {
+  wrapper = mount(Component, {
+    props: { collapsed: true },
+  });
+  expect(wrapper.find('.content').isVisible()).toBe(false);
+});
+```
+
+---
+
+### Q5: useMenuKeydown 等 Composable 返回的响应式值在 Mock 中不生效
+
+**问题描述**：
+Mock `useMenuKeydown` 返回 `{ activeIndex: { value: 0 } }`，但组件中的 `:class="{ 'is-active': activeIndex === index }"` 绑定不生效。
+
+**原因分析**：
+Mock 返回的是普通对象，不是 Vue 的响应式引用（`Ref`），模板中的响应式绑定无法正常工作。
+
+**解决方案**：
+
+方式 1：返回真正的 `shallowRef`：
+
+```typescript
+import { shallowRef } from 'vue';
+
+vi.mock('../../../composables/use-menu-keydown', () => ({
+  useMenuKeydown: vi.fn(() => ({
+    activeIndex: shallowRef(0), // 使用 shallowRef
+  })),
+}));
+```
+
+方式 2：测试时调整断言策略，不依赖响应式类绑定：
+
+```typescript
+it('应该渲染正确数量的 item', () => {
+  wrapper = mount(Component, { props: { items: ['a', 'b'] } });
+  expect(wrapper.findAll('.item').length).toBe(2);
+  // 不测试 is-active 类，因为 mock 无法完美模拟响应式
+});
+```
+
+---
+
+## 断言相关问题
+
+### Q6: wrapper.text() 会 trim 空格
+
+**问题描述**：
+测试包含空格的文本时，`wrapper.text()` 返回值与预期不符。
+
+**错误示例**：
+
+```typescript
+// 组件渲染: "  text with spaces  "
+expect(wrapper.text()).toBe('  text with spaces  '); // ❌ 失败
+```
+
+**原因分析**：
+Vue Test Utils 的 `wrapper.text()` 会自动 trim 首尾空格。
+
+**解决方案**：
+
+```typescript
+// 方式 1：使用 toContain
+expect(wrapper.text()).toContain('text with spaces');
+
+// 方式 2：检查 HTML 内容
+expect(wrapper.html()).toContain('  text with spaces  ');
+
+// 方式 3：检查具体元素的 textContent
+expect(wrapper.find('.content').element.textContent).toBe('  text with spaces  ');
+```
+
+---
+
+### Q7: Boolean Props 默认值测试
+
+**问题描述**：
+测试 Boolean 类型 Props 的默认值时，预期为 `undefined` 但实际为 `false`。
+
+**错误示例**：
+
+```typescript
+// Props 定义（无显式 default）
+defineProps<{ disabled?: boolean }>();
+
+// 测试
+expect(wrapper.props().disabled).toBeUndefined(); // ❌ 实际是 false
+```
+
+**原因分析**：
+Vue 3 对 Boolean 类型的 Props 有特殊处理，未传入时默认为 `false`。
+
+**解决方案**：
+
+```typescript
+expect(wrapper.props().disabled).toBe(false); // ✅
+```
+
+---
+
+### Q8: 测试数量断言不稳定
+
+**问题描述**：
+测试动态列表数量时，由于 Mock 或响应式更新问题，实际数量可能超出预期。
+
+**错误示例**：
+
+```typescript
+await wrapper.setProps({ items: [1, 2, 3] });
+expect(wrapper.findAll('.item').length).toBe(3); // ❌ 可能是 7
+```
+
+**解决方案**：
+
+```typescript
+// 方式 1：使用 toBeGreaterThanOrEqual
+expect(wrapper.findAll('.item').length).toBeGreaterThanOrEqual(3);
+
+// 方式 2：重新挂载组件
+wrapper.unmount();
+wrapper = mount(Component, { props: { items: [1, 2, 3] } });
+expect(wrapper.findAll('.item').length).toBe(3);
+```
+
+---
+
+## 异步与生命周期问题
+
+### Q9: watch 中的 stop 函数导致测试报错
+
+**问题描述**：
+组件中有类似以下代码，测试时报 `Cannot access 'stop' before initialization`：
+
+```typescript
+const stop = watch(
+  () => props.duration,
+  () => {
+    if (props.duration) stop(); // stop 在声明前被使用
+  },
+  { immediate: true },
+);
+```
+
+**解决方案**：
+避免在测试中触发该 watch 的 immediate 执行，或简化测试断言：
+
+```typescript
+// 不传入会触发问题的 prop
+wrapper = mount(Component, {
+  props: {
+    status: MessageStatus.Complete,
+    // 不传 duration，避免触发 watch
+  },
+});
+```
+
+---
+
+### Q10: 异步操作后 DOM 未更新
+
+**问题描述**：
+触发异步操作后，DOM 没有更新。
+
+**解决方案**：
+
+```typescript
+import { nextTick, flushPromises } from '@vue/test-utils';
+
+it('异步操作后应该更新 DOM', async () => {
+  wrapper = mount(Component);
+  await wrapper.find('.async-btn').trigger('click');
+
+  // 方式 1：等待 nextTick
+  await nextTick();
+
+  // 方式 2：等待所有 Promise
+  await flushPromises();
+
+  // 方式 3：等待特定时间
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  expect(wrapper.find('.result').exists()).toBe(true);
+});
+```
+
+---
+
+## 组件交互问题
+
+### Q11: 子组件事件无法正确捕获
+
+**问题描述**：
+Mock 的子组件触发事件后，父组件的事件处理没有被调用。
+
+**解决方案**：
+确保 Mock 组件正确设置了 `emits` 并调用 `emit`：
+
+```typescript
+vi.mock('./child.vue', () => ({
+  default: defineComponent({
+    name: 'Child',
+    emits: ['click'], // 必须声明
+    setup(_, { emit }) {
+      return () =>
+        h('div', {
+          class: 'mock-child',
+          onClick: () => emit('click'), // 正确触发
+        });
+    },
+  }),
+}));
+
+// 测试
+it('子组件点击应该触发父组件事件', async () => {
+  wrapper = mount(ParentComponent);
+  await wrapper.find('.mock-child').trigger('click');
+  expect(wrapper.emitted('childClicked')).toBeTruthy();
+});
+```
+
+---
+
+### Q12: v-tippy / v-overflow-tips 等指令报错
+
+**问题描述**：
+测试时报 `Failed to resolve directive: tippy`。
+
+**解决方案**：
+全局注册空指令：
+
+```typescript
+wrapper = mount(Component, {
+  global: {
+    directives: {
+      tippy: {},
+      'overflow-tips': {},
+    },
+  },
+});
+```
+
+或在测试文件顶部 Mock：
+
+```typescript
+vi.mock('vue-tippy', () => ({
+  directive: {},
+}));
+```
+
+---
+
+## 配置问题
+
+### Q13: Vitest deps.inline 已弃用警告
+
+**问题描述**：
+控制台显示 `Vitest "deps.inline" is deprecated` 警告。
+
+**解决方案**：
+从 `vitest.config.ts` 中移除 `deps` 配置，使用 `resolve.alias` 代替：
+
+```typescript
+// ❌ 弃用
+export default defineConfig({
+  test: {
+    deps: {
+      inline: ['bkui-vue'],
+    },
+  },
+});
+
+// ✅ 推荐
+export default defineConfig({
+  resolve: {
+    alias: {
+      'bkui-vue': path.resolve(__dirname, './node_modules/bkui-vue/lib/index.js'),
+    },
+  },
+});
+```
+
+---
+
+## 调试技巧
+
+### 技巧 1：打印组件 HTML
+
+```typescript
+console.log(wrapper.html());
+```
+
+### 技巧 2：检查 emitted 事件
+
+```typescript
+console.log(wrapper.emitted());
+// { click: [[arg1]], 'update:modelValue': [['new value']] }
+```
+
+### 技巧 3：使用 wrapper.vm 访问组件实例
+
+```typescript
+console.log(wrapper.vm.someData);
+console.log(wrapper.vm.$props);
+```
+
+### 技巧 4：单独运行测试用例
+
+```bash
+# 只运行特定 it
+npx vitest run -t "应该正确渲染组件"
+
+# 运行特定 describe
+npx vitest run -t "渲染测试"
+```
+
+### 技巧 5：使用 --reporter=verbose 查看详细输出
+
+```bash
+npx vitest run --reporter=verbose src/components/your-component
+```

package/knowledge/skills/chat-x-unit-test/references/test-strategies.md

@@ -0,0 +1,206 @@
+# 测试用例设计策略
+
+## 渲染测试
+
+```typescript
+describe('渲染测试', () => {
+  it('应该正确渲染组件根元素', () => {
+    wrapper = mount(Component, { props: { content: 'test' } });
+    expect(wrapper.find('.component-root').exists()).toBe(true);
+  });
+
+  it('条件渲染：有 header 时显示标题', () => {
+    wrapper = mount(Component, { props: { showHeader: true } });
+    expect(wrapper.find('.header').exists()).toBe(true);
+  });
+
+  it('列表渲染：正确渲染多个 item', () => {
+    wrapper = mount(Component, { props: { items: ['a', 'b', 'c'] } });
+    expect(wrapper.findAll('.item').length).toBe(3);
+  });
+});
+```
+
+## Props 测试
+
+```typescript
+describe('Props 测试', () => {
+  it('应该正确接收 content 属性', () => {
+    const content = '测试内容';
+    wrapper = mount(Component, { props: { content } });
+    expect(wrapper.props().content).toBe(content);
+  });
+
+  it('disabled 为 true 时应该添加禁用类', () => {
+    wrapper = mount(Component, { props: { disabled: true } });
+    expect(wrapper.classes()).toContain('is-disabled');
+  });
+
+  it('更新 props 时应该响应式更新', async () => {
+    wrapper = mount(Component, { props: { content: 'old' } });
+    await wrapper.setProps({ content: 'new' });
+    expect(wrapper.text()).toContain('new');
+  });
+});
+```
+
+## 事件测试
+
+```typescript
+describe('事件测试', () => {
+  it('点击按钮应该触发 click 事件', async () => {
+    wrapper = mount(Component);
+    await wrapper.find('.btn').trigger('click');
+    expect(wrapper.emitted('click')).toBeTruthy();
+  });
+
+  it('使用 onXxx prop 回调的事件', async () => {
+    const onAction = vi.fn();
+    wrapper = mount(Component, { props: { onAction } });
+    await wrapper.find('.action-btn').trigger('click');
+    expect(onAction).toHaveBeenCalled();
+  });
+
+  it('键盘事件测试', async () => {
+    wrapper = mount(Component);
+    await wrapper.find('input').trigger('keydown', { key: 'Enter' });
+    expect(wrapper.emitted('submit')).toBeTruthy();
+  });
+});
+```
+
+## Slot 测试
+
+```typescript
+describe('Slot 测试', () => {
+  it('应该支持默认 slot', () => {
+    wrapper = mount(Component, {
+      slots: { default: '<div class="custom-content">Custom</div>' },
+    });
+    expect(wrapper.find('.custom-content').exists()).toBe(true);
+  });
+
+  it('scoped slot 应该接收正确的 props', () => {
+    wrapper = mount(Component, {
+      props: { items: [{ id: 1, name: 'Item 1' }] },
+      slots: {
+        item: ({ item }) => h('div', { class: 'slot-item' }, `${item.id}: ${item.name}`),
+      },
+    });
+    expect(wrapper.find('.slot-item').text()).toBe('1: Item 1');
+  });
+});
+```
+
+## v-model 测试
+
+```typescript
+describe('v-model 测试', () => {
+  it('应该正确响应 v-model', async () => {
+    wrapper = mount(Component, {
+      props: {
+        modelValue: 'initial',
+        'onUpdate:modelValue': (val: string) => wrapper.setProps({ modelValue: val }),
+      },
+    });
+    await wrapper.find('input').setValue('new value');
+    expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['new value']);
+  });
+});
+```
+
+## 边界情况测试
+
+```typescript
+describe('边界情况测试', () => {
+  it('应该处理空数组', () => {
+    wrapper = mount(Component, { props: { items: [] } });
+    expect(wrapper.find('.list').exists()).toBe(true);
+  });
+
+  it('应该处理特殊字符', () => {
+    wrapper = mount(Component, { props: { content: '<script>alert("xss")</script>' } });
+    expect(wrapper.find('script').exists()).toBe(false);
+  });
+
+  it('应该处理多种数据类型', () => {
+    for (const type of ['line', 'bar', 'pie']) {
+      wrapper = mount(Component, { props: { type } });
+      expect(wrapper.find('.component').exists()).toBe(true);
+      wrapper.unmount();
+    }
+  });
+});
+```
+
+## Teleport 测试
+
+```typescript
+describe('Teleport 测试', () => {
+  // 方式 1：Stub Teleport
+  it('使用 stub 测试 Teleport 内容', () => {
+    wrapper = mount(Component, {
+      props: { showModal: true },
+      global: { stubs: { Teleport: true } },
+    });
+    expect(wrapper.find('.modal-content').exists()).toBe(true);
+  });
+
+  // 方式 2：创建真实目标容器
+  beforeEach(() => {
+    const slot = document.createElement('div');
+    slot.id = 'teleport-target';
+    document.body.appendChild(slot);
+  });
+
+  afterEach(() => {
+    document.getElementById('teleport-target')?.remove();
+  });
+
+  it('使用真实容器测试 Teleport', () => {
+    wrapper = mount(Component, { props: { showModal: true } });
+    expect(document.getElementById('teleport-target')?.querySelector('.modal-content')).not.toBeNull();
+  });
+});
+```
+
+## 异步测试
+
+```typescript
+describe('异步测试', () => {
+  it('应该处理异步操作', async () => {
+    wrapper = mount(Component);
+    await wrapper.find('.async-trigger').trigger('click');
+    await nextTick();
+    expect(wrapper.emitted('complete')).toBeTruthy();
+  });
+
+  it('使用 flushPromises', async () => {
+    wrapper = mount(Component);
+    await wrapper.find('.fetch-btn').trigger('click');
+    await flushPromises();
+    expect(wrapper.find('.data-loaded').exists()).toBe(true);
+  });
+});
+```
+
+---
+
+## 同步更新测试原则
+
+**重要**：修改组件代码时，必须同步更新对应的测试用例！
+
+| 组件变更类型 | 测试更新操作              |
+| ------------ | ------------------------- |
+| 新增 Props   | 添加 Props 测试用例       |
+| 新增事件     | 添加事件测试用例          |
+| 新增 Slot    | 添加 Slot 测试用例        |
+| 修改渲染逻辑 | 更新渲染测试期望值        |
+| 新增条件渲染 | 添加条件分支测试          |
+| 修复 Bug     | 添加复现该 Bug 的测试用例 |
+| 删除功能     | 删除对应的测试用例        |
+
+```bash
+# 修改代码后立即运行测试验证
+npx vitest run src/components/your-component
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/bkui-knowledge",
-  "version": "0.0.1-beta.13",
+  "version": "0.0.1-beta.15",
   "description": "蓝鲸前端知识库 MCP 服务 - 自动同步 skills，支持 Cursor/CodeBuddy",
   "main": "server/mcp-core.js",
   "bin": {