SKILL.md
Piercer 集成测试技能
此技能用于对 Piercer 服务进行端到端 (E2E) 黑盒测试，验证服务在真实环境中的完整功能。
⚠️ 前置条件
- 必须接入 VPN 网络 - API 仅在
10.8.0.1:8000可访问 - 服务必须已启动 - piercer 和 piercer-dns 服务需处于运行状态
测试流程
第一步：获取 API 规范
不要假设 API 结构，先动态获取 OpenAPI 文档：
curl -s http://10.8.0.1:8000/openapi.json从返回的 JSON 中提取：
paths- 所有可用的 API 端点- 每个端点的 HTTP 方法、参数、响应格式
第二步：分类测试端点
根据 OpenAPI 规范，将端点分为三类：
| 类型 | 特征 | 测试策略 |
|---|---|---|
| 只读端点 | GET 方法，无副作用 | 直接调用，验证响应格式 |
| 写入端点 | POST/PUT/DELETE，有副作用 | 需要创建→验证→清理的完整流程 |
| 外部依赖 | 依赖 WireGuard、文件系统等 | 验证集成是否正常 |
第三步：执行测试
3.1 只读端点测试
对所有 GET 端点：
- 调用端点
- 验证 HTTP 状态码为 200
- 验证响应包含预期字段（根据 OpenAPI schema）
- 记录关键数据（如当前资源数量）用于后续清理验证
3.2 写入端点测试（增删改）
必须遵循以下模式：
1. 记录初始状态（调用对应的 list 接口）
2. 执行写入操作（使用明显的测试数据，如 name 包含 "test-" 前缀）
3. 验证操作成功（检查响应）
4. 验证状态变更（再次调用 list 接口确认）
5. 执行清理操作（删除测试数据）
6. 验证清理完成（确认恢复到初始状态）测试数据命名规范：
- 名称：
test-{timestamp}或test-{random} - IP：使用高位地址如
10.8.0.200+，避免与真实设备冲突
3.3 清理验证（关键！）
测试完成后必须验证：
- 资源数量恢复：测试前后的 list 接口返回数量一致
- 无测试残留：list 中不应包含
test-前缀的资源 - ID/IP 分配正常：下一个分配的 ID/IP 应该是连续的，没有因测试而跳号
示例验证逻辑：
初始状态：count=2, next_ip=10.8.0.4
添加测试设备：count=3, next_ip=10.8.0.5 (或 10.8.0.201 如果用高位)
删除测试设备：count=2, next_ip=10.8.0.4 ← 必须恢复！第四步：DNS 测试（如适用）
如果服务包含 DNS 功能：
- 从 API 获取已注册设备列表
- 对每个设备名构造 DNS 查询
- 验证解析结果与 API 返回的 IP 一致
- 测试保留名称（如
server、gateway）
nslookup {设备名}.{域名后缀} 10.8.0.1第五步：生成测试报告
输出格式化的测试结果：
=== Piercer 集成测试报告 ===
测试时间: {timestamp}
API 基址: http://10.8.0.1:8000
【只读端点】
✅ GET / - 200 OK
✅ GET /health - 200 OK
✅ GET /api/wg/peer/list - 200 OK (2 peers)
...
【写入端点】
✅ POST /api/wg/peer/add - 创建成功
✅ POST /api/wg/peer/del - 删除成功
✅ 清理验证 - 无残留
【DNS 服务】
✅ server.xxx.xxx → 10.8.0.1
✅ device1.xxx.xxx → 10.8.0.2
...
【总结】
通过: X/Y
失败: Z/Y
清理状态: ✅ 干净故障排查
测试数据未清理干净
如果发现测试残留：
- 调用 list 接口找出
test-前缀的资源 - 逐个调用 delete 接口清理
- 验证 next_ip 是否恢复正常（可能需要手动调整）
API 不可达
- 确认 VPN 连接：
ping 10.8.0.1 - 确认服务状态：
ssh server "sudo systemctl status piercer" - 检查防火墙规则
DNS 解析失败
- 确认 DNS 服务状态：
ssh server "sudo systemctl status piercer-dns" - 检查 DNS 端口：
nslookup -port=53 server.xxx 10.8.0.1
注意事项
- 生产环境谨慎 - 此测试会实际创建/删除资源
- 使用测试前缀 - 所有测试数据必须有明显标识
- 必须清理 - 测试后务必验证清理完成
- 记录初始状态 - 便于异常时恢复
- 不要并行测试 - 避免资源竞争