marcel/familienarchiv
1
0
Fork 0
Code Issues 119 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

[test] Playwright e2e: PDF render-decode correctness across image codecs (CCITT/JBIG2/JPEG/JPX + multi-page + text-only) #714

New Issue
Open
opened 2026-06-01 21:22:32 +02:00 by marcel · 0 comments
marcel commented 2026-06-01 21:22:32 +02:00
Owner
Copy Link

Context

Follow-up to #708 / PR #713. That fix configured pdf.js 5.x wasmUrl so CCITT/JBIG2/JPEG2000 scans stop rendering blank, and serves the wasm from /pdfjs-wasm/.

In #713 we attempted an in-browser vitest behavioral test (render a committed fixture with the real pdf.js loader, assert the canvas is non-blank). It was green locally but flaky in CI — the pdf.js worker could not fetch /pdfjs-wasm/ in the CI Chromium container, so the canvas stayed blank. That test was removed in favour of deterministic guards:

  • unit guard — getDocument is called with a non-null wasmUrl ending in /;
  • build-output guard — frontend/scripts/assert-pdfjs-wasm.mjs (postbuild) asserts jbig2.wasm/openjpeg.wasm ship into build/client/pdfjs-wasm/;
  • manual — node build serves /pdfjs-wasm/jbig2.wasm → 200 application/wasm.

These cover the regression deterministically, but no automated test asserts a real page actually paints. Sara (QA) and Elicit (Requirements) flagged this gap on #713; this issue tracks closing it properly.

Why e2e, not vitest browser mode

The vitest browser server's serving of /pdfjs-wasm/ (and pdf.js worker behaviour) is environment-fragile in CI. A Playwright e2e test runs against a real built server (npm run build && npm run preview, or the adapter-node node build), where /pdfjs-wasm/ is served from build/client/ exactly as in production — the reliable place to assert real rendering. frontend/e2e/ already exists with Playwright configured and e2e/fixtures/*.pdf.

Scope

Add a Playwright e2e spec that, against a built+served frontend, renders PDFs through the document viewer and asserts the page canvas is non-blank (sample the canvas via page.evaluate + getImageData, count non-background pixels > threshold — mirror the pixel oracle from the removed vitest test).

