probatio_diabolica 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39336802d7f3c344f21acbf0567ea85a73dfbc68c2d339e7ab5e1e1866fc609e
-  data.tar.gz: c4f0fa5209ac0a7437edf9e6cf117b95fe859217b49e172557f05c44dc664307
+  metadata.gz: 330f1282105f0f742f5655a83dbf8e885eecb7d48308cad74c79418b7212cf8e
+  data.tar.gz: d13b0e8d80d2480ee3603b8002f0666672e35bd1c4357caff0e77dbe071e8093
 SHA512:
-  metadata.gz: f78a5ff31c1b5cbee275d596ef74529b0fad41426c4b7ee5303d98d4224cbcf20718485403ec048fc4f26159775c0ae8e33c07eeeb95e6944c2a21cf3feeec26
-  data.tar.gz: ffa412e8bc62906e1c9be463a9d48dc9a30bbf4e4fcf458abc1e203026bde0a7e5f60ae0dce03c33cd6375c5402060b80ae1b1cf0b610328b1808a5eb436b8cf
+  metadata.gz: 825c6a20382d228a6a319c49dff0986a019af07d6eb098a9c541bdd785fde0f85ee82a54302dfc94d7eb8d58ccf672ee134ec4b4b7ce9590e43c0d88b2326d9c
+  data.tar.gz: cf20aabac6b541278ed6978171e9b59d2eda1649e560f6221144a985907d1274e67117ac470504c9afe123fbd12ab0940f634fd5a7382395b35189408304bdc4

data/README.md

@@ -12,9 +12,10 @@ This project is experimental and not production-ready.
 
 `probatio_diabolica` runs `*_spec.rb` files through a custom runtime (`PrD::Runtime`) with an RSpec-like syntax:
 
-- `describe`, `context`, `it`, `pending`, `let`, `subject`
+- `describe`, `context`, `it`, `pending`, `let`, `subject`, `subject!`
+- `before`, `after`
 - `expect(...).to(...)` and `expect(...).not_to(...)`
-- standard matchers (`eq`, `be`, `includes`, `have`, `all`)
+- standard matchers (`eq`, `be`, `empty`, `gt`, `gte`, `lt`, `lte`, `includes`, `have`, `all`)
 - LLM matcher `satisfy(...)` to validate natural-language conditions
 
 Tests are evaluated with `instance_eval` (not through RSpec).
