The engine has two tiers of tests. Both run in real Chromium via Playwright — there is no jsdom or Node-only path.
| Tier | Location | Config | What it checks |
|---|---|---|---|
| Unit / integration | test/ |
test/playwright.config.js |
Layout algorithms, tokens, composition, DOM measurement |
| Specs (Visual ref test) | specs/ |
specs/playwright.config.js |
Pixel-compare fragmented output against hand-written refs |
npm test # unit/integration
npm run specs # specs
npm run lint # eslint (separate from tests)Both Playwright configs start a local static server. Set FRAG_TEST_PORT to
override the defaults (8787 for unit/integration tests and 8080 for specs),
for example FRAG_TEST_PORT=9000 npm test.
Specs are the primary way to verify fragmentation output against the CSS specs, modelled after and using Web Platform Tests reftests. Each spec is a pair of HTML files:
name.html— a page using CSS features like@page,break-*, multicol, etc. The runner injects the fragmentation engine and replaces body content with the paginated output.name-ref.html— a static hand-laid reference showing the expected visual output. It does not run the engine — instead it uses<page-container>elements sized with CSS custom properties to mimic each fragmentainer.
The runner screenshots each <page-container> from the processed test page and from the reference page, then compares them pixel-by-pixel. Many test cases are imported from Chromium's WPT suite and adapted; others are hand-authored against known-good output.
Spec refs are hand-crafted and belong to the test surface. Never regenerate or delete an existing ref like a snapshot — if the engine output genuinely improved, the ref should be updated deliberately.
Three suites live under specs/:
css-page/— WPT-imported@pagepagination testsat-page/— @page spec from pagedjsfragmentation/— CSS Fragmentation module tests
css-page:
- name: basic-pagination-001-print
type: print
- name: basic-pagination-002-print
type: print
at-page:
- name: awesome
type: print
- name: rebuild-all-tds
type: print
skip: true # skip: true or "reason string" to skip a testEach entry has:
name— the base filename (resolves toname.html+name-ref.htmlin the suite directory)type—print(runpaginate()) ormulticol(runmulticol()on detected multicol containers). Seespecs/helpers/process.js.skip— optional;trueor a reason string
- Drop the test file into the suite directory, e.g.
specs/fragmentation/my-test.html. Use real@page/break-*/ multicol CSS. The engine runs against the live DOM. - Author a reference file,
specs/fragmentation/my-test-ref.html, that renders the expected output using<page-container>elements with--page-width,--page-height, and--page-margin-*custom properties. Seespecs/fragmentation/border-padding-overflow-ref.htmlfor a complete example. - Add the entry to
specs/tests.ymlunder the right suite. - Run a single spec:
npm run specs -- --project fragmentation -g my-test
# Entire suite
npx playwright test --config specs/playwright.config.js --project at-page
# Single test by name
npx playwright test --config specs/playwright.config.js --project at-page -g awesome
# With trace/HTML report
npx playwright test --config specs/playwright.config.js --reporter=htmlThe HTML report (auto-opened on failure) attaches screenshots for each page plus a per-pixel diff, which is usually the fastest way to see what drifted.
The fragment bin (installed from debug/viewer.js) opens a spec in a headed browser with the fragmentation engine live-injected. Refresh the page to re-run the engine after editing source or CSS.
# Open a spec in a headed Chromium window
fragment specs/at-page/awesome.html
# Multicol spec
fragment specs/at-page/column-overflow.html --type multicol
# Try cross-browser
fragment specs/at-page/awesome.html --browser firefox
fragment specs/at-page/awesome.html --browser webkit
# View the reference page as-is (no engine injection)
fragment specs/at-page/awesome-ref.html --ref
# Visualize fragment boundaries
fragment specs/at-page/awesome.html --debugNon-interactive modes dump output instead of opening a window:
# Dump the fragmented HTML (stdout or file)
fragment specs/at-page/awesome.html --html
fragment specs/at-page/awesome.html --html out.html
# Print a per-page inspect report: block sizes, break tokens, element spans, issues
fragment specs/at-page/awesome.html --inspect
fragment specs/at-page/awesome.html --inspect report.txt
# Render to PDF
fragment specs/at-page/awesome.html --pdf book.pdffragment --help lists every flag. Use --inspect as the first stop when a spec fails — it surfaces which page a break token ended up on, which elements got split, and any zero-progress warnings — without needing to compare pixel screenshots.
DOM-based test — wrap a real element, run layout, assert on the result:
import { test, expect } from "../browser-fixture.js";
test("lays out a leaf node", async ({ page }) => {
const result = await page.evaluate(async () => {
const { runLayoutGenerator } = await import("/src/layout/layout-driver.js");
const { BlockContainerAlgorithm } = await import("/src/algorithms/block-container.js");
const { ConstraintSpace } = await import("/src/fragmentation/constraint-space.js");
const { DOMLayoutNode } = await import("/src/layout/layout-node.js");
const container = document.createElement("div");
container.style.cssText = "position:absolute;left:-9999px;width:600px";
container.innerHTML = '<div style="height:50px"></div>';
document.body.appendChild(container);
const root = new DOMLayoutNode(container.firstElementChild);
const space = new ConstraintSpace({
availableInlineSize: 600,
availableBlockSize: 800,
fragmentainerBlockSize: 800,
fragmentationType: "page",
});
const { fragment, breakToken } = runLayoutGenerator(
new BlockContainerAlgorithm(root, space, null),
);
container.remove();
return { blockSize: fragment.blockSize, broke: breakToken !== null };
});
expect(result.blockSize).toBe(50);
expect(result.broke).toBe(false);
});Mock-node test — use test/fixtures/nodes.js factories (blockNode, inlineNode, tableRowNode, flexNode, gridNode, multicolNode, etc.) to build a tree without touching the DOM. Useful for break scoring, margin collapsing, parallel-flow edge cases.
# Single file
npx playwright test --config test/playwright.config.js test/layout/block-layout.test.js
# Pattern match on test title
npx playwright test --config test/playwright.config.js -g "forced break"- Spec fails only on CI. DPR or font-rendering differences. The spec config pins
deviceScaleFactor: 1and--font-render-hinting=none; reproduce with the same flags locally. - Spec times out on
waitForSelector("[data-spec-ready]"). The engine threw insideprocess.js. Rerun withfragment <spec>and open DevTools — the error is also mirrored todocument.documentElement.dataset.specError. - Ref and test page counts don't match. The spec runner fails fast on
expect(testCount).toBe(refCount). Use--inspectto see how many fragmentainers the engine produced, then reconcile with the ref.