单元测试与 E2E 测试.md 23 KB

单元测试与 E2E 测试

本文引用的文件

  • HeaderScorerTest.java
  • AiTemplateMatcherTest.java
  • AiTemplateMatchEdgeTest.java
  • AiCleanSupportTest.java
  • run_tests.py
  • ai-template-match-test-cases.md
  • vitest.config.mts

目录

  1. 引言
  2. 测试分层与整体流程
  3. 后端 JUnit 测试组织方式
  4. 模板打分、绑定与边缘场景用例
  5. C/D 类 E2E 真实清洗链路
  6. Electron 主进程 vitest 单测指南
  7. 常见测试模式
  8. 调试断言失败与定位真实链路问题
  9. 结论

引言

本指南面向需要理解并扩展 AI 清洗测试的开发者,覆盖以下目标:

  • 说明后端 JUnit 测试如何验证表头归一化、指纹、同义词、模糊匹配、打分档位、候选绑定、模型兜底等确定性逻辑。
  • 说明 C/D 类 E2E 如何通过 HTTP API 在案件 A=16/B=17 上执行上传、智能清洗、批次核验,并通过 target/aitest_*.py 和 target/aitest/*.json 记录结果。
  • 说明 Electron 侧 vitest.config.mts 中 include=['electron/**/*.test.ts'] 与 passWithNoTests=true 的含义,以及如何在主进程新增 .test.ts 单测。
  • 总结测试数据隔离、数据库清理、登录态处理、重复上传去重、损坏文件容错等实践。
  • 给出断言失败排查和从单测回归到真实链路的步骤。

测试分层与整体流程

项目中的 AI 清洗测试采用“离线确定性 + 在线真实链路”的分层设计:

  • A 层:离线匹配规则(指纹、归一化、同义词、模糊词、打分组件),使用 JUnit 验证确定性分支。
  • B 层:绑定与计划(字段名解析、中文名改写、歧义丢弃、列计划)。
  • C 层:端到端真实链路(上传 → 智能清洗 → job/批次/数据/治理树),通过 HTTP API 执行并在数据库中核验。
  • D 层:异常容错(空表头、损坏文件、去重、跨案件复用)。
  • E 层:全量模板覆盖(遍历 table_info 模板族)。

    flowchart TD
    A["A 层:JUnit 确定性测试<br/>HeaderScorer / AiTemplateMatcher / Edge / Support"] --> B["B 层:绑定与计划<br/>filterBinds / 列计划 / 歧义处理"]
    B --> C["C 层:E2E 真链路<br/>HTTP API 上传 + 智能清洗"]
    C --> D["D 层:异常容错<br/>损坏文件 / 去重 / 跨案"]
    C --> DB["数据库核验<br/>ai_clean_job / ai_clean_batch / ai_clean_template"]
    A --> Result["结果:target/aitest_*.py / target/aitest/*.json"]
    B --> Result
    D --> Result
    

图示来源

  • ai-template-match-test-cases.md:1-111
  • run_tests.py:20-91

章节来源

  • ai-template-match-test-cases.md:1-111

后端 JUnit 测试组织方式

