Asserting on a Receipt

GET /api/printers/{id}/documents/canvas returns documents as the elements the parser produced - runs of text with their styling, barcodes, images, cuts - rather than a rendered picture. That is what makes them worth asserting on.

Assert on meaning, not on pixels

Good assertions survive a layout change that a human would call correct:

• the total appears once, with the expected value;
• the barcode carries the order number, in the expected symbology;
• the receipt ends with a cut;
• the logo is present;
• nothing is marked as an error.

Poor assertions break on every change: exact dot coordinates, the full text of the receipt compared byte for byte, the number of line feeds.

The exception is a deliberate golden-master test, where comparing the whole document is the point. Keep those few and update them consciously.

Waiting for the document

Two ways, and the second is better in a pipeline:

• Poll documents/canvas?limit=1 until it appears. Simple, and fine when you already have a retry helper.
• Subscribe to GET /api/printers/{id}/documents/canvas/stream, a Server-Sent Events stream that emits each completed document. No polling interval to tune, and no race between the assertion and the print.

Remember that a document is only finalized when the connection closes or after a short idle timeout. A test that asserts while its own socket is still open will always find nothing - see Nothing appears.

Isolating test cases

DELETE /api/printers/{id}/documents clears the history, which keeps one test from asserting on the receipt another test printed. Call it between cases, or create a printer per case - both are cheap.

Replaying a captured payload

POST /api/printers/{id}/documents/import takes a base64 payload and processes it as if it had been printed. When a bug report arrives with a byte dump attached, this turns it into a document you can look at, without reproducing whatever produced it.

It is also a way to write a regression test for a stream you cannot easily generate: keep the bytes as a fixture, import them, assert on the result.