@@ -141,14 +142,23 @@ It is inspired by RSpec but with a custom runtime and additional features.
 ```ruby
 describe 'My domain' do
   context 'my context' do
+    before do
+      @sum = 0
+    end
+
     let(:two) { 2 }
     let(:three) { 3 }
     subject { two + three }
 
     it 'runs an assertion' do
+      @sum += subject
       expect.to eq(5)
     end
 
+    after do
+      expect(@sum).to(eq(5))
+    end
+
     pending 'test to implement later'
   end
 end
@@ -159,7 +169,22 @@ end
 - `expect(actual).to matcher`
 - `expect(actual).not_to matcher`
 - `expect { |subject| ... }.to matcher`
-- `expect.to matcher` (uses `subject`)
+- `expect.to matcher` (uses `subject` / `subject!`)
+- In verbose formatter output, when `actual` or matcher `expected` come from a `let`, the expectation sentence uses the `let` name.
+- A failed expectation reports a detailed message (with names/values) in `Justification`.
+
+### Hooks (`before` / `after`)
+
+- `before { ... }` runs before each `it` in the current context and nested contexts
+- `after { ... }` runs after each `it` in the current context and nested contexts
+- nested order:
+  - `before`: outer to inner
+  - `after`: inner to outer
+
+### Subject (`subject` vs `subject!`)
+
+- `subject { ... }`: lazy, evaluated on first access in each example, memoized for that example
+- `subject! { ... }`: eager, evaluated before each example body (uses an implicit `before`)
 
 ### Spec best practices for `subject` (PRD reports)
 
@@ -201,10 +226,21 @@ end
 
 - `eq(expected)` equality with `==`
 - `be(expected)` object identity (`equal?`)
+- `empty` checks `empty?` on the actual value
+- `gt(expected)` strictly greater than (`>`)
+- `gte(expected)` greater than or equal (`>=`)
+- `lt(expected)` strictly less than (`<`)
+- `lte(expected)` less than or equal (`<=`)
 - `includes(expected)` inclusion for `String`, `Array`, `File`, `PDF::Reader`
 - `have(expected)` alias inclusion via `include?`
 - `all(proc)` checks all elements against a block
-- `satisfy(natural_language_condition)` LLM-based validation
+- `satisfy(natural_language_condition)` LLM-based validation (supports text, single image `File`, or array of image files)
+
+Example:
+
+```ruby
+expect(new_image_size).to be gt(0)
+```
 
 ### Browser helpers (Ferrum)
 
@@ -218,6 +254,9 @@ end
 - `pdf(at:, warmup_time:)` generates a PDF and returns a `PDF::Reader`
 - `html(at:, warmup_time:)` returns HTML (`browser.body`)
 
+Detailed dedicated documentation:
+- `docs/chrome_helper.md` (full API contract, inputs/outputs, errors, and LLM-oriented usage patterns)
+
 `BrowserSession` adds high-level page interactions:
 
 - `find(css:/xpath:, wait:, shadow:)`
@@ -315,31 +354,73 @@ In CLI usage:
 
 - selecting one formatter writes one output stream/file
 - selecting multiple formatters runs tests once and writes one file per formatter
+- expectation rendering is sentence-based across human-readable formatters (for example `Expect 321 to be equal to 321`) to reduce vertical noise
+- HTML/PDF also emphasize keywords and actual/expected values for faster scanning
 
-### Subject rendering policy (best effort)
+### Let/subject rendering policy (best effort)
 
-When you define a `subject`, each formatter tries to render it in the most useful way for its medium:
+When you define a `let` or `subject`, each formatter tries to render it in the most useful way for its medium:
 
 - `SimpleFormatter`:
   - renders readable text in terminal
+  - prints `Let(:name)` blocks to make fixture values explicit
+  - for `Hash`/`Array` subjects, prints one key/index per line with nested indentation
   - for files, prints a textual representation (for example path, file preview for `.txt`)
+  - for `Ferrum::Node`, prints a readable summary (`Ferrum::Node <tag#id.class> text="..."`) instead of the Ruby object id
 - `HtmlFormatter`:
+  - renders `let` values inside collapsed blocks (click to open)
   - renders text values directly
+  - for `Hash`/`Array` subjects, renders nested key/value blocks for better readability
   - for `PrD::Code`, renders syntax-highlighted code blocks (Rouge) inside collapsible sections
   - for image files (`.png`, `.jpg`, `.jpeg`), embeds the image in the report
   - for PDF subjects (`File` `.pdf` or `PDF::Reader`), embeds the PDF with a `data:application/pdf;base64,...` URI
+  - for `Ferrum::Node`, renders the same readable summary with HTML escaping
 - `PdfFormatter`:
   - renders text values as report lines
+  - for `Hash`/`Array` subjects, renders nested key/value lines
   - for `PrD::Code`, renders language + syntax-highlighted code block (Rouge -> Prawn colors)
   - for image files (`.png`, `.jpg`, `.jpeg`), inserts the image directly in the PDF report
+  - for `Ferrum::Node`, renders the same readable summary in the generated PDF text
 - `JsonFormatter`:
   - keeps a structured representation for machine processing
+  - includes `name` in `let` events when available
+  - preserves nested `Hash`/`Array` structure in event payloads
   - for `PrD::Code`, emits a structured payload (`type: "code"`, `language`, `source`)
   - `File` values (images, PDFs, text files, etc.) are embedded as base64 payloads
   - `PDF::Reader` values are also embedded as base64 (`application/pdf`)
+  - for `Ferrum::Node`, emits a structured payload (`type: "ferrum_node"`, `selector`, `text`, `html_preview`, `summary`)
 
 The goal is to preserve readability and report size while surfacing the richest representation each formatter can reasonably support.
 
+Detailed dedicated documentation:
+- `docs/let_subject_rendering.md` (rendering pipeline, adapter injection, formatter behavior, compatibility notes)
+
+### Inject custom display adapters
+
+You can inject custom display logic for domain objects that are not natively handled:
+
+```ruby
+formatter = PrD::Formatters::HtmlFormatter.new(
+  io: $stdout,
+  serializers: {},
+  display_adapters: {
+    MyDomainObject => lambda do |value|
+      {
+        title: value.name,
+        preview: PrD::Code.new(source: value.to_json, language: 'json')
+      }
+    end
+  }
+)
+```
+
+Rules:
+
+- adapter key (`MyDomainObject` above) can be a class/module, a symbol (duck-typing via `respond_to?`), or a predicate proc
+- adapter value must be callable
+- adapter output can reuse native display types (`String`, `Hash`, `Array`, `PrD::Code`, `File`, `PDF::Reader`, etc.)
+- adapters are applied before default formatter heuristics, so native rendering still applies to the transformed value
+
 ## Useful references in this repository
 
 - Basic example: `examples/basics_spec.rb`

