Documentation
¶
Overview ¶
Package pdforacle judges PDF output with programs that share no code with the PDF library under test: qpdf's JSON dump and checker for structure, Poppler's pdftotext for page text, and pdfinfo and pdftoppm for geometry. It deliberately does not import pdfcpu or the engine.
A Document is the structure of one file; Verify compares it with an Expectation written from the inputs (source page markers, link graphs, geometry) and returns the checks that failed. A test that should detect corruption is a negative control: it feeds Verify a wrong Expectation and requires the matching check to fail.
Index ¶
- Constants
- func Failed(findings []Finding) []string
- func HasMuPDF() bool
- func QPDFJSON(tools Tools, path string) ([]byte, error)
- type Document
- func (d *Document) AppearanceDifference(page int, source *Document, sourcePage int, tolerance uint8) (float64, error)
- func (d *Document) Attachments() int
- func (d *Document) CatalogKeys() []string
- func (d *Document) CatalogVersion() string
- func (d *Document) ColorCounts(number int, colors [][3]uint8) ([]int, error)
- func (d *Document) EffectiveVersion() int
- func (d *Document) FirstLine(number int) string
- func (d *Document) InfoKeys() []string
- func (d *Document) MuPDFRaster(number int) (image.Image, error)
- func (d *Document) ObjectCount() int
- func (d *Document) PageCount() int
- func (d *Document) PageObjects() []string
- func (d *Document) PixelColor(number, x, y int) ([3]uint8, error)
- func (d *Document) Raster(number int) (image.Image, error)
- func (d *Document) RawTexts() ([]string, error)
- func (d *Document) RenderedSize(number int) (int, int, error)
- func (d *Document) UserUnit(number int) float64
- func (d *Document) Verify(exp Expectation) []Finding
- type Expectation
- type ExpectedPage
- type Finding
- type Geometry
- type SourceFact
- type Tools
Constants ¶
const ( CheckStructure = "qpdf-check" CheckPageCount = "page-count" CheckPageText = "page-text-order" CheckDistinctPages = "distinct-page-dicts" CheckAnnotMembership = "annot-membership-per-page" CheckAnnotParent = "annot-P-is-own-page" CheckLinkDangling = "link-dest-not-dangling" CheckLinkInTree = "link-dest-in-output-page-tree" CheckLinkOccurrence = "link-dest-same-occurrence" CheckLinkPage = "link-dest-right-source-page" CheckNamedDests = "named-dests-reach-output-pages" CheckFormRoots = "form-widgets-reach-AcroForm-Fields" CheckFormParents = "form-parent-refs-resolve" CheckFormWidgets = "form-fields-have-page-widgets" CheckGeometry = "geometry-effective-attrs" CheckVersion = "output-version>=max-input" CheckOutlines = "outline-dests-reach-output-pages" CheckOrphanPages = "no-orphan-page-objects" )
Names of the checks Verify runs; Finding.Check holds one of them.
const RequireToolsEnv = "PDFCONCAT_REQUIRE_QA_TOOLS"
RequireToolsEnv names the environment variable that turns missing QA tools from a skip into a failure. CI sets it to "1"; a developer without the tools only loses these checks locally.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Document ¶
type Document struct {
// Path is the file.
Path string
// Version is the header version reported by qpdf, for example "1.7".
Version string
// contains filtered or unexported fields
}
Document is the parsed structure of one PDF file.
func (*Document) AppearanceDifference ¶
func (d *Document) AppearanceDifference(page int, source *Document, sourcePage int, tolerance uint8) (float64, error)
AppearanceDifference compares independent full-page rasterizations. The result is the fraction of pixels with a channel differing by more than tolerance; positions and image marks matter.
func (*Document) Attachments ¶
Attachments is the number of embedded files qpdf finds.
func (*Document) CatalogKeys ¶
CatalogKeys returns the names of the catalog entries, such as "/Pages".
func (*Document) CatalogVersion ¶
CatalogVersion is the catalog /Version entry without its slash, or "".
func (*Document) ColorCounts ¶ added in v0.2.0
ColorCounts counts exact RGB landmarks across one independent whole-page rendering. It detects formerly hidden marks anywhere on a sheet without repeatedly rendering for each sampled pixel.
func (*Document) EffectiveVersion ¶
EffectiveVersion is the larger of the header version and the catalog /Version, as major*10+minor.
func (*Document) FirstLine ¶
FirstLine returns the first non-blank text line of page number (1-based), or "" when the page has none.
func (*Document) InfoKeys ¶
InfoKeys returns the keys of the trailer's /Info dictionary, such as "/Producer".
func (*Document) MuPDFRaster ¶ added in v0.2.0
MuPDFRaster uses MuPDF's fixed PNG/72dpi interface; it does not affect runtime PDF assembly.
func (*Document) ObjectCount ¶
ObjectCount is the number of objects qpdf reports in the file.
func (*Document) PageObjects ¶
PageObjects returns the object reference of each page in order.
func (*Document) PixelColor ¶
PixelColor returns the 8-bit red, green and blue of the pixel at (x, y), counted from the top-left corner, in the 72 dpi rendering of page number (1-based).
func (*Document) Raster ¶ added in v0.2.0
Raster returns one independent Poppler rendering for batch pixel comparisons.
func (*Document) RawTexts ¶
RawTexts extracts without Poppler's physical-layout spacing heuristic. This preserves explicit spaces in very small text, which -layout may infer away despite the PDF's correct text mapping.
func (*Document) RenderedSize ¶
RenderedSize returns the pixel width and height of page number (1-based) rendered at 72 dpi with the CropBox and rotation applied. Poppler rounds sizes up and does not apply UserUnit; multiply by UserUnit for the physical size.
func (*Document) UserUnit ¶
UserUnit returns the /UserUnit of page number (1-based), or 1 when the page has none.
func (*Document) Verify ¶
func (d *Document) Verify(exp Expectation) []Finding
Verify runs every check against exp and returns the failures; no findings means the output matches.
type Expectation ¶
type Expectation struct {
// Sources holds the facts of each named source.
Sources map[string]SourceFact
// Pages lists the output pages in order.
Pages []ExpectedPage
}
Expectation is everything Verify checks the output against.
type ExpectedPage ¶
type ExpectedPage struct {
// Geometry, when set, is the expected geometry (used for generated pages).
Geometry *Geometry
// Text is the first text line the page must show.
Text string
// Source names the source in Expectation.Sources, or "" for a generated page.
Source string
// Occurrence numbers the occurrence of the source, from 1, so links must stay within it.
Occurrence int
// SourcePage is the 1-based source page.
SourcePage int
}
ExpectedPage is one output page.
type Finding ¶
type Finding struct {
// Check is one of the Check constants.
Check string
// Detail says what was wrong.
Detail string
}
Finding is one failed check.
type Geometry ¶
type Geometry struct {
// MediaBox is the effective MediaBox.
MediaBox []float64
// CropBox is the effective CropBox; nil requires that none is in effect.
CropBox []float64
// Rotate is the effective rotation in [0, 360).
Rotate int
// UserUnit is the page's UserUnit; 0 means the default 1.
UserUnit float64
}
Geometry is the page attributes an output page must have in effect.
type SourceFact ¶
type SourceFact struct {
// Links maps a source page to the source pages its link annotations and actions must reach.
Links map[int][]int
// Geometry maps a source page to its expected attributes; absent pages are not checked.
Geometry map[int]Geometry
// Pages is the page count.
Pages int
// Version is the effective version as major*10+minor.
Version int
}
SourceFact is what the test knows about a source document independently of the engine.
type Tools ¶
type Tools struct {
QPDF, PDFToText, PDFInfo, PDFToPPM string
}
Tools are the independent QA programs: qpdf for structure, Poppler for text and geometry.
func RequireTools ¶
RequireTools locates the QA tools. When one is missing it fails the test if RequireToolsEnv is "1" and otherwise skips it.