Piercer 集成测试技能
此技能用于对 Piercer 服务进行端到端 (E2E) 黑盒测试，验证服务在真实环境中的完整功能。
⚠️ 前置条件
- •必须接入 VPN 网络 - API 仅在
10.8.0.1:8000可访问 - •服务必须已启动 - piercer 和 piercer-dns 服务需处于运行状态
测试流程
第一步：获取 API 规范
不要假设 API 结构，先动态获取 OpenAPI 文档：
bash
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 写入端点测试（增删改）
必须遵循以下模式：
code
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 应该是连续的，没有因测试而跳号
示例验证逻辑：
code
初始状态：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）
bash
nslookup {设备名}.{域名后缀} 10.8.0.1
第五步：生成测试报告
输出格式化的测试结果：
code
=== 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
注意事项
- •生产环境谨慎 - 此测试会实际创建/删除资源
- •使用测试前缀 - 所有测试数据必须有明显标识
- •必须清理 - 测试后务必验证清理完成
- •记录初始状态 - 便于异常时恢复
- •不要并行测试 - 避免资源竞争