后端测试位于 ai-server/src/test/java/com/zsjz/ai/module/aiclean/**,主要围绕 AI 清洗模块中的“匹配—绑定—支撑工具”展开:

测试类 职责 关键断言目标
HeaderScorerTest 表头打分与出口 A 闸门 同表头高分、同义词 EXACT、模糊相似、单位差异、形状矛盾、必填缺失、F-01 收紧
AiTemplateMatcherTest 三腿匹配、向量召回、绑定过滤、模型幻觉兜底 指纹直通零模型、既有模板强命中出口 A、越界候选降级为未命中、绑定域合法性和改写
AiTemplateMatchEdgeTest 边界严格测试 空表头、重复列、必填相似覆盖、无关表头、短词边界、同义词改写
AiCleanSupportTest 纯逻辑支撑 列名归一化、表头指纹、复用安全、表块切分、列形状识别、列名消毒

这些测试共同保证:

  • 同表头指纹直通路径不调用 LLM。
  • 写用户既有业务表的出口 A 必须经过确定性闸门。
  • 模型返回不可信时,按未命中或低置信降级,而不是直接落库。

    classDiagram
    class HeaderScorerTest {
        +exactHeaders()
        +synonyms()
        +fuzzySimilarRules()
        +fuzzyNeverCollapsesUnits()
        +reordered()
        +shapeMismatchBlocksStrong()
        +requiredMissingBlocksStrong()
    }
    
    class AiTemplateMatcherTest {
        +fingerprintShortCircuits()
        +scoreHitsExistingTemplate()
        +hallucinatedIndexDegradesToNone()
        +filterBindsAcceptsBothDomainsAndRejectsInventedFields()
        +lowConfidenceCannotReachExistingTable()
    }
    
    class AiTemplateMatchEdgeTest {
        +emptyHeadersScoreZero()
        +duplicateColumnsDoNotInflateScore()
        +requiredCoveredBySimilarWord()
        +unrelatedHeadersScoreLow()
        +shortWordBoundary()
        +filterBindsExactViaSynonymEntry()
    }
    
    class AiCleanSupportTest {
        +normalizeHeaders()
        +fingerprintIsPositionSensitive()
        +sameOrderedHeaders()
        +singleBlockWithTitleRow()
        +twoBlocks()
        +colShapes()
        +colStats()
        +sanitizeColumns()
    }
    
    HeaderScorerTest --> "验证" HeaderScorer : "打分 / STRONG / WEAK"
    AiTemplateMatcherTest --> "依赖" LlmService : "mock"
    AiTemplateMatcherTest --> "依赖" AiCleanTemplateVectorIndex : "mock"
    AiTemplateMatchEdgeTest --> "验证" HeaderScorer : "边界条件"
    AiCleanSupportTest --> "验证" HeaderNormalizer : "归一化"
    AiCleanSupportTest --> "验证" HeaderFingerprint : "指纹"
    AiCleanSupportTest --> "验证" BlockDetector : "表块切分"
    AiCleanSupportTest --> "验证" ColStatBuilder : "列形状"
    

图示来源

  • HeaderScorerTest.java:1-200
  • AiTemplateMatcherTest.java:1-200
  • AiTemplateMatchEdgeTest.java:1-118
  • AiCleanSupportTest.java:1-147

章节来源

  • HeaderScorerTest.java:1-200
  • AiTemplateMatcherTest.java:1-200
  • AiTemplateMatchEdgeTest.java:1-118
  • AiCleanSupportTest.java:1-147

模板打分、绑定与边缘场景用例

表头打分与出口 A 闸门:HeaderScorerTest

该测试聚焦确定性打分逻辑,避免模型误判直接写入既有业务表:

  • 完全同表头应接近 1.0,并通过短模板强匹配线。
  • 同义词通过 GlobalCache.setSynonymsForTesting 注入,验证词条链路;无词条时不应命中。
  • 模糊规则支持等长编辑距离、同前缀双替换、后缀包含,但禁止金额单位差异被当成同一列。
  • 列序变化允许进入候选,但短模板不能直接出口 A。
  • 形状矛盾(例如日期形状对 MONEY 字段)拒绝出口 A。
  • 必填字段缺失拒绝出口 A。
  • 提供可读的逐列匹配明细,用于排障。
  • F-01 收紧:交易方向/交易金额、交易网点/交易金额不得判相似。

章节来源

  • HeaderScorerTest.java:53-94
  • HeaderScorerTest.java:97-134
  • HeaderScorerTest.java:136-170

匹配与向量召回:AiTemplateMatcherTest

该测试重点验证三件事:

  1. 同表头指纹直通必须零模型。
  2. 模型幻觉必须被兜住:越界候选序号降级为未命中。
  3. 出口 A 保留确定性闸门:向量召回只改候选顺序,不参与最终判档。

关键行为包括:

  • 指纹命中返回 BY_CACHE,不调用 LLM,且出口为 B。
  • 老模板存档 md5 是旧归一化算的,仍应按当前规则重算后走指纹直通。
  • 既有模板强命中走出口 A,不调模型。
  • 模型回不存在序号时,结果为 BY_NONE,candidate 为空。
  • 绑定过滤接受英文名和中文名;编造字段名和越界列号被丢弃。
  • AI 模板风格候选(en=c0..cN)下,模型回中文名也应放行并改写为物理列名。
  • 低置信度不允许出口 A。
  • 高置信度但确定性分数为 0 时,只能走出口 B。

    sequenceDiagram
    participant Test as "AiTemplateMatcherTest"
    participant Matcher as "AiTemplateMatcher"
    participant Vector as "AiCleanTemplateVectorIndex"
    participant LLM as "LlmService"
    
    Test->>Matcher: match(evidence, templates, byScore)
    alt 指纹命中
        Matcher-->>Test: BY_CACHE / 不调 LLM / 出口 B
    else 既有模板强命中
        Matcher-->>Test: BY_SCORE / 不调 LLM / 出口 A
    else 需要模型裁决
        Matcher->>Vector: recall(query, topK)
        Vector-->>Matcher: 候选列表
        Matcher->>LLM: chatAsDetail(...)
        LLM-->>Matcher: 结构化草稿
        alt 候选序号越界或无效
            Matcher-->>Test: BY_NONE / candidate=null
        else 有效草稿
            Matcher-->>Test: 由置信度与确定性分数决定出口
        end
    end
    

图示来源

  • AiTemplateMatcherTest.java:82-160
  • AiTemplateMatcherTest.java:162-259

章节来源

  • AiTemplateMatcherTest.java:1-200

边缘场景:AiTemplateMatchEdgeTest

该测试专门钉住容易退化的边界:

  • 空表头或空模板打分返回 0,且不抛异常。
  • 重复列不得膨胀 Jaccard 分数。
  • 必填字段靠相似命中也算覆盖,允许直通。
  • 完全无关表头应保持低分,不误命中。
  • 短词边界:单字词、2 字等长距 1 不触发模糊。
  • 同义词词条让绑定名 EXACT 命中并改写。

章节来源

  • AiTemplateMatchEdgeTest.java:1-118

支撑逻辑:AiCleanSupportTest

该测试覆盖整条 AI 链路中最关键的确定性部分:

  • 列名归一化抹平空白、全角、括号字符,但保留括号内限定词和单位语义。
  • 表头指纹对列序敏感,尾部 padding 空列不影响指纹。
  • 复用安全:只有同序、同义才允许复用存档列绑定。
  • 表块切分支持标题行 + 数据块、多表头块。
  • 列形状识别电话、身份证、日期、金额、文本。
  • 列名消毒防止 SQL 注入,生成安全标识符。

章节来源

  • AiCleanSupportTest.java:1-147

C/D 类 E2E 真实清洗链路

执行入口与环境

E2E 脚本位于 docs/testing/fixtures/ai-llm-match-20261026/run_tests.py,其职责是:

  • 连接本地服务 http://127.0.0.1:8980/js/a。
  • 使用账号 admin/admin123 登录。
  • 打开测试案件。
  • 读取 manifest.json 中的文件清单。
  • 分批上传文件。
  • 发起智能清洗。
  • 查询批次状态。
  • 拉取 ai_clean_job、ai_clean_batch、ai_clean_template 数据。
  • 将结果写入 target/aitest_*.py 和 target/aitest/*.json。

需要注意:脚本当前默认 CASE_ID = 20,而测试文档锚定的是案件 A=16、B=17。若要在 16/17 上执行真实链路,应调整脚本中的 CASE_ID 和相关配置,并确保服务地址、数据库连接、登录凭据与本环境一致。

章节来源

  • run_tests.py:20-91
  • run_tests.py:94-186
  • run_tests.py:189-295
  • ai-template-match-test-cases.md:1-111

HTTP API 工作流

E2E 客户端封装了常用接口:

阶段 API 作用
登录 /auth/login 获取 token,设置请求头 x-token
开案 /case/open 打开测试案件,带重试
上传 /dm/preFileUpload 上传 xlsx/csv,支持 batchId 和 reClean
智能清洗 /aiClean/smartClean 提交清洗任务
状态查询 /aiClean/smartClean/status 根据 batchId 查询批次状态
数据查看 /gt/treeTablePage 查看治理树中的表数据
sequenceDiagram
    participant Py as "run_tests.py"
    participant API as "后端 HTTP API"
    participant DB as "PostgreSQL"

    Py->>API: POST /auth/login
    API-->>Py: 返回 token
    Py->>API: POST /case/open
    API-->>Py: 开案成功
    Py->>API: POST /dm/preFileUpload(batchId, reClean)
    API-->>Py: 返回 file/batch 结构
    Py->>API: POST /aiClean/smartClean(fileInfos, reClean)
    API-->>Py: 返回清洗任务
    Py->>API: GET /aiClean/smartClean/status?batchId
    API-->>Py: 返回批次进度
    Py->>DB: 查询 ai_clean_job / ai_clean_batch
    DB-->>Py: 返回清洗结果
    Py-->>Py: 写入 target/aitest_*.py / target/aitest/*.json

图示来源

  • run_tests.py:34-91
  • run_tests.py:94-186

结果记录口径

E2E 结果关键字段包括:

  • matched_by:HEADER_CACHE、SCORE、LLM。
  • exit:A 表示写既有业务表,B 表示 AI 动态表。
  • llm:模型调用次数。
  • upload:OK、DATA_NULL、SKIP 等上传状态。
  • template_id、expected_template_id:实际命中模板与期望模板。
  • sheet_id、job_id、row_total、row_loaded、row_rejected:Sheet 与 Job 粒度数据。

测试文档明确说明:同表头文件在上传阶段可能被既有匹配器直中,AI 清洗作为兜底链路;因此“未产生 ai_clean_job”不一定是失败,而是设计内行为。

章节来源

  • ai-template-match-test-cases.md:56-111
  • run_tests.py:162-186

Electron 主进程 vitest 单测指南

include=['electron/*/.test.ts'] 的含义

