Run from the repository root. See Contributing for setup and architecture for source ownership. Omit mise exec -- when Elixir/Erlang are already on your PATH.

Focused checks

CheckCommand
One suitemise exec -- mix test test/html_to_pdf/tables/atomic_table_overflow_test.exs
Formattingmise exec -- mix format --check-formatted
Coveragemise exec -- mix test --cover --warnings-as-errors
DialyzerMIX_ENV=test mise exec -- mix dialyzer
Performancemise exec -- ./scripts/check-performance

Run focused checks while working and the full matrix before submitting a PR.

Full quality matrix

./scripts/quality-matrix
PrerequisiteRequirement
ToolsRunning Docker, Git, tar, jq, Bash 4+
LinuxDocker
macOSDocker Desktop and Bash 4+
WindowsWSL2 with Docker Desktop integration; native PowerShell/Command Prompt unsupported
StorageWritable checkout and .quality/

The runtime matrix is shared with CI:

ElixirImage
1.19sigdevelopers/native-elixir-pdf-ci:elixir-1.19
1.20, canonicalsigdevelopers/sigportal-ci:v2.8
CheckEvery runtimeCanonical only
Compile with warnings as errorsYes
Ordinary tests and Chromium parityYes
100% coverage, including ordinary testsYes
Formatting, unused dependencies, DialyzerYes
Performance guards/reportYes
Runner behaviorDetails
ImagesInclude Chromium, Poppler and fonts; missing images pulled, immutable IDs recorded. Refresh deliberately with docker pull <image>
SourceTracked and non-ignored untracked bytes, including edits, frozen in .quality/logs/<run>/source.tar
IsolationSeparate source copies, outputs and runtime caches; application build cleaned before compile
ConcurrencyTwo correctness lanes; QUALITY_MATRIX_JOBS=1 runs serially
PerformanceStarts after all local correctness containers exit; CI runs it after ordinary checks on a runner separate from browser parity
FailuresLater stages skip for that runtime; other runtimes continue
Lock recoveryInspect .quality/matrix.lock PID and pdf-quality-<run>-* containers; remove only after confirming the run stopped
CI agreementSame check policy and --matrix-json validation; host orchestration tests cover concurrency, isolation, failure reporting, performance ordering and future-runtime policy
Canonical runtimeNewest supported minor; coverage already includes its ordinary suite
Runtime updatesOnce a 1.21 image is available, add it to the matrix, keep three minors and measure its performance baseline

Keep browser cases and performance thresholds unchanged.

Results and warnings

Evidence under .quality/logs/<run>/Contains
results.tsvRuntime, stage, result, warning count, log path and seconds
Per-runtime logs/workspacesStage logs, container-checks.log and generated outputs
Canonical performance filescontainer-performance.log and performance.json
Source/configuration/image IDsIdentity of the validated inputs and runtimes
ResultAction
PASSPassed; still inspect warning counts
FAIL / WARNRead the referenced log; resolve project issues and identify third-party warnings/upstream fixes
SKIPFix the earlier failure
N/AExpected for canonical-only checks, or tests already included in coverage

A successful exit can include warnings. Report commands, runtimes, results and unresolved issues in the PR. Fix failures, rerun affected checks and require the complete matrix to pass before review readiness.

Counts include plain warning: messages and file:line[:column]: Warning: diagnostics, with terminal colours ignored. Project and third-party warnings both count. Use source paths and the dependency or PLT-build context in the stage log to identify their origin; a bare filename alone does not establish ownership.

Publishing documentation

Use the latest supported runtime when preparing a package:

MIX_ENV=dev mise exec -- mix deps.compile
MIX_ENV=dev mise exec -- mix docs --warnings-as-errors

Resolve errors before publishing. Documentation builds are excluded from routine matrix/CI checks.

Browser parity

Visible rendering changes require focused unit coverage and a Chromium fixture. Every supported runtime runs the full parity suite.

CI runs three file partitions per runtime on separate runners, alongside the ordinary checks. Every test file belongs to exactly one partition. The existing Elixir <version> checks require all jobs to pass. Local matrix lanes run the same three partitions sequentially to avoid competing browser workloads on one machine. The large generated rendering suite stays together, so partition durations can differ.

TaskCommand
Focused host feedbackCHROMIUM_BIN=/usr/bin/chromium mise exec -- mix test.browser_parity
Smaller hostmise exec -- mix test.browser_parity --max-cases 2
One CI partitionMIX_TEST_PARTITION=1 mise exec -- mix test.browser_parity --partitions 3 --warnings-as-errors
Diagnose CLI printingBROWSER_PARITY_BROWSER=cli mise exec -- mix test.browser_parity
ConcernRequirement or behavior
Host toolsChromium, Poppler and matching fonts; matrix includes DejaVu/Liberation. Inspect PDF fonts before changing layout expectations
ReferenceChromium renders authored source; Poppler rasterizes both PDFs identically. Native-to-native checks cannot replace this
ComparisonsPreserve source bytes, geometry, fonts, viewport, scale, thresholds and page/text/ink/pixel checks across adapters and fixture moves
ExecutionUp to six modules; process-wide environment changes and load-sensitive cases stay serial
Browser stateFresh process and context per capture, print media, author JavaScript disabled; processes/profiles cleaned afterward
Input encodingGenerated reference inputs declare UTF-8 with a BOM; authored fixture bytes remain unchanged
ReadinessChromium virtual time pauses for pending fetches; wait for frames, fonts and image decoding, then verify a stable frame tree. Capture deadlines use wall time; diagnostics stay beside PDFs
FailuresUse suite timeout, preserve broken-resource fallback; never retry to hide a failed comparison
Shared sheetsOnly independent cases with separate regions and unchanged checks; root-document, pagination and custom-reference cases stay separate

