# 软件测试

**Repository Path**: oooczk/software-testing

## Basic Information

- **Project Name**: 软件测试
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hotspot_agent 单元测试工程

基于 **pytest** 的独立单元测试工程。被测对象为外部仓库
`gitee.com/oooczk/opc-project` 中的 **`hotspot_agent`** 包(热点挖掘智能体后端:
内容归一化、去重、聚类、热度评分、LLM 生成摘要、结果入库/推送等)。

> 本仓库**只存放测试代码与测试工程配置**,不包含被测项目的任何源码;
> 被测源码由两位成员**各自本地 clone**(见「被测代码怎么来」),对被测仓库零写入、零修改。

## 目录结构

```
software-testing/
├── .gitignore              # 忽略规则:Python 缓存 / 测试缓存 / IDE / 密钥 / 日志 / sut/
├── .gitattributes          # 行尾统一:文本 LF,.bat CRLF
├── pytest.ini              # pytest 配置:testpaths / asyncio_mode=auto
├── conftest.py             # ★共享文件:自动发现被测仓库并注入 sys.path + 公共 fixture
├── requirements-dev.txt    # 测试工具依赖说明(默认无需安装,见下文)
├── run_tests.bat           # Windows 一键运行入口
├── README.md / README.en.md
├── sut/                    # ★预留目录:被测仓库的本地检出(.gitignore 已排除,不会入库)
│   ├── hotspot_agent/      #   被测包(import 目标)
│   └── .venv/              #   成员各自在本检出内创建的环境
├── tests/
│   └── test_*.py           # 主线用例文件,按被测模块划分,见「双人分工」
└── ai_tests/               # ★AI 生成测试代码对照目录,见「ai_tests:AI 生成测试代码对照」
    ├── __init__.py         #   包标记:避免与 tests/ 下同名文件冲突
    └── test_*.py           #   A 线测试代码的 AI 生成版本(60 条)
```

## 被测代码怎么来

被测仓库根目录由 `conftest.py` **自动发现**,顺序(取第一个存在的):

1. **环境变量 `HOTSPOT_AGENT_ROOT`** —— 显式指定时优先;指向的目录不存在会直接报错;
2. **本仓库预留目录 `sut/`** ——只需 clone 一次,之后零配置;
3. conftest.py 内置的成员A机器原路径(备用,仅 A 的机器上存在)。

**首次配置(推荐走 sut/,无需任何环境变量):**

```bash
# 0) 前提:能访问被测仓库远端(私有仓库需被加为协作者)
# 1) 在本仓库根目录 clone 被测仓库到 sut/
git clone https://gitee.com/oooczk/opc-project.git sut
cd sut
git checkout feat/hotspot-mining-agent     # 与成员A保持同一分支
# 2) 创建环境并安装依赖(一次性;含 FlagEmbedding/torch,耗时较长)
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
cd ..
# 3) 运行测试
run_tests.bat
```

若被测仓库检出在别的位置(如 A 的在研目录),设置用户环境变量指向其**仓库根目录**即可:

```bash
setx HOTSPOT_AGENT_ROOT "D:\your-path\opc-project"
```

被测代码更新后,`cd sut && git pull` 再重跑即可,不存在"拷贝副本过期"问题。

## 环境与运行

一键运行(全部用例):

```bat
run_tests.bat
```

run_tests.bat 的 Python 解释器解析顺序:
`HOTSPOT_AGENT_VENV`(显式指定)→ 本仓库 `sut\.venv\Scripts\python.exe` →
内置 A 机原路径。也可在仓库根目录手动执行(venv 随被测检出位置而定):

```bat
:: 被测检出在 sut\ 时:
sut\.venv\Scripts\python.exe -m pytest -v
:: 或任意位置检出时:
set HOTSPOT_AGENT_ROOT=D:\your-path\opc-project && <该检出>\.venv\Scripts\python.exe -m pytest -v
```

可覆盖的环境变量(均可选):

| 变量 | 作用 | 默认 |
|---|---|---|
| `HOTSPOT_AGENT_ROOT` | 显式指定被测仓库根目录 | 自动发现:`sut/` → conftest 内置路径 |
| `HOTSPOT_AGENT_VENV` | 显式指定 `python.exe` 完整路径(run_tests.bat 使用) | `sut\.venv` → 内置 A 机 venv |

若改用独立环境(自包含,不依赖被测仓库的 venv),先装被测项目运行依赖再装测试工具:

```bash
pip install -r <被测检出>/requirements.txt
pip install -r requirements-dev.txt
```

覆盖率(可选,需先 `pip install pytest-cov`):

```bash
python -m pytest --cov=hotspot_agent --cov-report=html
```

## 双人协作分工