ai-electron/vitest.config.mts 中:

  • include: ['electron/**/*.test.ts'] 表示只扫描 ai-electron/electron/ 目录下以 .test.ts 结尾的文件。
  • 前端代码位于 ai-electron/frontend/,有自己独立的工程,不在该配置范围内。
  • 新增主进程单测时,应将文件放在 ai-electron/electron/.../.test.ts,否则不会被发现。

passWithNoTests=true 的含义

  • 即使没有匹配到任何 .test.ts,vitest 也不会把整个命令当作失败。
  • 这适合当前主进程单测尚未大量落地时的渐进式演进:新增测试不会因“找不到测试”而阻塞构建。
  • 但这也意味着如果写错了路径或文件名,可能静默跳过,所以新增测试后应显式运行并确认用例数。

在主进程新增 .test.ts 的步骤

  1. 在 ai-electron/electron/ 下的功能目录创建 .test.ts 文件。
  2. 使用 Vitest 提供的断言和测试框架编写用例。
  3. 若依赖主进程能力,可 mock 外部服务或 Electron API,保持单测快速稳定。
  4. 在根目录或 ai-electron 工程下执行 vitest,确保扫描到新增文件。
  5. 如只需验证某几个测试,可使用 Vitest 的路径或名称过滤参数。

    flowchart TD
    Dev["开发者创建 electron/**/*.test.ts"] --> Config["vitest.config.mts 扫描 include 规则"]
    Config --> Match{"是否匹配 electron/**/*.test.ts"}
    Match -->|是| Run["vitest 执行测试"]
    Match -->|否| Skip["passWithNoTests=true,不报错但也不执行"]
    Run --> Report["输出测试结果"]
    Skip --> Warning["建议检查文件路径和命名"]
    

