300+格式的转换网站怎么测？我的5级质量契约+210个用例全公开

最近在做一个文件格式转换网站，支持文档、图片、电子书、表格、演示文稿共计80+种源格式、300+ 种转换对。

功能做完了，但一个问题摆在面前：怎么保证每种转换的结果都是"能用"的？

"能用"听起来简单，但对于一个要交付的商业网站来说，"文件存在且非空"远远不够。用户上传一个 Word 文档转 PDF，如果转出来文字丢了一半，那就是事故。

这篇文章完整记录了我为这个项目搭建测试体系的过程，包括：

●如何定义"转换质量"的量化标准

●如何用代码自动验证转换结果的正确性

●测试过程中发现了哪些真实 bug

●最终的测试报告长什么样

希望对同样在做文件处理类项目的同学有参考价值。

一、项目背景

快转是一个基于 FastAPI 构建的在线文件转换服务，核心架构如下：

┌─────────────────────────────────────────┐│ 前端界面（HTML） │├─────────────────────────────────────────┤│ FastAPI 后端 (main.py) ││ ├── 转换引擎 (converter_engine.py) ││ └── 图像转换器 (image_converter_pro.py) │├─────────────────────────────────────────┤│ LibreOffice / Pillow / ImageMagick ││ PyMuPDF / pdf2docx / python-docx │├─────────────────────────────────────────┤│ SQLite + JWT 认证 (auth.py) │└─────────────────────────────────────────┘

支持的格式覆盖五大类：

二、测试的核心问题:什么叫"转换成功"？

大多数人写测试会这样验证：

def test_txt_to_pdf(): output = converter.convert("test.txt", "pdf") assert output is not None # 文件存在 assert os.path.getsize(output) > 0 # 文件非空

这能发现"转换崩溃"的问题，但发现不了"转换结果不对"的问题。 比如 txt 转 pdf，文件生成了，但里面的中文全变成了乱码——上面的测试照样通过。

所以我设计了一套「质量契约体系」，把"能用"这个模糊概念拆成 5 个可量化的级别：

| 级别 | 名称 | 验证内容 ||------|------|---------|| L0 | 存活性 | 文件存在、非空、格式头合法 || L1 | 结构完整性 | 文件可被对应库正常打开 || L2 | 内容保真度 | 核心内容与原始一致 || L3 | 格式语义 | 格式特有属性保留（分辨率/动画帧/颜色模式） || L4 | 往返一致性 | A→B→A 后内容损失在阈值内 |

每种转换对都分配了对应的契约级别。比如：

- `xlsx → csv`：L2，要求逐行逐列逐单元格精确对比，零损失- `png → jpg`：L3，要求 SSIM ≥ 0.99，尺寸完全一致，透明背景正确合成为白色- `png → bmp → png`：L4，要求像素 100% 一致（无损格式往返零损失）

三、质量阈值：100% 能做到吗？

甲方的要求是"转换质量 100%"。这个目标是否现实？答案是：分情况。

可以做到 100% 的转换：

物理上不可能 100% 的转换：JPG 是有损压缩格式，即使 quality 设为 100，像素级别也会有微小变化。这不是代码 bug，是格式设计决定的。全球所有图像处理软件（Photoshop、GIMP、ImageMagick）都无法做到 png→jpg→png 像素完全一致。

我的做法是：把质量参数强制设为最高，SSIM 阈值推到物理极限。

对于文档转换（如 PDF→DOCX），我用"句子级内容存在性验证"替代模糊的"相似度百分比"：

def verify_content(original_text, converted_text): sentences = split_sentences(original_text) for s in sentences: assert s in converted_text, f"内容丢失: {s}"

每个原始句子都必须在转换结果中找到，找不到就是 bug。

四、测试数据：全部代码生成

测试数据不依赖任何外部文件，全部由 TestDataFactory 动态生成：

classTestDataFactory: @staticmethod def create_png(directory, width=100, height=100): """生成渐变色 PNG（比纯色更能检测质量损失）""" img = Image.new('RGB', (width, height)) pixels = img.load() for y in range(height): for x in range(width): pixels[x, y] = ( int(x * 255 / width), int(y * 255 / height), 128 ) path = directory / "test.png" img.save(str(path), 'PNG') return path @staticmethod def create_xlsx(directory): """生成含中文的 3×3 数据表""" wb = Workbook() ws = wb.active data = [ ["姓名", "年龄", "城市"], ["张三", "25", "北京"], ["李四", "30", "上海"], ] for row in data: ws.append(row) wb.save(str(directory / "test.xlsx"))

为什么用渐变色而不是纯色？因为纯色图片即使转换出了问题，SSIM 也可能很高（大面积相同颜色掩盖了边缘差异）。渐变色能更敏感地检测质量损失。

五、7类测试，210+用例

整个测试体系分为 7 大类：

几个有意思的测试用例

无损格式像素级验证：

