# AI管网预警系统的QA测试服务

**Repository Path**: ccq/water_project_tests_e2e

## Basic Information

- **Project Name**: AI管网预警系统的QA测试服务
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tests-e2e — 黑盒业务流测试工具

## 这是什么

一个**独立的 pytest 测试项目**，通过 HTTP API 黑盒驱动 `water_project` 全链路。**不依赖被测代码内部**——你不需要理解 LLM prompt、启发式融合、抑制门控的实现细节，只需关心"给定输入，是否产出预期的业务输出"。

## 🚀 5 分钟快速开始（远程 ECS）

```bash
# 1. 安装
pip install -e tests-e2e/ -i https://pypi.tuna.tsinghua.edu.cn/simple

# 2. 建立 SSH 隧道到远程 ECS
./scripts/tunnel.sh start

# 3. 设置环境变量
export API_BASE_URL=http://localhost:18000
export MONITOR_BASE_URL=http://localhost:18001
export SCADA_BASE_URL=http://localhost:18001
export API_TOKEN=wjj_secure_token_2026

# 4. 跑测试
cd tests-e2e && pytest -v

# 期望: 125 passed, 1 skipped in ~4min
# (1 skipped 是 LLM 不可达时的正常路径测试，可安全跳过)
```

详细文档：[`docs/handbook.md`](docs/handbook.md)（30 分钟完整指南）

## 为什么需要

`water_project` 当前有 **R23（🔴 高优）**：单元测试覆盖率 < 5%（17,600 行生产代码 vs 321 行测试）。

这意味着：
- 新代码改动是否破坏业务？**没人能快速回答**
- 模型上线后是否仍能识别真实异常？**靠人工**
- 鉴权、限流等横切关注点是否生效？**无验证手段**

本工具让任何贡献者用**一行命令**验证核心业务路径。

## 与 Apifox 的关系

