bidi2pdf 0.1.6 → 0.1.8

data/lib/bidi2pdf/test_helpers/matchers/contains_pdf_text.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../pdf_text_sanitizer"
+
+# Custom RSpec matcher for checking whether a PDF document contains specific text.
+#
+# This matcher allows you to assert that a certain string or regular expression
+# is present in the sanitized text of a PDF document.
+#
+# It supports chaining with `.at_page(n)` to limit the search to a specific page.
+#
+# ## Examples
+#
+#     expect(pdf_data).to contains_pdf_text("Total: 123.45")
+#     expect(pdf_data).to contains_pdf_text(/Invoice #\d+/).at_page(2)
+#
+# @param expected [String, Regexp] The text or pattern to match inside the PDF.
+#
+# @return [Boolean] true if the expected content is found (on the given page if specified)
+RSpec::Matchers.define :contains_pdf_text do |expected|
+  chain :at_page do |page_number|
+    @page_number = page_number
+  end
+
+  match do |actual|
+    Bidi2pdf::TestHelpers::PDFTextSanitizer.contains?(actual, expected, @page_number)
+  end
+
+  failure_message do |actual|
+    pages = Bidi2pdf::TestHelpers::PDFTextSanitizer.clean_pages(actual)
+
+    return "Document does not contain page #{@page_number}" if @page_number && !(@page_number && @page_number <= pages.size)
+
+    <<~MSG
+      PDF text did not contain expected content.
+
+      --- Expected (#{expected.inspect}) ---
+      On page #{@page_number || "any"}:
+
+      --- Actual ---
+      #{pages.each_with_index.map { |text, i| "Page #{i + 1}:\n#{text}" }.join("\n\n")}
+    MSG
+  end
+
+  description do
+    desc = "contain #{expected.inspect} in PDF"
+    desc += " on page #{@page_number}" if @page_number
+    desc
+  end
+end

data/lib/bidi2pdf/test_helpers/matchers/have_pdf_page_count.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "pdf-reader"
+require "base64"
+
+# RSpec matcher to assert the number of pages in a PDF document.
+#
+# This matcher is useful for verifying the structural integrity of generated or uploaded PDFs,
+# especially in tests for reporting, invoice generation, or document exports.
+#
+# It supports a variety of input types:
+# - Raw PDF data as a `String`
+# - File paths (`String`)
+# - `StringIO` or `File` objects
+# - Even Base64-encoded strings, if your `pdf_reader_for` method handles it
+#
+# ## Example
+#
+#     expect(pdf_data).to have_pdf_page_count(5)
+#     expect(StringIO.new(pdf_data)).to have_pdf_page_count(3)
+#
+# If the PDF is malformed, the matcher will gracefully fail and show the error message.
+#
+# @param expected_count [Integer] The number of pages the PDF is expected to contain.
+# @return [RSpec::Matchers::Matcher] The matcher object for use in specs.
+#
+# @note This matcher depends on `Bidi2pdf::TestHelpers::PDFReaderUtils.pdf_reader_for`
+#   to extract the page count. Make sure it supports all your intended input formats.
+RSpec::Matchers.define :have_pdf_page_count do |expected_count|
+  match do |pdf_data|
+    reader = Bidi2pdf::TestHelpers::PDFReaderUtils.pdf_reader_for(pdf_data)
+    @actual_count = reader.page_count
+    @actual_count == expected_count
+  rescue PDF::Reader::MalformedPDFError => e
+    @error_message = e.message
+    false
+  end
+
+  failure_message do |_pdf_data|
+    if @error_message
+      "Expected a valid PDF with #{expected_count} pages, but encountered an error: #{@error_message}"
+    else
+      "Expected PDF to have #{expected_count} pages, but it has #{@actual_count} pages"
+    end
+  end
+
+  description do
+    "have #{expected_count} PDF pages"
+  end
+end

data/lib/bidi2pdf/test_helpers/matchers/match_pdf_text.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../pdf_text_sanitizer"
+
+# Custom RSpec matcher to compare the **sanitized text content** of two PDF files.
+#
+# This matcher is useful for comparing PDF documents where formatting and metadata may differ,
+# but the actual visible text content should be the same. It uses `PDFTextSanitizer` internally
+# to normalize and clean the text before comparison.
+#
+# ## Example
+#
+#     expect(actual_pdf).to match_pdf_text(expected_pdf)
+#
+# If the texts don’t match, it prints a diff-friendly message showing cleaned text content.
+#
+# @param expected [String, StringIO, File] The expected PDF content (can be a file path, StringIO, or raw string).
+# @return [RSpec::Matchers::Matcher] An RSpec matcher to compare against an actual PDF.
+#
+# @note Ensure `PDFTextSanitizer.match?` and `PDFTextSanitizer.clean_pages` are implemented
+#   to handle your specific PDF processing logic.
+RSpec::Matchers.define :match_pdf_text do |expected|
+  match do |actual|
+    Bidi2pdf::TestHelpers::PDFTextSanitizer.match?(actual, expected)
+  end
+
+  failure_message do |actual|
+    cleaned_actual = Bidi2pdf::TestHelpers::PDFTextSanitizer.clean_pages(actual)
+    cleaned_expected = Bidi2pdf::TestHelpers::PDFTextSanitizer.clean_pages(expected)
+
+    <<~MSG
+      PDF text did not match.
+
+      --- Expected ---
+      #{cleaned_expected.join("\n")}
+
+      --- Actual ---
+      #{cleaned_actual.join("\n")}
+    MSG
+  end
+
+  description do
+    "match sanitized PDF text content"
+  end
+end

data/lib/bidi2pdf/test_helpers/pdf_reader_utils.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module TestHelpers
+    module PDFReaderUtils
+      class << self
+        # Extracts text content from a PDF document.
+        #
+        # This method accepts various PDF input formats and attempts to extract text content
+        # from all pages. If extraction fails due to malformed PDF data, it returns the original input.
+        #
+        # @param pdf_data [String, StringIO, File] The PDF data in one of the following formats:
+        #   * Base64-encoded PDF string
+        #   * Raw PDF data beginning with "%PDF-"
+        #   * StringIO object containing PDF data
+        #   * Path to a PDF file as String
+        #   * Raw PDF data as String
+        # @return [Array<String>] An array of strings, with each string representing the text content of a page
+        # @return [Object] The original input if PDF extraction fails
+        # @example Extract text from a PDF file
+        #   text_content = pdf_text('path/to/document.pdf')
+        #
+        # @example Extract text from Base64-encoded string
+        #   text_content = pdf_text(base64_encoded_pdf_data)
+        def pdf_text(pdf_data)
+          return pdf_data unless pdf_data.is_a?(String) || pdf_data.is_a?(StringIO) || pdf_data.is_a?(File)
+
+          begin
+            reader = pdf_reader_for pdf_data
+            reader.pages.map(&:text)
+          rescue PDF::Reader::MalformedPDFError
+            [pdf_data]
+          end
+        end
+
+        # Converts the input PDF data into an IO object and initializes a PDF::Reader.
+        #
+        # @param pdf_data [String, StringIO, File] The PDF data to be read.
+        # @return [PDF::Reader] A PDF::Reader instance for the given data.
+        # @raise [PDF::Reader::MalformedPDFError] If the PDF data is invalid.
+        def pdf_reader_for(pdf_data)
+          io = convert_data_to_io(pdf_data)
+          PDF::Reader.new(io)
+        end
+
+        # rubocop: disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        # Converts various input formats into an IO object for PDF::Reader.
+        #
+        # @param pdf_data [String, StringIO, File] The PDF data to be converted.
+        # @return [IO] An IO object containing the PDF data.
+        def convert_data_to_io(pdf_data)
+          # rubocop:disable Lint/DuplicateBranch
+          if pdf_data.is_a?(String) && (pdf_data.start_with?("JVBERi") || pdf_data.start_with?("JVBER"))
+            StringIO.new(Base64.decode64(pdf_data))
+          elsif pdf_data.start_with?("%PDF-")
+            StringIO.new(pdf_data)
+          elsif pdf_data.is_a?(StringIO)
+            pdf_data
+          elsif pdf_data.is_a?(String) && File.exist?(pdf_data)
+            File.open(pdf_data, "rb")
+          else
+            StringIO.new(pdf_data)
+          end
+          # rubocop:enable Lint/DuplicateBranch
+        end
+      end
+
+      # rubocop: enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      module InstanceMethods
+        def pdf_text(pdf_data)
+          PDFReaderUtils.pdf_text(pdf_data)
+        end
+
+        def pdf_reader_for(pdf_data)
+          PDFReaderUtils.pdf_reader_for(pdf_data)
+        end
+
+        def convert_data_to_io(pdf_data)
+          PDFReaderUtils.convert_data_to_io(pdf_data)
+        end
+      end
+
+      def self.included(base)
+        base.include(InstanceMethods)
+      end
+    end
+  end
+end

data/lib/bidi2pdf/test_helpers/pdf_text_sanitizer.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "unicode_utils"
+require "diff/lcs"
+require "diff/lcs/hunk"
+
+module Bidi2pdf
+  module TestHelpers
+    # rubocop: disable Metrics/ModuleLength
+    # Provides utilities for sanitizing and comparing PDF text content.
+    # This module includes methods for cleaning text, comparing PDF content,
+    # and reporting differences between actual and expected PDF outputs.
+    #
+    # The sanitization process includes normalizing whitespace, replacing
+    # typographic ligatures, and handling other common text formatting issues.
+    #
+    # @example Cleaning text
+    #   sanitized_text = Bidi2pdf::TestHelpers::PDFTextSanitizer.clean("Some text")
+    #
+    # @example Comparing PDF content
+    #   match = Bidi2pdf::TestHelpers::PDFTextSanitizer.match?(actual_pdf, expected_pdf)
+    module PDFTextSanitizer
+      class << self
+        # Cleans the given text by replacing common typographic ligatures,
+        # normalizing whitespace, and removing unnecessary characters.
+        #
+        # @param [String] text The text to clean.
+        # @return [String] The cleaned text.
+        def clean(text)
+          text = UnicodeUtils.nfkd(text)
+
+          text.gsub("\uFB01", "fi")
+              .gsub("\uFB02", "fl")
+              .gsub("-\n", "")
+              .gsub(/["]/, '"')
+              .gsub(/[']/, "'")
+              .gsub("…", "...")
+              .gsub("—", "--")
+              .gsub("–", "-")
+              .gsub(/\s+/, " ") # Replace all whitespace sequences with a single space
+              .strip
+        end
+
+        # Cleans an array of PDF page texts by applying the `clean` method
+        # to each page's content.
+        #
+        # @param [Object] actual_pdf_thingy The PDF object to clean.
+        # @return [Array<String>] An array of cleaned page texts.
+        def clean_pages(actual_pdf_thingy)
+          Bidi2pdf::TestHelpers::PDFReaderUtils.pdf_text(actual_pdf_thingy).map { |text| clean(text) }
+        end
+
+        # Cleans the given text and removes all whitespace for comparison purposes.
+        #
+        # @param [String] text The text to clean and normalize.
+        # @return [String] The cleaned text without whitespace.
+        def normalize(text)
+          clean(text).gsub(/\s+/, "")
+        end
+
+        # Checks if the given PDF contains the expected text or pattern.
+        #
+        # @param [Object] actual_pdf_thingy The PDF object to search.
+        # @param [String, Regexp] expected The expected text or pattern.
+        # @param [Integer, nil] page_number The specific page to search (optional).
+        # @return [Boolean] `true` if the expected text is found, `false` otherwise.
+        def contains?(actual_pdf_thingy, expected, page_number = nil)
+          pages = Bidi2pdf::TestHelpers::PDFReaderUtils.pdf_text(actual_pdf_thingy)
+          cleaned_pages = clean_pages(pages)
+
+          return false if page_number && page_number > cleaned_pages.size
+
+          # Narrow to specific page if requested
+          if page_number
+            text = cleaned_pages[page_number - 1]
+            return match_expected?(text, expected)
+          end
+
+          # Search all pages
+          cleaned_pages.any? { |page| match_expected?(page, expected) }
+        end
+
+        # Matches the given text against the expected text or pattern.
+        #
+        # @param [String] text The text to match.
+        # @param [String, Regexp] expected The expected text or pattern.
+        # @return [Boolean] `true` if the text matches, `false` otherwise.
+        def match_expected?(text, expected)
+          return false unless text
+
+          expected.is_a?(Regexp) ? text.match?(expected) : text.include?(expected.to_s)
+        end
+
+        # Compares the content of two PDF objects for equality.
+        #
+        # @param [Object] actual_pdf_thingy The actual PDF object.
+        # @param [Object] expected_pdf_thingy The expected PDF object.
+        # @return [Boolean] `true` if the content matches, `false` otherwise.
+        def match?(actual_pdf_thingy, expected_pdf_thingy)
+          actual = Bidi2pdf::TestHelpers::PDFReaderUtils.pdf_text actual_pdf_thingy
+          expected = Bidi2pdf::TestHelpers::PDFReaderUtils.pdf_text expected_pdf_thingy
+
+          cleaned_actual = clean_pages(actual)
+          cleaned_expected = clean_pages(expected)
+
+          # Compare without whitespace for equality check
+          actual_for_comparison = cleaned_actual.map { |text| normalize(text) }
+          expected_for_comparison = cleaned_expected.map { |text| normalize(text) }
+
+          if actual_for_comparison == expected_for_comparison
+            true
+          else
+            report_content_mismatch(cleaned_actual, cleaned_expected)
+            false
+          end
+        end
+
+        # Reports differences between actual and expected PDF content.
+        #
+        # @param [Array<String>] actual The actual PDF content.
+        # @param [Array<String>] expected The expected PDF content.
+        # @return [void]
+        def report_content_mismatch(actual, expected)
+          puts "--- PDF content mismatch ---"
+          print_differences(actual, expected)
+        end
+
+        # Prints detailed differences between actual and expected PDF content.
+        #
+        # @param [Array<String>] actual The actual PDF content.
+        # @param [Array<String>] expected The expected PDF content.
+        # @return [void]
+        def print_differences(actual, expected)
+          max_pages = [actual.length, expected.length].max
+
+          (0...max_pages).each do |page_idx|
+            actual_page = actual[page_idx] || "(missing page)"
+            expected_page = expected[page_idx] || "(missing page)"
+
+            print_differences_for_page(actual_page, expected_page, page_idx)
+          end
+        end
+
+        # Prints the differences between actual and expected content for a specific page.
+        # This method compares the content ignoring whitespace and, if differences are found,
+        # outputs a formatted representation of those differences.
+        #
+        # @param [String] actual_page The actual page content.
+        # @param [String] expected_page The expected page content.
+        # @param [Integer] page_idx The zero-based index of the page being compared.
+        # @return [void]
+        def print_differences_for_page(actual_page, expected_page, page_idx)
+          # Compare without whitespace
+          actual_no_space = normalize(actual_page.to_s)
+          expected_no_space = normalize(expected_page.to_s)
+
+          return if actual_no_space == expected_no_space
+
+          puts "\nPage #{page_idx + 1} differences (ignoring whitespace):"
+
+          # Create diffs between the two pages
+          diffs = Diff::LCS.sdiff(expected_page, actual_page)
+
+          # Format and display the differences
+          puts format_diff_output(diffs, expected_page, actual_page)
+        end
+
+        # Formats the output of differences for display.
+        #
+        # @param [Array<Diff::LCS::ContextChange>] diffs The list of differences.
+        # @param [String] expected The expected text.
+        # @param [String] actual The actual text.
+        # @return [String] The formatted differences.
+        def format_diff_output(diffs, expected, actual)
+          output = []
+
+          changes = group_changed_diffs(diffs)
+
+          # Output each change with context
+          changes.each do |change|
+            output += format_change expected, actual, change
+          end
+
+          output.join("\n")
+        end
+
+        private
+
+        # Groups contiguous “real” diffs (added/removed/changed) into blocks,
+        # splitting whenever you hit an unchanged (“=”) diff.
+        def group_changed_diffs(diffs)
+          diffs
+            .chunk_while { |_prev, curr| curr.action != "=" }
+            .map { |chunk| chunk.reject { |elem| elem.action == "=" } }
+            .select(&:any?)
+            .map { |chunk| { diffs: chunk } }
+        end
+
+        def format_change(expected, actual, change)
+          pos = change[:diffs].first.old_position
+          snippets = extract_snippets(expected, actual, change, pos)
+
+          build_output(snippets, pos)
+        end
+
+        def extract_snippets(expected, actual, change, pos)
+          {
+            context_start: [0, pos - 20].max,
+            context: expected,
+            expected_snip: expected[pos, 50],
+            actual_snip: actual[change[:diffs].first.new_position, 50]
+          }
+        end
+
+        # 3. Build the final lines of output
+        def build_output(snip_data, pos)
+          start = snip_data[:context_start]
+          ctx = snip_data[:context]
+
+          [
+            "  Context: ...#{ctx[start...pos]}",
+            "  Expected: #{snip_data[:expected_snip]}...",
+            "  Actual:   #{snip_data[:actual_snip]}...",
+            "  Expected (no spaces): #{normalize(snip_data[:expected_snip])}...",
+            "  Actual (no spaces):   #{normalize(snip_data[:actual_snip])}..."
+          ]
+        end
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/bidi2pdf/test_helpers/testcontainers/chromedriver_container.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+begin
+  require "testcontainers"
+rescue LoadError
+  warn "Missing #{dep}. Add it to your Gemfile if you're using Bidi2pdf test helpers."
+end
+
+module Bidi2pdf
+  module TestHelpers
+    module Testcontainers
+      class ChromedriverContainer < ::Testcontainers::DockerContainer
+        DEFAULT_CHROMEDRIVER_PORT = 3000
+        DEFAULT_IMAGE = "dieters877565/chromedriver"
+
+        attr_reader :docker_file, :build_dir
+
+        def initialize(image = DEFAULT_IMAGE, **options)
+          @docker_file = options.delete(:docker_file) || "Dockerfile"
+          @build_dir = options.delete(:build_dir) || options[:working_dir]
+
+          super
+
+          @wait_for ||= add_wait_for(:logs, /ChromeDriver was started successfully on port/)
+        end
+
+        def start
+          with_exposed_ports(port)
+          super
+        end
+
+        def port
+          DEFAULT_CHROMEDRIVER_PORT
+        end
+
+        # rubocop: disable Metrics/AbcSize
+        def build_local_image
+          old_timeout = Docker.options[:read_timeout]
+          Docker.options[:read_timeout] = 60 * 10
+
+          Docker::Image.build_from_dir(build_dir, { "t" => image, "dockerfile" => docker_file }) do |lines|
+            lines.split("\n").each do |line|
+              next unless (log = JSON.parse(line)) && log.key?("stream")
+              next unless log["stream"] && !(trimmed_stream = log["stream"].strip).empty?
+
+              timestamp = Time.now.strftime("[%Y-%m-%dT%H:%M:%S.%6N]")
+              $stdout.write "#{timestamp} #{trimmed_stream}\n"
+            end
+          end
+
+          Docker.options[:read_timeout] = old_timeout
+        end
+
+        # rubocop: enable  Metrics/AbcSize
+
+        # rubocop: disable Metrics/AbcSize
+        def start_local_image
+          build_local_image
+
+          with_exposed_ports(port)
+
+          @_container ||= Docker::Container.create(_container_create_options)
+          @_container.start
+
+          @_id = @_container.id
+          json = @_container.json
+          @name = json["Name"]
+          @_created_at = json["Created"]
+
+          @wait_for&.call(self)
+
+          self
+        rescue Docker::Error::NotFoundError => e
+          raise Testcontainers::NotFoundError, e.message
+        rescue Excon::Error::Socket => e
+          raise Testcontainers::ConnectionError, e.message
+        end
+
+        # rubocop: enable Metrics/AbcSize
+
+        def session_url(protocol: "http")
+          "#{protocol}://#{host}:#{mapped_port(port)}/session"
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/test_helpers.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+%w[pdf-reader diff-lcs unicode_utils].each do |dep|
+  require dep
+rescue LoadError
+  warn "Missing #{dep}. Add it to your Gemfile if you're using Bidi2pdf test helpers."
+end
+
+require "bidi2pdf/test_helpers/pdf_text_sanitizer"
+require "bidi2pdf/test_helpers/pdf_reader_utils"
+require "bidi2pdf/test_helpers/matchers/match_pdf_text"
+require "bidi2pdf/test_helpers/matchers/contains_pdf_text"
+require "bidi2pdf/test_helpers/matchers/have_pdf_page_count"

data/lib/bidi2pdf/verbose_logger.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  class VerboseLogger < SimpleDelegator
+    VERBOSITY_LEVELS = {
+      none: 0,
+      low: 1,
+      medium: 2,
+      high: 3
+    }.freeze
+
+    attr_reader :logger, :verbosity
+
+    def initialize(logger, verbosity = :low)
+      super(logger)
+      self.verbosity = verbosity
+      @logger = logger
+    end
+
+    def verbosity=(verbosity)
+      min_verbosity = VERBOSITY_LEVELS.values.min
+
+      @verbosity = if verbosity.is_a?(Numeric)
+                     verbosity = verbosity.to_i
+                     max_verbosity = VERBOSITY_LEVELS.values.max
+
+                     verbosity.clamp(min_verbosity, max_verbosity)
+                   else
+                     VERBOSITY_LEVELS.fetch verbosity.to_sym, min_verbosity
+                   end
+    end
+
+    def verbosity_sym
+      VERBOSITY_LEVELS.find { |_, v| v == verbosity }.first
+    end
+
+    def debug1(progname = nil, &)
+      return unless debug1?
+
+      logger.debug("[D1] #{progname}", &)
+    end
+
+    def debug1?
+      verbosity >= 1
+    end
+
+    def debug1!
+      @verbosity = VERBOSITY_LEVELS[:high]
+    end
+
+    def debug2(progname = nil, &)
+      return unless debug2?
+
+      logger.debug("[D2] #{progname}", &)
+    end
+
+    def debug2?
+      verbosity >= 2
+    end
+
+    def debug2!
+      @verbosity = VERBOSITY_LEVELS[:high]
+    end
+
+    def debug3(progname = nil, &)
+      return unless debug3?
+
+      logger.debug("[D3] #{progname}", &)
+    end
+
+    def debug3?
+      verbosity >= 3
+    end
+
+    def debug3!
+      @verbosity = VERBOSITY_LEVELS[:high]
+    end
+  end
+end

data/lib/bidi2pdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
-  VERSION = "0.1.6"
+  VERSION = "0.1.8"
 end