DataTest

DataTest 是一套以需求为中心的 ETL 数据测试框架。当前版本使用本地 SQLite 跑通：

需求 → Metadata → 测试案例 → 确定性执行 → 断言 → 指标 → 报告

它同时提供：

• 原生 SwiftUI macOS 工作台
• datatest 命令行
• 可供 Codex 等 Agent 调用的本地 MCP Server
• 隔离调用本机 Codex CLI 的 AI 适配器

快速开始

当前版本不需要安装第三方 Python 包。

./bin/datatest init
./bin/datatest demo
./bin/datatest metadata REQ-CUSTOMER-001
./bin/datatest cases REQ-CUSTOMER-001
./bin/datatest run REQ-CUSTOMER-001 --batch-id 2026-08-22 --biz-date 2026-08-22

复杂大数据体验会创建 10 万客户、20 万账户、100 万笔增量交易、30 个业务日期分区、一个全量画像目标表和一个日增量指标目标表：

./bin/datatest complex-demo

该数据集故意保留一条风险评分/等级错误。运行 REQ-RISK-002 后，预期只有复合风险指标一致性案例失败，可继续使用界面的“Codex 调查根因”体验诊断。调试或自动化测试时可缩小规模，或通过 --no-error 生成完全正确的数据：

./bin/datatest complex-demo --customers 1000 --transactions 12000
./bin/datatest complex-demo --no-error

运行结果会输出 run_id。使用它查看结果、生成报告；如果某案例结果为 FAIL 或 ERROR，还可以明确调用 Codex 调查根因：

./bin/datatest result RUN-XXXXXXXXXXXX
./bin/datatest report RUN-XXXXXXXXXXXX
./bin/datatest analyze-failure RUN-XXXXXXXXXXXX CASE-003

本地数据默认保存在 .datatest/：

.datatest/
├── app.sqlite
├── source.sqlite
├── target.sqlite
└── artifacts/

SwiftUI 客户端

构建：

swift build --package-path macos

运行：

swift run --package-path macos DataTestApp

也可以生成可双击启动的标准 macOS App：

./bin/build-macos-app
open macos/.build/DataTest.app

客户端会调用同一套 Python 核心能力，并展示需求、案例、运行批次和历史指标。

导入真实需求

./bin/datatest requirement-import ./requirement.md \
  --project-id PROJECT-001 \
  --project-name 客户主题项目 \
  --requirement-id REQ-001 \
  --requirement-name 客户主题ETL需求

通过本机 Codex CLI 解析需求：

./bin/datatest ai-parse REQ-001
./bin/datatest requirement-confirm REQ-001
./bin/datatest ai-generate-cases REQ-001

AI 生成的案例状态为 draft，必须通过确定性校验并明确批准后才能运行：

./bin/datatest case-approve CASE-007
./bin/datatest case-approve-all REQ-001
./bin/datatest case-reject CASE-008 --comment "缺少分区条件"

完整状态流为：导入需求 → Agent 只读探索数据库并解析需求 → 形成候选 Metadata → 人工确认范围 → 重新采集并锁定正式 Metadata → Codex 生成草稿 → 人工审核 → 确定性执行。 探索阶段只读取真实表目录、DDL、字段、索引、行数和少量样例；执行器始终只选择 approved 案例。

生成案例后可继续与 Codex 沟通调整或补充案例：

./bin/datatest case-chat REQ-001 "补充历史数据量波动和字段值分布案例"

沟通内容、Codex 回复和案例变更都会按需求保存。任何新增或修改案例都会重新置为 draft，包括原本已经批准的案例，必须再次人工审核后才能执行。

macOS 协作页面通过流式命令展示当前处理过程；也可以直接消费 JSONL 事件：

./bin/datatest case-chat-stream REQ-001 "补充历史数据量波动案例"

事件只包含上下文准备、Codex 活动摘要、确定性校验和草稿保存等运行阶段，不输出模型内部思维内容。

可使用 DATATEST_CODEX_PATH 指定 Codex CLI。默认依次检查 PATH 和：

/Applications/ChatGPT.app/Contents/Resources/codex

内部 Codex 调用使用临时会话、--ignore-user-config 和只读沙箱，避免 DataTest MCP 递归调用自身。失败调查只生成结构化证据、根因判断、建议和只读验证 SQL，不会修改测试数据；结果及调用审计保存到 app.sqlite。

Codex MCP 接入

先初始化数据，然后将本地 STDIO Server 添加到 Codex。请将路径换成项目绝对路径：

codex mcp add datatest -- \
  /absolute/path/to/datatestool/bin/datatest \
  --home /absolute/path/to/datatestool/.datatest mcp

当前提供的工具包括查看项目、需求、Metadata、案例，调用 Codex 解析需求和生成案例，运行已审核案例，查询结果、生成报告，以及调查失败案例根因。

测试

PYTHONPATH=src python3 -m unittest discover -s tests -v

当前边界

• 当前只有 SQLite 数据源适配器。
• 测试 SQL 只允许 SELECT 和 WITH，数据库连接同时启用 query_only。
• PDF、DOCX 文本提取和远程数据源尚未实现。
• Hive、Impala、Spark 的方言、分区和性能能力将在后续适配器中实现。

详细架构见 docs/architecture.md。