图示来源

  • vitest.config.mts:1-10

章节来源

  • vitest.config.mts:1-10

常见测试模式

测试数据隔离

  • JUnit 测试通过构造内存对象、Mock 外部依赖、使用 GlobalCache.clearForTesting() 和 setSynonymsForTesting() 控制全局缓存。
  • E2E 测试通过独立 batchId 区分不同批次,并通过 manifest.json 固定测试文件和期望模板。
  • 数据库访问仅用于核验结果,不要求每个测试都完整重建 schema。

章节来源

  • HeaderScorerTest.java:33-52
  • AiTemplateMatcherTest.java:68-80
  • run_tests.py:189-295

数据库清理

现有 E2E 脚本更偏向“执行并记录”,并未在每轮测试前自动清空数据库。若需强隔离:

  • 在测试开始前备份相关表。
  • 或在测试结束后删除本次 batch/job 的数据。
  • 对于 JUnit,优先使用 Mock 和内存快照,避免污染真实 PG。

章节来源

  • run_tests.py:94-186

登录态处理

E2E 客户端使用 requests.Session 保存会话,登录后将 token 放入 x-token 请求头。响应码为 401 时会重试一次登录并重新开案,提升弱网或服务重启后的稳定性。

章节来源

  • run_tests.py:34-66

