From 33fcc89398d190f43c5b2a02dd0e5e6eb0666954 Mon Sep 17 00:00:00 2001 From: ".CooCoo" Date: Mon, 16 Nov 2026 18:35:17 -0800 Subject: [PATCH] craft-pdf: test-support exports the test PDF builder as craft_pdf::testing::Pdf (#1398) --- crates/pdf/Cargo.toml | 6 ++++ crates/pdf/README.md | 6 ++-- crates/pdf/src/cos.rs | 2 +- crates/pdf/src/cos/testkit.rs | 7 +++-- crates/pdf/src/lib.rs | 2 ++ crates/pdf/src/testing.rs | 16 ++++++++++ crates/pdf/tests/testing_pdf.rs | 52 +++++++++++++++++++++++++++++++++ 7 files changed, 85 insertions(+), 6 deletions(-) create mode 100644 crates/pdf/src/testing.rs create mode 100644 crates/pdf/tests/testing_pdf.rs diff --git a/crates/pdf/Cargo.toml b/crates/pdf/Cargo.toml index a04f030c1..f4c2d0b23 100644 --- a/crates/pdf/Cargo.toml +++ b/crates/pdf/Cargo.toml @@ -27,6 +27,8 @@ cos = ["crypt", "filters", "dep:chrono", "dep:js-sys", "dep:wasm-bindgen"] # tokenizer ends them. content = ["cos", "dep:hayro-syntax"] crypt = ["dep:aes", "dep:md-5", "dep:sha2", "dep:stringprep", "dep:zeroize", "dep:thiserror"] +# `testing`: a builder of small synthetic PDF files, for the tests of crates that read them. +test-support = ["cos"] [dependencies] hayro-syntax = { workspace = true, optional = true } @@ -72,6 +74,10 @@ proptest = { workspace = true } [target.'cfg(target_arch = "wasm32")'.dev-dependencies] wasm-bindgen-test = "0.3" +[[test]] +name = "testing_pdf" +required-features = ["test-support"] + [[example]] name = "cos_info" required-features = ["cos"] diff --git a/crates/pdf/README.md b/crates/pdf/README.md index a1332ce4f..f1de94d17 100644 --- a/crates/pdf/README.md +++ b/crates/pdf/README.md @@ -16,6 +16,7 @@ No feature is enabled by default. | `filters` | The `/Filter` chain for editing and writing PDF files: decode and encode, with limits and accounting. No reader or writer dependency | | `crypt` | The standard security handler: decrypt, encrypt and create encryption. No reader or writer dependency | | `cos` | `crypt` and `filters` plus the object layer: open, edit and save PDF files (incremental and full saves). No reader or writer dependency | +| `test-support` | `cos` plus `testing::Pdf`, a builder of small synthetic PDF files for tests | | `content` | `cos` plus `cos::content`: parse content streams into operators with source spans, write them back, and the matrix arithmetic. Uses hayro-syntax's tokenizer for inline images | ## Reading and rendering @@ -164,8 +165,9 @@ The code comes from PdfCraft's `pdfcraft-cos` crate (revision comments. Its test helpers come along: `src/cos/testkit.rs` (synthetic files, from `pdfcraft-testkit`) and `tests/cos/oracle.rs` (qpdf runs, from `pdfcraft-oracle`; a missing `qpdf` skips those tests, or fails them when `CRAFT_PDF_ORACLES_REQUIRED` is set). Tests: -`cargo test -p craft-pdf --no-default-features --features cos`. Examples: `cos_info` and -`cos_protect` (`--features cos`). +`cargo test -p craft-pdf --no-default-features --features cos`. Other crates' tests use the +builder as `craft_pdf::testing::Pdf` by enabling `test-support` in their dev-dependency on +`craft-pdf`. Examples: `cos_info` and `cos_protect` (`--features cos`). ## Stream filters diff --git a/crates/pdf/src/cos.rs b/crates/pdf/src/cos.rs index d67543041..cedd5eb35 100644 --- a/crates/pdf/src/cos.rs +++ b/crates/pdf/src/cos.rs @@ -23,7 +23,7 @@ mod parser; mod security; mod writer; -#[cfg(test)] +#[cfg(any(test, feature = "test-support"))] pub(crate) mod testkit; pub use crate::crypt::{ diff --git a/crates/pdf/src/cos/testkit.rs b/crates/pdf/src/cos/testkit.rs index 44e07b702..30b45bc1f 100644 --- a/crates/pdf/src/cos/testkit.rs +++ b/crates/pdf/src/cos/testkit.rs @@ -14,8 +14,9 @@ //! .build(); //! ``` //! -//! Test scaffolding: compiled into the unit tests (`cfg(test)`) and into the `cos` integration -//! test binary, never into the library. +//! Test scaffolding: compiled into the unit tests (`cfg(test)`), into the `cos` integration test +//! binary, and into the library only with the `test-support` feature, which exports [`Pdf`] as +//! `craft_pdf::testing::Pdf`. #![allow(dead_code)] /// A small PDF with a classic cross-reference table, built one object at a time. @@ -80,7 +81,7 @@ impl Pdf { /// The number the next object added will get, so a caller can refer forward to it. /// /// ``` - /// # use crate::cos::testkit::Pdf; + /// # use craft_pdf::testing::Pdf; /// let mut p = Pdf::new().obj("<< /Type /Catalog /Pages 2 0 R >>"); /// assert_eq!(p.next_obj(), 2); /// ``` diff --git a/crates/pdf/src/lib.rs b/crates/pdf/src/lib.rs index 7356ab743..8893a84b0 100644 --- a/crates/pdf/src/lib.rs +++ b/crates/pdf/src/lib.rs @@ -25,6 +25,8 @@ pub use read::*; pub mod paths; #[cfg(feature = "raster")] pub mod raster; +#[cfg(all(feature = "cos", any(test, feature = "test-support")))] +pub mod testing; #[cfg(feature = "write")] pub mod write; #[cfg(feature = "write-raster")] diff --git a/crates/pdf/src/testing.rs b/crates/pdf/src/testing.rs new file mode 100644 index 000000000..c829f5458 --- /dev/null +++ b/crates/pdf/src/testing.rs @@ -0,0 +1,16 @@ +//! Test support (feature `test-support`): builds small synthetic PDF files in code, so that crates +//! which read PDF files can test with a real file instead of a binary fixture. +//! +//! ``` +//! use craft_pdf::testing::Pdf; +//! +//! let bytes = Pdf::new() +//! .obj("<< /Type /Catalog /Pages 2 0 R >>") +//! .obj("<< /Type /Pages /Kids [3 0 R] /Count 1 >>") +//! .obj("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 300] /Contents 4 0 R >>") +//! .stream("", b"0 0 50 50 re f") +//! .build(); +//! assert!(bytes.starts_with(b"%PDF-1.7\n")); +//! ``` + +pub use crate::cos::testkit::Pdf; diff --git a/crates/pdf/tests/testing_pdf.rs b/crates/pdf/tests/testing_pdf.rs new file mode 100644 index 000000000..81fa98189 --- /dev/null +++ b/crates/pdf/tests/testing_pdf.rs @@ -0,0 +1,52 @@ +//! `craft_pdf::testing::Pdf`, the builder other crates' tests reach through `test-support`: a file +//! it builds opens in the object layer with every object where the cross-reference table says. +#![cfg(feature = "test-support")] +#![allow(clippy::unwrap_used, clippy::panic)] + +use std::sync::Arc; + +use craft_pdf::cos::{Document, ObjRef, Object, XrefEntry}; +use craft_pdf::testing::Pdf; + +fn one_page() -> Pdf { + Pdf::new() + .version("1.4") + .obj("<< /Type /Catalog /Pages 2 0 R >>") + .obj("<< /Type /Pages /Kids [3 0 R] /Count 1 >>") + .obj("<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 300] /Contents 4 0 R >>") + .stream("", b"0 0 50 50 re f") + .trailer_entry("/Info 5 0 R") + .obj("<< /Title (Fixture) >>") +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[cfg_attr(not(target_arch = "wasm32"), test)] +fn a_built_file_opens_without_repair() { + let bytes = one_page().build(); + assert!(bytes.starts_with(b"%PDF-1.4\n")); + assert!(bytes.ends_with(b"%%EOF\n")); + + let doc = Document::open(Arc::new(bytes)).unwrap(); + assert!(!doc.reconstructed(), "the cross-reference table is exact: {:?}", doc.repair_log()); + assert_eq!(doc.version(), "1.4"); + assert_eq!(doc.root(), Some(ObjRef::new(1, 0))); + for num in 1..=5 { + assert!(matches!(doc.xref_entry(num), Some(XrefEntry::InFile { generation: 0, .. })), "object {num} is in the table"); + assert!(doc.xref_entry_is_exact(num), "object {num} is at its table offset"); + } + assert_eq!(doc.xref_entry(6), None); + let Object::Stream(contents) = &*doc.get(ObjRef::new(4, 0)) else { panic!("object 4 is the content stream") }; + assert_eq!(contents.decoded().unwrap(), b"0 0 50 50 re f"); + assert_eq!(doc.trailer().get(b"Info"), Some(&Object::Ref(ObjRef::new(5, 0)))); +} + +#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)] +#[cfg_attr(not(target_arch = "wasm32"), test)] +fn next_obj_names_the_object_added_next() { + let pdf = one_page(); + assert_eq!(pdf.next_obj(), 6); + let doc = Document::open(Arc::new(pdf.obj("<< /Marker true >>").build())).unwrap(); + assert!(matches!(doc.xref_entry(6), Some(XrefEntry::InFile { .. }))); + assert!(doc.xref_entry_is_exact(6)); + assert_eq!(doc.dict(&doc.get(ObjRef::new(6, 0))).and_then(|d| d.get(b"Marker").cloned()), Some(Object::Bool(true))); +}