Brevierv0.6.0

Pages

Docs

Features

DE
Docs menu

Reference

Output and tests

Choose between PDF, product HTML and debug HTML output, and test your generated documents in CI with snapshot files instead of PDF diffs.

On this page

Community

Three kinds of output

Output Command Stable? Use it for
PDF brevier pdf … -o doc.pdf yes the document you send
Product HTML brevier html … -o doc.html yes showing the document in a web portal, and snapshot tests
Debug HTML brevier pdf … --debug no finding out why a page looks wrong

Product HTML

brevier html writes the finished document as HTML. Its class names are part of Brevier's contract: an update adds classes but never removes a class or changes what it selects. Style them in your portal's CSS. Today there is one:

Class On Meaning
brevier-page <body> The whole document. The web theme puts all its rules under this class.

Brevier adds no other class of its own. A class that your template puts on its own elements is part of your document and passes through unchanged.

Debug HTML

--debug writes .debug.html and .debug.css next to the output. They show exactly what the engine received. They can change in any release, so do not build on them: --debug output has no stability promise.

One difference from the product HTML: the debug HTML writes each soft hyphen (U+00AD) that Brevier inserted for hyphenation as the visible entity &shy;. Editors and diff tools show the real character as nothing. The engine still gets the real character. Only the copy on disk changes.

Snapshot tests

Comparing two PDFs is hard. Comparing two HTML files is a text diff. So test the product HTML: render a fixed example and compare it with a file in your repository.

test_invoice.py
from brevier.testing import assert_matches_snapshot


def test_invoice_snapshot():
    html = render_my_invoice()  # your own code, with brevier html
    assert_matches_snapshot(html, "snapshots/invoice.html")
Case Result
The HTML matches the file The test passes.
The HTML differs The test fails and shows the changed lines.
No file yet The test fails and tells you how to create it.

When a change is on purpose, write the new snapshot instead of editing the test:

BREVIER_UPDATE_SNAPSHOTS=1 pytest test_invoice.py

This writes every snapshot the run touches and never fails. Review the changed snapshot files in your diff, then run the tests again without the variable.

assert_matches_snapshot(html, path, update=True) does the same for one call, whatever the environment says.