See fixture scripts for regeneration; inspect affected regions afterward.

Tests that install application limits or change process-wide environment must run with async: false. Synchronize worker lifecycle assertions with messages before triggering cancellation; a longer timeout cannot fix a monitor race. For deadline behavior, advance an injected clock after the tested operation starts so browser startup speed does not determine the assertion.

Performance measurements

GuardRequirement
ReductionsAt or below recorded v1.0.0 baselines, zero regression allowance
Time and sizeOne-second workload ceiling plus output-size guard
Baseline changesOnly intentional workload changes or measured, explained tradeoffs; adding features never resets existing baselines
VM settingsUse scripts/check-performance: 4 normal, 4 dirty CPU, 10 dirty IO schedulers locally and in CI

Save a complete report:

PERFORMANCE_REPORT=.quality/performance/candidate.json mise exec -- ./scripts/check-performance

Compare cumulative timing against the original capture from the start of the work:

PERFORMANCE_BASELINE_REPORT=.quality/performance/baselines/reports.json \
PERFORMANCE_REPORT=.quality/performance/candidate.json mise exec -- ./scripts/check-performance
Comparison/report detailRule
Fixed captureSame idle host, runtime, scheduler settings, workloads, fixture/font hashes and dependency lock
Baseline fileSingle report or bundle; bundle defaults to elixir-<major.minor>.json, overridden by PERFORMANCE_BASELINE_KEY
TimingEvery existing workload must meet its original elapsed baseline across the whole change; preserve that baseline when recapturing
EvidenceKeep samples, medians, reductions, PDF sizes, runtime details and hashes, including failures; CI uploads failed reports too
MemorySeparate BEAM sampling avoids timing effects but misses peaks/native allocations; use an OS profiler for native memory
RetriesOther builds distort timing. Retain all attempts, compare whole workload sets and keep inputs/limits fixed; never combine selected passing workloads
SlowdownsInvestigate reproducible baseline regressions or obtain an explicit exception
StorageReports/logs in ignored .quality/; investigations in ignored tmp/

Test organization

Paths are relative to test/; grouped html_to_pdf/ entries name sibling directories.

DirectoryCoverage
api/Public operations and rendered results
core/Diagnostics and limits
pdf/Reader, object mapping, encodings and appearances
validators/Input boundaries and diagnostics
project/Style and project structure
html_to_pdf/{parsing,css}/DOM and computed styles
html_to_pdf/{layout,tables,ruby}/Geometry and pagination
html_to_pdf/{forms,images,fonts}/Controls, images and fonts
html_to_pdf/{composition,embedded}/Templates, shadows, source ownership and child documents
html_to_pdf/{mathml,svg}/Math and SVG conversion
html_to_pdf/{resources,writing}/Resource scope, caches and PDF paint
html_to_pdf/integration/Cross-feature behavior
html_to_pdf/browser_parity/Dedicated Chromium comparisons
support/Shared builders, paths, geometry and browser helpers

*_browser_parity_test.exs suites and individual :browser_parity cases compare with Chromium.

Naming

ItemConvention
Suite/module<feature>_<scenario>_test.exs / FeatureScenarioTest
Exampletables/atomic_table_overflow_test.exs under test/html_to_pdf/
Test descriptionObservable behavior and trigger, with a clear feature owner or integration purpose
Fixtures, tags, artifactsSame feature/scenario vocabulary, such as atomic_table_hidden_overflow.html
Temporary labelsBatch numbers and unfinished-work labels belong in local records

Shared paths and fixtures

Use TestSupport.Paths so file nesting does not affect input lookup:

alias NativeElixirPdfUtilities.TestSupport.Paths

html = File.read!(Paths.fixture("html_to_pdf/browser_parity/atomic_table_hidden_overflow.html"))
font = Paths.project("priv/fonts/dejavu/DejaVuSans.ttf")
Location/concernRule
fixtures/html_to_pdf/browser_parity/Registered HTML comparisons, feature sheets and reference-only inputs; preserve the shared assets/ resource base
fixtures/html_to_pdf/documents/Invoice, order, label and report samples
fixtures/images/jpeg/JPEG encoding cases
Other fixturesExisting PDF, font, template and converter feature directories
Temporary outputsUnique feature/scenario directories in tmp/; create and clean up owned inputs
Browser sibling filesHelper preserves the authored relative-resource base and removes temporary input after printing