**约定:用例文件严格一人一个、按被测模块认领;共享文件(conftest.py、pytest.ini、
.gitignore、.gitattributes、README、run_tests.bat)由成员A维护,成员B改动前先沟通。
被测仓库位置由各人机器决定(conftest 自动发现),测试代码不因位置不同而改动。
git 提交作者归属各自本机 `git config user.name/email`,各写各的文件,天然避免合并冲突。**

| 成员 | 认领被测模块 | 对应用例文件(后续迭代新建) |
|---|---|---|
| A | `config`、`models`、`dedup/*`、`pipeline/heat_scorer`、`clustering/*`、`scheduler` | `test_config.py`、`test_models.py`、`test_hash_dedup.py`、`test_semantic_dedup.py`、`test_heat_scorer.py`、`test_clustering.py`、`test_scheduler.py` |
| B | `adapters/*`、`agent/*`、`db/*`、`output/*`、`pipeline/platform_pipeline` | `test_adapters.py`、`test_llm_client.py`、`test_chat_agent.py`、`test_claude_agent.py`、`test_db_clients.py`、`test_api.py`、`test_feishu_push.py`、`test_pipeline.py` |

A 线多为纯逻辑/算法(依赖少、运行快),B 线多为外部交互类(httpx/FastAPI/DB,
**一律 mock,不连真实服务**),工作量大致均衡。

## 如何新增测试

1. 在 `tests/` 下新建 `test_<被测模块>.py`(仅认领属于自己分工的模块);
2. 被测模块内无三方依赖时可放心 import;涉及 `httpx`/DB/LLM 的一律用
   `monkeypatch`/`unittest.mock` 打桩,不发起真实网络/数据库请求;
3. 异步用例直接写 `async def test_...()`(`pytest.ini` 已开 `asyncio_mode = auto`);
4. 先本地跑通 `run_tests.bat tests/test_xxx.py -q`,再提交。

## ai_tests:AI 生成测试代码对照目录

`ai_tests/` 用于**对照验证 AI 工具生成的测试代码**,内容是 A 线(成员 A 认领模块)单元测试的完整一份:
8 个测试文件、60 条用例、984 行,覆盖 `hotspot_agent` 的 config / models / dedup(hash + semantic) /
pipeline/heat_scorer / clustering / scheduler 六个功能域与 1 组工程接线冒烟。

| 目录 | 内容 | 用例数 |
|---|---|---|
| `tests/` | 主线测试代码(含 A 线 + B 线) | 78(A 线 60 + B 线 18) |
| `ai_tests/` | **A 线测试代码的 AI 生成对照版本**(与 `tests/` 中 A 线文件内容一致) | 60 |

- `ai_tests/__init__.py` 使该目录成为一个包,避免与 `tests/` 下同名文件(如两个 `test_config.py`)
  在同一次 pytest 会话中出现模块名冲突;
- `pytest.ini` 中 `testpaths = tests`,因此**默认运行 `run_tests.bat` 不会重复收集该目录**。

运行方式:

```bat
:: 只跑 AI 生成版本(A 线 60 条)
run_tests.bat ai_tests -q

:: 只跑主线(tests/,默认行为)
run_tests.bat -q

:: 两条一起跑(共 138 条:78 + 60)
run_tests.bat tests ai_tests -q
```

说明:

- 该目录的用例与主线 A 线用例**断言完全一致**(逐文件 SHA256 比对一致),运行结果同为 60 passed;
  它用于"AI 生成测试代码"的样本留存与对比,不替代主线用例;
- 被测对象仍是外部仓库的 `hotspot_agent` 包,由根目录 `conftest.py` 自动发现并注入 `sys.path`,
  无需额外配置;
- 如需与"另一版 AI 生成结果"对比(例如更换用例拆分方式、断言粒度或测试数据构造),
  可在该目录下另建子目录(如 `ai_tests/variant_b/`)并各自保留 `__init__.py`。

## 注意事项

- **`sut/` 是被测仓库的本地检出,已被 .gitignore 排除**——不要 `git add -A`
  把它提交进测试仓库,也不要删除它内部的 `.git`;两套 git 完全独立、互不干扰;
- `hotspot_agent/config.py` 在导入时会自动加载**被测仓库自己根目录**的 `.env`
  (只读默认值,不触碰真实密钥);全新 clone 的检出中本就没有 `.env`,加载失败时
  静默回落默认值,测试不受影响;本仓库不包含也不提交任何 `.env`;
- 若 import 的 `hotspot_agent` 报"不在被测仓库内"(conftest 校验失败),说明
  本机安装了同名的其他包,先卸载或调整 `sys.path` 优先级;
- 报"未找到被测项目仓库"时,按报错提示 clone 到 `sut/`,或设置
  `HOTSPOT_AGENT_ROOT`。