data/bin/prd

@@ -24,12 +24,12 @@ class CompositeFormatter
     @formatters = formatters
   end
 
-  def method_missing(name, *args, &block)
+  def method_missing(name, *args, **kwargs, &block)
     handled = false
     @formatters.each do |formatter|
       next unless formatter.respond_to?(name)
 
-      formatter.public_send(name, *args, &block)
+      formatter.public_send(name, *args, **kwargs, &block)
       handled = true
     end
 

data/lib/pr_d/formatters/formatter.rb

@@ -2,13 +2,16 @@ module PrD
   module Formatters
     class Formatter
       SUPPORTED_MODES = %i[verbose synthetic].freeze
+      MISSING_VALUE = Object.new
+      NO_EXPECTED_VALUE = Object.new
 
-      def initialize(io: $stdout, serializers: {}, mode: :verbose)
+      def initialize(io: $stdout, serializers: {}, mode: :verbose, display_adapters: {})
         @io = io
         @serializers = serializers
         @level = 0
         @mode = normalize_mode(mode)
         @current_test_title = nil
+        @display_adapters = normalize_display_adapters(display_adapters)
       end
 
       def title(message)
@@ -43,11 +46,27 @@ module PrD
         raise NotImplementedError, "#{self.class} must implement #subject"
       end
 
+      def subject_display_strategy
+        :on_evaluation
+      end
+
+      def eager_subject_display_strategy
+        subject_display_strategy
+      end
+
+      def register_display_adapter(matcher, callable = nil, &block)
+        adapter = callable || block
+        raise ArgumentError, 'Display adapter must be callable.' unless adapter.respond_to?(:call)
+
+        @display_adapters << [matcher, adapter]
+        self
+      end
+
       def pending(description = nil)
         raise NotImplementedError, "#{self.class} must implement #pending"
       end
 
-      def expect(expectation)
+      def expect(expectation, label: nil)
         raise NotImplementedError, "#{self.class} must implement #expect"
       end
 
@@ -92,8 +111,12 @@ module PrD
       end
 
       def serialize(value)
+        value = apply_display_adapter(value)
+        return 'nil' if value.nil?
+
         serializer = @serializers[value.class]
         return serializer.call(value) if serializer
+        return ferrum_node_summary(value) if ferrum_node?(value)
         return value.path if value.is_a?(File)
         return value.map { |v| serialize(v) } if value.is_a?(Array)
         return value.transform_values { |v| serialize(v) } if value.is_a?(Hash)
@@ -104,6 +127,332 @@ module PrD
       def code_object?(value)
         defined?(PrD::Code) && value.is_a?(PrD::Code)
       end
