trmnl_preview 0.19.0 → 0.21.0

data/lib/trmnlp/testing/browser.rb

@@ -7,15 +7,15 @@ require_relative '../browser_pool'
 require_relative '../firefox_driver'
 require_relative '../screen_generator'
 require_relative '../screenshot'
-require_relative 'inline_stylesheets'
 
 module TRMNLP
   module Testing
     # The Firefox one example renders in, checked out of the pool on first use and back in by #release.
-    # Pages load the way `trmnlp build --png` loads them, through ScreenGenerator and Screenshot.
+    # Pages are drawn through ScreenGenerator and Screenshot like `trmnlp build --png`'s, but opened from page_server.
     class Browser
-      def initialize(pool:)
+      def initialize(pool:, page_server:)
         @pool = pool
+        @page_server = page_server
         @screenshot = Screenshot.new(pool:)
         @pages = {}.compare_by_identity
         @fresh_browsers = []
@@ -24,21 +24,25 @@ module TRMNLP
       # A Firefox of its own, with nothing cached, closed when this browser is released.
       def fresh
         pool = BrowserPool.new(driver_factory: FirefoxDriver.method(:build), max_size: 1)
-        self.class.new(pool:).tap { @fresh_browsers << [it, pool] }
+        self.class.new(pool:, page_server: @page_server).tap { @fresh_browsers << [it, pool] }
+      end
+
+      # Loads the screen's page; its picture is only taken when a test asks for it.
+      def load(screen)
+        generator = generator(screen)
+        @pages[screen] = [generator.html, generator.width, generator.height, @page_server.add(generator.html)]
+        show(screen)
       end
 
       # The PNG path, quantized to the device's bit depth like a build's.
       def capture(screen)
         @capturing = screen
-        keep(generate(screen))
+        keep(generator(screen).process)
       end
 
-      # ScreenGenerator's screenshot interface: html arrives with chart libraries swapped for TRMNL's copies.
-      def call(html:, width:, height:)
-        @pages[@capturing] = [html, width, height]
-        show(@capturing)
-        @screenshot.capture(driver)
-      end
+      # ScreenGenerator's screenshot interface: the page is already loaded, or loaded again if a later
+      # render replaced it.
+      def call(**) = on(@capturing) { @screenshot.capture(it) }
 
       # Yields the driver with screen's page loaded, reloading it if a later render replaced it.
       def on(screen)
@@ -52,6 +56,8 @@ module TRMNLP
           pool.shutdown
         end
         @fresh_browsers.clear
+        @pages.each_value { @page_server.forget(it.last) }
+        @pages.clear
         @pool.checkin(@driver) if @driver
         @driver = nil
         @showing = nil
@@ -59,19 +65,18 @@ module TRMNLP
 
       private
 
-      def generate(screen)
+      def generator(screen)
         device = screen.device
-        html = InlineStylesheets.call(screen.html)
-        ScreenGenerator.new(html, screenshot: self, width: device.width, height: device.height,
-                                  color_depth: device.bit_depth).process
+        ScreenGenerator.new(screen.html, screenshot: self, width: device.width, height: device.height,
+                                         color_depth: device.bit_depth)
       end
 
       def driver = @driver ||= @pool.checkout
 
       def show(screen)
-        html, width, height = @pages.fetch(screen)
-        @screenshot.show(driver, html, width, height,
-                         wait_for: screen.wait_for, wait_for_timeout: screen.wait_for_timeout)
+        html, width, height, url = @pages.fetch(screen)
+        waits = { wait_for: screen.wait_for, wait_for_timeout: screen.wait_for_timeout }
+        @screenshot.show(driver, html, width, height, url:, **waits)
         @showing = screen
       end
 

