@kkeve/suite 0.0.1 → 0.0.2

package/doc/skills/keve-component-gen/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: keve-component-gen
+description: 从 Vue 组件源码自动生成组件行为模型和 Vitest 组件测试。分析组件 Props/emit/Slots/条件渲染，生成 Component Model（场景 + 断言）和测试脚本，执行验证后输出覆盖索引。
+allowed-tools: Bash(shell:*) Bash(npx:*) Bash(npm:*) Bash(node:*) Bash(git:*) Bash(pnpm:*) Bash(yarn:*)
+---
+
+# keve-component-gen
+
+## 定位
+
+**本技能负责**：从 Vue 组件源码自动生成组件行为模型和组件测试（不负责单元测试、E2E 测试）。
+
+组件测试覆盖测试金字塔中层：Vue 组件的 Props、事件、条件渲染、Slots。
+运行环境为 Node.js + jsdom，不需要真实浏览器，秒级执行。
+
+***
+
+## 触发条件
+
+| 触发方式 | 场景 | 说明 |
+|----------|------|------|
+| `use_skill("keve-component-gen")` | 开发阶段测试流水线 | 由 keve-dev-test-agent 调度 |
+| `/keve-component-gen` 指令 | 用户主动要求生成组件测试 | 手动触发 |
+
+***
+
+## 输入
+
+- 项目组件源码（由 Step 1 自动扫描识别，`.vue` SFC 文件）
+- 可选：已有的 `keve_test_spec/component/registry.json`
+
+**排除**：
+- 页面级组件（pages/、views/、layouts/ 目录下的组件，由 E2E 覆盖）
+- 纯布局组件（无交互、无 Props、无逻辑）
+- 第三方组件库组件
+- 已在 `coverage.yaml` 中标记 100% 覆盖的组件
+
+***
+
+## 流程
+
+### Step 1: 扫描组件文件
+
+**分析项目结构**，自动识别包含 `.vue` SFC 文件的目录，不硬编码路径：
+
+```
+扫描策略:
+  1. 读取项目 src/ 目录结构
+  2. 识别包含 .vue 文件的目录
+  3. 过滤条件：
+     - **只扫描 components/ 目录下的组件**（页面级组件由 E2E 覆盖）
+     - 排除: pages/、views/、layouts/ 目录（页面级，依赖路由+API，组件测试 ROI 低）
+     - 排除: 纯布局组件（无 script 或 script 只有 name）
+     - 排除: 第三方组件库组件（node_modules 下的）
+     - 排除: 已在 coverage.yaml 中 coverage=100% 的组件
+
+  判断标准：
+  - 组件能独立 mount（只依赖 Props + stub 子组件）→ 适合组件测试
+  - 组件依赖路由/API/页面级生命周期 → 不适合，由 E2E 覆盖
+
+  常见组件目录（仅供参考，不硬编码）：
+  - src/components/
+  - 项目可能有自定义目录名，需逐一分析
+```
+
+### Step 2: 分析组件 API
+
+对每个组件分析：
+
+| 分析维度 | 提取来源 | 用途 |
+|---------|---------|------|
+| Props 定义 | `defineProps` / `props` 选项 | 场景 Props + 默认值 |
+| emit 事件 | `defineEmits` / `emits` 选项 | 断言 emitted |
+| Slots | `$slots` / `<slot>` 标签 | 断言插槽渲染 |
+| 条件渲染 | `v-if` / `v-show` | true/false 分支各 1 test |
+| 计算属性 | `computed` | 断言派生值 |
+| 事件处理器 | `@click` / `@input` 等 | trigger + 断言 |
+
+### Step 3: 生成 Component Model
+
+**生成路径**：`keve_test_spec/component/models/{ComponentName}.model.ts`
+
+**model.ts 结构**（纯数据，不依赖 Storybook，D14）：
+
+```typescript
+// keve_test_spec/component/models/SearchFilter.model.ts
+
+import SearchFilter from '@/components/SearchFilter.vue';
+
+export const SearchFilterModel = {
+  // ─── 组件标识 ───
+  name: 'SearchFilter',
+  source: 'src/components/SearchFilter.vue',
+  component: SearchFilter,
+
+  // ─── 组件 API ───
+  events: ['update:modelValue'],
+  slots: [],
+
+  // ─── 组件场景 ───
+  scenarios: [
+    {
+      id: 'SF-DEFAULT',
+      name: '默认状态',
+      description: '显示三个选项，当前选中"全部"',
+      props: { modelValue: 'all', disabled: false, options: ['全部', '我创建的', '可编辑的'] },
+      mountConfig: { globalStubs: ['RouterLink'] },
+      assertions: [
+        { type: 'visible', target: '三个筛选按钮' },
+        { type: 'checked', target: '"全部"按钮' },
+      ],
+    },
+    {
+      id: 'SF-DISABLED',
+      name: '禁用状态',
+      description: '所有按钮 disabled，不响应点击',
+      props: { modelValue: 'all', disabled: true, options: ['全部', '我创建的', '可编辑的'] },
+      mountConfig: { globalStubs: ['RouterLink'] },
+      assertions: [
+        { type: 'disabled', target: '所有按钮' },
+        { type: 'no-emit', event: 'update:modelValue' },
+      ],
+    },
+  ],
+};
+```
+
+**场景 ID 命名规则**：`{组件缩写}-{场景描述}`（如 `SF-DEFAULT`）
+
+### Step 4: 生成组件测试脚本
+
+**生成路径**：`keve_test_spec/component/__test__/{ComponentName}.test.ts`
+
+```typescript
+// keve_test_spec/component/__test__/SearchFilter.test.ts
+
+import { describe, it, expect } from 'vitest';
+import { mount } from '@vue/test-utils';
+import SearchFilter from '@/components/SearchFilter.vue';
+import { SearchFilterModel } from '@/keve_test_spec/component/models/SearchFilter.model';
+
+function mountFromScenario(scenarioId: string, overrides: Record<string, unknown> = {}) {
+  const scenario = SearchFilterModel.scenarios.find(s => s.id === scenarioId)!;
+  return mount(SearchFilter, {
+    props: { ...scenario.props, ...overrides },
+    global: {
+      stubs: Object.fromEntries(scenario.mountConfig.globalStubs.map(n => [n, true])),
+    },
+  });
+}
+
+describe('SearchFilter', () => {
+  it('SF-DEFAULT: 默认状态', async () => {
+    const wrapper = mountFromScenario('SF-DEFAULT');
+    expect(wrapper.findAll('button')).toHaveLength(3);
+  });
+
+  it('SF-DISABLED: 禁用状态', async () => {
+    const wrapper = mountFromScenario('SF-DISABLED');
+    await wrapper.find('button').trigger('click');
+    expect(wrapper.emitted('update:modelValue')).toBeUndefined();
+  });
+});
+```
+
+### Step 5: Mock 策略
+
+| 场景 | Mock 方式 |
+|------|----------|
+| 子组件 | `global.stubs: { ChildComponent: true }` |
+| RouterLink | `global.stubs: { RouterLink: true }` |
+| Pinia Store | `global.plugins: [createTestingPinia()]` |
+| API 调用 | `vi.mock('@/api/xxx')` |
+
+**原则**：使用 `stubChildComponent`（通过 `global.stubs`）避免级联渲染，
+只在 model 的 `mountConfig.globalStubs` 中声明需要 stub 的组件名。
+
+### Step 6: 执行验证
+
+```bash
+npx vitest run keve_test_spec/component/__test__/SearchFilter.test.ts
+```
+
+- 如果通过 → 继续
+- 如果失败 → AI 分析错误，修复测试（≤3 轮）
+- 超过 3 轮仍失败 → 用 `it.todo` 标记
+
+### Step 7: 生成覆盖索引
+
+生成 `keve_test_spec/component/coverage.yaml`：
+
+```yaml
+generated_at: 2026-06-16T16:08:00
+total_components: 20
+tested_components: 12
+untested_components: 8
+
+components:
+  - source: src/components/SearchFilter.vue
+    model: component/models/SearchFilter.model.ts
+    test: component/__test__/SearchFilter.test.ts
+    scenarios_total: 2
+    scenarios_tested: 2
+    coverage: 100%
+    missing: []
+
+  - source: src/components/ToolManagement.vue
+    model: null
+    test: null
+    missing: [全部场景]
+```
+
+***
+
+## 产出
+
+| 产出 | 路径 |
+|------|------|
+| 组件行为模型 | `keve_test_spec/component/models/*.model.ts` |
+| 组件测试脚本 | `keve_test_spec/component/__test__/*.test.ts` |
+| 覆盖索引 | `keve_test_spec/component/coverage.yaml` |
+
+***
+
+## 硬性约束
+
+- **不打标**（不需要 `data-e2e-name`，D07）
+- **不生成 POM**（组件测试不需要页面操作模型，D07）
+- **不生成 .stories.ts**（延后，D14）
+- **model.ts 保持纯数据**（不依赖 Storybook，D14）
+- **test.ts 通过 model 的 scenarios 获取 mount 配置**
+- **model 和 test 放在 `keve_test_spec/component/`**（长期资产，D12）
+- **每轮修复后重新执行验证**
+- **失败用例用 `it.todo` 标记**
+
+***
+
+## Key Decisions
+
+| ID | 决策 | 说明 |
+|----|------|------|
+| CG01 | 先生成 model 再生成 test | model 是唯一数据源，test 引用 model |
+| CG02 | model.ts 保持纯数据 | 不依赖 Storybook，后续可按需扩展（D14） |
+| CG03 | 不打标、不 POM | jsdom 中直接 mount，不需要浏览器定位（D07） |
+| CG04 | 最多 3 轮修复 | 组件测试比单测复杂，允许更多轮次 |
+| CG05 | 覆盖索引从 model 生成 | 场景信息已含在 model 中，直接提取 |
+
+***
+
+## References
+
+- [component-model-template.md](references/component-model-template.md) — model.ts 结构和字段说明
+- [component-test-template.md](references/component-test-template.md) — .test.ts 生成模板
+- [component-mock-strategy.md](references/component-mock-strategy.md) — stub + vi.mock 策略
+- [vue-test-utils-guide.md](references/vue-test-utils-guide.md) — @vue/test-utils API 速查

