qt-unittest-make

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Qt Unit Test Generator

Overview

Core principle: 使用 LSP 精确分析类结构，生成 100% 函数覆盖率的测试用例，并强制验证构建成功。

架构模式: Skill 路由 + 子 Agent 全栈执行。子 Agent 负责所有具体工作，Skill 仅负责调用和结果反馈。

关键特性: 智能 CMake 合并、增量更新支持、严格的构建验证、详细的错误处理。

Core principle: Precisely analyze class structures using LSP, generate test cases with 100% function coverage, and enforce build success verification.

Architecture Pattern: Skill routing + full-stack execution by sub-agents. Sub-agents handle all specific tasks, while the Skill only takes charge of invocation and result feedback.

Key Features: Smart CMake merging, incremental update support, strict build verification, detailed error handling.

Iron Laws

仅使用 Google Test: 测试框架固定为 GTest，不支持 Qt Test
100% 函数覆盖率: 每个 public/protected 函数必须至少一个测试用例
智能 CMake 合并: 根据项目实际情况优化合并，确保通用性
支持增量更新: 对比现有测试，补全未覆盖函数
必须验证构建: 生成后必须编译成功才能报告完成
编译失败必须修正: 每个错误最多重试 3 次，最大循环 10 次

Google Test Only: The testing framework is fixed to GTest, Qt Test is not supported
100% Function Coverage: Each public/protected function must have at least one test case
Smart CMake Merging: Optimize merging based on actual project conditions to ensure universality
Incremental Update Support: Compare with existing tests to complete uncovered functions
Mandatory Build Verification: Must compile successfully before reporting completion
Fix Compilation Failures: Retry each error up to 3 times, with a maximum of 10 cycles

When to Use

触发条件:

用户请求为模块生成单元测试：
```
为 src/lib/ui 模块创建单元测试
```
用户请求为类生成测试：
```
为 MyClass 生成测试
```
用户请求补全测试：
```
为 MyClass 补全测试
```

不使用此技能时:

用户请求生成测试框架（使用
```
qt-unittest-build
```
）
用户请求修复测试失败（使用
```
systematic-debugging
```
）
用户请求分析测试覆盖率（使用其他工具）

Trigger Conditions:

User requests to generate unit tests for a module:
```
Create unit tests for the src/lib/ui module
```
User requests to generate tests for a class:
```
Generate tests for MyClass
```
User requests to complete tests:
```
Complete tests for MyClass
```

When Not to Use This Skill:

User requests to generate a testing framework (use
```
qt-unittest-build
```
)
User requests to fix test failures (use
```
systematic-debugging
```
)
User requests to analyze test coverage (use other tools)

执行流程

Execution Flow

步骤 1: 检查测试框架

Step 1: Check Testing Framework

验证

autotests/CMakeLists.txt

和

autotests/3rdparty/stub/

存在。如不存在，提示用户先运行

qt-unittest-build

。

Verify that

autotests/CMakeLists.txt

and

autotests/3rdparty/stub/

exist. If not, prompt the user to run

qt-unittest-build

first.

步骤 2: 分析类结构

Step 2: Analyze Class Structure

模块批量生成: glob 扫描目录所有

.h/.hpp

，提取类名。

单个类: 直接分析指定类。

使用 LSP 工具：

```
lsp_document_symbols
```
- 提取类结构
```
lsp_goto_definition
```
- 读取函数实现
```
lsp_find_references
```
- 查找依赖

Batch Generation for Modules: Use glob to scan all

.h/.hpp

files in the directory and extract class names.

Single Class: Directly analyze the specified class.

Use LSP tools:

```
lsp_document_symbols
```
- Extract class structures
```
lsp_goto_definition
```
- Read function implementations
```
lsp_find_references
```
- Find dependencies

步骤 3: 调用子 Agent（MUST DO）

Step 3: Invoke Sub-Agent (MUST DO)

重要: 必须调用子 Agent，不能跳过！

子 Agent 位置:

agent/unittest-generator.md

调用方式:

使用

task

工具调用子 Agent：

task(
    description="生成单元测试代码",
    prompt="完整的任务说明，包括：
- 目标模块或类
- 测试框架要求（Google Test）
- 函数覆盖率要求（100%）
- 验证构建要求",
    subagent_type="general"
)

为什么需要子 Agent:

独立上下文: 为单个类或小模块生成测试时，独立上下文避免污染
并行执行: 为多个类批量生成测试时，可以 fork 多个子 Agent 并行执行，提高效率
任务隔离: 子 Agent 失败不影响主 Agent，便于错误处理

调用时机:

模块批量生成: 为每个类调用一个子 Agent（并行）
单个类生成: 调用一个子 Agent
增量更新: 调用子 Agent 分析差异

Important: Must invoke the sub-agent, cannot skip this step!

Sub-Agent Location:

agent/unittest-generator.md

Invocation Method:

Use the

task

tool to invoke the sub-agent:

task(
    description="Generate unit test code",
    prompt="Complete task description including:
- Target module or class
- Testing framework requirement (Google Test)
- Function coverage requirement (100%)
- Build verification requirement",
    subagent_type="general"
)

Why Sub-Agents Are Needed:

Independent Context: Avoids context pollution when generating tests for a single class or small module
Parallel Execution: Fork multiple sub-agents to execute in parallel when generating tests for multiple classes in batches, improving efficiency
Task Isolation: Sub-agent failures do not affect the main agent, facilitating error handling

Invocation Timing:

Batch Module Generation: Invoke one sub-agent per class (parallel execution)
Single Class Generation: Invoke one sub-agent
Incremental Update: Invoke sub-agent to analyze differences