data/lib/trmnlp/testing/page_server.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'socket'
+
+module TRMNLP
+  module Testing
+    # Serves each page `trmnlp test` renders from one local address, so Firefox opens it as a page of its own.
+    # Written into about:blank, as TRMNL writes its page, every page has its stylesheets parsed again, 1.5 seconds
+    # for the Framework's; pages that share an address share the parsed copy, and a page's scripts wait for its
+    # stylesheets as on any site.
+    class PageServer
+      def initialize
+        @pages = {}
+        @lock = Mutex.new
+      end
+
+      def start
+        @server = TCPServer.new('127.0.0.1', 0)
+        @thread = Thread.new { loop { Thread.new(@server.accept) { serve(it) } } }
+        self
+      end
+
+      def stop
+        @thread&.kill
+        @server&.close
+      end
+
+      # The address html is served at until #forget.
+      def add(html)
+        id = SecureRandom.hex(8)
+        @lock.synchronize { @pages[id] = html }
+        "http://127.0.0.1:#{@server.addr[1]}/pages/#{id}"
+      end
+
+      def forget(url) = @lock.synchronize { @pages.delete(url.to_s.split('/').last) }
+
+      private
+
+      def serve(socket)
+        path = socket.gets.to_s.split[1].to_s
+        nil while (line = socket.gets) && !line.strip.empty?
+        html = @lock.synchronize { @pages[path[%r{\A/pages/(\h+)\z}, 1]] }
+        socket.write(html ? response('200 OK', html) : response('404 Not Found', ''))
+      rescue IOError, SystemCallError
+        nil
+      ensure
+        socket.close unless socket.closed?
+      end
+
+      def response(status, body)
+        "HTTP/1.1 #{status}\r\ncontent-type: text/html; charset=utf-8\r\ncache-control: no-store\r\n" \
+          "content-length: #{body.bytesize}\r\nconnection: close\r\n\r\n#{body}"
+      end
+    end
+  end
+end

data/lib/trmnlp/testing/plugin.rb

