pdf 0.1.0 → 0.1.1

data/.claude/execution/08-integration-tests.md

@@ -0,0 +1,978 @@
+# Phase 8: Integration Tests
+
+Comprehensive integration tests covering full PDF generation workflows.
+
+## Files
+- `test/integration/basic_view_test.rb`
+- `test/integration/layout_test.rb`
+- `test/integration/inheritance_test.rb`
+- `test/integration/conditional_rendering_test.rb`
+- `test/integration/components_test.rb`
+- `test/integration/error_handling_test.rb`
+
+---
+
+## 8.1 Basic View Integration
+
+```ruby
+# test/integration/basic_view_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class BasicViewIntegrationTest < Minitest::Test
+  def test_simple_view_generates_valid_pdf
+    view_class = Class.new(Pdf::View) do
+      title "Test Document"
+      subtitle "A Subtitle"
+      paragraph "This is a test paragraph with some content."
+      hr
+      spacer amount: 20
+      heading "Section Heading"
+      span "Some inline text"
+    end
+
+    pdf = view_class.new.to_pdf
+    assert pdf.start_with?("%PDF")
+    assert pdf.length > 1000
+  end
+
+  def test_simple_view_contains_expected_text
+    view_class = Class.new(Pdf::View) do
+      title "Test Document"
+      subtitle "A Subtitle"
+    end
+
+    pdf = view_class.new.to_pdf
+    assert_includes pdf, "Test Document"
+    assert_includes pdf, "A Subtitle"
+  end
+
+  def test_view_with_data_binding_resolves_symbols
+    view_class = Class.new(Pdf::View) do
+      title :document_title
+      paragraph :description
+      date :created_at
+
+      def document_title = data[:title]
+      def description = "Created by #{data[:author]}"
+      def created_at = data[:date]
+    end
+
+    view = view_class.new(
+      title: "Dynamic Title",
+      author: "John Doe",
+      date: Date.new(2024, 6, 15)
+    )
+    pdf = view.to_pdf
+    assert_includes pdf, "Dynamic Title"
+    assert_includes pdf, "John Doe"
+    assert_includes pdf, "June 15, 2024"
+  end
+
+  def test_view_with_table_renders_from_array_of_hashes
+    view_class = Class.new(Pdf::View) do
+      title "Table Report"
+      table :items, columns: [
+        { key: :name, label: "Name" },
+        { key: :qty, label: "Quantity" },
+        { key: :price, label: "Price" }
+      ]
+
+      def items = data[:items]
+    end
+
+    view = view_class.new(items: [
+      { name: "Widget", qty: 5, price: "$10" },
+      { name: "Gadget", qty: 3, price: "$25" }
+    ])
+    pdf = view.to_pdf
+    assert pdf.start_with?("%PDF")
+    assert_includes pdf, "Widget"
+    assert_includes pdf, "Gadget"
+  end
+
+  def test_view_with_empty_table
+    view_class = Class.new(Pdf::View) do
+      title "Table Report"
+      table :items, columns: [:name, :qty]
+      def items = data[:items]
+    end
+
+    view = view_class.new(items: [])
+    view.to_pdf  # Should not raise
+  end
+
+  def test_view_with_sections
+    view_class = Class.new(Pdf::View) do
+      title "Sectioned Document"
+
+      section "First Section" do
+        paragraph "Content of first section"
+        table :section1_data, columns: [:key, :value]
+      end
+
+      section "Second Section" do
+        paragraph "Content of second section"
+        alert title: "Notice", color: "blue"
+      end
+
+      def section1_data
+        [{ key: "A", value: "1" }, { key: "B", value: "2" }]
+      end
+    end
+
+    pdf = view_class.new.to_pdf
+    assert_includes pdf, "First Section"
+    assert_includes pdf, "Second Section"
+    assert_includes pdf, "Content of first section"
+  end
+
+  def test_view_with_each_loop_iterates
+    view_class = Class.new(Pdf::View) do
+      title "Items List"
+
+      each(:items) do |item|
+        heading item[:name]
+        paragraph item[:description]
+        hr
+      end
+
+      def items = data[:items]
+    end
+
+    view = view_class.new(items: [
+      { name: "Item 1", description: "First item" },
+      { name: "Item 2", description: "Second item" },
+      { name: "Item 3", description: "Third item" }
+    ])
+    pdf = view.to_pdf
+    assert_includes pdf, "Item 1"
+    assert_includes pdf, "Item 2"
+    assert_includes pdf, "Item 3"
+  end
+
+  def test_view_with_empty_each_collection
+    view_class = Class.new(Pdf::View) do
+      each(:items) { |item| paragraph item[:name] }
+      def items = data[:items]
+    end
+
+    view = view_class.new(items: [])
+    view.to_pdf  # Should not raise
+  end
+end
+```
+
+---
+
+## 8.2 Layout Integration
+
+```ruby
+# test/integration/layout_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class LayoutIntegrationTest < Minitest::Test
+  def test_view_with_layout_applies_margins
+    layout_class = Class.new(Pdf::Layout) do
+      header do
+        context :header_lines
+      end
+
+      footer do
+        text :footer_text, size: 8
+        page_number position: :right, format: "Page %<page>d of %<total>d"
+      end
+
+      margins top: 80, bottom: 70, left: 50, right: 50
+    end
+
+    lc = layout_class
+    view_class = Class.new(Pdf::View) do
+      layout lc
+
+      title "Document with Layout"
+      paragraph :content
+
+      def header_lines
+        ["Company: #{data[:company]}", "Date: #{Date.today}"]
+      end
+
+      def footer_text = "Confidential - #{data[:company]}"
+      def content = data[:content]
+    end
+
+    pdf = view_class.new(company: "Acme Corp", content: "Test content").to_pdf
+    assert pdf.start_with?("%PDF")
+  end
+
+  def test_view_with_layout_renders_header
+    layout_class = Class.new(Pdf::Layout) do
+      header do
+        context :header_lines
+      end
+    end
+
+    lc = layout_class
+    view_class = Class.new(Pdf::View) do
+      layout lc
+      title "Doc"
+      def header_lines = ["Company: #{data[:company]}"]
+    end
+
+    pdf = view_class.new(company: "Test Co").to_pdf
+    assert_includes pdf, "Test Co"
+  end
+
+  def test_layout_with_qr_code_generates_from_data
+    layout_class = Class.new(Pdf::Layout) do
+      header do
+        qr_code data: :qr_data, size: 50, position: :right
+        context :header_info
+      end
+
+      footer do
+        page_number
+      end
+    end
+
+    lc = layout_class
+    view_class = Class.new(Pdf::View) do
+      layout lc
+
+      title "QR Code Document"
+      paragraph "Document with QR code in header"
+
+      def qr_data = "https://example.com/doc/#{data[:id]}"
+      def header_info = ["Document ##{data[:id]}"]
+    end
+
+    pdf = view_class.new(id: "12345").to_pdf
+    assert pdf.start_with?("%PDF")
+    assert pdf.length > 5000  # QR code adds size
+  end
+
+  def test_multi_page_document_with_footer
+    layout_class = Class.new(Pdf::Layout) do
+      footer do
+        text "Footer on every page"
+        page_number position: :right
+      end
+    end
+
+    lc = layout_class
+    view_class = Class.new(Pdf::View) do
+      layout lc
+
+      title "Multi-Page Document"
+
+      each(:pages) do |page|
+        heading page[:title]
+        paragraph page[:content]
+        page_break
+      end
+
+      def pages = data[:pages]
+    end
+
+    pages = 5.times.map { |i| { title: "Page #{i + 1}", content: "Content " * 100 } }
+    pdf = view_class.new(pages: pages).to_pdf
+    assert pdf.start_with?("%PDF")
+  end
+end
+```
+
+---
+
+## 8.3 Inheritance Integration
+
+```ruby
+# test/integration/inheritance_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class InheritanceIntegrationTest < Minitest::Test
+  def test_child_includes_parent_elements
+    base_view = Class.new(Pdf::View) do
+      title "Base Report"
+      hr
+      spacer amount: 10
+    end
+
+    child_view = Class.new(base_view) do
+      subtitle "Child Section"
+      paragraph :content
+
+      def content = data[:content]
+    end
+
+    pdf = child_view.new(content: "Child content").to_pdf
+    assert_includes pdf, "Base Report"
+    assert_includes pdf, "Child Section"
+    assert_includes pdf, "Child content"
+  end
+
+  def test_parent_remains_unchanged_after_child_access
+    base_view = Class.new(Pdf::View) do
+      title "Base Report"
+      hr
+      spacer amount: 10
+    end
+
+    child_view = Class.new(base_view) do
+      subtitle "Child Section"
+      paragraph :content
+      def content = data[:content]
+    end
+
+    # Trigger child
+    child_view.new(content: "test").to_pdf
+
+    # Parent should still only have its own elements
+    assert_equal 3, base_view.blueprint.elements.size
+  end
+
+  def test_maintains_element_order
+    base_view = Class.new(Pdf::View) do
+      title "Base Report"
+      hr
+      spacer amount: 10
+    end
+
+    child_view = Class.new(base_view) do
+      subtitle "Child Section"
+      paragraph "Content"
+    end
+
+    elements = child_view.blueprint.elements
+    types = elements.map { |e| e[:type] }
+
+    assert_equal [:title, :hr, :spacer, :subtitle, :paragraph], types
+  end
+
+  def test_multi_level_inheritance_accumulates_elements
+    level1 = Class.new(Pdf::View) do
+      title "Level 1"
+    end
+
+    level2 = Class.new(level1) do
+      subtitle "Level 2"
+    end
+
+    level3 = Class.new(level2) do
+      paragraph "Level 3"
+    end
+
+    assert_equal 1, level1.blueprint.elements.size
+    assert_equal 2, level2.blueprint.elements.size
+    assert_equal 3, level3.blueprint.elements.size
+  end
+
+  def test_multi_level_inheritance_generates_pdf_with_all_elements
+    level1 = Class.new(Pdf::View) do
+      title "Level 1"
+    end
+
+    level2 = Class.new(level1) do
+      subtitle "Level 2"
+    end
+
+    level3 = Class.new(level2) do
+      paragraph "Level 3"
+    end
+
+    pdf = level3.new.to_pdf
+    assert_includes pdf, "Level 1"
+    assert_includes pdf, "Level 2"
+    assert_includes pdf, "Level 3"
+  end
+
+  def test_child_inherits_layout_from_parent
+    shared_layout = Class.new(Pdf::Layout) do
+      footer do
+        text "Shared Footer"
+        page_number
+      end
+    end
+
+    lc = shared_layout
+    base_with_layout = Class.new(Pdf::View) do
+      layout lc
+      title "Base with Layout"
+    end
+
+    child_with_layout = Class.new(base_with_layout) do
+      paragraph "Extended content"
+    end
+
+    assert_equal shared_layout, child_with_layout.blueprint.layout_class
+  end
+
+  def test_generates_pdf_with_inherited_layout
+    shared_layout = Class.new(Pdf::Layout) do
+      footer do
+        text "Shared Footer"
+        page_number
+      end
+    end
+
+    lc = shared_layout
+    base_with_layout = Class.new(Pdf::View) do
+      layout lc
+      title "Base with Layout"
+    end
+
+    child_with_layout = Class.new(base_with_layout) do
+      paragraph "Extended content"
+    end
+
+    pdf = child_with_layout.new.to_pdf
+    assert_includes pdf, "Base with Layout"
+    assert_includes pdf, "Extended content"
+  end
+end
+```
+
+---
+
+## 8.4 Conditional Rendering Integration
+
+```ruby
+# test/integration/conditional_rendering_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ConditionalRenderingIntegrationTest < Minitest::Test
+  def test_render_if_renders_when_condition_true
+    view_class = Class.new(Pdf::View) do
+      title "Conditional Document"
+
+      render_if(:show_summary) do
+        alert title: "Summary", description: "This is the summary", color: "blue"
+      end
+
+      render_if(:show_details) do
+        section "Details" do
+          table :detail_items, columns: [:key, :value]
+        end
+      end
+
+      paragraph "Always visible"
+
+      def show_summary = data[:summary]
+      def show_details = data[:details]
+      def detail_items = [{ key: "A", value: "1" }]
+    end
+
+    pdf = view_class.new(summary: true, details: false).to_pdf
+    assert_includes pdf, "Summary"
+    refute_includes pdf, "Details"
+  end
+
+  def test_render_if_skips_when_condition_false
+    view_class = Class.new(Pdf::View) do
+      title "Conditional Document"
+
+      render_if(:show_summary) do
+        alert title: "Summary", color: "blue"
+      end
+
+      paragraph "Always visible"
+
+      def show_summary = data[:summary]
+    end
+
+    pdf = view_class.new(summary: false).to_pdf
+    refute_includes pdf, "Summary"
+    assert_includes pdf, "Always visible"
+  end
+
+  def test_render_if_handles_multiple_conditions
+    view_class = Class.new(Pdf::View) do
+      render_if(:show_summary) do
+        alert title: "Summary", color: "blue"
+      end
+
+      render_if(:show_details) do
+        section "Details" do
+          paragraph "Detail content"
+        end
+      end
+
+      def show_summary = data[:summary]
+      def show_details = data[:details]
+    end
+
+    pdf = view_class.new(summary: true, details: true).to_pdf
+    assert_includes pdf, "Summary"
+    assert_includes pdf, "Details"
+  end
+
+  def test_render_unless_renders_when_condition_false
+    view_class = Class.new(Pdf::View) do
+      title "Document"
+
+      render_unless(:is_draft) do
+        alert title: "FINAL", color: "green"
+      end
+
+      render_unless(:hide_watermark) do
+        paragraph "CONFIDENTIAL"
+      end
+
+      def is_draft = data[:draft]
+      def hide_watermark = data[:no_watermark]
+    end
+
+    pdf = view_class.new(draft: false, no_watermark: false).to_pdf
+    assert_includes pdf, "FINAL"
+    assert_includes pdf, "CONFIDENTIAL"
+  end
+
+  def test_render_unless_skips_when_condition_true
+    view_class = Class.new(Pdf::View) do
+      title "Document"
+
+      render_unless(:is_draft) do
+        alert title: "FINAL", color: "green"
+      end
+
+      render_unless(:hide_watermark) do
+        paragraph "CONFIDENTIAL"
+      end
+
+      def is_draft = data[:draft]
+      def hide_watermark = data[:no_watermark]
+    end
+
+    pdf = view_class.new(draft: true, no_watermark: true).to_pdf
+    refute_includes pdf, "FINAL"
+    refute_includes pdf, "CONFIDENTIAL"
+  end
+
+  def test_nested_conditionals
+    view_class = Class.new(Pdf::View) do
+      title "Nested Conditions"
+
+      render_if(:level1) do
+        heading "Level 1 Visible"
+
+        render_if(:level2) do
+          paragraph "Level 2 Also Visible"
+        end
+      end
+
+      def level1 = data[:l1]
+      def level2 = data[:l2]
+    end
+
+    pdf = view_class.new(l1: true, l2: true).to_pdf
+    assert_includes pdf, "Level 1 Visible"
+    assert_includes pdf, "Level 2 Also Visible"
+  end
+
+  def test_nested_conditionals_outer_false_prevents_inner
+    view_class = Class.new(Pdf::View) do
+      title "Nested Conditions"
+
+      render_if(:level1) do
+        heading "Level 1 Visible"
+
+        render_if(:level2) do
+          paragraph "Level 2 Also Visible"
+        end
+      end
+
+      def level1 = data[:l1]
+      def level2 = data[:l2]
+    end
+
+    pdf = view_class.new(l1: false, l2: true).to_pdf
+    refute_includes pdf, "Level 1 Visible"
+    refute_includes pdf, "Level 2 Also Visible"
+  end
+
+  def test_conditional_with_complex_boolean_logic
+    view_class = Class.new(Pdf::View) do
+      title "Complex Logic"
+
+      render_if(:has_premium_features) do
+        section "Premium Features" do
+          paragraph "Exclusive content"
+        end
+      end
+
+      def has_premium_features
+        data[:plan] == "premium" && data[:active]
+      end
+    end
+
+    premium_active = view_class.new(plan: "premium", active: true).to_pdf
+    assert_includes premium_active, "Premium Features"
+
+    premium_inactive = view_class.new(plan: "premium", active: false).to_pdf
+    refute_includes premium_inactive, "Premium Features"
+
+    basic_active = view_class.new(plan: "basic", active: true).to_pdf
+    refute_includes basic_active, "Premium Features"
+  end
+end
+```
+
+---
+
+## 8.5 Components Integration
+
+```ruby
+# test/integration/components_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ComponentsIntegrationTest < Minitest::Test
+  def test_all_built_in_components_render_without_error
+    view_class = Class.new(Pdf::View) do
+      title "Component Showcase", size: 24
+      subtitle "All Components Demo"
+      date :today, format: "%Y-%m-%d"
+      hr
+      spacer amount: 15
+      heading "Main Heading", size: 16
+      paragraph "A paragraph with content.", leading: 4
+      span "Inline span text"
+
+      alert title: "Info Alert", description: "This is informational", color: "blue"
+      alert title: "Success", color: "green"
+      alert title: "Warning", color: "orange"
+      alert title: "Error", color: "red"
+
+      section "Data Section" do
+        table :sample_table, columns: [:id, :name, :status]
+      end
+
+      context :context_lines, label: "METADATA"
+
+      def today = Date.today
+      def sample_table
+        [
+          { id: 1, name: "Alpha", status: "Active" },
+          { id: 2, name: "Beta", status: "Pending" }
+        ]
+      end
+      def context_lines
+        ["Line 1: Value", "Line 2: Another Value"]
+      end
+    end
+
+    view_class.new.to_pdf  # Should not raise
+  end
+
+  def test_all_components_generate_substantial_pdf
+    view_class = Class.new(Pdf::View) do
+      title "Component Showcase", size: 24
+      subtitle "All Components Demo"
+      alert title: "Info", color: "blue"
+      section "Data" do
+        table :items, columns: [:a, :b]
+      end
+      def items = [{ a: "1", b: "2" }]
+    end
+
+    pdf = view_class.new.to_pdf
+    assert pdf.length > 10_000
+  end
+
+  def test_date_component_formats_dates_correctly
+    view_class = Class.new(Pdf::View) do
+      date :report_date
+      date :custom_date, format: "%d/%m/%Y"
+      date "String date"
+
+      def report_date = Date.new(2024, 12, 25)
+      def custom_date = Date.new(2024, 1, 15)
+    end
+
+    pdf = view_class.new.to_pdf
+    assert_includes pdf, "December 25, 2024"
+    assert_includes pdf, "15/01/2024"
+    assert_includes pdf, "String date"
+  end
+
+  def test_table_with_various_data_formats
+    view_class = Class.new(Pdf::View) do
+      # Array of hashes with columns
+      table :hash_data, columns: [:a, :b]
+
+      # Pre-formatted data
+      table :formatted_data
+
+      # With percentage widths
+      table :width_data, columns: [:col1, :col2], widths: ["70%", "30%"]
+
+      def hash_data
+        [{ a: "A1", b: "B1" }, { a: "A2", b: "B2" }]
+      end
+
+      def formatted_data
+        { headers: ["X", "Y"], rows: [["x1", "y1"], ["x2", "y2"]] }
+      end
+
+      def width_data
+        [{ col1: "Wide", col2: "Narrow" }]
+      end
+    end
+
+    pdf = view_class.new.to_pdf
+    assert_includes pdf, "A1"
+    assert_includes pdf, "x1"
+    assert_includes pdf, "Wide"
+  end
+
+  def test_custom_registered_component_in_dsl
+    badge_class = Class.new(Pdf::Component) do
+      def render(text, style: "default", **_opts)
+        @pdf.text "[#{style.upcase}] #{text}", size: 10
+        move_down 5
+      end
+    end
+    Pdf.register_component(:badge, badge_class)
+
+    view_class = Class.new(Pdf::View) do
+      title "Custom Component Test"
+      badge "Active", style: "success"
+      badge "Warning", style: "warn"
+    end
+
+    pdf = view_class.new.to_pdf
+    assert_includes pdf, "[SUCCESS] Active"
+    assert_includes pdf, "[WARN] Warning"
+  ensure
+    Pdf.instance_variable_get(:@components).delete(:badge)
+  end
+end
+```
+
+---
+
+## 8.6 Error Handling Integration
+
+```ruby
+# test/integration/error_handling_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ErrorHandlingIntegrationTest < Minitest::Test
+  def test_raises_file_not_found_error_for_missing_logo
+    renderer = Pdf::Renderer.new.setup
+    logo = Pdf::Components::Logo.new(renderer.pdf)
+
+    error = assert_raises(Pdf::FileNotFoundError) do
+      logo.render("/nonexistent/logo.png")
+    end
+    assert_match(/Logo not found/, error.message)
+  end
+
+  def test_raises_file_not_found_error_for_missing_image
+    renderer = Pdf::Renderer.new.setup
+
+    error = assert_raises(Pdf::FileNotFoundError) do
+      renderer.image("/nonexistent/image.png")
+    end
+    assert_match(/Image not found/, error.message)
+  end
+
+  def test_raises_resolution_error_for_undefined_symbols
+    view_class = Class.new(Pdf::View) do
+      title :undefined_method
+    end
+
+    view = view_class.new
+    error = assert_raises(Pdf::ResolutionError) do
+      view.to_pdf
+    end
+    assert_match(/Cannot resolve/, error.message)
+  end
+
+  def test_raises_argument_error_for_non_component_class
+    error = assert_raises(ArgumentError) do
+      Pdf.register_component(:bad, String)
+    end
+    assert_match(/must inherit from Pdf::Component/, error.message)
+  end
+
+  def test_raises_error_for_unknown_component
+    error = assert_raises(Pdf::Error) do
+      Pdf.component(:nonexistent)
+    end
+    assert_match(/Unknown component/, error.message)
+  end
+
+  def test_raises_for_invalid_table_width_format
+    renderer = Pdf::Renderer.new.setup
+    table = Pdf::Components::Table.new(renderer.pdf)
+
+    error = assert_raises(ArgumentError) do
+      table.render(headers: ["A"], rows: [["1"]], widths: [{ invalid: true }])
+    end
+    assert_match(/Invalid width/, error.message)
+  end
+
+  def test_raises_for_nil_context_lines
+    renderer = Pdf::Renderer.new.setup
+    context = Pdf::Components::Context.new(renderer.pdf)
+
+    error = assert_raises(ArgumentError) do
+      context.render(nil)
+    end
+    assert_match(/cannot be nil/, error.message)
+  end
+
+  def test_handles_empty_collections_gracefully
+    view_class = Class.new(Pdf::View) do
+      title "Safe Document"
+
+      # Empty collection - should not error
+      each(:items) { |i| paragraph i[:name] }
+
+      # Empty context - should not error
+      render_if(:has_context) do
+        context :ctx_lines
+      end
+
+      def items = []
+      def has_context = false
+      def ctx_lines = []
+    end
+
+    view_class.new.to_pdf  # Should not raise
+  end
+end
+```
+
+---
+
+## 8.7 Raw Prawn Access Integration
+
+```ruby
+# test/integration/raw_access_test.rb
+# frozen_string_literal: true
+
+require "test_helper"
+
+class RawAccessIntegrationTest < Minitest::Test
+  def test_raw_block_executes_prawn_commands
+    view_class = Class.new(Pdf::View) do
+      title "Document with Raw Access"
+
+      raw do |pdf|
+        pdf.stroke_color "FF0000"
+        pdf.line_width 2
+        pdf.stroke_horizontal_line 0, pdf.bounds.width
+        pdf.stroke_color "000000"
+        pdf.line_width 1
+      end
+
+      paragraph "Content after raw block"
+
+      raw do |pdf|
+        pdf.fill_color "CCCCCC"
+        pdf.fill_rectangle [0, pdf.cursor], 100, 20
+        pdf.fill_color "000000"
+      end
+    end
+
+    pdf = view_class.new.to_pdf
+    assert pdf.start_with?("%PDF")
+    assert_includes pdf, "Content after raw block"
+  end
+
+  def test_complex_raw_drawing
+    view_class = Class.new(Pdf::View) do
+      title "Custom Drawing"
+
+      raw do |pdf|
+        # Draw a simple chart-like element
+        pdf.stroke_color "333333"
+
+        # Axes
+        pdf.stroke do
+          pdf.line [50, 200], [50, 50]   # Y axis
+          pdf.line [50, 50], [250, 50]   # X axis
+        end
+
+        # Bars
+        pdf.fill_color "4CAF50"
+        pdf.fill_rectangle [70, 150], 30, 100
+        pdf.fill_color "2196F3"
+        pdf.fill_rectangle [120, 120], 30, 70
+        pdf.fill_color "FF9800"
+        pdf.fill_rectangle [170, 180], 30, 130
+
+        pdf.fill_color "000000"
+      end
+
+      paragraph "Chart rendered above"
+    end
+
+    view_class.new.to_pdf  # Should not raise
+  end
+
+  def test_renderer_raw_yields_prawn_document
+    renderer = Pdf::Renderer.new.setup
+    yielded = nil
+
+    renderer.raw { |pdf| yielded = pdf }
+
+    assert_equal renderer.pdf, yielded
+  end
+end
+```
+
+---
+
+## Running Integration Tests
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run specific test file
+bundle exec ruby -Itest test/integration/basic_view_test.rb
+
+# Run with verbose output
+bundle exec rake test TESTOPTS="--verbose"
+```
+
+## Test Helpers
+
+```ruby
+# test/test_helper.rb
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "pdf"
+require "minitest/autorun"
+
+# Optional: Add helper methods available to all tests
+module PdfTestHelpers
+  def extract_text(pdf_binary)
+    # Basic text extraction - for more robust extraction use pdf-reader gem
+    pdf_binary.scan(/\((.*?)\)/).flatten.join(" ")
+  end
+
+  def pdf_page_count(pdf_binary)
+    pdf_binary.scan(/\/Type\s*\/Page[^s]/).size
+  end
+end
+
+# Include helpers in all tests
+class Minitest::Test
+  include PdfTestHelpers
+end
+```