Codec / structure matrix (one fixture per row)

  • CCITTFax (G4) — non-blank. This is the actual #708 failure class; exercises the shared jbig2.wasm module.
  • JBIG2 — non-blank. Same jbig2.wasm path; needs a real JBIG2 fixture (no jbig2enc was available when #713 was done — source a small public-domain sample or generate one in CI).
  • DCTDecode (JPEG) — non-blank (no-regression; decodes natively).
  • JPEG2000 / JPXDecode — non-blank (covered by openjpeg.wasm); assert if a fixture can be produced, else explicitly skip with a note.
  • Multi-page mixed-codec (e.g. page 1 JPEG + page 2 CCITT, via pdfunite) — both pages and the page between render.
  • Text-only (no image XObject — e2e/fixtures/minimal.pdf already qualifies) — renders, guards over-scoping.
  • Console-warning assertion — fail if JBig2 failed to initialize / wasmUrl warnings appear in the page console.

Fixtures

  • Hermetic, committed (synthesize with ImageMagick: -compress Group4 for CCITT, -compress JPEG for DCT; pdfunite to build the mixed-codec doc). Do not fetch from staging at test time.
  • A document-viewer route needs a document with a file; either seed one in the e2e setup or add a minimal harness route that renders PdfViewer against a fixture URL (prefer the former to avoid test-only routes).

Acceptance criteria

  • A Playwright e2e spec covering the matrix above passes in CI against the built frontend (not the vitest dev server).
  • The CCITT case is demonstrably load-bearing: it fails (blank) if wasmUrl is removed from getDocument.
  • No wasmUrl / JBig2 failed to initialize console warnings on affected docs.
  • Runs in the existing frontend/e2e/ Playwright setup; documented in the test how to regenerate fixtures.

Out of scope

  • Re-introducing an in-browser vitest render gate (the fragile path #713 removed).
  • standardFontDataUrl / iccUrl (still no affected document found).

References

  • #708, PR #713 (the deterministic guards + ADR-028)
  • frontend/src/lib/document/viewer/usePdfRenderer.svelte.ts (WASM_URL), frontend/scripts/assert-pdfjs-wasm.mjs, docs/adr/028-pdfjs-wasm-decoders-and-csp-constraint.md
## Context Follow-up to #708 / PR #713. That fix configured pdf.js 5.x `wasmUrl` so CCITT/JBIG2/JPEG2000 scans stop rendering blank, and serves the wasm from `/pdfjs-wasm/`. In #713 we attempted an **in-browser vitest** behavioral test (render a committed fixture with the real pdf.js loader, assert the canvas is non-blank). It was **green locally but flaky in CI** — the pdf.js worker could not fetch `/pdfjs-wasm/` in the CI Chromium container, so the canvas stayed blank. That test was removed in favour of deterministic guards: - **unit guard** — `getDocument` is called with a non-null `wasmUrl` ending in `/`; - **build-output guard** — `frontend/scripts/assert-pdfjs-wasm.mjs` (postbuild) asserts `jbig2.wasm`/`openjpeg.wasm` ship into `build/client/pdfjs-wasm/`; - **manual** — `node build` serves `/pdfjs-wasm/jbig2.wasm` → 200 `application/wasm`. These cover the regression deterministically, but **no automated test asserts a real page actually paints**. Sara (QA) and Elicit (Requirements) flagged this gap on #713; this issue tracks closing it properly. ## Why e2e, not vitest browser mode The vitest browser server's serving of `/pdfjs-wasm/` (and pdf.js worker behaviour) is environment-fragile in CI. A **Playwright e2e** test runs against a **real built server** (`npm run build && npm run preview`, or the adapter-node `node build`), where `/pdfjs-wasm/` is served from `build/client/` exactly as in production — the reliable place to assert real rendering. `frontend/e2e/` already exists with Playwright configured and `e2e/fixtures/*.pdf`. ## Scope Add a Playwright e2e spec that, against a built+served frontend, renders PDFs through the document viewer and asserts the page canvas is **non-blank** (sample the canvas via `page.evaluate` + `getImageData`, count non-background pixels > threshold — mirror the pixel oracle from the removed vitest test). ### Codec / structure matrix (one fixture per row) - [ ] **CCITTFax (G4)** — non-blank. This is the actual #708 failure class; exercises the shared `jbig2.wasm` module. - [ ] **JBIG2** — non-blank. Same `jbig2.wasm` path; needs a real JBIG2 fixture (no `jbig2enc` was available when #713 was done — source a small public-domain sample or generate one in CI). - [ ] **DCTDecode (JPEG)** — non-blank (no-regression; decodes natively). - [ ] **JPEG2000 / JPXDecode** — non-blank (covered by `openjpeg.wasm`); assert if a fixture can be produced, else explicitly skip with a note. - [ ] **Multi-page mixed-codec** (e.g. page 1 JPEG + page 2 CCITT, via `pdfunite`) — both pages and the page between render. - [ ] **Text-only** (no image XObject — `e2e/fixtures/minimal.pdf` already qualifies) — renders, guards over-scoping. - [ ] **Console-warning assertion** — fail if `JBig2 failed to initialize` / `wasmUrl` warnings appear in the page console. ### Fixtures - Hermetic, committed (synthesize with ImageMagick: `-compress Group4` for CCITT, `-compress JPEG` for DCT; `pdfunite` to build the mixed-codec doc). Do **not** fetch from staging at test time. - A document-viewer route needs a document with a file; either seed one in the e2e setup or add a minimal harness route that renders `PdfViewer` against a fixture URL (prefer the former to avoid test-only routes). ## Acceptance criteria - [ ] A Playwright e2e spec covering the matrix above passes in CI against the **built** frontend (not the vitest dev server). - [ ] The CCITT case is demonstrably **load-bearing**: it fails (blank) if `wasmUrl` is removed from `getDocument`. - [ ] No `wasmUrl` / `JBig2 failed to initialize` console warnings on affected docs. - [ ] Runs in the existing `frontend/e2e/` Playwright setup; documented in the test how to regenerate fixtures. ## Out of scope - Re-introducing an in-browser **vitest** render gate (the fragile path #713 removed). - `standardFontDataUrl` / `iccUrl` (still no affected document found). ## References - #708, PR #713 (the deterministic guards + ADR-028) - `frontend/src/lib/document/viewer/usePdfRenderer.svelte.ts` (`WASM_URL`), `frontend/scripts/assert-pdfjs-wasm.mjs`, `docs/adr/028-pdfjs-wasm-decoders-and-csp-constraint.md`
marcel added the P2-mediumtest labels 2026-06-01 21:22:36 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
P0-critical
Blocks a core user journey, causes data loss, or is a security/accessibility barrier. Work on this before P1+.
 P1-high
Significant friction on a main user journey; workaround exists but is non-obvious. Next up after P0.
 P2-medium
Noticeable improvement; doesn't block anything; schedule opportunistically.
 P3-later
Cosmetic or parking-lot work; fine to stay open indefinitely.
 audit
Read-only audit / assessment work; produces a report rather than changing code
 bug
Something isn't working
 cleanup
Removal of dead code, vague comments, naming violations, and scratch artifacts
 collaboration
We want to extend the family archive to have more collaboration tools
 conversation
descoped
We will do that later
 devops
documentation
README, ARCHITECTURE, GLOSSARY, CONTRIBUTING, per-domain docs
 epic
Marker for epic-level issues that group multiple child issues
 feature
file-upload
legibility
Codebase Legibility Refactor — preparing the codebase for human evaluation and bus-factor reduction
 needs-discussion
Has an open decision or design question that must be resolved before implementation can start.
 notification
person
phase-1: security
Security hygiene — must be done first
 phase-2: container-images
Production-ready multi-stage Docker images
 phase-3: prod-compose
Production compose overlay + Caddy reverse proxy
 phase-4: spring-prod-profile
Spring Boot production configuration profile
 phase-5: backups
Database and object storage backup strategy
 phase-6: deployment-docs
.env.example, DEPLOYMENT.md, runbook
 phase-7: monitoring
Prometheus, Loki, Grafana, Alertmanager
 refactor
Code restructuring without behaviour change
 security
test
ui
UI/UX and accessibility issues
 user
No Label P2-medium test
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
Jens marcel
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: marcel/familienarchiv#714
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?