步骤 4: 等待子 Agent 完成

Step 4: Wait for Sub-Agent Completion

监听子 Agent 的执行结果：

收集生成的测试文件
检查验证构建结果
记录遇到的错误（如果有）

Monitor the sub-agent's execution results:

Collect generated test files
Check build verification results
Record any errors encountered

步骤 5: 反馈用户

Step 5: Provide Feedback to User

根据子 Agent 的结果反馈用户：

如果成功：报告生成的测试文件和覆盖率
如果失败：报告详细的错误信息和修正建议

Provide feedback to the user based on the sub-agent's results:

If successful: Report generated test files and coverage
If failed: Report detailed error information and correction suggestions

Red Flags

❌ 使用 Qt Test 框架
❌ 覆盖率不足 100%
❌ 硬编码 CMake 模板
❌ 不验证构建
❌ 不支持增量更新
❌ 编译失败仍报告完成
❌ 跳过子 Agent 调用（直接手动工作）

❌ Use Qt Test framework
❌ Coverage less than 100%
❌ Hard-coded CMake templates
❌ No build verification
❌ No incremental update support
❌ Report completion even if compilation fails
❌ Skip sub-agent invocation (manual work directly)

Quick Reference

测试文件命名:

test_myclass.cpp

测试类命名:

MyClassTest

测试用例命名:

{Feature}_{Scenario}_{ExpectedResult}

LSP 工具:

lsp_document_symbols

lsp_goto_definition

lsp_find_references

Stub 模式:

&Class::method

VADDR(Class, method)

static_cast<...>

编译重试逻辑: 每个错误最多重试 3 次，最大循环 10 次

Test File Naming:

test_myclass.cpp

Test Class Naming:

MyClassTest

Test Case Naming:

{Feature}_{Scenario}_{ExpectedResult}

LSP Tools:

lsp_document_symbols

lsp_goto_definition

lsp_find_references

Stub Patterns:

&Class::method

VADDR(Class, method)

static_cast<...>

Compilation Retry Logic: Retry each error up to 3 times, with a maximum of 10 cycles

子 Agent 调用

Sub-Agent Invocation

必须使用 task 工具调用子 Agent:

task(
    description="生成单元测试代码",
    prompt="完整任务描述，包括目标、要求、验证流程",
    subagent_type="general"
)

子 Agent 执行内容:

分析项目结构（LSP）
生成测试文件（100% 覆盖率）
智能合并 CMake
验证构建（每个错误重试 3 次，最大循环 10 次）

为什么需要子 Agent:

独立上下文，防止污染
并行执行，提高效率
任务隔离，便于错误处理

Must Use the
task
Tool to Invoke Sub-Agents:

task(
    description="Generate unit test code",
    prompt="Complete task description including target, requirements, and verification process",
    subagent_type="general"
)

Sub-Agent Execution Content:

Analyze project structure (LSP)
Generate test files (100% coverage)
Smart CMake merging
Verify build (retry each error up to 3 times, maximum 10 cycles)

Why Sub-Agents Are Needed:

Independent context to prevent pollution
Parallel execution to improve efficiency
Task isolation to facilitate error handling

常见错误

Common Errors

错误	原因	修复
测试框架不存在	未运行 qt-unittest-build	提示用户先运行框架构建技能
覆盖率不足	未分析所有函数	确保 lsp_document_symbols 提取完整
CMake 合并失败	硬编码模板	使用 AI 智能合并，根据项目实际情况优化
编译失败	Stub 签名错误	使用 LSP 获取精确签名
编译失败仍报告完成	跳过验证或验证不严谨	必须编译成功才能报告用户
多个错误未修正	全局重试 3 次不足	每个错误重试 3 次，最大循环 10 次

Error	Cause	Fix
Testing framework not found	`qt-unittest-build` not run	Prompt user to run the framework build skill first
Insufficient coverage	All functions not analyzed	Ensure `lsp_document_symbols` extracts complete information
CMake merging failed	Hard-coded templates	Use AI for smart merging, optimize based on actual project conditions
Compilation failed	Incorrect stub signature	Use LSP to obtain precise signatures
Report completion despite compilation failure	Verification skipped or not rigorous	Must only report to user after successful compilation
Multiple errors not fixed	Global 3 retries insufficient	Retry each error up to 3 times, not 3 global retries

Rationalization Table

Excuse	Reality
"直接手动工作更快"	手动工作无法保证 100% 覆盖率和构建验证，子 Agent 是强制要求
"跳过子 Agent 调用"	违反技能的铁律，必须调用子 Agent
"编译失败也可以报告完成"	违反强制构建验证要求，必须编译成功才能报告
"全局重试 3 次就够了"	每个错误重试 3 次，不是全局 3 次
"覆盖率 80% 就可以了"	铁律要求 100% 函数覆盖率，无例外
"Qt Test 也一样"	技能固定使用 Google Test，不支持 Qt Test

Excuse	Reality
"Manual work is faster directly"	Manual work cannot guarantee 100% coverage and build verification; sub-agents are mandatory
"Skip sub-agent invocation"	Violates the skill's iron laws; sub-agent invocation is mandatory
"Can report completion even if compilation fails"	Violates mandatory build verification requirements; must only report after successful compilation
"3 global retries are enough"	Retry each error up to 3 times, not 3 global retries
"80% coverage is sufficient"	Iron law requires 100% function coverage, no exceptions
"Qt Test is the same"	The skill is fixed to use Google Test; Qt Test is not supported