package/doc/skills/keve-component-gen/references/component-mock-strategy.md

@@ -0,0 +1,74 @@
+# 组件测试 Mock 策略
+
+> AI 生成组件测试时的 stub/mock 指南
+
+---
+
+## 优先级
+
+| 优先级 | 方式 | 适用场景 |
+|--------|------|---------|
+| 1 | `global.stubs` | 子组件、RouterLink、RouterView |
+| 2 | `createTestingPinia` | Pinia Store |
+| 3 | `vi.mock` | API 调用、工具函数 |
+| 4 | 直接传 Props | 不需要 mock |
+
+---
+
+## 子组件 Stub
+
+```typescript
+// 方式1：通过 mountConfig.globalStubs（在 model 中声明）
+mount(Component, {
+  global: {
+    stubs: { RouterLink: true, ChildComponent: true },
+  },
+});
+
+// 方式2：stub 所有子组件（粗暴，不推荐）
+mount(Component, {
+  global: {
+    stubs: { stubChildComponent: true },
+  },
+});
+```
+
+**原则**：只 stub 有副作用的子组件（API 调用、路由跳转），不 stub 纯展示组件。
+
+---
+
+## Pinia Store Mock
+
+```typescript
+import { createTestingPinia } from '@pinia/testing';
+
+mount(Component, {
+  global: {
+    plugins: [createTestingPinia({ stubActions: false })],
+  },
+});
+```
+
+**原则**：默认 `stubActions: false`，保留 Store 逻辑；只在 Store 有 API 调用时 `stubActions: true`。
+
+---
+
+## API Mock
+
+```typescript
+vi.mock('@/api/agent', () => ({
+  getAgentList: vi.fn().mockResolvedValue({ list: [], total: 0 }),
+  getAgentDetail: vi.fn().mockResolvedValue({ id: 1, name: 'Test Agent' }),
+}));
+```
+
+---
+
+## 禁止做法
+
+| 禁止 | 原因 |
+|------|------|
+| Stub 被测组件本身 | 失去测试意义 |
+| Mock Vue 内置组件 | `Transition`、`Teleport` 不需要 mock |
+| `shallowMount` 替代 `mount` | 会跳过子组件渲染，断言不完整 |
+| 在 `global.stubs` 中 stub 所有 | 过度 stub 导致测试无意义 |