重复上传去重

  • 不带 reClean 的重复上传会触发 md5 去重,可能出现 data=null,即无需再次解析。
  • 带 reClean 的请求会触发重新清洗。
  • E2E 文档记录了“同案件重复上传不带 reClean 时 data=null”的行为。

章节来源

  • run_tests.py:68-77
  • ai-template-match-test-cases.md:88-111

损坏文件容错

E2E 文档记录:损坏 xlsx(伪造内容)时,job 应为 SKIP,llm=0,不会拖垮整个批次。这是 E2E 验收的关键容错点。

章节来源

  • ai-template-match-test-cases.md:88-111

调试断言失败与定位真实链路问题

JUnit 断言失败排查

  1. 先确认失败发生在哪一层:
    • 打分失败:看 HeaderScorerTest 相关断言。
    • 匹配失败:看 AiTemplateMatcherTest 的指纹、评分、模型兜底。
    • 边界失败:看 AiTemplateMatchEdgeTest。
    • 支撑逻辑失败:看 AiCleanSupportTest。
  2. 检查 GlobalCache 是否被其他测试污染:确认 @BeforeEach/@AfterEach 中的 clearForTesting() 生效。
  3. 如果是同义词或模糊匹配问题,检查是否注入了预期词条,或是否触发了 F-01 收紧。
  4. 如果是出口 A 问题,重点检查形状、必填、置信度和确定性分数组合。

章节来源

  • HeaderScorerTest.java:33-52
  • AiTemplateMatcherTest.java:68-80

E2E 失败排查

  1. 确认服务地址、数据库地址、登录账号与脚本一致。
  2. 确认 CASE_ID 是否为期望值;文档锚定 A=16/B=17,脚本默认 CASE_ID=20。
  3. 先单独执行登录和开案,确认 /auth/login 和 /case/open 返回 200。
  4. 查看上传响应:upload_code、upload_message、upload、sheets。
  5. 查看批次状态:/aiClean/smartClean/status 的 stage、failed_count、need_review_count。
  6. 查数据库:
    • ai_clean_job:matched_by、exit_code、exit、llm_calls、fail_reason。
    • ai_clean_batch:stage、loaded_rows、rejected_rows、self_built_count。
    • ai_clean_template:模板 headers、status、confidence、match_tier。
  7. 对比 target/aitest_*.py 和 target/aitest/*.json,确认是哪一批次、哪个 sheet、哪个 job 失败。

章节来源

  • run_tests.py:20-91
  • run_tests.py:94-186
  • ai-template-match-test-cases.md:56-111

从单测回归到真实链路

推荐顺序:

  1. 先用 JUnit 验证确定性分支,确保归一化、指纹、打分、绑定逻辑正确。
  2. 再用最小 E2E 用例验证上传和智能清洗接口。
  3. 最后跑完整 manifest 分组,观察 target/aitest_*.py 和 target/aitest/*.json 汇总。
  4. 若 E2E 失败但 JUnit 通过,优先检查:
    • 服务配置是否与测试环境一致。
    • 是否有既有匹配器直中导致 AI 链路未触发。
    • 模型调用是否被 verify 拦截转为 NEED_REVIEW。
    • 是否因跨案件、重复上传、损坏文件触发预期容错分支。

章节来源

  • ai-template-match-test-cases.md:1-111

结论

这套测试体系的核心价值在于:

  • 用 JUnit 钉住确定性分支,避免“模型调通了但核心打分和闸门退化”的隐蔽问题。
  • 用 E2E 验证真实上传、清洗、批次、治理树链路,并把结果落到 target/aitest_*.py 和 target/aitest/*.json。
  • 用 Electron vitest 配置明确主进程单测范围,同时保留 passWithNoTests=true 支持渐进式补充。
  • 用出口 A 的确定性闸门、verify 拦截、损坏文件 SKIP、重复上传去重等机制,保障 AI 清洗既灵活又安全。

新增测试时,建议遵循“先确定性、再 E2E、再全量覆盖”的顺序,并始终关注:同表头是否零模型、出口 A 是否过闸、模型幻觉是否被兜住、E2E 结果是否可回溯。