Test utilities

The render, parse, assert, and snapshot exports of @lupinum/nuxt-pdf/test.

@lupinum/nuxt-pdf/test exposes the helpers Nuxt PDF is tested with. They are runner-agnostic (they throw PdfAssertionError, not Vitest/Jest matchers) and load pdfjs-dist and @napi-rs/canvas lazily. See Testing your PDFs for a worked example.

renderPdfTemplate

const { bytes, parsed } = await renderPdfTemplate(Component, props)

Renders a Vue PDF component through the real registry pipeline, with or without a definePdf block. Returns the raw bytes, immutable result, and a parsed document. Options use the same input shapes as pdf.remote and pdf.limits, so partial limits and URL-prefix allowlists can be shared with nuxt.config.

Use renderPdfSfc when the document depends on discovered local images or custom font files. Prepared asset maps, embedded font descriptors, and template attribution are registry internals and are not public test configuration.

renderPdfSfc

const rendered = await renderPdfSfc('./pdfs/invoice.vue', props, {
  fonts: [{ family: 'Invoice Sans', src: 'InvoiceSans-Regular.ttf' }],
})

Compiles a real template and its nested child SFCs with the production compiler, discovers and validates pdfs/assets, and bundles the declared faces from pdfs/fonts. Its options mirror pdf.fonts, pdf.remote, and pdf.limits; the application root and template identity are inferred from the pdfs/*.vue path. loadPdfSfc exposes only the compile step when a test needs the Vue component separately.

parsePdf

const parsed = await parsePdf(input)

Accepts PDF bytes (Uint8Array/ArrayBuffer/Buffer) or a PdfRenderResult straight from the #pdf registry. Returns page text, page count, flattened link annotations (named destination or external URL), and the outline hierarchy with its initial expanded/collapsed state.

expectPdf

expectPdf(parsed)
  .toHavePageCount(2)
  .toContainText('Invoice for Acme Corp', { page: 1 })
  .toHaveLink({ destination: 'terms', page: 1 })
  .toHaveLink({ url: 'https://example.com/' })
  .toHaveOutline([{ title: 'Terms', expanded: true }])

A chainable expectation that throws PdfAssertionError with an actionable message on failure.

Method	Checks
`toHavePageCount(n)`	Page count equals `n`
`toContainText(text, { page? })`	Extracted text contains `text`
`toHaveLink({ destination?, url?, page? })`	A matching link annotation exists
`toHaveOutline(shape)`	The outline matches the title hierarchy and any requested expansion states

rasterizePdf and comparePdfSnapshot

await comparePdfSnapshot(bytes, './test/baselines/invoice')

rasterizePdf renders pages to PNGs; comparePdfSnapshot implements the reviewed-baseline flow. It writes per-page baselines when UPDATE_PDF_BASELINES=1 (or { update: true }) and otherwise compares within a pixel threshold.

parsePdf also returns page dimensions and normalized textRuns with text, position, size, font name, direction, width, and height. Use tolerant numeric assertions for geometry because font and raster backends can vary slightly between supported environments.

When a raster comparison fails, the helper checks every page and writes expected, actual, and diff PNGs plus a machine-readable metrics.json to reports/pdf-snapshots/<baseline-name>. Pass { artifactDir } to choose a different CI artifact directory.

All exports

Export	Kind	Purpose
`renderPdfTemplate`	function	Render a component through the real pipeline
`renderPdfSfc`	function	Compile and render a real nested `pdfs/*.vue` graph
`loadPdfSfc`	function	Compile a PDF SFC graph into a Vue component
`parsePdf`	function	Parse bytes or a render result into a `ParsedPdf`
`rasterizePdf`	function	Render pages to PNG images
`comparePdfSnapshot`	function	Reviewed-baseline raster comparison
`toPdfBytes`	function	Normalize inputs to PDF bytes
`expectPdf`	function	Fluent, runner-agnostic assertions
`PdfAssertionError`	class	Thrown by assertions on failure
`ParsedPdf`, `ParsedPdfPage`, `ParsedPdfTextRun`, `ParsedPdfLink`, `PdfOutlineItem`, `PdfInput`, `PdfPageImage`, and related types	types	Parser and helper types

pdfjs-dist and @napi-rs/canvas are optional peer dependencies; install them in the project under test. They are absent from the module's production dependency graph.