package/doc/skills/keve-component-gen/references/component-model-template.md

@@ -0,0 +1,98 @@
+# Component Model 模板
+
+> AI 生成 component model 时的参考
+
+---
+
+## 基本结构
+
+```typescript
+import ComponentName from '@/components/ComponentName.vue';
+
+export const ComponentNameModel = {
+  name: 'ComponentName',
+  source: 'src/components/ComponentName.vue',
+  component: ComponentName,
+
+  events: ['update:modelValue', 'confirm', 'cancel'],
+  slots: ['default', 'footer'],
+
+  scenarios: [
+    {
+      id: 'CN-DEFAULT',
+      name: '默认状态',
+      description: '组件在默认 Props 下的渲染',
+      props: { /* default prop values */ },
+      mountConfig: {
+        globalStubs: ['RouterLink'],
+      },
+      assertions: [
+        { type: 'visible', target: '组件根元素' },
+      ],
+    },
+  ],
+};
+```
+
+---
+
+## 场景设计规则
+
+### Props 变化场景
+
+每个有意义的 Props 变化 → 独立场景：
+
+| Props | 场景 ID | 场景名 |
+|-------|---------|--------|
+| 默认值 | `CN-DEFAULT` | 默认状态 |
+| disabled: true | `CN-DISABLED` | 禁用状态 |
+| loading: true | `CN-LOADING` | 加载中 |
+| empty: [] | `CN-EMPTY` | 空数据 |
+
+### 条件渲染场景
+
+每个 `v-if` → true/false 两个场景：
+
+| 条件 | 场景 ID | 场景名 |
+|------|---------|--------|
+| `v-if="detail"` 为 true | `CN-WITH-DETAIL` | 有详情 |
+| `v-if="detail"` 为 false | `CN-NO-DETAIL` | 无详情 |
+
+### 交互场景
+
+每个用户交互 → 独立场景：
+
+| 交互 | 场景 ID | 场景名 |
+|------|---------|--------|
+| 点击确认按钮 | `CN-CONFIRM` | 确认操作 |
+| 点击取消按钮 | `CN-CANCEL` | 取消操作 |
+| 输入文本 | `CN-INPUT` | 输入内容 |
+
+---
+
+## 场景 ID 命名规则
+
+格式：`{组件缩写}-{场景描述}`（大写英文 + 连字符）
+
+示例：
+- `SF-DEFAULT` — SearchFilter 默认
+- `SF-DISABLED` — SearchFilter 禁用
+- `SF-EMPTY` — SearchFilter 空选项
+- `SF-FILTER-MINE` — SearchFilter 切换到我创建的
+
+---
+
+## 断言类型速查
+
+| type | 用途 | 必填字段 |
+|------|------|---------|
+| `visible` | 元素可见 | target |
+| `hidden` | 元素隐藏 | target |
+| `disabled` | 元素禁用 | target |
+| `enabled` | 元素可用 | target |
+| `emitted` | 事件触发 | event |
+| `no-emit` | 事件未触发 | event |
+| `text` | 文本内容 | target, value |
+| `value` | 输入值 | target, value |
+| `class` | CSS 类 | target, value |
+| `attribute` | HTML 属性 | target, value |

