开发与测试
add-test-fixture
Add a deterministic PDF test fixture via gen_fixtures.rs with hand-computed expected geometry. Use when a new feature or bug fix needs a PDF exercising specific structure (fonts, forms, rotation, images, annotations, malformed content).
F2-AI-Inc · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add F2-AI-Inc/docray --skill add-test-fixture技能说明
name: add-test-fixture description: Add a deterministic PDF test fixture via gen_fixtures.rs with hand-computed expected geometry. Use when a new feature or bug fix needs a PDF exercising specific structure (fonts, forms, rotation, images, annotations, malformed content).
Adding a test fixture
Fixtures are generated, never downloaded or hand-crafted binaries — the
generator is crates/docray-pdf/examples/gen_fixtures.rs (lopdf-based).
Real-world PDFs must not be committed (size, licensing, and privacy).
Rules
- Deterministic: no timestamps, no randomness. Running the generator
twice must produce byte-identical files — CI enforces this
(
gen_fixturesthengit diff --exit-code testdata/). - Compute expected geometry by hand before writing the test. Example:
text at PDF-space
(72, 720)on a 612×792 page lands at top-left-spacey ≈ 792 − 720 − ascent. Put the arithmetic in a comment next to the assertion. Tolerances: ±2pt for glyph loose bounds (platform font substitution), exact for rects/images/annotations you placed yourself. - Placement in
testdata/:- Top level (
testdata/foo.pdf) → automatically picked up by the golden harness; you must generate its golden (see theregenerate-goldensskill) and eyeball it against your hand math before committing. testdata/malformed/→ crash-corpus; excluded from goldens; test via CLI exit codes / warnings instead.testdata/encrypted/→ excluded from goldens (extraction fails by design).
- Top level (
- Write the test at the level the behavior lives: extraction behavior
in
crates/docray-pdf/tests/, CLI contract incrates/docray-cli/tests/, HTTP behavior incrates/docray-server/tests/. - A fixture earns its place by pinning behavior no existing fixture pins —
check what
simple.pdf,form.pdf,rotated.pdf,image.pdf,link.pdf, andscan.pdfalready cover first.
lopdf tips (learned the hard way)
- Build pages via the existing
base_doc()helper; reuse the deterministic 2×2 gray image for image content. - Form XObjects: a
StreamwithType: XObject, Subtype: Form, BBox, invoked withq <matrix> cm /Fx Do Q— thecmmatrix is how PowerPoint places things, so prefer it over/Matrixentries. - After changing the generator, regenerate twice and confirm
git statusshows only your intended new/changed files.