# 搜索引擎测试流水线指南

本文档是测试套件的**权威入口**，涵盖目录约定、运行方式、回归锚点矩阵、以及手动
联调脚本的分工。任何与这里不一致的历史文档（例如提到 `tests/unit/` 或
`scripts/start_test_environment.sh`）都是过期信息，以本文为准。

## 1. 测试目录与分层

```
tests/
├── conftest.py              # 只做 sys.path 注入；不再维护全局 fixture
├── ci/                      # API/服务契约（FastAPI TestClient + 全 fake 依赖）
│   └── test_service_api_contracts.py
├── manual/                  # 需真实服务才能跑的联调脚本，pytest 默认不 collect
│   ├── test_build_docs_api.py
│   ├── test_cnclip_service.py
│   └── test_facet_api.py
└── test_*.py                # 子系统单测（全部自带 fake，无外部依赖）
```

关键约束（写在 `pytest.ini` 里，不要另起分支）：

- `testpaths = tests`，`norecursedirs = tests/manual`；
- `--strict-markers`：所有 marker 必须先在 `pytest.ini::markers` 登记；
- 测试**不得**依赖真实 ES / DeepL / LLM 服务。需要外部依赖的脚本请放 `tests/manual/`。

## 2. 运行方式

| 场景 | 命令 | 覆盖范围 |
|------|------|----------|
| CI 门禁（每次提交） | `./scripts/run_ci_tests.sh` | `tests/ci` + `contract` marker + `search ∧ regression` |
| 发版 / 大合并前 | `./scripts/run_regression_tests.sh` | 所有 `@pytest.mark.regression` |
| 子系统子集 | `SUBSYSTEM=search ./scripts/run_regression_tests.sh` | 指定子系统的 regression 锚点 |
| 全量（含非回归） | `python -m pytest tests/ -q` | 全部自动化用例 |
| 手动联调 | `python tests/manual/<script>.py` | 需提前起对应服务 |

## 3. Marker 体系与回归锚点矩阵

marker 定义见 `pytest.ini`。每个测试文件通过模块级 `pytestmark` 贴标，同时
属于 `regression` 的用例构成“**回归锚点集合**”。

| 子系统 marker | 关键文件（锚点） | 保护的行为 |
|---------------|------------------|------------|
| `contract`    | `tests/ci/test_service_api_contracts.py` | Search / Indexer / Embedding / Reranker / Translation 的 HTTP 契约 |
| `search`      | `test_search_rerank_window.py`, `test_es_query_builder.py`, `test_es_query_builder_text_recall_languages.py` | Searcher 主路径、排序 / 召回、keywords 副 combined_fields、多语种 |
| `query`       | `test_query_parser_mixed_language.py`, `test_tokenization.py` | 中英混合解析、HanLP 分词、language detect |
| `intent`      | `test_style_intent.py`, `test_product_title_exclusion.py`, `test_sku_intent_selector.py` | 风格意图、商品标题排除、SKU 选型 |
| `rerank`      | `test_rerank_client.py`, `test_rerank_query_text.py`, `test_rerank_provider_topn.py`, `test_reranker_server_topn.py`, `test_reranker_dashscope_backend.py`, `test_reranker_qwen3_gguf_backend.py` | 粗排 / 精排 / topN / 后端切换 |
| `embedding`   | `test_embedding_pipeline.py`, `test_embedding_service_limits.py`, `test_embedding_service_priority.py`, `test_cache_keys.py` | 文本/图像向量客户端、inflight limiter、优先级队列、缓存 key |
| `translation` | `test_translation_deepl_backend.py`, `test_translation_llm_backend.py`, `test_translation_local_backends.py`, `test_translator_failure_semantics.py` | DeepL / LLM / 本地回退、失败语义 |
| `indexer`     | `test_product_enrich_partial_mode.py`, `test_process_products_batching.py`, `test_llm_enrichment_batch_fill.py` | LLM Partial Mode、batch 拆分、空结果补位 |
| `suggestion`  | `test_suggestions.py` | 建议索引构建 |
| `eval`        | `test_eval_metrics.py`（regression） + `test_search_evaluation_datasets.py` / `test_eval_framework_clients.py`（非 regression） | NDCG / ERR 指标、数据集加载、评估客户端 |

> 任何新写的子系统单测，都应该在顶部加 `pytestmark = [pytest.mark.<子系统>, pytest.mark.regression]`。
> 不贴 `regression` 的测试默认**不会**被 `run_regression_tests.sh` 选中，请谨慎决定。

## 4. 当前覆盖缺口（跟踪中）

以下场景目前没有被 `regression` 锚点覆盖，优先级从高到低：

1. **`api/routes/search.py` 的请求参数映射**：`QueryParser.parse(...)` 透传是否完整（目前只有 `tests/ci` 间接覆盖）。
2. **`indexer/document_transformer.py` 的端到端转换**：从 MySQL 行到 ES doc 的 snapshot 对比。
3. **`config/loader.py` 加载多租户配置**：含继承 / override 的合并规则。
4. **`search/searcher.py::_build_function_score`**：function_score 装配。
5. **Facet 聚合 / disjunctive 过滤**。
6. **图像搜索主路径**（`search/image_searcher.py`）。

补齐时记得同步贴 `regression` + 对应子系统 marker，并在本表删除条目。

## 5. 手动联调：索引文档构建流水线

除自动化测试外，联调/问题排查时建议走一遍“**MySQL → ES doc**”链路，确保字段与 mapping
与查询逻辑对齐。

```bash
cd /home/tw/saas-search
./scripts/stop.sh                  # 停掉已有进程（可选）
./scripts/start_indexer.sh         # 启动 indexer 服务，默认端口 6004

curl -X POST "http://127.0.0.1:6004/indexer/build-docs-from-db" \
  -H "Content-Type: application/json" \
  -d '{ "tenant_id": "170", "spu_ids": ["223167"] }'
```

返回中 `docs[0]` 即当前代码构造的 ES doc（与 `mappings/search_products.json` 对齐）。
与真实 ES 数据对比的查询参考 `docs/常用查询 - ES.md`；若字段不一致，按以下路径定位：

- `indexer/document_transformer.py` — 文档构造逻辑
- `indexer/incremental_service.py` — 增量查库逻辑
- `logs/indexer.log` — 索引日志

## 6. 编写测试的约束（与 `开发原则` 对齐）

- **fail fast**：测试输入不合法时应直接抛错，不用 `if ... return`；不要用 `try/except` 吃掉异常再 `assert not exception`。
- **不做兼容双轨**：用例对准当前实现，不为历史行为保留“旧 assert”。若确有外部兼容性（例如 API 上标注 Deprecated 的字段），在 `tests/ci` 里单独写**契约**用例并注明 Deprecated。
- **外部依赖全 fake**：凡是依赖 HTTP / Redis / ES / LLM 的测试必须注入 fake stub，否则归入 `tests/manual/`。
- **一处真相**：共享 fixture 如果超过 2 个文件使用，放 `tests/conftest.py`；只给 1 个文件用就放在该文件内。避免再次出现全库无人引用的 dead fixture。