# 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](/docs/troubleshooting/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.