Data Formulator 后端测试夹具Test Fixtures设计与应用实践【免费下载链接】data-formulator Data Formulator is an interactive AI-powered data analysis system makes it easy to connect, explore and visualize data.项目地址: https://gitcode.com/GitHub_Trending/da/data-formulator导读本文以 tests/backend/fixtures/README.md 为核心系统梳理 Data Formulator 后端测试夹具目录的定位、规划思路与真实落地形态。你将了解到夹具目录如何支撑中文文件名/列名/表名、Excel 多 Sheet、CSV 编码等上传解析回归测试仓库中真实存在哪些夹具文件它们分别被哪些集成测试消费以及夹具在create-table上传链路Flask 路由 → 文件解析 → 统一转 Parquet 存储中扮演的验证角色。读完即可在tests/backend/fixtures/下继续扩展自己的回归样本并快速定位对应的测试用例。一、夹具目录的定位后端测试的样本库在 Data Formulator 的测试体系中后端测试按关注点组织见 tests/backend/README.mdauth/身份认证、OIDC 提供商、凭据保险库、会话配置routes/Flask 端点测试表、Agent、会话、凭据data/数据加载器、连接器、工作区、Parquet、表名agents/AI Agent、模型注册表、提示词security/代码签名、日志脱敏、URL 白名单、沙箱、路径安全fixtures/共享的测试数据CSV、JSON、Parquet。fixtures/是唯一一个不以测试逻辑而是以测试数据为核心的目录其 README 开篇即点明定位This directory is for backend test sample data.从源码结构看它是多个测试模块通过Path(__file__).resolve().parents[1] / fixtures / ...这类相对路径共同引用的数据源避免各测试文件重复内联构造样本。这种共享夹具 各测试按需引用的组织方式既保证数据样本的唯一来源也让回归测试的样本可审查、可版本化。二、README 规划的演进蓝图与现状fixtures 的 README 明确给出了未来扩展建议这实际上是一份夹具目录 Roadmap规划目录建议样本类型现状excel/手工构造的 Excel 样本用于上传与解析回归测试✅ 已落地4 个 Excel 2 个 CSV 文件json/含中文表名、中文列名的 JSON 样本待补充csv/含中文表头的 CSV 文件✅ 已部分落地员工花名册_*.csvexpected/期望输出说明或 golden 文件待补充README 还特别提示Current contents may include hand-crafted regression samples such asexcel/test_cn.xls. 这一提示已被证实——仓库中确实存在tests/backend/fixtures/excel/test_cn.xls并且被多个测试用例消费。2.1 现有夹具清单tests/backend/fixtures/excel/目录当前包含 6 个真实样本文件test_cn.xls老式二进制格式BIFFExcel 文件中文表名/列名样本sales_report.xlsx含Orders、Returns两个英文 Sheet 的多 Sheet 工作簿产品利润分析.xlsx含销售数据、利润汇总两个中文 Sheet 的工作簿mixed_report_混合报表.xlsx含Summary、明细数据、Q1三个中英混合 Sheet 的工作簿员工花名册_gbk.csvGBK 编码的中文 CSV模拟中文 Windows/Excel 导出场景员工花名册_utf8.csvUTF-8 编码的中文 CSV对照基准。这些文件基本覆盖了 README 规划的Excel 上传解析与CSV 中文表头两大场景为后续json/、expected/的补充留下了清晰的空间。三、夹具如何支撑上传链路以 test_cn.xls 为例3.1 单文件解析冒烟测试tests/backend/data/test_excel_fixture_parsing.py 是最基础的夹具可解析性冒烟测试——它不依赖任何 Flask 路由直接用 pandas 读取夹具并断言非空def test_manual_xls_fixture_can_be_parsed() - None: fixture_path ( Path(__file__).resolve().parents[1] / fixtures / excel / test_cn.xls ) assert fixture_path.exists() df pd.read_excel(fixture_path) assert not df.empty该测试的价值在于先验证夹具文件本身合法、可被 pandas 解析再把它交给上层集成测试。若夹具被误改动导致损坏这一层会最先失败帮助快速定位是样本问题还是代码问题。3.2 完整上传链路集成测试tests/backend/routes/test_create_table_xls_upload.py 是文档注释里明确标注的全链路演练Exercises the real chain: Flask request - create_table route - save_uploaded_file - workspace parquet storage, using the test_cn.xls fixture.它针对POST /api/tables/create-table构造 multipart 请求用test_cn.xls验证了 5 个关键行为上传成功并建表返回status success、row_count 0、columns非空且工作区能以返回的表名读回相同行数的 DataFrame中文列名完整保留将 pandas 直接读取的原始列集合与接口返回的列集合比对断言完全一致——这是test_cn.xls存在的核心价值专门防止中文表头在链路中被破坏的回归纯中文表名不被清洗成空传入订单明细这样的表名后清洗结果仍保留中文断言订单 in table_name缺少 table_name 返回 400 错误返回error.code INVALID_REQUEST上传后 list-tables 可检索/api/tables/list-tables返回的条目包含正确row_count、非空sample_rows和columns。3.3 解析预览端点tests/backend/routes/test_parse_file_endpoint.py 用同一夹具验证POST /api/tables/parse-file上传预览/解析端点解析test_cn.xls返回至少一个 sheet且row_count、columns、data长度一致缺少文件或不支持的格式如data.txt均返回INVALID_REQUEST内联构造的 UTF-8 CSV 也能正确解析出 2 行数据。四、多 Sheet 工作簿夹具Sheet 解析策略的验证矩阵多 Sheet 场景是 Excel 上传中最容易出问题的部分。sales_report.xlsx、产品利润分析.xlsx、mixed_report_混合报表.xlsx三个夹具共同构成一张覆盖英文 Sheet / 中文 Sheet / 中英混合 Sheet的验证矩阵由 tests/backend/routes/test_upload_parquet_conversion.py 消费。4.1 后端 Sheet 解析策略Sheet 选择逻辑实现在 tables.py 的_resolve_excel_sheet中解析优先级为前端显式 hint 优先若前端在sheet_name字段传入了工作簿中真实存在的 Sheet 名不区分大小写直接采用后缀精确匹配table_name以_sheet_lower结尾时命中如sales_report_xlsx_orders→Orders表子串宽松匹配sheet_lower in table_name兜底取第一个 Sheetindex 0。对应的测试用例完整验证了这套策略test_upload_orders_sheet_via_suffix/test_upload_returns_sheet_via_suffix后缀匹配分别命中 Orders5 行与 Returns2 行test_upload_both_sheets_coexist同一文件的两个 Sheet 可同时存在为两张独立 Parquet 表test_sheet_hint_overrides_inference传入sheet_nameReturns时后端采用 hinttest_invalid_sheet_hint_falls_back传入不存在的NoSuchSheet时优雅回退到后缀/兜底逻辑test_upload_sales_sheet/test_upload_profit_sheet中文 Sheet 名销售数据、利润汇总同样支持后缀匹配与 hinttest_load_all_three_sheetsmixed_report_混合报表.xlsx的 Summary3 行、明细数据4 行、Q13 行三个 Sheet 可全部加载并存。4.2 统一转 Parquet 与元数据完整性test_upload_parquet_conversion.py还验证了上传文件的存储格式契约无论源格式是 CSV、XLSX 还是 XLS工作区一律存储为.parquet文件并记录source_type upload、source_file与original_name元数据。例如产品利润分析.xlsx上传后元数据中file_type parquet、filename以.parquet结尾、row_count 5。tests/backend/routes/test_create_table_replace_source.py 则利用夹具验证替换语义同名重复上传直接覆盖而非生成_1replace_sourcetrue时来自同一源文件的所有旧表含孤立 Sheet 表被清除。五、中文编码夹具GBK 与 UTF-8 双样本的设计价值员工花名册_gbk.csv与员工花名册_utf8.csv是同一业务数据、两种编码的成对样本专门用于验证中文 CSV 编码归一化。5.1 编码归一化实现编码处理在 file_manager.py 的normalize_text_encoding中实现仅处理csv、txt文本类型策略链为剥离 UTF-8 BOM\xef\xbb\xbf严格 UTF-8 解码成功则直接放行常见路径零开销GBK 解码尝试——覆盖绝大多数中文 Windows/Excel 导出的非 UTF-8 文件GBK 是 GB2312 的超集且兼容 GB18030 BMP 字符交给charset_normalizer检测但仅信任_TRUSTED_DETECTIONS白名单中的编码含gbk、gb18030、big5、shift_jis、euc-kr、各 Windows-125x、ISO-8859 系列等手动兜底链gb18030 → shift_jis → euc-kr最后手段latin-1永不抛错、字节 1:1 映射。这套分层策略在 tests/backend/data/test_file_manager_encoding.py 中有针对性单测UTF-8 原样返回、UTF-8 BOM 剥离、GBK 转为 UTF-8、GB18030 超集字符可解码等。5.2 集成链路验证test_upload_parquet_conversion.py中test_csv_upload_stored_as_parquet上传员工花名册_utf8.csv断言工作区存为 Parquet 且source_file 员工花名册.csvtest_gbk_csv_converted_correctly上传员工花名册_gbk.csv断言读回 DataFrame 后姓名列存在且首行值为张三——证明 GBK 编码的中文 CSV 经normalize_text_encoding归一化后列名与数据均无损。六、如何在 fixtures 下继续扩展结合 README 的 Roadmap 与现有测试的组织方式扩展新夹具时建议遵循以下约定样本真实可解析先确保文件能被 pandas 直接读取参考 test_excel_fixture_parsing.py 的模式中文场景成对设计编码类样本应同时提供 UTF-8 与目标编码如 GBK两份便于验证归一化前后一致性命名含语义从现有文件看文件名即契约——员工花名册_gbk.csv中的_gbk后缀让测试一眼可辨编码mixed_report_混合报表.xlsx直接暴露中英混合属性在路由测试中声明式引用通过FIXTURE_DIR Path(__file__).resolve().parents[1] / fixtures / excel定位夹具并用pytest.skip兜底夹具缺失的情况参见 test_create_table_xls_upload.py按 README 补全规划目录后续可在fixtures/json/下添加含中文表名/列名的 JSON 样本在fixtures/expected/下添加 golden 期望输出。运行全部后端测试的命令为uv run pytest tests/backend/见 tests/backend/README.md依赖 Docker 的数据库测试位于tests/database-dockers/不会被 pytest 自动发现。七、小结tests/backend/fixtures/虽只是一个数据目录却是 Data Formulator 后端上传链路质量保障的基石test_cn.xls守护中文列名/表名的完整生命周期三个多 Sheet 工作簿验证 Sheet 解析策略的完整矩阵成对的中文 CSV 验证编码归一化链路。README 中规划的json/、expected/目录则为未来的回归测试扩展保留了清晰方向——任何新增的上传解析逻辑都可以在这里补充对应的手工样本形成样本即契约的可审查测试资产。【免费下载链接】data-formulator Data Formulator is an interactive AI-powered data analysis system makes it easy to connect, explore and visualize data.项目地址: https://gitcode.com/GitHub_Trending/da/data-formulator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考