[czj]

An application that renders PDFs has no good way to test them: most suites check that some bytes came out. Gamba's test support already compared text with its position, pixels in two renderers and validity, but none of it shipped in the gem, and the README sent people to our test support to compare their PDFs before switching. Closes #72.

The oracle's checks move into the gem as Gamba::PdfCheck, which the oracle now calls, and come as assertions and matchers loaded only on request.

• Minitest assertions: with require "gamba/minitest", tests get assert_pdf_text pdf, "Invoice INV-2026-0001", page: 1, at: [x, y] (a String whose spaces match any run of spaces, or a Regexp), assert_same_pages, assert_valid_pdf and assert_pdf_a. A PDF is its bytes or a path.
• RSpec matchers: with require "gamba/rspec", specs get have_pdf_text, have_same_pages_as, be_a_valid_pdf and be_pdf_a, negatable.
• Failures in words: they say what the page reads instead, or name the page and the glyph that moved, or the pixel rows that differ in MuPDF or Poppler, as the oracle words them.
• Never unchecked: a missing tool fails with its install command, or skips the check when Gamba::Testing.missing_tools = :skip.
• One implementation: the oracle calls Gamba::PdfCheck. script/capture_pdfs.rb PRAWN_DIR GAMBA_DIR compares two capture directories with the same checks and exits 1 on a difference. The README and the guide show both.

Proof

test/testing_test.rb covers text on any page or a given one, at a position or not; failure messages; same pages, and a glyph moved by 1 pt named with its pixel rows in Poppler; a broken xref reported invalid; paths and Pathnames as well as bytes; a missing qpdf failing with its install command, then skipping when told; the RSpec matchers run by rspec in a subprocess (6 examples, 1 failure, 1 pending, as written); and the compare mode of capture_pdfs.rb. The oracle runs on Gamba::PdfCheck with no other change: 265 examples, 0 failures, the encrypted manual examples included. rake test: 1377 runs, 0 failures; RuboCop is clean.

---

Generated by Claude Code