def test_png_to_bmp(self, work_dir): """png→bmp 像素 100% 一致""" src = TestDataFactory.create_png(work_dir) out = converter.convert(str(src), "bmp")# numpy 逐像素对比，差异必须为 0 assert image_pixel_exact_match(str(src), out)

GIF 动画帧数验证：

def test_gif_to_gif_animation(self, work_dir): """gif→gif 帧数一致 + 时长一致""" src = TestDataFactory.create_gif(work_dir) out = converter.convert(str(src), "gif") with Image.open(str(src)) as orig: orig_frames = orig.n_frames with Image.open(out) as conv: assert conv.n_frames == orig_frames

属性测试（随机输入验证不变量）：

@given(width=st.integers(10, 200), height=st.integers(10, 200))@settings(max_examples=10)def test_image_size_preserved(self, width, height): """随机宽高的图片转换后尺寸不变""" img = Image.new('RGB', (width, height), (128, 64, 32)) # ...转换后验证尺寸一致

截取 pytest 运行结果的终端输出（显示 96 passed, 1 xfailed）

六、测试过程中发现的真实 Bug

测试不是走过场，跑测试的过程中真的发现了问题。

Bug 1：PDF 转换路由错误（严重）

现象：pdf→txt、pdf→docx、pdf→html 全部失败，报错"无法转换"。

原因：converter_engine.py 的 convert() 方法先检查图像转换器是否支持该格式。PDF 在图像转换器里被识别为支持的格式（因为 PDF 确实可以作为图像处理），于是 PDF 被路由到了图像转换器，而图像转换器不知道怎么把 PDF 转成 txt。

# 修复前：先查图像转换器，PDF 被劫持if pro_image_converter.is_format_supported(source_format): return pro_image_converter.convert(...)# 修复后：先查文档格式的专用方法converter_method = f"_{source_format}_to_{output_format}"if hasattr(self, converter_method): getattr(self, converter_method)(input_path, output_path)elif pro_image_converter.is_format_supported(source_format): return pro_image_converter.convert(...)

影响：这个 bug 意味着线上所有 PDF 转文档的功能都是坏的。如果没有测试，这个问题可能要等用户投诉才能发现。

Bug 2：格式查询同样被劫持

修了 convert() 之后，发现 get_supported_formats('pdf') 返回的还是图像格式列表（png/jpg/gif...），没有 docx/txt/html。原因一样——查询方法也是先走图像转换器。

这个 bug 是在线上验证时发现的，说明本地测试通过 ≠ 线上没问题，需要对线上环境也做验证。

Bug 3：前端 JS 语法错误导致整站瘫痪

// 同一个 try 块里声明了两次 const convertDataconst convertData = { file_id: fileId, ... };// ...几十行后...const convertData = await convertRes.json(); // 重复声明！

const 不允许重复声明，浏览器解析 JS 时直接报错，导致所有函数都未定义——文件选了没反应，按钮不出来。

七、测试报告

最终生成了一份 HTML 格式的测试报告，包含：

●测试概况卡片（通过率、执行时间）

●每个用例的详细结果

●质量评估（含进度条可视化）

●发现的缺陷和修复记录

最终结果：96 passed, 0 failed, 1 xfailed（已知低优先级问题），执行时间 28 秒。

八、经验总结

"文件非空"不等于"转换成功"。必须验证内容，不同格式用不同的验证方法（文本用句子匹配，图像用 SSIM，表格用逐单元格对比）。

测试数据用代码生成，不要依赖外部文件。渐变色图比纯色图更能检测质量问题，中英文混合文本比纯英文更能暴露编码问题。

100% 质量是分情况的。无损格式之间可以做到像素级零损失，有损格式只能推到物理极限。把这个事实写进测试方案，比承诺做不到的 100% 更专业。

测试真的能发现 bug。这次发现了 PDF 路由错误、格式查询劫持、前端 JS 语法错误三个真实问题，其中 PDF 路由错误意味着线上核心功能是坏的。

本地测试通过 ≠ 线上没问题。需要对线上环境也做验证，特别是依赖系统组件（LibreOffice、ImageMagick）的功能。

文件转换看起来是个简单的功能，但要做到"每种格式都能用"其实很难。300+ 种转换对，每种都有自己的质量标准和边界条件。没有系统化的测试体系，靠人工验证根本覆盖不过来。

这套测试方案的核心思路是质量契约——不是笼统地说"测一下"，而是为每种转换定义明确的、可量化的、可自动化验证的质量标准。 这个思路不只适用于文件转换，任何涉及数据转换、格式处理的项目都可以参考。

☑️想涨薪、想走得更远，最稳妥的办法永远是投资自己的技能。

☑️可如果行业的天花板已经压到头顶，与其在原地内卷，不如借AI的东风换个赛道。

☑️AI，正是个低门槛、高成长的方向。

可以戳⬇️⬇️⬇️

✔️即可加入——>公主号【Atstudy技术社区】，内含项目实战等各种资料包