Your best ways to test your PDFs

[PhilippePerret]

I would very much like to know what you consider to be the best way to test your output with Prawn/Prawn-table.

Personally, I haven't found anything better, especially nothing simpler than the FileUtils::identical? method.

Let's say I have a piece of code that generates an invoice. I refine it until it produces the expected document.

Once I've precisely obtained this document, I name it expected.pdf and set it aside.

Then, in my test that evaluates this piece of code, I generate a document that I call actual.pdf. All I need to do then is make sure that the two documents are identical.

require 'fileutils' # and minitest etc.

class MyTest < Minitest::Test

  def test_the_invoice_is_good_with_build_invoice_method

    # --- test it ---
    actual_pdf_path = build_invoice(with_data)
    # => produce actual.pdf

    # --- check it ---
    assert FileUtils.identical?(expected_pdf_path, actual_pdf_path)

  end
end

[pointlessone]

This is pretty much it. In Prawn we have a test for the generated manual. We use hashes instead of full documents though. That way we don't have to keep a copy of the file in the repo. One caveat is that while Prawn does make some effort to make documents stable it's not a stated goal. For example, we need to have a hash per supported Ruby implementation because implementations have minute differences that result in insignificant differences but differences nonetheless. For example, JRuby's gzip compression produces different output to MRI. It's still valid just not byte-identical.

[PhilippePerret]

Thank you, I'll go to sleep less ignorant tonight!

And what hashing function do you generally use?

require 'digest/md5'

def test_is_same_document
  # --- test ---
  actual_book_path =  build_a_nice_pdf_and_return_path(with_data)
  # --- check ---
  # Recorded hash
  expected_hash = get_hash_for(this_test)
  # => "f8cde659ca0708071f889d6bd5c296ad"
  actual_hash = Digest::MD5.file(actual_book_path).hexdigest
  assert_equal(expected_hash, actual_hash)
end

[pointlessone]

We use SHA512 but it doesn't matter much. Longer hash in theory has a bit more space to avoid collisions but I don't think you'll hit one with shorter hashes, like SHA1, or weaker algorithms, like MD5, since it's used in a non-adversarial environment.

Here's the spec. I think you can use it wholesale apart from setting CI env var. We do that because that's how we know not to include version/git commit into the manual. That's the only variable part of the manual and including it would change the hash on every commit. We don't expect anything else to change. Though, if we do expect a change it's easy to update the hash(es): just run the spec and it would tell you the new one (it would fail with "expected <old hash> but got <new hash>" message).

[PhilippePerret]

A big thank you for your insights, Alexander! It's very helpful, and it's interesting to know how the pros work ;-). There are a lot of code examples on GitHub (and elsewhere), but you never know who you're dealing with... Thank you very much.