在日常开发和测试工作中PDF 文件往往是最容易被低估的一类测试对象。很多人拿到一个 PDF 后的第一反应是打开看一眼确认没有乱码就结束了但只要涉及自动化测试、批量校验、数据抽取或者接口回归PDF 很快就会暴露出各种问题文字不能选中、表格错位、字体缺失、页面方向不对、加密导致解析失败。这篇文章要聊的就是一套围绕 PDF 的完整测试方案换句话说就是给 Tests for a PDF 这样一个小目标落地成真正可运行的测试脚本和验证流程。这套方案的重点不是某一个 PDF 阅读器也不是某一个转换工具而是站在测试角度把 PDF 当作一个被测对象用 Python 生态里常见的库去拆解它、断言它、批量验证它。文章会覆盖文本提取、表格提取、OCR 扫描件识别、PDF 转 Word/Excel、压缩、加密解密、元数据检查、二维码生成与识别以及通过 FastAPI 把 PDF 测试能力封装成接口服务。不讲太多理论知识直接给可复制的命令、测试样例和常见问题排查清单。适合的读者有两类一类是正在做文档处理系统、知识库导入或 RAG 检索的同学需要把 PDF 解析质量纳入自动化测试另一类是测试工程师想把 PDF 转换工具的回归测试从“人工打开看”升级成“脚本断言”。如果你只是找一个临时工具转一下 PDF这篇文章帮助有限但如果你的目标是“让 PDF 处理结果可重复、可验证、可批量检查”那接下来的内容可以直接参考。1. 核心能力速览在开始动手之前先把这套 PDF 测试方案的核心能力整理成一张表。后面的章节会围绕这些能力逐项展开。能力项说明文本提取测试校验 PDF 中的文字是否可以被正确抽取包括英文、中文、数字和空白字符表格提取与转换从 PDF 中提取表格结构并导出为 Excel/CSV用于数据比对图片与扫描件 OCR对扫描版 PDF 做图片化处理再通过 OCR 识别文字格式转换验证PDF 转 Word、Word 转 PDF、PDF 转 Excel 的正确性检查压缩与加密解密验证压缩率、加密后访问控制、解密后是否可正常解析元数据与页面结构检查页数、页面尺寸、书签、嵌入字体、Metadata 信息二维码生成与识别生成带有 URL 的 PDF 二维码并验证识别结果批量任务对目录下的多个 PDF 文件批量执行测试输出汇总报告接口 API封装成 HTTP 接口供其他系统或测试脚本调用CI 集成使用 pytest 运行测试并生成 JUnit 报告接入 Jenkins/GitLab CI这个能力列表基本覆盖了日常 PDF 处理中 80% 的测试需求。实际落地时不需要全部实现建议先选择与你业务最相关的 2 到 3 个能力跑通后再扩展。2. 适用场景与使用边界2.1 适合谁这套方案最直接的使用者是文档处理系统的开发人员和测试工程师。如果你正在做一个 PDF 解析工具、文件转换服务、知识库导入管道或者邮件附件归档系统那么 PDF 的解析结果、转换结果都需要被反复验证。把验证过程自动化之后每次代码改动都可以快速回归而不是依赖人工看几十个 PDF 文件。批量转换场景也适合。例如每天有一批 PDF 需要转成 Excel 或 Word转换后要检查页数是否一致、表格行数是否丢失、文件是否能正常打开。用脚本自动完成这些检查可以省掉大量重复劳动。2.2 不适合什么这套自动化测试并不适合代替人工排版审阅。PDF 的视觉呈现是否美观、字号是否协调、水印位置是否合适这类主观问题仍然需要人工确认。另外如果只是偶尔转一个文件没必要搭建这套测试环境直接用在线工具或本地 PDF 编辑器更快。2.3 合规边界处理 PDF 时必须注意授权问题。测试样本应当使用自己生成的 PDF或者明确有权限处理的文档。不要批量解析、转换、识别未经授权的他人文档尤其是涉及隐私、版权或商业机密的 PDF。在团队内共享测试样本时也要确认样本中不包含敏感信息。3. 环境准备与前置条件这套方案基于 Python 3.9建议使用虚拟环境隔离依赖。主要用到的库包括PyMuPDF提取文本、图片、页面大小、元数据。pdfplumber提取表格和精细文本位置信息。PyPDF2 / pypdf处理合并、拆分、加密、解密。pdf2image pytesseract扫描件转图片并 OCR。pytest编写和执行测试用例。Pillow处理图片和二维码识别。openpyxl / pandasExcel 结果写入与比对。reportlab生成测试用 PDF。fastapi uvicorn提供接口服务。qrcode / pyzbar生成和识别二维码。安装命令可以在虚拟环境中一次完成python -m venv .venv source .venv/bin/activate # Windows 下用 .venv\Scripts\activate pip install --upgrade pip pip install pymupdf pdfplumber pypdf pdf2image pytesseract pytest pillow openpyxl pandas reportlab fastapi uvicorn qrcode pyzbar如果只需要文本提取和表格提取可以只安装前几个库避免依赖过重。OCR 用到的 tesseract 需要在系统中单独安装macOS 下可以用 Homebrew 安装Linux 下可以用 apt 安装Windows 需要下载安装包。如果你的机器上没有 tesseract后面 OCR 测试会直接报错这是正常的。准备测试样本时建议用 reportlab 自己生成一个包含文字、表格、图片的 PDF这样版权和内容都可控也方便预期结果比对。下面给出一段生成测试 PDF 的 Python 脚本from reportlab.lib.pagesizes import A4 from reportlab.pdfgen import canvas from reportlab.lib.utils import ImageReader from PIL import Image, ImageDraw # 先创建一张临时图片 img Image.new(RGB, (200, 100), white) draw ImageDraw.Draw(img) draw.text((10, 10), Test Image, fillblack) img.save(test_image.png) c canvas.Canvas(sample_test.pdf, pagesizeA4) c.drawString(50, 750, Hello PDF Test) c.drawString(50, 730, 第一行中文文本) c.drawImage(ImageReader(test_image.png), 50, 600, width200, height100) c.showPage() c.save() print(sample_test.pdf 已生成)这段脚本会生成一个 1 页的 PDF包含一行英文、一行中文和一张图片。后面所有测试都可以基于这个样本文件做验证。4. 安装部署与基础启动依赖安装完成后建议按下面的目录结构组织测试工程pdf_tests/ ├── samples/ # 测试用 PDF 文件 │ └── sample_test.pdf ├── output/ # 测试输出 ├── tests/ │ ├── test_text.py # 文本提取测试 │ ├── test_table.py # 表格提取测试 │ ├── test_ocr.py # OCR 测试 │ └── test_convert.py # 转换测试 ├── services/ │ └── pdf_api.py # FastAPI 服务 ├── requirements.txt └── pytest.ini在pytest.ini中把测试目录和执行选项配置好[pytest] testpaths tests addopts -v --tbshort然后运行一条命令执行全部测试pytest如果一切正常控制台会打印每个测试的执行结果。刚开始先跑一个最简单的文本提取测试确认环境链路是通的。写一个最基础的测试用例使用 PyMuPDF 从 PDF 中提取文本并断言关键词存在import fitz # PyMuPDF def test_extract_text_from_pdf(): doc fitz.open(samples/sample_test.pdf) text for page in doc: text page.get_text() doc.close() assert Hello PDF Test in text, 英文文本未提取到 assert 第一行中文文本 in text, 中文文本未提取到运行时如果提示ModuleNotFoundError: No module named fitz说明 PyMuPDF 没有安装成功。PyMuPDF 安装成功后import fitz是它的标准导入名不要改写成import pymupdf除非你安装的是新版 pymupdf 包。为了统一建议在 requirements 中固定库版本。5. 功能测试与效果验证PDF 测试的核心不只是“能打开”而是“解析结果对不对”。这一节把功能测试拆成几个独立小节每个小节都给出了验证思路和代码骨架。5.1 PDF 文本提取测试文本提取是 PDF 测试最基础的一环。测试时重点检查三件事文本内容是否完整、中文是否乱码、空白字符是否异常。import fitz def test_pdf_text_structure(): doc fitz.open(samples/sample_test.pdf) first_page doc[0] text first_page.get_text() # 断言页面数量 assert doc.page_count 1 # 断言文本行数 line_count len([line for line in text.splitlines() if line.strip()]) assert line_count 2, f文本行数过少: {line_count} # 断言没有异常替换字符 assert \ufffd not in text, 检测到 Unicode 替换字符可能有乱码 doc.close()实际工作中PDF 生成器如果不嵌入字体提取出来的中文可能是乱码或者文字顺序错乱。这类问题在测试中很难靠肉眼发现所以建议在断言里加入常见乱码符号检查比如\ufffd、□等。5.2 PDF 表格提取与转 Excel 测试表格是 PDF 测试的重灾区。PDF 本身不保存表格结构只有线条和文字所以提取表格需要依赖版面分析。pdfplumber 可以提取包含边框的表格但如果表格没有边框线提取结果可能不稳定。准备一个带表格的 PDF然后执行提取import pdfplumber import pandas as pd def test_extract_table_to_excel(): with pdfplumber.open(samples/table_test.pdf) as pdf: page pdf.pages[0] tables page.extract_tables() assert len(tables) 1, PDF 中未提取到表格 table_data tables[0] # 第一行作为表头 headers table_data[0] rows table_data[1:] df pd.DataFrame(rows, columnsheaders) df.to_excel(output/table_output.xlsx, indexFalse) assert len(df) 1, 转换后的 Excel 没有数据行 print(表格行数:, len(df))这个测试有两个关键验证点一是表格是否被成功提取出来二是提取后的数据能否写入 Excel。实际项目中经常遇到“表格行数不对”“列错位”“数字变成科学计数法”等问题建议在测试中断言行数和关键单元格值而不仅仅是断言tables不为空。5.3 PDF 图片提取与扫描件 OCR 测试扫描版 PDF 没有文本层必须先把页面转成图片再做 OCR。这个流程在测试中属于耗时操作建议单独标记为慢测试不要在每次 CI 提交中都跑。先试试把 PDF 页面转成图片import fitz from PIL import Image def test_pdf_to_image(): doc fitz.open(samples/scan_test.pdf) page doc[0] pix page.get_pixmap(dpi200) pix.save(output/page_0.png) doc.close() img Image.open(output/page_0.png) assert img.width 0 and img.height 0 print(生成图片尺寸:, img.size)如果 PDF 里面有扫描图片可以用page.get_images(fullTrue)获取页面上引用的图片对象然后用doc.extract_image(xref)提取原图。这个操作适合验证图片是否完整嵌入而不是简单截图。OCR 测试依赖 tesseract。下面是一个最简单的调用示例from pdf2image import convert_from_path import pytesseract def test_ocr_pdf_text(): images convert_from_path(samples/scan_test.pdf, dpi150) text for img in images: text pytesseract.image_to_string(img, langchi_simeng) assert len(text.strip()) 0, OCR 未识别出任何文本 with open(output/ocr_result.txt, w, encodingutf-8) as f: f.write(text)OCR 的效果受原始扫描质量影响很大。分辨率、字体、对比度都会影响识别率。测试中不要只断言“有输出”更合适的做法是将 OCR 结果与人工标注的期望文本比较允许一定比例的字符差异。这个比例需要根据实际样本调整。5.4 PDF 转 Word 和 Word 转 PDF 验证大家搜索 PDF 转 Word 的频率很高作为测试方案重点不是“能不能转成功”而是“转换后内容是否对得上”。由于 Word 转 PDF 再转回 Word 会丢失部分排版建议采用文件级和文本级两层验证。文件级验证比较简单转出的 Word 必须能打开、页数不能为 0、文件大小要合理。文本级验证则需要先解压 Word 中的 XML再提取文本。下面是一个不依赖第三方转换库的脚本思路import zipfile import re from pathlib import Path def extract_text_from_docx(docx_path): with zipfile.ZipFile(docx_path, r) as z: xml_content z.read(word/document.xml).decode(utf-8) text re.sub(r[^], , xml_content) return text def test_docx_contains_keyword(): text extract_text_from_docx(output/converted.docx) assert Hello PDF Test in text, Word 文档中缺少源 PDF 的文本这里没有使用 python-docx 或者 LibreOffice而是直接读取 docx 压缩包中的 XML更轻量。实际操作中从 PDF 转 Word 通常需要调用 LibreOffice 或者在线转换接口转换结果会存放在指定目录然后再跑上面的断言。5.5 PDF 压缩与加密解密测试压缩和加密是常见的 PDF 操作。压缩测试要关注压缩率但不能只看文件变小还要看压缩后文本是否能正常提取。加密解密测试则要验证密码保护是否生效、解密后是否能读取。from pypdf import PdfReader, PdfWriter def test_encrypt_pdf(): reader PdfReader(samples/sample_test.pdf) writer PdfWriter() for page in reader.pages: writer.add_page(page) writer.encrypt(test123) with open(output/encrypted.pdf, wb) as f: writer.write(f) # 验证加密文件需要密码才能打开 encrypted_reader PdfReader(output/encrypted.pdf) assert encrypted_reader.is_encrypted, 文件未加密 encrypted_reader.decrypt(test123) assert len(encrypted_reader.pages) 0, 解密后页面为空压缩测试通常用 Ghostscript 或者 pikepdf 处理。pikepdf 在处理 PDF 压缩时比 PyPDF2 更稳定尤其是处理带图片的 PDF。压缩后仍然要跑一遍文本提取测试确认内容没有损坏。5.6 PDF 元数据与页面结构测试PDF 的页数、页面尺寸、书签和 Metadata 在很多业务流程中都很关键。例如上传系统要求 PDF 不能超过 10 页打印系统要求 PDF 页面必须是 A4这些都可以通过自动化断言来检查。import fitz def test_pdf_metadata_and_size(): doc fitz.open(samples/sample_test.pdf) metadata doc.metadata page doc[0] assert pdf in metadata.get(format, ).lower(), PDF 格式信息异常 assert page.rect.width 0 and page.rect.height 0, 页面尺寸异常 # 检查是否包含书签 toc doc.get_toc() print(书签数量:, len(toc)) doc.close()如果你的业务要求 PDF 必须包含标题、作者等元数据可以在这个测试中断言metadata中的具体字段。有些 PDF 没有设置 Metadata提取结果可能是空字符串需要提前确定业务规则。5.7 PDF 转二维码与链接测试热词里出现了“pdf转二维码”实际场景中更多是把 PDF 的下载链接或查看链接转成二维码方便线下快速访问。测试时先使用 qrcode 库生成二维码再用 pyzbar 识别确认识别出的内容等于原始 URL。import qrcode from pyzbar.pyzbar import decode from PIL import Image def test_pdf_url_qrcode(): url https://example.com/docs/sample_test.pdf qr qrcode.QRCode( version1, error_correctionqrcode.constants.ERROR_CORRECT_L, box_size10, border4, ) qr.add_data(url) qr.make(fitTrue) img qr.make_image(fill_colorblack, back_colorwhite) img.save(output/pdf_url_qrcode.png) # 识别二维码 decoded decode(Image.open(output/pdf_url_qrcode.png)) assert decoded and decoded[0].data.decode() url, 二维码识别结果与原始 URL 不一致这里是把 URL 编码到二维码并不把 PDF 内容直接变成二维码。PDF 内容本身不适合做二维码数据量太大。测试的目的是验证“生成→扫描→访问”链路是否可用。6. 接口 API 与批量任务把 PDF 测试能力封装成 HTTP 接口可以进一步接到其他系统里。尤其是在 CI 流水线或者自动化测试平台中经常需要通过接口上传 PDF然后返回解析结果。这里用 FastAPI 写一个简单的/api/pdf_check接口接收 PDF 文件返回页数、文本数量、是否能提取表格等信息。from fastapi import FastAPI, UploadFile, File import fitz import pdfplumber import io app FastAPI() app.post(/api/pdf_check) async def pdf_check(file: UploadFile File(...)): content await file.read() doc fitz.open(streamcontent, filetypepdf) text for page in doc: text page.get_text() # 解析表格 table_count 0 with pdfplumber.open(io.BytesIO(content)) as pdf: for page in pdf.pages: table_count len(page.extract_tables()) result { filename: file.filename, page_count: doc.page_count, char_count: len(text), table_count: table_count, } doc.close() return result启动接口服务uvicorn services.pdf_api:app --host 127.0.0.1 --port 8000用 curl 测试一下curl -X POST http://127.0.0.1:8000/api/pdf_check \ -F filesamples/sample_test.pdf如果服务正常会返回类似下面的 JSON{ filename: sample_test.pdf, page_count: 1, char_count: 36, table_count: 0 }批量任务可以放在一个独立脚本中遍历目录下的所有 PDF逐个调用接口或直接调用函数并生成一个汇总报告。不需要引入复杂的任务队列只要目录规模在几千个文件以内用 Python 的concurrent.futures就能并行处理。from pathlib import Path import concurrent.futures def process_pdf(pdf_path): # 这里调用上面封装好的解析函数 return pdf_path.name, pdf_path.stat().st_size pdf_files list(Path(samples).glob(*.pdf)) with concurrent.futures.ThreadPoolExecutor(max_workers4) as executor: results executor.map(process_pdf, pdf_files) for name, size in results: print(name, size)批量处理时要注意给每个文件增加超时控制避免某个损坏的 PDF 卡住整个流程。如果使用接口调用还要设置请求超时比如timeout30。7. 资源占用与性能观察PDF 测试看起来只是文件解析但一旦进入批量或 OCR 场景性能问题会很明显。建议在测试环境中重点观察三类指标CPU 使用率、内存占用、单文件处理时间。对于常规文本 PDFPyMuPDF 的解析速度通常非常快文件只要不是特别大单文件耗时在几百毫秒以内。但 pdfplumber 的表格解析比纯文本提取慢很多因为要做版面分析。对扫描件做 OCR 是最耗资源的不仅 CPU 占用高内存也会随着图片分辨率上升而增加建议把扫描件测试单独设置一个线程数上限。观察资源占用可以用psutil在脚本内采样也可以在外部用系统监控工具。下面是一个简单的测试耗时统计方法import time import psutil def measure_pdf_parse_time(pdf_path): process psutil.Process() start_cpu process.cpu_percent(intervalNone) start_time time.time() # 解析逻辑 import fitz doc fitz.open(pdf_path) text for page in doc: text page.get_text() doc.close() elapsed time.time() - start_time print(f耗时: {elapsed:.2f}s, CPU%: {start_cpu}) return elapsed值得强调的是不同环境下这些数字差异很大。你不需要关心别人的机器跑多快只要设置一个相对合理的基线比如“单个文本 PDF 解析小于 5 秒”“OCR 单页小于 30 秒”超过基线就要排查。这个基线要通过多次运行取平均值来定不能拍脑袋。降低资源占用的几个常见手段文本解析用 PyMuPDF 而不是 pdfplumberOCR 前把页面降采样到 150 DPI 左右批量任务采用限制并发数而不是无限线程PDF 文件很大时先拆分再处理避免一次性读入内存。8. 常见问题与排查方法自己在写 PDF 测试脚本时最容易遇到下面这些问题。问题现象可能原因排查方式解决方案ModuleNotFoundError: No module named fitzPyMuPDF 未安装或安装失败检查pip list中是否有 PyMuPDF执行pip install pymupdf确认版本中文文本提取出来是乱码PDF 未嵌入字体或使用了非标准编码用阅读器打开确认文字是否可选更换生成 PDF 的工具或使用 OCR 方案pdfplumberextract_tables()返回空列表PDF 表格没有明显的边框线先查看页面对象确认表格结构调整表格提取参数或先转换为图片再识别OCR 报找不到 tesseract系统未安装 tesseract 引擎在终端执行tesseract --version安装 tesseract并配置环境变量pdfplumber 打开 PDF 报错文件损坏、加密或有特殊结构先检查文件能否被阅读器打开加密 PDF 先解密再解析损坏文件跳过端口被占用导致 uvicorn 启动失败8000 端口已被其他服务占用执行lsof -i:8000或netstat -ano换一个端口启动例如--port 8001批量任务卡住某个 PDF 文件损坏或网络请求超时加日志打印当前处理文件增加 per-file 超时和失败重试逻辑转换后的 Excel 数据错位表格边框不完整或合并单元格对比原始 PDF 的表格结构先清洗表头再将合并单元格拆分表格里的问题在第一批测试脚本中几乎都会遇到。遇到问题不要急着改业务代码先确认是不是测试样本本身有问题。建议准备至少 3 种不同类型的 PDF纯文本、带复杂表格、扫描图片分别覆盖不同解析路径。9. 最佳实践与使用建议9.1 测试样本单独管理PDF 测试样本要放在独立目录并且保持稳定。不要拿生产环境里的临时文件当测试样本因为内容可能会变测试结果不可复现。样本文件命名建议带上用途例如text_sample.pdf、table_sample.pdf、scan_sample.pdf。如果样本涉及客户数据要脱敏后再使用或者直接用脚本生成类似数据。9.2 第一次先小参数跑通很多同学一上来就写完整流程结果环境还没准备好就输出一堆报错。更稳妥的做法是先跑通一个最简单的文本提取测试确认 Python、PyMuPDF、pytest 三个环节正常再逐步增加表格、OCR、接口测试。每增加一个能力就多一个可验证的测试用例而不是堆一堆代码后一起调试。9.3 把测试断言写具体断言不要只写“结果不为空”要尽量检查内容值。比如提取表格后不只断言len(rows) 0还要断言表头是否等于预期、第一行第一个单元格是否等于某个值。这样在后续代码改动中才能快速定位是哪一个字段出了问题。9.4 接入 CI 并保留失败现场推荐把 pytest 测试接入 CI。一旦测试失败直接把失败的 PDF 文件、提取出的文本、报错信息一起保留到输出目录方便查看。对于 OCR 这类不稳定测试可以允许一定的失败率但主流程的文本提取和表格提取测试必须可靠。9.5 注意合规与安全最后再强调一次PDF 中可能包含敏感信息。批量解析、转换、OCR 之前先确认文件是否获得了授权是否涉及个人信息、版权内容或商业机密。测试脚本中处理完的临时文件要及时清理不要把客户 PDF 留在公共网盘或测试服务器上。如果有人脸、声音、身份信息等内容更要严格遵守隐私保护要求。10. 总结与下一步“Tests for a PDF”看起来像是一个很窄的题目真正展开之后你会发现它其实覆盖了文本提取、表格解析、OCR、格式转换、加密解密、接口封装和批量处理一整条链路。对于正在做文档处理或知识库集成的团队来说这套测试脚本不是额外负担而是保证解析质量稳定的一层安全网。建议先跑通文本提取和表格提取两个基础测试把测试样本、输出目录、pytest 配置一次性准备好。之后再把接口服务和批量处理加进来最后才是 OCR 这种重资源场景。最容易踩的坑往往不是 PDF 解析算法本身而是环境依赖和样本数据不干净所以先固定环境版本再固定样本最后再讨论功能优化。后续可以继续扩展的方向包括把测试报告接入企业微信或钉钉告警、用 AI 模型辅助识别版面结构、把测试样本集扩大到更多 PDF 变体。这个方向继续做下去文档处理质量就会从“人工抽查”变成“自动回归”价值会越来越明显。