forked from Gitlink/gitlink-cli
683 lines
15 KiB
Markdown
683 lines
15 KiB
Markdown
# gitlink-code-review Skill 测试指南
|
||
|
||
## 📋 测试概述
|
||
|
||
本文档提供完整的测试指南，帮助你验证 gitlink-code-review Skill 的功能完整性、AI Agent 集成和实际可用性。
|
||
|
||
## 🎯 测试目标
|
||
|
||
1. **功能验证**: 确保所有功能按预期工作
|
||
2. **AI 集成测试**: 验证 AI Agent 可以正确使用此 Skill
|
||
3. **文档验证**: 确保文档完整且易于理解
|
||
4. **实用验证**: 确保在实际场景中可用
|
||
|
||
## 🔧 前置条件
|
||
|
||
### 1. 环境准备
|
||
|
||
```bash
|
||
# 确认 gitlink-cli 已安装
|
||
gitlink-cli --version
|
||
|
||
# 确认已认证
|
||
gitlink-cli auth status
|
||
|
||
# 如果未认证，执行登录
|
||
gitlink-cli auth login
|
||
```
|
||
|
||
### 2. 准备测试 PR
|
||
|
||
需要一个测试用的 PR，可以是：
|
||
- 真实项目中的 PR
|
||
- 自己创建的测试 PR
|
||
- 公开项目的 PR
|
||
|
||
```bash
|
||
# 查看可用的 PR
|
||
gitlink-cli pr +list --owner <owner> --repo <repo> --format json
|
||
```
|
||
|
||
## 📊 测试计划
|
||
|
||
### 测试级别
|
||
|
||
| 级别 | 测试内容 | 优先级 |
|
||
|------|---------|--------|
|
||
| Level 1 | 文档结构验证 | P0 |
|
||
| Level 2 | 基础功能测试 | P0 |
|
||
| Level 3 | AI Agent 集成测试 | P0 |
|
||
| Level 4 | 完整工作流测试 | P1 |
|
||
| Level 5 | 边界情况测试 | P2 |
|
||
|
||
---
|
||
|
||
## 🧪 Level 1: 文档结构验证
|
||
|
||
### 测试 1.1: 检查必需文件存在
|
||
|
||
**目的**: 确保所有必需的文档文件都存在。
|
||
|
||
**步骤**:
|
||
```bash
|
||
cd skills/gitlink-code-review
|
||
|
||
# 检查必需文件
|
||
ls -la SKILL.md
|
||
ls -la README.md
|
||
ls -la REFERENCE.md
|
||
|
||
# 检查目录结构
|
||
ls -la references/
|
||
ls -la examples/
|
||
|
||
# 验证文件内容
|
||
wc -l SKILL.md
|
||
wc -l README.md
|
||
wc -l REFERENCE.md
|
||
```
|
||
|
||
**预期结果**:
|
||
- ✅ SKILL.md 存在且 >100 行
|
||
- ✅ README.md 存在且 >100 行
|
||
- ✅ REFERENCE.md 存在且 >200 行
|
||
- ✅ references/ 目录包含至少 3 个 .md 文件
|
||
- ✅ examples/ 目录包含至少 3 个 .md 文件
|
||
|
||
### 测试 1.2: 验证 Frontmatter 格式
|
||
|
||
**目的**: 确保 SKILL.md 的 frontmatter 符合规范。
|
||
|
||
**步骤**:
|
||
```bash
|
||
# 查看 SKILL.md 的前 20 行
|
||
head -20 SKILL.md
|
||
```
|
||
|
||
**预期结果**:
|
||
```yaml
|
||
---
|
||
name: gitlink-code-review
|
||
version: 1.0.0
|
||
description: "智能代码审查：..."
|
||
metadata:
|
||
requires:
|
||
bins: ["gitlink-cli"]
|
||
cliHelp: "gitlink-cli pr --help"
|
||
---
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 包含 `name` 字段
|
||
- ✅ 包含 `version` 字段
|
||
- ✅ 包含 `description` 字段
|
||
- ✅ 包含 `metadata` 字段
|
||
- ✅ `metadata.requires.bins` 包含 `gitlink-cli`
|
||
|
||
### 测试 1.3: 验证文档引用
|
||
|
||
**目的**: 确保文档之间的相互引用正确。
|
||
|
||
**步骤**:
|
||
```bash
|
||
# 检查 SKILL.md 中的引用
|
||
grep -n "\[.*\](.*.md)" SKILL.md
|
||
|
||
# 检查 README.md 中的引用
|
||
grep -n "\[.*\](.*.md)" README.md
|
||
|
||
# 验证引用的文件是否存在
|
||
# [手动检查引用的文件路径是否正确]
|
||
```
|
||
|
||
**预期结果**:
|
||
- ✅ 所有引用的文件都存在
|
||
- ✅ 引用路径正确
|
||
- ✅ 没有断开的链接
|
||
|
||
---
|
||
|
||
## 🧪 Level 2: 基础功能测试
|
||
|
||
### 测试 2.1: 验证 gitlink-cli PR 命令
|
||
|
||
**目的**: 确保依赖的 gitlink-cli 命令正常工作。
|
||
|
||
**步骤**:
|
||
```bash
|
||
# 设置测试变量
|
||
OWNER="Gitlink"
|
||
REPO="forgeplus"
|
||
PR_ID=<一个真实的PR编号>
|
||
|
||
# 测试 pr +view 命令
|
||
echo "=== 测试 pr +view ==="
|
||
gitlink-cli pr +view --id $PR_ID --format json > test_pr_view.json
|
||
cat test_pr_view.json | jq '.ok'
|
||
|
||
# 测试 pr +files 命令
|
||
echo "=== 测试 pr +files ==="
|
||
gitlink-cli pr +files --id $PR_ID --format json > test_pr_files.json
|
||
cat test_pr_files.json | jq '.ok'
|
||
|
||
# 测试 pr +diff 命令
|
||
echo "=== 测试 pr +diff ==="
|
||
gitlink-cli pr +diff --id $PR_ID --format json > test_pr_diff.json
|
||
cat test_pr_diff.json | jq '.ok'
|
||
```
|
||
|
||
**预期结果**:
|
||
- ✅ `pr +view` 返回 `{"ok": true}`
|
||
- ✅ `pr +files` 返回 `{"ok": true}`
|
||
- ✅ `pr +diff` 返回 `{"ok": true}`
|
||
- ✅ JSON 文件包含有效的数据
|
||
|
||
### 测试 2.2: 验证数据解析
|
||
|
||
**目的**: 确保能够正确解析 gitlink-cli 返回的数据。
|
||
|
||
**步骤**:
|
||
```bash
|
||
# 验证 PR 数据结构
|
||
echo "=== 验证 PR 详情 ==="
|
||
cat test_pr_view.json | jq '.data | keys'
|
||
# 应包含: id, title, author, status, etc.
|
||
|
||
echo "=== 验证文件列表 ==="
|
||
cat test_pr_files.json | jq '.data.files | length'
|
||
# 应该 > 0
|
||
|
||
echo "=== 验证 diff 内容 ==="
|
||
cat test_pr_diff.json | jq '.data.diff' | head -c 100
|
||
# 应该包含 diff 内容
|
||
```
|
||
|
||
**预期结果**:
|
||
- ✅ PR 详情包含必要的字段
|
||
- ✅ 文件列表非空
|
||
- ✅ diff 内容存在
|
||
|
||
### 测试 2.3: 手动代码审查模拟
|
||
|
||
**目的**: 手动执行一次完整的代码审查流程。
|
||
|
||
**步骤**:
|
||
```bash
|
||
# 1. 获取 PR 信息
|
||
echo "步骤 1: 获取 PR 信息"
|
||
gitlink-cli pr +view --id $PR_ID --format json | jq '{id: .data.id, title: .data.title, author: .data.author.login}'
|
||
|
||
# 2. 获取文件列表
|
||
echo "步骤 2: 获取文件列表"
|
||
gitlink-cli pr +files --id $PR_ID --format json | jq '.data.files[] | {filename: .filename, changes: .changes}'
|
||
|
||
# 3. 获取 diff
|
||
echo "步骤 3: 获取 diff"
|
||
gitlink-cli pr +diff --id $PR_ID --format json | jq -r '.data.diff' | head -50
|
||
|
||
# 4. 手动分析代码（需要人工查看）
|
||
echo "步骤 4: 手动分析代码"
|
||
echo "请查看上面的代码变更，识别潜在问题"
|
||
```
|
||
|
||
**预期结果**:
|
||
- ✅ 每个步骤都能成功执行
|
||
- ✅ 数据格式正确
|
||
- ✅ 可以看到代码变更内容
|
||
|
||
---
|
||
|
||
## 🧪 Level 3: AI Agent 集成测试
|
||
|
||
### 测试 3.1: Claude Code 基础测试
|
||
|
||
**目的**: 验证 Claude Code 可以识别和使用此 Skill。
|
||
|
||
**在 Claude Code 中执行**:
|
||
|
||
```
|
||
用户: 我需要审查一个 PR，PR 编号是 123
|
||
|
||
[预期行为]:
|
||
1. Claude Code 应该识别需要使用 gitlink-code-review Skill
|
||
2. 自动读取 SKILL.md 了解如何操作
|
||
3. 执行正确的命令序列
|
||
4. 生成审查报告
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ AI 识别到需要使用 gitlink-code-review Skill
|
||
- ✅ AI 执行了 `pr +view`, `pr +files`, `pr +diff` 命令
|
||
- ✅ AI 生成了结构化的审查报告
|
||
- ✅ 提供了可操作的建议
|
||
|
||
### 测试 3.2: Claude Code 场景测试
|
||
|
||
**场景 1: 基础审查**
|
||
|
||
```
|
||
用户: 审查 PR #123
|
||
|
||
[预期输出]:
|
||
- 获取 PR 信息
|
||
- 分析代码变更
|
||
- 生成审查报告
|
||
- 提供改进建议
|
||
```
|
||
|
||
**场景 2: 重点安全审查**
|
||
|
||
```
|
||
用户: 审查 PR #456，重点关注安全问题
|
||
|
||
[预期输出]:
|
||
- 获取 PR 信息
|
||
- 重点分析安全问题
|
||
- 列出发现的安全漏洞
|
||
- 提供修复建议
|
||
```
|
||
|
||
**场景 3: 自动添加评论**
|
||
|
||
```
|
||
用户: 审查 PR #789 并添加评论到 PR
|
||
|
||
[预期输出]:
|
||
- 获取 PR 信息
|
||
- 分析代码
|
||
- 生成报告
|
||
- 添加评论到 PR
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ AI 根据用户请求调整审查重点
|
||
- ✅ AI 正确执行相应的命令
|
||
- ✅ 输出格式符合预期
|
||
- ✅ 提供了有价值的建议
|
||
|
||
### 测试 3.3: 提示词测试
|
||
|
||
**目的**: 验证 Skill 中的提示词是否有效。
|
||
|
||
**测试提示词**:
|
||
```
|
||
请分析以下 PR 的代码变更，检查代码质量、安全性和性能问题。
|
||
|
||
PR 数据：
|
||
[粘贴 test_pr_view.json, test_pr_files.json, test_pr_diff.json 的内容]
|
||
|
||
请以 JSON 格式输出审查报告，包含：
|
||
- overall_assessment: 总体评估
|
||
- issues: 问题列表
|
||
- positive_notes: 优秀实践
|
||
- recommendations: 改进建议
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ AI 理解任务要求
|
||
- ✅ AI 分析代码变更
|
||
- ✅ 输出格式符合要求
|
||
- ✅ 发现了真实的问题
|
||
|
||
---
|
||
|
||
## 🧪 Level 4: 完整工作流测试
|
||
|
||
### 测试 4.1: 基础审查工作流
|
||
|
||
**目的**: 验证 `basic-review-workflow.md` 中的工作流。
|
||
|
||
**步骤**:
|
||
```bash
|
||
# 按照基础审查工作流执行
|
||
PR_ID=<测试PR编号>
|
||
|
||
# 步骤 1: 获取 PR 详情
|
||
gitlink-cli pr +view --id $PR_ID --format json
|
||
|
||
# 步骤 2: 获取变更文件列表
|
||
gitlink-cli pr +files --id $PR_ID --format json
|
||
|
||
# 步骤 3: 获取 diff 内容
|
||
gitlink-cli pr +diff --id $PR_ID --format json
|
||
|
||
# 步骤 4: 浏览代码变更
|
||
gitlink-cli pr +diff --id $PR_ID --format json | jq -r '.data.diff' | less
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 所有步骤都能成功执行
|
||
- ✅ 数据格式正确
|
||
- ✅ 可以看到代码变更
|
||
|
||
### 测试 4.2: 全面审查工作流
|
||
|
||
**目的**: 验证 `comprehensive-review-workflow.md` 中的工作流。
|
||
|
||
**步骤**:
|
||
```bash
|
||
# 按照全面审查工作流执行
|
||
PR_ID=<测试PR编号>
|
||
|
||
# 1. 获取数据
|
||
gitlink-cli pr +view --id $PR_ID --format json > pr_info.json
|
||
gitlink-cli pr +files --id $PR_ID --format json > pr_files.json
|
||
gitlink-cli pr +diff --id $PR_ID --format json > pr_diff.json
|
||
|
||
# 2. 数据预处理
|
||
cat pr_files.json | jq '.data.files | map(select(.changes > 10))' > main_changes.json
|
||
|
||
# 3. 组织分析数据
|
||
cat > analysis_input.json <<EOF
|
||
{
|
||
"pr_info": $(cat pr_info.json | jq '.data'),
|
||
"files": $(cat pr_files.json | jq '.data.files'),
|
||
"diff": $(cat pr_diff.json | jq -r '.data.diff')
|
||
}
|
||
EOF
|
||
|
||
# 4. 验证数据
|
||
cat analysis_input.json | jq '.pr_info.title'
|
||
cat analysis_input.json | jq '.files | length'
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 数据预处理成功
|
||
- ✅ 分析数据格式正确
|
||
- ✅ 包含所有必要的信息
|
||
|
||
### 测试 4.3: 自动审查工作流
|
||
|
||
**目的**: 验证 `auto-review-pr.md` 中的自动化流程。
|
||
|
||
**在 Claude Code 中测试**:
|
||
|
||
```
|
||
用户: 使用自动审查模式审查 PR #123
|
||
|
||
[预期行为]:
|
||
1. AI 自动获取所有必要数据
|
||
2. AI 自动分析代码
|
||
3. AI 自动生成报告
|
||
4. AI 询问是否添加评论
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 流程完全自动化
|
||
- ✅ 不需要人工干预
|
||
- ✅ 生成完整的报告
|
||
|
||
---
|
||
|
||
## 🧪 Level 5: 边界情况测试
|
||
|
||
### 测试 5.1: 大型 PR 测试
|
||
|
||
**目的**: 测试对大型 PR 的处理能力。
|
||
|
||
**步骤**:
|
||
```bash
|
||
# 查找一个大型 PR（>500 行变更）
|
||
gitlink-cli pr +list --format json | \
|
||
jq '.data[] | select(.additions > 500) | {id: .id, additions: .additions}'
|
||
|
||
# 测试获取 diff
|
||
gitlink-cli pr +diff --id <大型PR编号> --format json | \
|
||
jq '.data | length'
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 能够处理大型 diff
|
||
- ✅ 不会超时或崩溃
|
||
- ✅ 输出格式正确
|
||
|
||
### 测试 5.2: 错误处理测试
|
||
|
||
**目的**: 测试错误情况的处理。
|
||
|
||
**测试不存在的 PR**:
|
||
```bash
|
||
gitlink-cli pr +view --id 999999 --format json
|
||
# 应该返回错误信息
|
||
```
|
||
|
||
**测试无权限的 PR**:
|
||
```bash
|
||
gitlink-cli pr +view --id <私有PR编号> --format json
|
||
# 应该返回 403 错误
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 错误信息清晰
|
||
- ✅ 包含错误原因
|
||
- ✅ 提供解决建议
|
||
|
||
### 测试 5.3: 不同文件类型测试
|
||
|
||
**目的**: 测试对不同文件类型的处理。
|
||
|
||
**步骤**:
|
||
```bash
|
||
# 查找包含不同文件类型的 PR
|
||
# Go 文件
|
||
gitlink-cli pr +files --id $PR_ID --format json | \
|
||
jq '.data.files[] | select(.filename | endswith(".go"))'
|
||
|
||
# JavaScript 文件
|
||
gitlink-cli pr +files --id $PR_ID --format json | \
|
||
jq '.data.files[] | select(.filename | endswith(".js"))'
|
||
|
||
# Python 文件
|
||
gitlink-cli pr +files --id $PR_ID --format json | \
|
||
jq '.data.files[] | select(.filename | endswith(".py"))'
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 能够识别不同语言
|
||
- ✅ 能够针对性分析
|
||
- ✅ 建议符合语言特性
|
||
|
||
---
|
||
|
||
## 📊 测试报告模板
|
||
|
||
### 测试执行记录
|
||
|
||
```markdown
|
||
# gitlink-code-review Skill 测试报告
|
||
|
||
**测试日期**: 2026-06-12
|
||
**测试人员**: [姓名]
|
||
**测试环境**: [环境描述]
|
||
|
||
## 测试结果总览
|
||
|
||
| 测试级别 | 通过/总数 | 状态 |
|
||
|---------|----------|------|
|
||
| Level 1 | ?/? | ⏳ |
|
||
| Level 2 | ?/? | ⏳ |
|
||
| Level 3 | ?/? | ⏳ |
|
||
| Level 4 | ?/? | ⏳ |
|
||
| Level 5 | ?/? | ⏳ |
|
||
|
||
## 详细测试结果
|
||
|
||
### Level 1: 文档结构验证
|
||
|
||
- [ ] 测试 1.1: 检查必需文件存在 - ⏳
|
||
- [ ] 测试 1.2: 验证 Frontmatter 格式 - ⏳
|
||
- [ ] 测试 1.3: 验证文档引用 - ⏳
|
||
|
||
### Level 2: 基础功能测试
|
||
|
||
- [ ] 测试 2.1: 验证 gitlink-cli PR 命令 - ⏳
|
||
- [ ] 测试 2.2: 验证数据解析 - ⏳
|
||
- [ ] 测试 2.3: 手动代码审查模拟 - ⏳
|
||
|
||
### Level 3: AI Agent 集成测试
|
||
|
||
- [ ] 测试 3.1: Claude Code 基础测试 - ⏳
|
||
- [ ] 测试 3.2: Claude Code 场景测试 - ⏳
|
||
- [ ] 测试 3.3: 提示词测试 - ⏳
|
||
|
||
### Level 4: 完整工作流测试
|
||
|
||
- [ ] 测试 4.1: 基础审查工作流 - ⏳
|
||
- [ ] 测试 4.2: 全面审查工作流 - ⏳
|
||
- [ ] 测试 4.3: 自动审查工作流 - ⏳
|
||
|
||
### Level 5: 边界情况测试
|
||
|
||
- [ ] 测试 5.1: 大型 PR 测试 - ⏳
|
||
- [ ] 测试 5.2: 错误处理测试 - ⏳
|
||
- [ ] 测试 5.3: 不同文件类型测试 - ⏳
|
||
|
||
## 发现的问题
|
||
|
||
### 问题 1
|
||
- **描述**: [问题描述]
|
||
- **严重性**: [高/中/低]
|
||
- **状态**: [待修复/已修复]
|
||
|
||
## 建议和改进
|
||
|
||
### 建议 1
|
||
- **描述**: [建议描述]
|
||
- **优先级**: [高/中/低]
|
||
|
||
## 总结
|
||
|
||
**总体评估**: [通过/不通过]
|
||
**评分**: [?/100]
|
||
**建议**: [是否建议投入使用]
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 快速测试脚本
|
||
|
||
为了快速验证 Skill 的基本功能，可以使用以下脚本：
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# quick-test.sh - 快速测试脚本
|
||
|
||
set -e
|
||
|
||
echo "=== gitlink-code-review Skill 快速测试 ==="
|
||
|
||
# 配置
|
||
PR_ID=${1:-<默认PR编号>}
|
||
OWNER=${2:-Gitlink}
|
||
REPO=${3:-forgeplus}
|
||
|
||
echo "测试 PR: $PR_ID"
|
||
echo ""
|
||
|
||
# Level 1: 文档检查
|
||
echo "Level 1: 检查文档..."
|
||
if [ -f "SKILL.md" ] && [ -f "README.md" ] && [ -f "REFERENCE.md" ]; then
|
||
echo "✅ 文档文件存在"
|
||
else
|
||
echo "❌ 缺少必需文档"
|
||
exit 1
|
||
fi
|
||
|
||
# Level 2: 功能测试
|
||
echo ""
|
||
echo "Level 2: 测试 gitlink-cli 命令..."
|
||
|
||
# 测试 pr +view
|
||
if gitlink-cli pr +view --id $PR_ID --format json | jq -e '.ok == true' > /dev/null; then
|
||
echo "✅ pr +view 正常"
|
||
else
|
||
echo "❌ pr +view 失败"
|
||
exit 1
|
||
fi
|
||
|
||
# 测试 pr +files
|
||
if gitlink-cli pr +files --id $PR_ID --format json | jq -e '.ok == true' > /dev/null; then
|
||
echo "✅ pr +files 正常"
|
||
else
|
||
echo "❌ pr +files 失败"
|
||
exit 1
|
||
fi
|
||
|
||
# 测试 pr +diff
|
||
if gitlink-cli pr +diff --id $PR_ID --format json | jq -e '.ok == true' > /dev/null; then
|
||
echo "✅ pr +diff 正常"
|
||
else
|
||
echo "❌ pr +diff 失败"
|
||
exit 1
|
||
fi
|
||
|
||
echo ""
|
||
echo "=== 快速测试完成 ==="
|
||
echo "✅ 所有基础测试通过"
|
||
echo ""
|
||
echo "下一步："
|
||
echo "1. 在 Claude Code 中测试 AI 集成"
|
||
echo "2. 执行完整工作流测试"
|
||
echo "3. 验证边界情况"
|
||
```
|
||
|
||
**使用方法**:
|
||
```bash
|
||
chmod +x quick-test.sh
|
||
./quick-test.sh <PR编号>
|
||
```
|
||
|
||
---
|
||
|
||
## 📞 获取帮助
|
||
|
||
如果测试过程中遇到问题：
|
||
|
||
1. **查看文档**
|
||
- [SKILL.md](SKILL.md) - 技能总览
|
||
- [README.md](README.md) - 使用说明
|
||
- [REFERENCE.md](REFERENCE.md) - API 参考
|
||
|
||
2. **检查配置**
|
||
```bash
|
||
# 检查 gitlink-cli 版本
|
||
gitlink-cli --version
|
||
|
||
# 检查认证状态
|
||
gitlink-cli auth status
|
||
```
|
||
|
||
3. **查看错误日志**
|
||
```bash
|
||
# 启用调试模式
|
||
gitlink-cli pr +view --id $PR_ID --format json --debug
|
||
```
|
||
|
||
---
|
||
|
||
## 🎓 测试最佳实践
|
||
|
||
### 1. 渐进式测试
|
||
|
||
- 从 Level 1 开始，逐步升级
|
||
- 每个级别通过后再进行下一级
|
||
- 记录每个测试的结果
|
||
|
||
### 2. 真实场景测试
|
||
|
||
- 使用真实的 PR 进行测试
|
||
- 覆盖不同类型的 PR（功能、修复、重构）
|
||
- 测试不同大小的 PR
|
||
|
||
### 3. 持续改进
|
||
|
||
- 记录发现的问题
|
||
- 及时修复和改进
|
||
- 定期重新测试
|
||
|
||
---
|
||
|
||
**测试完成后，请填写测试报告并评估 Skill 是否可以投入使用。**
|
||
|
||
*最后更新: 2026-06-12*
|