+
+      def ferrum_node?(value)
+        value.respond_to?(:class) && value.class.respond_to?(:name) && value.class.name == 'Ferrum::Node'
+      rescue StandardError
+        false
+      end
+
+      def ferrum_node_payload(node)
+        payload = ferrum_node_payload_from_js(node) || {}
+        payload[:tag] = payload[:tag].to_s.downcase.strip unless blank_text?(payload[:tag])
+        payload[:id] = payload[:id].to_s.strip unless blank_text?(payload[:id])
+        payload[:classes] = normalize_classes(payload[:classes])
+        payload[:text] = normalize_preview_text(payload[:text], max_length: 160)
+        payload[:html] = normalize_preview_text(payload[:html], max_length: 220)
+        payload[:description] = normalize_preview_text(payload[:description], max_length: 160)
+        payload
+      rescue StandardError
+        {}
+      end
+
+      def ferrum_node_summary(node)
+        payload = ferrum_node_payload(node)
+        selector = ferrum_node_selector(payload)
+        summary = +'Ferrum::Node'
+        summary << " <#{selector}>" unless selector.nil?
+
+        if blank_text?(payload[:text]) && !blank_text?(payload[:description])
+          summary << " #{payload[:description]}"
+          return summary
+        end
+
+        summary << %( text="#{payload[:text]}") unless blank_text?(payload[:text])
+        summary
+      rescue StandardError
+        'Ferrum::Node'
+      end
+
+      def ferrum_node_selector(payload)
+        return nil unless payload.is_a?(Hash)
+
+        selector = +''
+        selector << payload[:tag].to_s unless blank_text?(payload[:tag])
+        selector << "##{payload[:id]}" unless blank_text?(payload[:id])
+        Array(payload[:classes]).each do |class_name|
+          class_name_text = class_name.to_s.strip
+          next if class_name_text.empty?
+
+          selector << ".#{class_name_text}"
+        end
+
+        return nil if selector.empty?
+
+        selector
+      end
+
+      def ferrum_node_payload_from_js(node)
+        return nil unless node.respond_to?(:evaluate)
+
+        raw_payload = node.evaluate(<<~JS)
+          (() => {
+            const element = this;
+            if (!element) return null;
+
+            const rawClassName = element.className;
+            const className =
+              typeof rawClassName === "string" ? rawClassName :
+              (rawClassName && typeof rawClassName.baseVal === "string" ? rawClassName.baseVal : "");
+
+            const classes = className
+              .split(/\\s+/)
+              .map((token) => token.trim())
+              .filter((token) => token.length > 0);
+
+            const textValue = (element.innerText || element.textContent || "").replace(/\\s+/g, " ").trim();
+            const htmlValue = element.outerHTML || "";
+
+            return {
+              tag: element.tagName ? element.tagName.toLowerCase() : null,
+              id: element.id || null,
+              classes,
+              text: textValue.length > 160 ? `${textValue.slice(0, 157)}...` : textValue,
+              html: htmlValue.length > 220 ? `${htmlValue.slice(0, 217)}...` : htmlValue
+            };
+          })()
+        JS
+        return nil unless raw_payload.is_a?(Hash)
+
+        {
+          tag: raw_payload['tag'] || raw_payload[:tag],
+          id: raw_payload['id'] || raw_payload[:id],
+          classes: raw_payload['classes'] || raw_payload[:classes],
+          text: raw_payload['text'] || raw_payload[:text],
+          html: raw_payload['html'] || raw_payload[:html]
+        }
+      rescue StandardError
+        {
+          tag: safe_node_call(node, :tag_name),
+          text: safe_node_call(node, :text),
+          description: safe_node_call(node, :description)
+        }
+      end
+
+      def safe_node_call(node, method_name)
+        return nil unless node.respond_to?(method_name)
+
+        node.public_send(method_name)
+      rescue StandardError
+        nil
+      end
+
+      def normalize_classes(value)
+        Array(value)
+          .flat_map { |entry| entry.to_s.split(/\s+/) }
+          .map(&:strip)
+          .reject(&:empty?)
+          .uniq
+      end
+
+      def normalize_preview_text(value, max_length:)
+        text = value.to_s.gsub(/\s+/, ' ').strip
+        return nil if text.empty?
+        return text if text.length <= max_length
+
+        "#{text[0, max_length - 3]}..."
+      end
+
+      def blank_text?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+
+      def named_value_arguments(name_or_value, value)
+        return [nil, name_or_value] if value.equal?(MISSING_VALUE)
+
+        [name_or_value, value]
+      end
+
+      def display_node(value, seen: {})
+        resolved = apply_display_adapter(value)
+
+        if code_object?(resolved)
+          return {
+            type: :code,
+            language: resolved.language.to_s,
+            source: resolved.source.to_s
+          }
+        end
+
+        image_path = display_image_path(resolved)
+        return { type: :image, path: image_path } unless image_path.nil?
+
+        pdf_path = display_pdf_path(resolved)
+        return { type: :pdf_file, path: pdf_path } unless pdf_path.nil?
+
+        if display_pdf_reader?(resolved)
+          return { type: :pdf_reader, reader: resolved }
+        end
+
+        if resolved.is_a?(Hash)
+          return { type: :text, text: '[Circular reference]' } if circular_reference?(resolved, seen)
+
+          begin
+            entries = resolved.map do |key, entry_value|
+              { label: serialize(key).to_s, value: display_node(entry_value, seen: seen) }
+            end
+          ensure
+            seen.delete(resolved.object_id)
+          end
+
+          return { type: :map, entries: entries }
+        end
+
+        if resolved.is_a?(Array)
+          return { type: :text, text: '[Circular reference]' } if circular_reference?(resolved, seen)
+
+          begin
+            items = resolved.map { |entry| display_node(entry, seen: seen) }
+          ensure
+            seen.delete(resolved.object_id)
+          end
+
+          return { type: :list, items: items }
+        end
+
+        { type: :text, text: serialize(resolved).to_s }
+      end
+
+      def display_file_path(value)
+        return value.path if value.is_a?(File)
+        return nil unless value.respond_to?(:path)
+
+        path = value.path
+        path.is_a?(String) && !path.empty? ? path : nil
+      rescue StandardError
+        nil
+      end
+
+      def display_image_path(value)
+        path = display_file_path(value)
+        return nil if path.nil?
+        return nil unless path.match?(/\.(png|jpe?g)\z/i)
+
+        path
+      end
+
+      def display_pdf_path(value)
+        path = display_file_path(value)
+        return nil if path.nil?
+        return nil unless path.match?(/\.pdf\z/i)
+
+        path
+      end
+
+      def display_pdf_reader?(value)
+        defined?(PDF::Reader) && value.is_a?(PDF::Reader)
+      end
+
+      def apply_display_adapter(value)
+        adapter = find_display_adapter(value)
+        return value if adapter.nil?
+
+        if adapter.arity.abs >= 2
+          adapter.call(value, self)
+        else
+          adapter.call(value)
+        end
+      end
+
+      def find_display_adapter(value)
+        @display_adapters.each do |matcher, adapter|
+          return adapter if display_matcher_matches?(matcher, value)
+        end
+
+        nil
+      end
+
+      def display_matcher_matches?(matcher, value)
+        case matcher
+        when Symbol
+          value.respond_to?(matcher)
+        when Proc
+          matcher.call(value)
+        else
+          matcher === value
+        end
+      rescue StandardError
+        false
+      end
+
+      def normalize_display_adapters(display_adapters)
+        return [] if display_adapters.nil?
+
+        entries =
+          if display_adapters.is_a?(Hash)
+            display_adapters.to_a
+          elsif display_adapters.is_a?(Array)
+            display_adapters
+          else
+            raise ArgumentError, '`display_adapters` must be a Hash or an Array of [matcher, adapter].'
+          end
+
+        entries.map do |entry|
+          matcher, adapter =
+            if entry.is_a?(Array) && entry.length == 2
+              entry
+            else
+              raise ArgumentError, '`display_adapters` entries must be [matcher, adapter].'
+            end
+
+          raise ArgumentError, 'Display adapter matcher is required.' if matcher.nil?
+          raise ArgumentError, 'Display adapter must be callable.' unless adapter.respond_to?(:call)
+
+          [matcher, adapter]
+        end
+      end
+
+      def circular_reference?(value, seen)
+        object_id = value.object_id
+        return true if seen.key?(object_id)
+
+        seen[object_id] = true
+        false
+      end
+
+      def matcher_sentence_parts(matcher, sources:)
+        case matcher
+        when Matchers::EqMatcher
+          ['be equal to', matcher.expected]
+        when Matchers::BeMatcher
+          ['be the same object as', matcher.expected]
+        when Matchers::EmptyMatcher
+          ['be empty', NO_EXPECTED_VALUE]
+        when Matchers::GtMatcher
+          ['be greater than', matcher.expected]
+        when Matchers::GteMatcher
+          ['be greater than or equal to', matcher.expected]
+        when Matchers::IncludesMatcher
+          ['include', matcher.expected]
+        when Matchers::HaveMatcher
+          ['have', matcher.expected]
+        when Matchers::LtMatcher
+          ['be less than', matcher.expected]
+        when Matchers::LlmMatcher
+          ['satisfy condition', matcher.expected]
+        when Matchers::LteMatcher
+          ['be less than or equal to', matcher.expected]
+        when Matchers::AllMatcher
+          if sources
+            code_line = matcher.expected.source_location.last.to_i
+            code = sources.lines[code_line - 1]
+            expected = code&.strip
+            if expected.nil? || expected.empty?
+              ['all match the given condition', NO_EXPECTED_VALUE]
+            else
+              ['all match condition', expected]
+            end
+          else
+            ['all match the given condition', NO_EXPECTED_VALUE]
+          end
+        else
+          ['match', matcher.class.to_s]
+        end
+      end
+
+      def expectation_operator_text(operator)
+        operator == :not_to ? 'not to' : 'to'
+      end
     end
   end
 end