dieter-medium/bidi2pdf/pdf-specs

RSpec specs with bidi2pdf's test helpers

bidi2pdf ships RSpec matchers for PDFs and helpers that start a chromedriver container for the suite. This skill is how to use them, and the mistakes that made such specs flaky before.

Does not: replace a project's own spec conventions - follow those for naming and layout. And it does not cover bidi2pdf-rails' own test helpers (see that gem).

Ground rules

• bidi2pdf is the renderer. If it fails, report its error.code, error.hint and exit code;

never make the PDF or screenshot another way (Chrome's own print-to-PDF, another PDF engine).

• Install nothing unasked. Name what is missing and suggest a way (the render-pdf skill's

preflight); run nothing that changes the system without the user's yes.

• bidi2pdf's results first. Read its --json result instead of inspecting the PDF with other

tools.

1. Set up

# spec/spec_helper.rb
require "bidi2pdf/test_helpers"             # matchers and file helpers; needs pdf-reader, diff-lcs, unicode_utils
require "bidi2pdf/test_helpers/images"      # only for contains_pdf_image (ruby-vips, dhash-vips)
require "bidi2pdf/test_helpers/testcontainers" # only to start Chrome in Docker for the suite

Add the gems the comments name to the test group of the Gemfile; each helper warns when one is missing instead of failing the suite.

2. Assert on the PDF

pdf = tab.print                                   # base64; a path or raw bytes work too
expect(pdf).to have_pdf_page_count(2)
expect(pdf).to contains_pdf_text("Invoice #123")
expect(pdf).to contains_pdf_text(/Total: \d+/).at_page(2)
expect(pdf).to match_pdf_text(expected_pdf)       # the whole text equal, after cleaning both texts
expect(pdf).to contains_pdf_image("spec/fixtures/logo.png").at_page(1) # perceptually similar, tolerance: 10

• PDF text extraction lays words out by position: a sidebar and a main column can interleave on

one line. Assert on words that occur once, not on whole lines.

• One render, several fields of it, is one example; do not render the same PDF again per field.

3. A Chrome for the suite

Tag examples :chromedriver: the helper starts the chromedriver container once for the suite (Docker required) and gives the example session_url, create_session(session_url) and with_tab(session_url) { |tab| ... }, which opens and always closes the session. Without Docker, point the specs at an existing chromedriver instead (a remote-chrome service, see that skill) and skip the tag.

4. Browser specs that stay green

• Wait on the outcome, not on the network. wait_until_network_idle only sees requests that

have started; a debounced search or a deferred fetch starts later, and the assertion runs too early. Poll for the DOM state you expect (a selector that appears, a text that changes), with a deadline that raises.

• A script that throws returns no value. execute_script returns the BiDi result: check

result["type"] - an "exception" there, not a nil value, means your selector or script failed.

• Visible is not the same as present. A scripted .click() works on hidden elements; a real

user cannot click them. Navigate to the state where the element is visible before asserting on it.

• Close cleanly. Close tab, window and session in an ensure; let in-flight requests finish

before the test server tears down its database connection, or a request still rendering fails outside any example.

• Ports. A test server on a fixed port collides with a running development server: pick a free

one, and let the browser reach it by a name it resolves.

• Locale-dependent output. Date fields render in the browser's locale; pin LANG on the browser

container and set dates as ISO strings.