| 工具 | 角色 | 谁维护 |
|---|---|---|
| **Apifox**（已有，免费版） | 接口文档 + Mock + 手动场景测试 + 业务方可视化 | QA + 业务方 |
| **tests-e2e/**（本工具） | 自动化 CI + 数据库断言 + 复杂业务逻辑 | 开发 |

**不是替代，是协同**。Apifox 跑不到的部分（如数据库状态、复杂业务编排），由 pytest 补强。

## 怎么用

### 1. 安装（一次性）

```bash
cd water_project/
pip install -e tests-e2e/ -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 2. 启动测试环境

```bash
docker compose -f tests-e2e/docker-compose-test.yml up -d
# 等待 30-60 秒（自动健康轮询）
```

### 3. 运行测试

```bash
# 冒烟（5 个场景，< 1 分钟）
pytest tests-e2e/ -m smoke

# 业务（4 个 P0 场景已完成 + P1 待扩展，5-10 分钟）
pytest tests-e2e/ -m business

# 元测试（工具自身，< 10 秒）
pytest tests-e2e/ -m meta

# 全量回归（~4 分钟）
pytest tests-e2e/

# 并行加速
pytest tests-e2e/ -n auto

# 指定某个场景
pytest tests-e2e/scenarios/business/test_010_wushan_burst.py -v
```

### 4. 查看报告

```bash
open tests-e2e/reports/report.html  # macOS
xdg-open tests-e2e/reports/report.html  # Linux
```

## 怎么贡献

### 添加一个新的冒烟场景

1. 在 `tests-e2e/scenarios/smoke/` 创建 `test_XXX_xxx.py`
2. 复制 `test_001_health.py` 作为模板
3. 用 `utils/` 下的工具构造数据、发起请求、断言
4. 标记 `@pytest.mark.smoke`

### 添加一个新的业务场景

1. 在 `tests-e2e/scenarios/business/` 创建 `test_XXX_xxx.py`
2. 参考已有业务场景（如 `test_010_wushan_burst.py`）
3. 优先复用 `utils/assertions.py` 中的业务级断言
4. 标记 `@pytest.mark.business` 和 `@pytest.mark.slow`（如果 > 1 分钟）

### 编写业务级断言

如 `utils/assertions.py` 中的断言不够用，在 `utils/assertions.py` 添加新函数：

```python
async def assert_your_business_logic(...):
    """
    断言 XXX 业务逻辑

    业务含义: ...
    期望: ...
    """
    # 实现
```

## 怎么维护

### 每周（< 1h）
- 查看 nightly 报告：Gitee Go → Pipeline → 失败排查
- 修复因被测项目变更导致的测试失败（API 改动、字段调整等）

### 每月（< 2h）
- 与 Apifox 项目同步接口定义
- 新增业务场景（仅当业务规则变化时）
- 更新业务级断言库

### 每季度（< 4h）
- 与被测项目 Owner 评审：测试覆盖是否充分？新增风险？
- 评估是否引入新工具（如性能基线）

## 关键约束（不可违反）

1. ❌ **禁止** `import api.ingest_api.services.xxx` —— 工具必须保持黑盒
2. ❌ **禁止** 直接修改 `water_project/` 下被测代码（必须独立 PR）
3. ❌ **禁止** 提交 `.env`、`reports/*.html` 等敏感/临时文件
4. ✅ **必须** 使用 `utils/assertions.py` 中的断言函数（业务级，非 HTTP 状态码）
5. ✅ **必须** 在测试方法 docstring 写明"业务含义、期望、失败排查指引"

## 故障排查

| 症状 | 可能原因 | 排查命令 |
|---|---|---|
| smoke 全部失败 | 测试环境未启动 | `docker compose -f tests-e2e/docker-compose-test.yml ps` |
| 401 Unauthorized | Token 不匹配 | `echo $API_TOKEN` 检查是否与 .env 一致 |
| 数据库查询失败 | test DB 未就绪 | `psql -h localhost -p 5433 -U test -d water_test` |
| 业务场景超时 | 时序参数未调（默认 330s 等待） | 加 `@pytest.mark.timeout(60)` 或缩短 `FUSION_SETTLE_SECONDS` |
| Apifox Mock 不生效 | Mock 服务未启动 | 检查 Apifox 项目设置 |

## 项目结构

```
tests-e2e/
├── pyproject.toml              # 项目配置 + 依赖
├── pytest.ini                  # pytest 配置
├── conftest.py                 # 全局 fixtures
├── docker-compose-test.yml     # 独立测试环境
├── README.md                   # 本文件
├── utils/                      # 工具层
│   ├── http_client.py          # httpx 封装
│   ├── data_factory.py         # 测试数据生成
│   ├── db_inspector.py         # 数据库只读查询
│   ├── assertions.py           # 业务级断言
│   └── toxiproxy_helper.py     # 故障注入
├── scenarios/                  # 测试场景
│   ├── smoke/                  # 冒烟（< 1 min）
│   └── business/               # 业务（5-10 min）
├── tests/                      # 元测试（工具自身）
│   └── meta/
├── fixtures/                   # 测试样本数据
└── reports/                    # 输出报告
```

## 进阶阅读

- 📄 `docs/opportunity_blackbox_testkit_v3.md` — 完整机会文档（决策记录）
- 📄 `docs/onboarding_for_newcomers.md` — water_project 业务理解
- 📄 `docs/stage1-4_*.md` — water_project 调研报告
- 🔗 Apifox 项目空间（团队账号内）— 手动场景测试

## 标记说明

| 标记 | 含义 | 何时跑 |
|---|---|---|
| `smoke` | 核心冒烟 | PR 必跑（< 1 min） |
| `business` | 业务场景 | nightly 跑（5-10 min） |
| `slow` | 长时序 | 单独调度 |
| `flaky` | 已知不稳定 | 待修复 |
| `contract` | 契约测试 | API 变更时 |
| `meta` | 工具自身测试 | 工具修改时 |

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---|---|
| `API_BASE_URL` | `http://localhost:8000` | ingest_api 地址 |
| `MONITOR_BASE_URL` | `http://localhost:8001` | monitor_api 地址 |
| `SCADA_BASE_URL` | `http://localhost:8001` | SCADA webhook 地址 |
| `API_TOKEN` | 自动探测 | API 鉴权 token |