probatio_diabolica 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 891d8275e2ccd96dea0d74c456a55693ab667fd556fedf9b5d1fe9470b0949cb
-  data.tar.gz: d53faf24d75c1f112e5cb064048372d7ac7c5391f50ed3e546a5f7990cb7d02f
+  metadata.gz: 39336802d7f3c344f21acbf0567ea85a73dfbc68c2d339e7ab5e1e1866fc609e
+  data.tar.gz: c4f0fa5209ac0a7437edf9e6cf117b95fe859217b49e172557f05c44dc664307
 SHA512:
-  metadata.gz: faafc8c84e60b7058d57ceb6d457502822724aea22325e3e0ccd4efb3e3765903f21f8525f0e4c9937bea8e69901d39e543796a776b5a1305922492955ce373e
-  data.tar.gz: 4d9f2a94aee2e50112544aa6c0be783ee79f95ee0b4dd7ef95731590b45f335a4e2e61044a99bfa4d2b6125767c9f9b6f91ba2b7e8b70e275ab792b62b138be3
+  metadata.gz: f78a5ff31c1b5cbee275d596ef74529b0fad41426c4b7ee5303d98d4224cbcf20718485403ec048fc4f26159775c0ae8e33c07eeeb95e6944c2a21cf3feeec26
+  data.tar.gz: ffa412e8bc62906e1c9be463a9d48dc9a30bbf4e4fcf458abc1e203026bde0a7e5f60ae0dce03c33cd6375c5402060b80ae1b1cf0b610328b1808a5eb436b8cf

data/README.md

@@ -161,6 +161,42 @@ end
 - `expect { |subject| ... }.to matcher`
 - `expect.to matcher` (uses `subject`)
 
+### Spec best practices for `subject` (PRD reports)
+
+When a test defines a `subject`, PRD can surface it more clearly in generated reports.
+For CLI and integration specs, prefer:
+
+- grouping with explicit `context`
+- one `subject` per context for the main action
+- assertions written with `expect.to(...)` when the assertion targets `subject`
+
+Example:
+
+```ruby
+context 'when CLI receives an unknown formatter type' do
+  subject { Open3.capture3('bundle exec ruby bin/prd spec/self_hosted_spec.rb -t unknown') }
+
+  it 'fails fast on unknown formatter type in CLI' do
+    _stdout, stderr, status = subject
+
+    expect(status.success?).to(be(false))
+    expect(stderr).to(includes('Unsupported formatter type: unknown. Supported: simple, html, json, pdf'))
+  end
+end
+```
+
+For simple value checks, this pattern keeps specs concise:
+
+```ruby
+context 'with strings' do
+  subject { 'probatio diabolica' }
+
+  it 'matches expected content' do
+    expect.to(includes('diabolica'))
+  end
+end
+```
+
 ### Matchers
 
 - `eq(expected)` equality with `==`
@@ -174,13 +210,30 @@ end
 
 `PrD::Runtime` exposes helpers to test content loaded in Chrome:
 
+- `page(at:, warmup_time:)` opens a page and returns a `BrowserSession`
 - `screen(at:, width:, height:, warmup_time:)` captures a PNG and returns a `File`
-- `text(at:, css:, warmup_time:)` extracts a CSS node into a `.txt` file and returns a `File`
+- `text(at:, css:, warmup_time:)` extracts a CSS node and returns `PrD::Code` (language: `text`)
 - `network(at:, warmup_time:)` returns Ferrum network traffic
 - `network_urls(at:, warmup_time:)` returns traffic URLs
 - `pdf(at:, warmup_time:)` generates a PDF and returns a `PDF::Reader`
 - `html(at:, warmup_time:)` returns HTML (`browser.body`)
 
+`BrowserSession` adds high-level page interactions:
+
+- `find(css:/xpath:, wait:, shadow:)`
+- `exists?(css:/xpath:, wait:, shadow:)`
+- `click(css:/xpath:, wait:, shadow:)`
+- `fill(css:/xpath:, with:, clear:, blur:, wait:, shadow:)`
+- `select_option(css:, value:/values:, by:, wait:, shadow:)`
+- `set_files(css:, path:/paths:, wait:, shadow:)` (alias `upload_files`)
+- `navigate(to:, warmup_time:)`
+
+About `shadow:`:
+
+- `shadow:` is an ordered CSS path used to narrow the scope before the target selector.
+- Each step can be a shadow host or a regular container.
+- If a step has `shadowRoot`, search continues inside it; otherwise search continues inside the matched node.
+
 Prerequisites:
 
 - Chrome/Chromium must be installed.