package/doc/skills/keve-component-gen/references/component-test-template.md

@@ -0,0 +1,100 @@
+# 组件测试生成模板
+
+> AI 生成组件测试脚本时的参考
+
+---
+
+## 基本结构
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import { mount } from '@vue/test-utils';
+import ComponentName from '@/components/ComponentName.vue';
+import { ComponentNameModel } from '@/keve_test_spec/component/models/ComponentName.model';
+
+function mountFromScenario(scenarioId: string, overrides: Record<string, unknown> = {}) {
+  const scenario = ComponentNameModel.scenarios.find(s => s.id === scenarioId)!;
+  return mount(ComponentName, {
+    props: { ...scenario.props, ...overrides },
+    global: {
+      stubs: Object.fromEntries(
+        scenario.mountConfig.globalStubs.map(n => [n, true])
+      ),
+    },
+  });
+}
+
+describe('ComponentName', () => {
+  it('CN-DEFAULT: 默认状态', async () => {
+    const wrapper = mountFromScenario('CN-DEFAULT');
+    // 断言...
+  });
+});
+```
+
+---
+
+## 常见测试模式
+
+### 默认渲染
+
+```typescript
+it('CN-DEFAULT: 默认状态', async () => {
+  const wrapper = mountFromScenario('CN-DEFAULT');
+  expect(wrapper.find('.component-root').exists()).toBe(true);
+});
+```
+
+### Props 变更
+
+```typescript
+it('CN-DISABLED: 禁用状态', async () => {
+  const wrapper = mountFromScenario('CN-DISABLED');
+  expect(wrapper.find('button').attributes('disabled')).toBeDefined();
+});
+```
+
+### 事件触发
+
+```typescript
+it('CN-CONFIRM: 点击确认', async () => {
+  const wrapper = mountFromScenario('CN-DEFAULT');
+  await wrapper.find('[data-test="confirm-btn"]').trigger('click');
+  expect(wrapper.emitted('confirm')).toHaveLength(1);
+});
+```
+
+### 条件渲染
+
+```typescript
+it('CN-WITH-DETAIL: 有详情', async () => {
+  const wrapper = mountFromScenario('CN-WITH-DETAIL');
+  expect(wrapper.find('.detail-section').exists()).toBe(true);
+});
+
+it('CN-NO-DETAIL: 无详情', async () => {
+  const wrapper = mountFromScenario('CN-NO-DETAIL');
+  expect(wrapper.find('.detail-section').exists()).toBe(false);
+});
+```
+
+### Slots
+
+```typescript
+it('CN-SLOT-FOOTER: 底部插槽', async () => {
+  const wrapper = mount(ComponentName, {
+    props: ComponentNameModel.scenarios[0].props,
+    slots: { footer: '<div class="custom-footer">Footer</div>' },
+    global: { stubs: { RouterLink: true } },
+  });
+  expect(wrapper.find('.custom-footer').exists()).toBe(true);
+});
+```
+
+---
+
+## 失败用例处理
+
+```typescript
+it.todo('CN-LOADING: 加载中状态');
+```

package/doc/skills/keve-component-gen/references/vue-test-utils-guide.md

@@ -0,0 +1,91 @@
+# @vue/test-utils API 速查
+
+> AI 生成组件测试时的 API 参考
+
+---
+
+## mount / shallowMount
+
+```typescript
+import { mount } from '@vue/test-utils';
+
+const wrapper = mount(Component, {
+  props: { modelValue: 'test' },
+  attrs: { id: 'my-component' },
+  slots: { default: '<div>Slot content</div>' },
+  global: {
+    plugins: [router, pinia],
+    stubs: { RouterLink: true },
+    mocks: { $t: (key: string) => key },
+    provide: { theme: 'dark' },
+  },
+});
+```
+
+---
+
+## Wrapper 方法
+
+### 查询
+
+| 方法 | 说明 |
+|------|------|
+| `wrapper.find(selector)` | 查找单个元素 |
+| `wrapper.findAll(selector)` | 查找所有元素 |
+| `wrapper.findComponent(Component)` | 查找子组件 |
+| `wrapper.get(selector)` | 查找元素（不存在则抛错） |
+| `wrapper.vm` | 组件实例 |
+
+### 交互
+
+| 方法 | 说明 |
+|------|------|
+| `wrapper.trigger('click')` | 触发 DOM 事件 |
+| `wrapper.trigger('click', { button: 0 })` | 带参数的事件 |
+| `wrapper.setValue('new value')` | 设置表单值 |
+| `wrapper.setChecked(true)` | 设置 checkbox |
+| `wrapper.setSelected('option1')` | 设置 select |
+
+### 断言
+
+| 方法 | 说明 |
+|------|------|
+| `wrapper.exists()` | 元素是否存在 |
+| `wrapper.isVisible()` | 元素是否可见（v-show） |
+| `wrapper.text()` | 元素文本内容 |
+| `wrapper.html()` | 元素 HTML |
+| `wrapper.classes()` | 元素 CSS 类列表 |
+| `wrapper.attributes('href')` | 元素属性值 |
+| `wrapper.emitted()` | 所有触发的事件 |
+| `wrapper.emitted('update')` | 特定事件的参数列表 |
+
+### 状态操作
+
+| 方法 | 说明 |
+|------|------|
+| `wrapper.setProps({ key: value })` | 更新 Props |
+| `wrapper.setData({ key: value })` | 更新 data（Options API） |
+| `await wrapper.vm.$nextTick()` | 等待下次渲染 |
+
+---
+
+## 常见模式
+
+### 等待异步渲染
+
+```typescript
+await wrapper.setProps({ loading: false });
+await wrapper.vm.$nextTick();
+// 或
+await flushPromises();
+```
+
+### 测试 v-model
+
+```typescript
+const wrapper = mount(Component, {
+  props: { modelValue: 'initial', 'onUpdate:modelValue': (e: any) => wrapper.setProps({ modelValue: e }) },
+});
+await wrapper.find('input').setValue('new value');
+expect(wrapper.emitted('update:modelValue')).toHaveLength(1);
+```