@@ -18,6 +18,7 @@ module TRMNLP
         (() => {
           const problems = window.__trmnlpProblems = [];
           window.addEventListener('error', (event) => {
+            if (String(event.message).startsWith('ResizeObserver loop')) return;
             const source = event.target && event.target !== window && (event.target.src || event.target.href);
             problems.push(source ? `failed to load ${source}` :
               `${event.message}${event.filename ? ` (${event.filename}:${event.lineno})` : ''}`);
@@ -28,10 +29,25 @@ module TRMNLP
           console.error = (...parts) => { problems.push(`console.error: ${parts.join(' ')}`); consoleError(...parts); };
         })();
       JS
-      PAGE_CLOCK_SCRIPT = '(() => { const offset = %d; const RealDate = Date; ' \
-                          'class TestDate extends RealDate { constructor(...args) { args.length ? super(...args) : ' \
-                          'super(RealDate.now() + offset); } static now() { return RealDate.now() + offset; } } ' \
-                          'window.Date = TestDate; })();'
+      # Takes its offset when the page runs, so the time Firefox takes to load the page does not put it behind now:.
+      PAGE_CLOCK_SCRIPT = <<~JS.gsub(/\s+/, ' ').strip
+        (() => {
+          const RealDate = Date;
+          const offset = %d - RealDate.now();
+          class TestDate extends RealDate {
+            constructor(...args) { args.length ? super(...args) : super(RealDate.now() + offset); }
+            static now() { return RealDate.now() + offset; }
+          }
+          window.Date = new Proxy(TestDate, { apply: () => new TestDate().toString() });
+          const prototype = Intl.DateTimeFormat.prototype;
+          const format = Object.getOwnPropertyDescriptor(prototype, 'format').get;
+          const formatToParts = prototype.formatToParts;
+          Object.defineProperty(prototype, 'format', {
+            get() { const bound = format.call(this); return (date = TestDate.now()) => bound(date); }
+          });
+          prototype.formatToParts = function (date = TestDate.now()) { return formatToParts.call(this, date); };
+        })();
+      JS
 
       def initialize(dir, browser:, authority:)
         @dir = dir
@@ -83,8 +99,8 @@ module TRMNLP
       def with_page_clock(html, now)
         return html unless now
 
-        offset = ((time(now).to_f - Time.now.to_f) * 1000).round
-        html.sub(/<head>/i) { "<head><script>#{format(PAGE_CLOCK_SCRIPT, offset)}</script>" }
+        milliseconds = (time(now).to_f * 1000).round
+        html.sub(/<head>/i) { "<head><script>#{format(PAGE_CLOCK_SCRIPT, milliseconds)}</script>" }
       end
     end
   end

data/lib/trmnlp/testing/publishable_recipe.rb

@@ -34,16 +34,17 @@ end
 # rubocop:disable-next Metrics/BlockLength -- one shared group, one check per example
 RSpec.shared_examples 'a publishable recipe' do |screens: TRMNLP::Testing::PUBLISHABLE_RECIPE_SCREENS|
   let(:recipe_inputs) do
-    { mocks: respond_to?(:mocks) ? mocks : {}, custom_fields: respond_to?(:custom_fields) ? custom_fields : {} }
+    { mocks: respond_to?(:mocks) ? mocks : {}, custom_fields: respond_to?(:custom_fields) ? custom_fields : {},
+      variables: respond_to?(:variables) ? variables : {}, now: respond_to?(:now) ? now : nil }
   end
 
-  def draw_cleanly = have_no_overflow.and(have_no_problems).and(have_no_leaked_text)
+  def draw_cleanly = have_no_problems.and(have_no_leaked_text)
 
   TRMNLP::Testing::PUBLISHABLE_RECIPE_VIEWS.product(screens).each do |view, screen|
     device = screen[:device].is_a?(Hash) ? screen[:device][:model] : screen[:device]
     screen_name = [device, screen[:orientation]].compact.join(' ')
 
-    it "draws the #{view} view on #{screen_name} without overflow or page errors" do
+    it "draws the #{view} view on #{screen_name} without page errors" do
       expect(trmnl.render(view:, **screen, **recipe_inputs)).to draw_cleanly
     end
   end

data/lib/trmnlp/testing/qr_scanner.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'mini_magick'
+require 'nokogiri'
+require 'open3'
+require 'tempfile'
+
+module TRMNLP
+  module Testing
+    # Reads the QR codes in a PNG the way a phone would, with zbar's `zbarimg`.
+    class QrScanner
+      COMMAND = 'zbarimg'
+      MISSING = 'Scanning a QR code needs zbar (`brew install zbar` or `apt-get install zbar-tools`; ' \
+                'already in the Docker image)'
+
+      def initialize(path, area: nil)
+        @path = path
+        @area = area
+      end
+
+      # The text of every code found, in the order zbar reports them.
+      def texts = @area ? cropped { scan(it) } : scan(@path)
+
+      private
+
+      def scan(path)
+        xml, error, status = Open3.capture3(COMMAND, '--quiet', '--xml', '-Sdisable', '-Sqrcode.enable', path)
+        # zbarimg exits 4 when the picture has no code.
+        raise TestingError, "zbarimg could not scan #{path}: #{error.strip}" unless [0, 4].include?(status.exitstatus)
+
+        Nokogiri::XML(xml).remove_namespaces!.xpath('//symbol/data').map(&:text)
+      rescue Errno::ENOENT
+        raise TestingError, MISSING
+      end
+
+      def cropped
+        return [] unless (geometry = crop_geometry)
+
+        Tempfile.create(['trmnlp-qr-', '.png']) do |file|
+          MiniMagick::Image.open(@path).crop(geometry).write(file.path)
+          yield file.path
+        end
+      end
+
+      def crop_geometry
+        left = [@area.left.floor, 0].max
+        top = [@area.top.floor, 0].max
+        width = @area.right.ceil - left
+        height = @area.bottom.ceil - top
+        # ImageMagick reads a 0 width or height as the whole picture, so an area off it has nothing to crop.
+        "#{width}x#{height}+#{left}+#{top}" if width.positive? && height.positive?
+      end
+    end
+  end
+end

data/lib/trmnlp/testing/report.rb

@@ -25,7 +25,7 @@ module TRMNLP
       end
 
       def initialize(dir)
-        @dir = dir
+        @dir = "#{dir}#{ENV.fetch('TEST_ENV_NUMBER', '')}" # parallel_tests: report, report2, report3...
         @examples = {}
         @images = 0
       end

data/lib/trmnlp/testing/rspec.rb

@@ -10,6 +10,7 @@ require_relative '../browser_pool'
 require_relative '../firefox_driver'
 require_relative 'browser'
 require_relative 'certificate_authority'
+require_relative 'page_server'
 require_relative 'plugin'
 require_relative 'report'
 require_relative 'publishable_recipe'
@@ -31,18 +32,24 @@ module TRMNLP
       @browser_pool ||= BrowserPool.new(driver_factory: FirefoxDriver.method(:build), max_size: 1)
     end
 
+    def self.page_server
+      @page_server ||= PageServer.new.start.tap { |server| at_exit { server.stop } }
+    end
+
     module Helpers
       def trmnl = @trmnl ||= Plugin.new(Testing.plugin_dir, browser: trmnl_browser, authority: Testing.authority)
 
-      def trmnl_browser = @trmnl_browser ||= Browser.new(pool: Testing.browser_pool)
+      def trmnl_browser
+        @trmnl_browser ||= Browser.new(pool: Testing.browser_pool, page_server: Testing.page_server)
+      end
     end
   end
 end
 
-RSpec::Matchers.define :have_no_overflow do
-  match { |screen| screen.overflowing.empty? }
+RSpec::Matchers.define :have_no_overflow do |except: nil|
+  match { |screen| screen.overflowing(except:).empty? }
   failure_message do |screen|
-    "expected nothing to overflow on #{screen.inspect}, but: #{screen.overflowing.join(', ')}"
+    "expected nothing to overflow on #{screen.inspect}, but: #{screen.overflowing(except:).join(', ')}"
   end
 end
 
@@ -73,6 +80,21 @@ RSpec::Matchers.define :have_no_problems do
   failure_message { |screen| "expected no problems on #{screen.inspect}, but: #{screen.problems.join('; ')}" }
 end
 
+# A QR code that scans in the PNG; with a String or Regexp, one that reads as it.
+RSpec::Matchers.define :have_qr_code do |text = nil, within: nil|
+  match do |screen|
+    @found = screen.qr_codes(within:)
+    text ? @found.any? { text === it } : @found.any? # rubocop:disable Style/CaseEquality -- a String or a Regexp
+  end
+  failure_message do |screen|
+    wanted = text ? "a QR code reading #{text.inspect}" : 'a QR code that scans'
+    place = within ? " in #{within}" : ''
+    "expected #{wanted}#{place} on #{screen.inspect}, but " \
+      "#{@found.empty? ? 'none scans' : "found #{@found.map(&:inspect).join(', ')}"}"
+  end
+  failure_message_when_negated { |screen| "expected no QR code on #{screen.inspect}, but found #{@found.inspect}" }
+end
+
 RSpec::Matchers.define :fit_image_size_limit do
   match { |screen| screen.png_bytes.bytesize <= screen.device.image_size_limit.to_i }
   failure_message do |screen|

data/lib/trmnlp/testing/run.rb

@@ -75,7 +75,7 @@ module TRMNLP
       def build_context(cache_dir, proxy)
         transform_client = inputs[:transform] ? transform_client(proxy) : nil
         context = Context.new(plugin, reporter:, cache_dir:, project_overrides:, outbound_request: table,
-                                      transform_client:)
+                                      transform_client:, source_data: inputs[:data] && stringify(inputs[:data]))
         seed(context.paths)
         context
       end

data/lib/trmnlp/testing/screen.rb

@@ -4,6 +4,8 @@ require 'capybara'
 require 'delegate'
 require 'nokogiri'
 
+require_relative 'qr_scanner'
+
 module TRMNLP
   module Testing
     # A rendered view, as Firefox drew it. Capybara's finders and matchers (have_text, have_css, within...)
@@ -11,19 +13,77 @@ module TRMNLP
     class Screen < SimpleDelegator
       Box = Data.define(:left, :top, :right, :bottom, :width, :height)
 
-      # Every element drawn past the screen's edge or cut off inside a box that hides its overflow.
+      # Every element drawn past the screen's edge, and every box that cuts a child box or a glyph's ink.
       OVERFLOW_SCRIPT = <<~JS
+        const except = arguments[0];
         const screen = document.documentElement.getBoundingClientRect();
         const describe = (el) => el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') +
           (el.classList.length ? '.' + [...el.classList].join('.') : '');
+        const clips = (el) => getComputedStyle(el).overflow !== 'visible';
+        const truncatesOnPurpose = (style) => style.textOverflow === 'ellipsis' || style.webkitLineClamp !== 'none';
+        const drawn = (rect) => rect.width > 0 || rect.height > 0;
+        const insideTruncation = (el) => {
+          for (let parent = el.parentElement; parent; parent = parent.parentElement) {
+            if (truncatesOnPurpose(getComputedStyle(parent))) return true;
+          }
+          return false;
+        };
+        const clippedOnlyBy = (node, el) => {
+          for (let parent = node.parentElement; parent !== el; parent = parent.parentElement) {
+            if (clips(parent)) return false;
+          }
+          return true;
+        };
+        const inlineBox = (el) => getComputedStyle(el).display === 'inline' &&
+          !(el instanceof HTMLImageElement || el instanceof SVGSVGElement || el instanceof HTMLCanvasElement);
+        const textMeasuringContext = document.createElement('canvas').getContext('2d');
+        const glyphInk = (glyph, rect) => {
+          const metrics = textMeasuringContext.measureText(glyph);
+          const scale = rect.height / (metrics.fontBoundingBoxAscent + metrics.fontBoundingBoxDescent);
+          const baseline = rect.top + metrics.fontBoundingBoxAscent * scale;
+          return { left: rect.left - metrics.actualBoundingBoxLeft * scale,
+                   right: rect.left + metrics.actualBoundingBoxRight * scale,
+                   top: baseline - metrics.actualBoundingBoxAscent * scale,
+                   bottom: baseline + metrics.actualBoundingBoxDescent * scale };
+        };
+        const glyphRects = (el) => {
+          const found = [];
+          const range = document.createRange();
+          const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+          for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+            if (!node.data.trim() || !clippedOnlyBy(node, el) || node.parentElement instanceof SVGElement) continue;
+            const style = getComputedStyle(node.parentElement);
+            textMeasuringContext.font = `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+            for (let start = 0; start < node.data.length;) {
+              const end = start + String.fromCodePoint(node.data.codePointAt(start)).length;
+              const glyph = node.data.slice(start, end);
+              if (glyph.trim()) {
+                range.setStart(node, start);
+                range.setEnd(node, end);
+                [...range.getClientRects()].filter(drawn).forEach((rect) => found.push(glyphInk(glyph, rect)));
+              }
+              start = end;
+            }
+          }
+          return found;
+        };
+        const cutsChildOrGlyph = (el) => {
+          const box = el.getBoundingClientRect();
+          const left = box.left + el.clientLeft;
+          const top = box.top + el.clientTop;
+          const crossesBoxEdge = (rect) => rect.left < left - 1 || rect.top < top - 1 ||
+            rect.right > left + el.clientWidth + 1 || rect.bottom > top + el.clientHeight + 1;
+          const children = [...el.querySelectorAll('*')].filter((child) => clippedOnlyBy(child, el) && !inlineBox(child))
+            .map((child) => child.getBoundingClientRect()).filter(drawn);
+          return children.some(crossesBoxEdge) || glyphRects(el).some(crossesBoxEdge);
+        };
         return [...document.querySelectorAll('.view *')].filter((el) => {
           const box = el.getBoundingClientRect();
-          if (box.width === 0 && box.height === 0) return false;
+          if (!drawn(box) || insideTruncation(el) || (except && el.closest(except))) return false;
           const outside = box.right > screen.right + 1 || box.bottom > screen.bottom + 1 || box.left < -1 || box.top < -1;
           const style = getComputedStyle(el);
-          const clips = ['hidden', 'clip'].includes(style.overflowX) || ['hidden', 'clip'].includes(style.overflowY);
-          const cut = clips && (el.scrollWidth > el.clientWidth + 1 || el.scrollHeight > el.clientHeight + 1);
-          return outside || cut;
+          const overflows = el.scrollWidth > el.clientWidth + 1 || el.scrollHeight > el.clientHeight + 1;
+          return outside || (clips(el) && !truncatesOnPurpose(style) && overflows && cutsChildOrGlyph(el));
         }).map(describe);
       JS
 
@@ -39,7 +99,7 @@ module TRMNLP
         return copy.outerHTML;
       JS
 
-      attr_reader :html, :device, :view, :png_path, :result, :wait_for, :wait_for_timeout
+      attr_reader :html, :device, :view, :result, :wait_for, :wait_for_timeout
 
       # rubocop:disable-next Metrics/ParameterLists -- what a render produced and how to wait for it
       def initialize(html:, device:, view:, browser:, result:, wait_for: nil, wait_for_timeout: 5)
@@ -50,7 +110,7 @@ module TRMNLP
         @view = view
         @browser = browser
         @result = result
-        @png_path = browser.capture(self)
+        browser.load(self)
         super(Capybara.string(drawn_dom(browser.on(self) { it.execute_script(DRAWN_DOM_SCRIPT) })))
       end
 
@@ -64,13 +124,21 @@ module TRMNLP
 
       def evaluate(expression) = @browser.on(self) { it.execute_script("return (#{expression});") }
 
-      def overflowing = @browser.on(self) { it.execute_script(OVERFLOW_SCRIPT) }
+      def overflowing(except: nil) = @browser.on(self) { it.execute_script(OVERFLOW_SCRIPT, except) }
 
       # Script errors, unhandled rejections, console.error lines and files that failed to load.
       def problems = evaluate('window.__trmnlpProblems || []')
 
+      # The screenshot, quantized for the device. It is taken the first time it is asked for, so a test that
+      # only reads the page does not wait for a picture.
+      def png_path = @png_path ||= @browser.capture(self)
+
       def png_bytes = File.binread(png_path)
 
+      # The text of each QR code that scans in the PNG, so on what the device shows; within: a selector
+      # limits the scan to that element.
+      def qr_codes(within: nil) = QrScanner.new(png_path, area: within && box(within)).texts
+
       def drawn_dom(source)
         document = Nokogiri::HTML(source)
         document.css("[#{HIDDEN_MARK}]").each { it['hidden'] = 'hidden' }

data/lib/trmnlp/update_check.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require_relative 'reporter'
+require_relative 'version'
+
+module TRMNLP
+  # Tells the user when RubyGems has a newer trmnl_preview. The answer is
+  # cached for a day so routine commands do not wait on the network; a
+  # failed lookup is cached too, so an offline run stalls at most once a day.
+  class UpdateCheck
+    ENDPOINT = 'https://rubygems.org/api/v1/gems/trmnl_preview.json'
+    TIMEOUT = 2
+    CACHE_TTL = 24 * 60 * 60
+    DISABLE_ENV_KEY = 'TRMNLP_NO_UPDATE_NOTIFIER'
+
+    def self.disabled? = !ENV[DISABLE_ENV_KEY].to_s.empty?
+
+    def initialize(cache_path, reporter: Reporter.new(stream: $stderr))
+      @cache_path = Pathname.new(cache_path)
+      @reporter = reporter
+    end
+
+    # Reports a newer stable release. fresh: asks RubyGems now instead of
+    # trusting a cached answer from the last day.
+    def call(fresh: false)
+      latest = fresh ? refresh : cached
+      return unless latest && latest > Gem::Version.new(VERSION)
+
+      reporter.info("trmnl_preview #{latest} is available (installed: #{VERSION}).")
+      reporter.info(update_guidance)
+    end
+
+    private
+
+    attr_reader :cache_path, :reporter
+
+    def cached
+      cache = read_cache
+      return version_from(cache['version']) if cache && Time.now.to_i - cache['checked_at'] < CACHE_TTL
+
+      refresh
+    end
+
+    def refresh
+      latest = fetch_latest
+      write_cache(latest)
+      latest
+    end
+
+    def read_cache
+      data = JSON.parse(cache_path.read)
+      data if data.is_a?(Hash) && data['checked_at'].is_a?(Integer)
+    rescue SystemCallError, JSON::ParserError
+      nil
+    end
+
+    def write_cache(latest)
+      cache_path.dirname.mkpath
+      cache_path.write(JSON.generate(checked_at: Time.now.to_i, version: latest&.to_s))
+    rescue SystemCallError
+      nil
+    end
+
+    def fetch_latest
+      response = Faraday.get(ENDPOINT) do |request|
+        request.options.open_timeout = TIMEOUT
+        request.options.timeout = TIMEOUT
+      end
+      parse_version(response.body) if response.success?
+    rescue Faraday::Error, JSON::ParserError, ArgumentError
+      nil
+    end
+
+    def parse_version(body)
+      data = JSON.parse(body)
+      version_from(data['version']) if data.is_a?(Hash)
+    end
+
+    def version_from(value)
+      return unless value.is_a?(String) && !value.empty? && Gem::Version.correct?(value)
+
+      version = Gem::Version.new(value)
+      version unless version.prerelease?
+    end
+
+    def update_guidance
+      return 'Update with: gem update trmnl_preview' if ENV['BUNDLE_GEMFILE'].to_s.empty?
+
+      'Update the trmnl_preview constraint in your Gemfile if needed, then run: bundle update trmnl_preview'
+    end
+  end
+end

data/lib/trmnlp/user_data_assembler.rb

@@ -12,7 +12,9 @@ module TRMNLP
     DEFAULT_DEVICE_WIDTH = 800
     DEFAULT_DEVICE_HEIGHT = 480
 
-    def initialize(config:, paths:, transform_pipeline:, oauth_session: nil)
+    # source_data: a test's own data, in place of what the plugin's strategy would read.
+    def initialize(config:, paths:, transform_pipeline:, oauth_session: nil, source_data: nil)
+      @given_source_data = source_data
       @config = config
       @paths = paths
       @transform_pipeline = transform_pipeline
@@ -73,7 +75,9 @@ module TRMNLP
     def previous_merge_variables = config.plugin.webhook? ? source_data : transform_pipeline.previous_output
 
     def source_data
-      if config.plugin.static?
+      if @given_source_data
+        @given_source_data
+      elsif config.plugin.static?
         config.plugin.static_data
       elsif config.plugin.plugin_merge?
         MergedPluginLocals.new(config:, paths:).call

data/lib/trmnlp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TRMNLP
-  VERSION = '0.19.0'
+  VERSION = '0.21.0'
 end

data/lib/trmnlp.rb

@@ -3,7 +3,7 @@
 module TRMNLP; end
 require 'oj'
 require 'trmnl/liquid'
-require_relative 'trmnlp/qr_code_intrinsic_size'
+require_relative 'trmnlp/qr_code'
 Oj.mimic_JSON
 require_relative 'trmnlp/rails_helpers'
 require_relative 'trmnlp/errors'