@@ -197,6 +250,22 @@ it 'checks dynamic content loaded in browser' do
 end
 ```
 
+Form interaction and file upload example:
+
+```ruby
+it 'uploads a file in a shadow-dom form' do
+  html(at: 'https://example.com/upload', warmup_time: 2) do |page|
+    page.click(css: 'button[data-open-upload]')
+    page.fill(css: 'input[name="title"]', with: 'Invoice')
+    page.set_files(
+      css: 'input[type="file"]',
+      shadow: ['vax-scanner', '[data-view="upload"]'],
+      path: 'examples/random_photo.png'
+    )
+  end
+end
+```
+
 ### Source code helper (Prism)
 
 `source_code(...)` uses the `prism` gem to parse Ruby source and extract class/method code.
@@ -256,12 +325,12 @@ When you define a `subject`, each formatter tries to render it in the most usefu
   - for files, prints a textual representation (for example path, file preview for `.txt`)
 - `HtmlFormatter`:
   - renders text values directly
-  - for `PrD::Code`, renders syntax-highlighted code blocks (Rouge)
+  - 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
 - `PdfFormatter`:
   - renders text values as report lines
-  - for `PrD::Code`, renders language + code block (plain, without syntax colors)
+  - 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
 - `JsonFormatter`:
   - keeps a structured representation for machine processing

data/lib/pr_d/code.rb

@@ -1,8 +1,9 @@
 module PrD
-  class Code
+  class Code < SimpleDelegator
     attr_reader :source, :language
 
     def initialize(source:, language: 'ruby')
+      super(source.to_s)
       @source = source.to_s
       @language = language.to_s
     end

data/lib/pr_d/formatters/html_formatter.rb

@@ -357,19 +357,49 @@ module PrD
                 .code-language {
                   color: var(--muted);
                   font-size: 0.85rem;
-                  margin-bottom: 0.35rem;
                   text-transform: uppercase;
                   letter-spacing: 0.05em;
                 }
 
                 .code-block {
                   margin: 0.45rem 0 0.7rem;
+                  border: 1px solid var(--line);
+                  border-radius: 10px;
+                  background: #fff;
+                }
+
+                .code-toggle {
+                  list-style: none;
+                  cursor: pointer;
+                  padding: 0.6rem 0.8rem;
+                  display: flex;
+                  align-items: center;
+                  justify-content: space-between;
+                  gap: 0.8rem;
+                  font-size: 0.88rem;
+                  color: var(--text);
+                }
+
+                .code-toggle::-webkit-details-marker {
+                  display: none;
+                }
+
+                .code-toggle::after {
+                  content: 'Open';
+                  color: var(--muted);
+                  font-size: 0.78rem;
+                  letter-spacing: 0.03em;
+                  text-transform: uppercase;
+                }
+
+                .code-block[open] .code-toggle::after {
+                  content: 'Close';
                 }
 
                 .highlight {
                   margin: 0;
-                  border: 1px solid var(--line);
-                  border-radius: 10px;
+                  border-top: 1px solid var(--line);
+                  border-radius: 0 0 10px 10px;
                   overflow-x: auto;
                 }
 
@@ -515,10 +545,12 @@ module PrD
         language = normalize_text(code.language)
         highlighted = highlight_code(source, language)
         <<~HTML
-          <div class="code-block">
-            <div class="code-language">#{escape(language)}</div>
+          <details class="code-block">
+            <summary class="code-toggle">
+              <span class="code-language">#{escape(language)}</span>
+            </summary>
             #{highlighted}
-          </div>
+          </details>
         HTML
       end
 

data/lib/pr_d/formatters/pdf_formatter.rb

@@ -1,4 +1,5 @@
 require 'prawn'
+require 'rouge'
 
 module PrD
   module Formatters
@@ -76,7 +77,7 @@ module PrD
         add_event(:subject, message: 'Subject', level: @level)
         if code_object?(subject)
           add_event(:code_header, message: "Language: #{subject.language}", level: @level + 1)
-          add_event(:code_block, message: subject.source, level: @level + 1)
+          add_event(:code_block, message: subject.source, level: @level + 1, language: subject.language)
         elsif image_file?(subject)
           add_event(:detail, message: serialize(subject).to_s, level: @level + 1)
           add_event(:subject_image, message: subject.path, level: @level + 1)
@@ -98,7 +99,7 @@ module PrD
         return if synthetic?
         if code_object?(expectation)
           add_event(:code_header, message: "Expect (#{expectation.language})", level: @level + 1)
-          add_event(:code_block, message: expectation.source, level: @level + 1)
+          add_event(:code_block, message: expectation.source, level: @level + 1, language: expectation.language)
         else
           add_event(:detail, message: "Expect: #{serialize(expectation)}", level: @level + 1)
         end
@@ -153,13 +154,13 @@ module PrD
 
       private
 
-      def add_event(type, message:, level:, anchor_id: nil)
+      def add_event(type, message:, level:, anchor_id: nil, **extra)
         @events << {
           type:,
           message: safe_pdf_text(message.to_s),
           level: [level, 0].max,
           anchor_id:
-        }
+        }.merge(extra)
       end
 
       def add_index_entry(type:, label:, level:, anchor_id:)
@@ -177,6 +178,43 @@ module PrD
           .encode('UTF-8')
       end
 
+      def rouge_lexer_for(source, language)
+        Rouge::Lexer.find_fancy(language.to_s, source.to_s) || Rouge::Lexers::PlainText
+      rescue StandardError
+        Rouge::Lexers::PlainText
+      end
+
+      def rouge_token_color(token)
+        qualname = token.qualname.to_s
+
+        return '6B7280' if qualname.start_with?('Comment')
+        return 'C2410C' if qualname.start_with?('Keyword', 'Operator')
+        return '1D4ED8' if qualname.start_with?('Name.Function', 'Name.Class', 'Name.Builtin')
+        return '047857' if qualname.start_with?('Literal.String')
+        return '7C3AED' if qualname.start_with?('Literal.Number')
+
+        COLORS[:text]
+      end
+
+      def highlighted_code_fragments(source, language)
+        lexer = rouge_lexer_for(source, language)
+        fragments = lexer.lex(source.to_s).filter_map do |token, value|
+          next if value.nil? || value.empty?
+
+          {
+            text: safe_pdf_text(value),
+            color: rouge_token_color(token),
+            font: 'Courier'
+          }
+        end
+
+        return fragments unless fragments.empty?
+
+        [{ text: safe_pdf_text(source.to_s), color: COLORS[:text], font: 'Courier' }]
+      rescue StandardError
+        [{ text: safe_pdf_text(source.to_s), color: COLORS[:text], font: 'Courier' }]
+      end
+
       def render_header(document)
         document.fill_color COLORS[:title]
         document.text 'Probatio Diabolica', size: 20, style: :bold
@@ -238,7 +276,7 @@ module PrD
           when :code_header
             styled_line(document, event[:message], level: event[:level], size: 10, style: :bold, color: COLORS[:muted])
           when :code_block
-            render_code_block(document, event[:message], level: event[:level])
+            render_code_block(document, event[:message], level: event[:level], language: event[:language])
           when :detail, :subject, :justification
             styled_line(document, event[:message], level: event[:level], size: 10, color: COLORS[:text])
           when :subject_image
@@ -296,12 +334,11 @@ module PrD
         document.move_down 2
       end
 
-      def render_code_block(document, text, level:)
+      def render_code_block(document, text, level:, language: nil)
         document.indent(level * 14) do
           document.fill_color COLORS[:muted]
           document.text '--- Code Block ---', size: 9, style: :italic
-          document.fill_color COLORS[:text]
-          document.font('Courier') { document.text text, size: 9 }
+          document.formatted_text(highlighted_code_fragments(text, language), size: 9)
           document.fill_color COLORS[:muted]
           document.text '--- End Block ---', size: 9, style: :italic
           document.fill_color COLORS[:text]
@@ -312,7 +349,7 @@ module PrD
       def add_matcher_value_event(label, value)
         if code_object?(value)
           add_event(:matcher, message: "#{label} (#{value.language})", level: @level + 2)
-          add_event(:code_block, message: value.source, level: @level + 2)
+          add_event(:code_block, message: value.source, level: @level + 2, language: value.language)
         else
           add_event(:matcher, message: "#{label}: #{serialize(value)}", level: @level + 2)
         end

data/lib/pr_d/helpers/chrome_helper.rb

@@ -5,10 +5,199 @@ require 'pdf-reader'
 module PrD
   module Helpers
     module ChromeHelper
+      class BrowserSession
+        SHADOW_QUERY_FUNCTION = <<~JS.freeze
+          function(shadowSelectors, targetSelector, within) {
+            let scope = within || document;
+
+            for (const scopeSelector of shadowSelectors) {
+              if (!scope || typeof scope.querySelector !== "function") return null;
+              const node = scope.querySelector(scopeSelector);
+              if (!node) return null;
+              scope = node.shadowRoot || node;
+            }
+
+            if (!scope || typeof scope.querySelector !== "function") return null;
+            return scope.querySelector(targetSelector);
+          }
+        JS
+
+        def initialize(browser, poll_interval: 0.05)
+          @browser = browser
+          @poll_interval = poll_interval
+        end
+
+        attr_reader :browser
+
+        def navigate(to:, warmup_time: 0)
+          @browser.go_to(to)
+          sleep(warmup_time.to_f) if warmup_time.to_f.positive?
+          self
+        end
+
+        def wait(seconds)
+          sleep(seconds.to_f) if seconds.to_f.positive?
+          self
+        end
+
+        def wait_for(css: nil, xpath: nil, within: nil, shadow: nil, timeout: 2)
+          find(css:, xpath:, within:, shadow:, wait: timeout)
+        end
+
+        def exists?(css: nil, xpath: nil, within: nil, shadow: nil, wait: 0)
+          !find(css:, xpath:, within:, shadow:, wait:, raise_on_missing: false).nil?
+        end
+
+        def find(css: nil, xpath: nil, within: nil, shadow: nil, wait: 2, raise_on_missing: true)
+          selector = normalize_selector(css:, xpath:)
+          node = find_with_wait(selector:, within:, shadow:, wait:)
+          return node if node
+          return nil unless raise_on_missing
+
+          raise ArgumentError, "Selector not found: #{selector[:label]}"
+        end
+
+        def click(css: nil, xpath: nil, within: nil, shadow: nil, wait: 2, mode: :left, keys: [], offset: {}, delay: 0)
+          node = find(css:, xpath:, within:, shadow:, wait:)
+          node.scroll_into_view
+          node.click(mode:, keys:, offset:, delay:)
+          node
+        end
+
+        def fill(css: nil, xpath: nil, within: nil, shadow: nil, with:, wait: 2, clear: true, blur: false, dispatch_events: true)
+          node = find(css:, xpath:, within:, shadow:, wait:)
+          node.focus
+          node.evaluate("this.value = ''") if clear
+          node.type(with.to_s)
+          dispatch_input_events(node) if dispatch_events
+          node.blur if blur
+          node
+        end
+
+        def select_option(css:, within: nil, shadow: nil, value: nil, values: nil, by: :value, wait: 2)
+          node = find(css:, within:, shadow:, wait:)
+          option_values = Array(values || value).flatten.compact
+          raise ArgumentError, 'select_option requires `value` or `values`.' if option_values.empty?
+
+          node.select(*option_values, by:)
+          node
+        end
+
+        def set_files(css:, within: nil, shadow: nil, path: nil, paths: nil, wait: 2, dispatch_events: true)
+          node = find(css:, within:, shadow:, wait:)
+          file_paths = normalize_file_paths(path:, paths:)
+          node.select_file(file_paths)
+          dispatch_input_events(node) if dispatch_events
+          node
+        end
+        alias upload_files set_files
+
+        def method_missing(method_name, *args, **kwargs, &block)
+          return @browser.public_send(method_name, *args, **kwargs, &block) if @browser.respond_to?(method_name)
+
+          super
+        end
+
+        def respond_to_missing?(method_name, include_private = false)
+          @browser.respond_to?(method_name, include_private) || super
+        end
+
+        private
+
+        def normalize_selector(css:, xpath:)
+          css = normalize_optional_selector(css)
+          xpath = normalize_optional_selector(xpath)
+
+          if css.nil? && xpath.nil?
+            raise ArgumentError, 'Provide a selector with `css:` or `xpath:`.'
+          end
+
+          if css && xpath
+            raise ArgumentError, 'Use either `css:` or `xpath:`, not both.'
+          end
+
+          if xpath && !xpath.nil?
+            { type: :xpath, value: xpath, label: "xpath=#{xpath}" }
+          else
+            { type: :css, value: css, label: "css=#{css}" }
+          end
+        end
+
+        def normalize_optional_selector(value)
+          return nil if value.nil?
+
+          selector = value.to_s.strip
+          return nil if selector.empty?
+
+          selector
+        end
+
+        def find_with_wait(selector:, within:, shadow:, wait:)
+          timeout = wait.to_f
+          timeout = 0 if timeout.negative?
+          deadline = monotonic_now + timeout
+
+          loop do
+            node = resolve_node(selector:, within:, shadow:)
+            return node if node
+
+            break if monotonic_now >= deadline
+
+            sleep(@poll_interval)
+          end
+
+          nil
+        end
+
+        def resolve_node(selector:, within:, shadow:)
+          case selector[:type]
+          when :xpath
+            raise ArgumentError, '`shadow:` can only be used with `css:` selectors.' if shadow && !Array(shadow).empty?
+
+            within ? within.at_xpath(selector[:value]) : @browser.at_xpath(selector[:value])
+          when :css
+            if shadow && !Array(shadow).empty?
+              @browser.evaluate_func(SHADOW_QUERY_FUNCTION, Array(shadow), selector[:value], within)
+            elsif within
+              within.at_css(selector[:value])
+            else
+              @browser.at_css(selector[:value])
+            end
+          end
+        end
+
+        def dispatch_input_events(node)
+          node.evaluate("this.dispatchEvent(new Event('input', { bubbles: true }))")
+          node.evaluate("this.dispatchEvent(new Event('change', { bubbles: true }))")
+        end
+
+        def normalize_file_paths(path:, paths:)
+          raw_paths = Array(paths || path).flatten.compact.map { |value| value.to_s.strip }.reject(&:empty?)
+          raise ArgumentError, 'set_files requires `path` or `paths`.' if raw_paths.empty?
+
+          expanded_paths = raw_paths.map { |file_path| File.expand_path(file_path, Dir.pwd) }
+          missing = expanded_paths.reject { |file_path| File.exist?(file_path) }
+          raise ArgumentError, "File not found: #{missing.join(', ')}" unless missing.empty?
+
+          expanded_paths
+        end
+
+        def monotonic_now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+
+      def page(at:, warmup_time: 2)
+        session = prepare_browser_session(at:, warmup_time:)
+        yield session if block_given?
+        session
+      end
+
       def screen(at:, width: 1280, height: 800, warmup_time: 2)
-        browser = prepare_browser(at:, warmup_time:)
+        session = prepare_browser_session(at:, warmup_time:)
+        browser = session.browser
         browser.set_viewport(width:, height:)
-        yield browser if block_given?
+        yield session if block_given?
 
         screenshot_id = Digest::SHA256.hexdigest("#{at}-#{width}-#{height}-#{warmup_time}")
         file_name = File.join(chrome_annex_dir, "screenshot-#{screenshot_id}.png")
@@ -17,19 +206,19 @@ module PrD
       end
 
       def text(at:, css: 'body', warmup_time: 2)
-        browser = prepare_browser(at:, warmup_time:)
-        yield browser if block_given?
+        session = prepare_browser_session(at:, warmup_time:)
+        yield session if block_given?
 
-        text_node = browser.at_css(css)
+        text_node = session.find(css:, wait: 0, raise_on_missing: false)
         raise ArgumentError, "CSS selector not found: #{css}" unless text_node
 
         PrD::Code.new(source: text_node.text, language: 'text')
       end
 
       def network(at:, warmup_time: 2)
-        browser = prepare_browser(at:, warmup_time:)
-        yield browser if block_given?
-        browser.network.traffic
+        session = prepare_browser_session(at:, warmup_time:)
+        yield session if block_given?
+        session.browser.network.traffic
       end
 
       def network_urls(at:, warmup_time: 2, &block)
@@ -37,8 +226,9 @@ module PrD
       end
 
       def pdf(at:, warmup_time: 2)
-        browser = prepare_browser(at:, warmup_time:)
-        yield browser if block_given?
+        session = prepare_browser_session(at:, warmup_time:)
+        browser = session.browser
+        yield session if block_given?
 
         pdf_id = Digest::SHA256.hexdigest(at)
         file_name = File.join(chrome_annex_dir, "pdf-#{pdf_id}.pdf")
@@ -47,10 +237,10 @@ module PrD
       end
 
       def html(at:, warmup_time: 2)
-        browser = prepare_browser(at:, warmup_time:)
-        yield browser if block_given?
+        session = prepare_browser_session(at:, warmup_time:)
+        yield session if block_given?
 
-        PrD::Code.new(source: browser.body, language: 'html')
+        PrD::Code.new(source: session.browser.body, language: 'html')
       end
 
       def close_chrome_browser
@@ -68,6 +258,11 @@ module PrD
         @browser ||= Ferrum::Browser.new
       end
 
+      def prepare_browser_session(at:, warmup_time:)
+        browser = prepare_browser(at:, warmup_time:)
+        BrowserSession.new(browser)
+      end
+
       def prepare_browser(at:, warmup_time:)
         browser = chrome_browser
         browser.go_to(at)

data/lib/pr_d/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PrD
-  VERSION = "0.3.0"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: probatio_diabolica
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Laporte Mathieu