trmnl_preview 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73458f9c8bc2782cf56c7e5e2ceb2e9b06e16fdc865ee68787a90cd11ab3930d
-  data.tar.gz: 59de88bc00c8168785fe2117b008eed21f4fac9b85d5ef32546882787060624b
+  metadata.gz: 323b81319ed9997a0d49fb77fbe563b30464e7b92ba533388f8d619b68d2426e
+  data.tar.gz: 4ebe10b57d8815de4efb146c3ad4fa2376f8723160f4ae83748162620d38b716
 SHA512:
-  metadata.gz: 58865958ff6709443c7a8789757ce6b7951088561229edf1771db2c80c4dab318dabc6be36f81a75200878adc85111b025d0a36fb90ba74d72dae8adfaa5be7f
-  data.tar.gz: 4e8e15211854ebae382e7f8deaacda24217e2e1a6f77c7aafafe0199e57c0919c4ac170ec7a38953fe2a5e59ac334b469e229b5bb19d0955cfeceace62f9df83
+  metadata.gz: 99afef29e4890046747621ad575e45b7d51fb93c676921f32efb35c585f84fbfe160839b3d1f77b3cce319699fe187c302f0e498bda27de56a1982a9bfdc81e1
+  data.tar.gz: 3190bf99270ccf553479edbb4f3bf97027216f0d147156a8c2ec57301ce533ed100bf0d9e4dd99cb876af740bee4ba0007ef433d6ad8670fb349b11f52c841fb

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 
 # Changelog
 
+## 0.29.0
+
+- `trmnlp test` fails a screen that draws text over other text, or content text under the title bar, and names both texts, such as a name printed across the last line of a quote. Only glyphs that share inked pixels count, so a unit tucked against a number passes.
+- `trmnlp test`'s publishable recipe group fails "has a mock for every request it makes" when the polling or the transform asks for a url no mock answers, and names each url without its query. Such a request is answered with status 599, so the screens drew the error state as if the API had failed. The matcher is `have_a_mock_for_every_request`.
+- `trmnlp test` checks each view in dark mode on the TRMNL X: a view fails when its layout keeps less than half its content, as when text, lines or icons are drawn in a fixed black and stay black on the black screen. Pass `dark_mode_screen:` to the shared group to check another screen.
+- `trmnlp test` fails a screen where the Framework clamped text whose full text fits on one line in the width its parent gives it, such as a chart title cut to `Egg Pric...`. It names the cut text and the full text.
+
 ## 0.28.0
 
 - `trmnlp test`, `serve` and `build --png` close their headless Firefox when they exit. Each run left one running, with nothing left to stop it, and a loop of runs could fill memory and swap.

data/lib/trmnlp/testing/ink_count.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'mini_magick'
+
+module TRMNLP
+  module Testing
+    # How many pixels of a PNG stand out from its background, the gray level most pixels have; area: a box
+    # counts only inside it.
+    class InkCount
+      # Half the gray scale: text and lines pass; a faint tint or frame does not, on white or on black.
+      MIN_DIFFERENCE = 128
+
+      def initialize(path, area: nil)
+        @path = path
+        @area = area
+      end
+
+      def pixels
+        levels = histogram
+        return 0 if levels.empty?
+
+        background = levels.max_by(&:last).first
+        levels.sum { |level, count| (level - background).abs > MIN_DIFFERENCE ? count : 0 }
+      end
+
+      private
+
+      # [gray level 0-255, pixel count] for each level the picture uses.
+      def histogram
+        output = MiniMagick.convert do |convert|
+          convert << @path
+          convert << '-crop' << crop_geometry << '+repage' if @area
+          convert << '-colorspace' << 'gray' << '-depth' << '8' << '-format' << '%c' << 'histogram:info:-'
+        end
+        output.lines.filter_map do |line|
+          (match = line.match(/\A\s*(\d+):\s*\(\s*(\d+)/)) && [match[2].to_i, match[1].to_i]
+        end
+      end
+
+      def crop_geometry = "#{@area.width.round}x#{@area.height.round}+#{@area.left.round}+#{@area.top.round}"
+    end
+  end
+end

data/lib/trmnlp/testing/overlapping_text.js

@@ -0,0 +1,96 @@
+const shown = (el) => el.checkVisibility({ opacityProperty: true, visibilityProperty: true });
+const intersect = (a, b) => ({ left: Math.max(a.left, b.left), top: Math.max(a.top, b.top),
+                               right: Math.min(a.right, b.right), bottom: Math.min(a.bottom, b.bottom) });
+const area = (r) => Math.max(0, r.right - r.left) * Math.max(0, r.bottom - r.top);
+const covers = (a, b, share) => area(intersect(a, b)) > Math.min(area(a), area(b)) * share;
+const visiblePart = (rect, el) => {
+  let part = rect;
+  for (let parent = el; parent; parent = parent.parentElement) {
+    if (getComputedStyle(parent).overflow !== 'visible') part = intersect(part, parent.getBoundingClientRect());
+  }
+  return part;
+};
+const textMeasuringContext = document.createElement('canvas').getContext('2d');
+// A text range's box is as tall as its line, so the font's own box sits in the middle of it.
+const baselineOf = (rect, metrics) => rect.top + metrics.fontBoundingBoxAscent +
+  (rect.height - metrics.fontBoundingBoxAscent - metrics.fontBoundingBoxDescent) / 2;
+const inkOf = (rect, text, style, oneLine) => {
+  textMeasuringContext.font = `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+  const metrics = textMeasuringContext.measureText(text);
+  const baseline = baselineOf(rect, metrics);
+  const left = oneLine ? rect.left - metrics.actualBoundingBoxLeft : rect.left;
+  const right = oneLine ? rect.left + metrics.actualBoundingBoxRight : rect.right;
+  return { left, right, top: baseline - metrics.actualBoundingBoxAscent,
+           bottom: baseline + metrics.actualBoundingBoxDescent };
+};
+const texts = [];
+const range = document.createRange();
+const walker = document.createTreeWalker(document.querySelector('.view') || document.body, NodeFilter.SHOW_TEXT);
+for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+  const owner = node.parentElement;
+  if (!node.data.trim() || owner instanceof SVGElement || owner.closest('script, style, svg') || !shown(owner)) continue;
+  range.selectNodeContents(node);
+  const style = getComputedStyle(owner);
+  const lines = [...range.getClientRects()];
+  lines.map((rect) => visiblePart(inkOf(rect, node.data.trim(), style, lines.length === 1), owner))
+    .filter((rect) => area(rect) > 4)
+    .forEach((rect) => texts.push({ node, owner, rect, text: node.data.trim().slice(0, 40) }));
+}
+const SHARED_INK_PIXELS = 4;
+const glyphCache = new Map();
+const glyphsOf = (node) => {
+  if (glyphCache.has(node)) return glyphCache.get(node);
+  const style = getComputedStyle(node.parentElement);
+  const font = `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+  const glyphs = [];
+  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()].forEach((rect) => {
+        textMeasuringContext.font = font;
+        const metrics = textMeasuringContext.measureText(glyph);
+        const box = visiblePart(inkOf(rect, glyph, style, false), node.parentElement);
+        if (area(box) > 1) glyphs.push({ glyph, font, box, x: rect.left, baseline: baselineOf(rect, metrics) });
+      });
+    }
+    start = end;
+  }
+  glyphCache.set(node, glyphs);
+  return glyphs;
+};
+// Draws each glyph where the page put it and counts the pixels both inked, so a glyph tucked into the
+// empty corner of another glyph's box does not count.
+const inkPixels = (glyph, region) => {
+  const canvas = document.createElement('canvas');
+  canvas.width = Math.ceil(region.right - region.left);
+  canvas.height = Math.ceil(region.bottom - region.top);
+  const context = canvas.getContext('2d');
+  context.font = glyph.font;
+  context.fillText(glyph.glyph, glyph.x - region.left, glyph.baseline - region.top);
+  const alpha = context.getImageData(0, 0, canvas.width, canvas.height).data;
+  const inked = new Set();
+  for (let i = 3; i < alpha.length; i += 4) if (alpha[i] > 127) inked.add(i);
+  return inked;
+};
+const inkOverlaps = (one, other) => {
+  const shared = intersect(one.box, other.box);
+  if (area(shared) < 1) return false;
+  const otherInk = inkPixels(other, shared);
+  return [...inkPixels(one, shared)].filter((pixel) => otherInk.has(pixel)).length >= SHARED_INK_PIXELS;
+};
+const inkTouches = (a, b) => glyphsOf(a.node).some((glyph) => glyphsOf(b.node).some((other) => inkOverlaps(glyph, other)));
+const related = (a, b) => a === b || a.contains(b) || b.contains(a);
+const found = [];
+texts.forEach((a, i) => texts.slice(i + 1).forEach((b) => {
+  if (!related(a.owner, b.owner) && covers(a.rect, b.rect, 0) && inkTouches(a, b)) found.push(`"${a.text}" and "${b.text}"`);
+}));
+const titleBar = document.querySelector('.view .title_bar');
+if (titleBar) {
+  const bar = titleBar.getBoundingClientRect();
+  texts.filter((t) => !titleBar.contains(t.owner) && covers(t.rect, bar, 1 / 3))
+    .forEach((t) => found.push(`"${t.text}" and the title bar`));
+}
+return [...new Set(found)];

data/lib/trmnlp/testing/publishable_recipe.rb

@@ -18,6 +18,9 @@ module TRMNLP
     }.freeze
     # A field with more options than this is drawn with its first and last.
     PUBLISHABLE_RECIPE_MAX_OPTIONS = 20
+    # Share of a layout's ink its dark mode render must keep. Of 17 recipes measured on 10-13, those that draw
+    # well in dark mode kept 85% or more; those whose text turned black on black kept 0% to 15%.
+    DARK_MODE_MIN_INK_KEPT = 0.5
 
     # Each select field's keyname and the values its options save, from the plugin's settings.yml.
     def self.select_field_values
@@ -32,14 +35,18 @@ module TRMNLP
 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|
+RSpec.shared_examples 'a publishable recipe' do |screens: TRMNLP::Testing::PUBLISHABLE_RECIPE_SCREENS,
+                                                 dark_mode_screen: { device: 'v2' }|
   let(:recipe_inputs) do
     { mocks: respond_to?(:mocks) ? mocks : {}, custom_fields: respond_to?(:custom_fields) ? custom_fields : {},
       variables: respond_to?(:variables) ? variables : {}, now: respond_to?(:now) ? now : nil,
       data: respond_to?(:data) ? data : nil }
   end
 
-  def draw_cleanly = have_no_problems.and(have_no_leaked_text)
+  def draw_cleanly
+    have_no_problems.and(have_no_leaked_text)
+                    .and(have_no_text_clamped_with_room_to_spare).and(have_no_overlapping_text)
+  end
 
   TRMNLP::Testing::PUBLISHABLE_RECIPE_VIEWS.product(screens).each do |view, screen|
     device = screen[:device].is_a?(Hash) ? screen[:device][:model] : screen[:device]
@@ -51,6 +58,13 @@ RSpec.shared_examples 'a publishable recipe' do |screens: TRMNLP::Testing::PUBLI
     end
   end
 
+  TRMNLP::Testing::PUBLISHABLE_RECIPE_VIEWS.each do |view|
+    it "keeps the #{view} view's content in dark mode" do
+      light = trmnl.render(view:, **dark_mode_screen, **recipe_inputs)
+      expect(trmnl.render(view:, **dark_mode_screen, **recipe_inputs, dark_mode: true)).to keep_the_content_of(light)
+    end
+  end
+
   TRMNLP::Testing::PUBLISHABLE_RECIPE_API_FAILURES.each do |failure, answer|
     it "draws the full view when the API #{failure}" do
       screen = trmnl.render(**screens.first, **recipe_inputs, mocks: { '*' => answer })
@@ -67,6 +81,10 @@ RSpec.shared_examples 'a publishable recipe' do |screens: TRMNLP::Testing::PUBLI
     end
   end
 
+  it 'has a mock for every request it makes' do
+    expect(trmnl.transform(device: screens.first[:device], **recipe_inputs)).to have_a_mock_for_every_request
+  end
+
   it 'runs its transform without error' do
     expect(trmnl.transform(device: screens.first[:device], **recipe_inputs).error).to be_nil
   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 'ink_count'
 require_relative 'page_server'
 require_relative 'plugin'
 require_relative 'report'
@@ -75,6 +76,49 @@ RSpec::Matchers.define :have_no_transform_error do
   failure_message { |screen| "expected the transform to run without error, but: #{screen.result.error}" }
 end
 
+# A request no mock answers gets status 599, which draws the plugin's error screen as if its API failed.
+RSpec::Matchers.define :have_a_mock_for_every_request do
+  def unmocked(run) = run.requests.reject { it[:mocked] }.map { "#{it[:method]} #{it[:url].split('?', 2).first}" }.uniq
+
+  match { |run| unmocked(run).empty? }
+  failure_message do |run|
+    "expected a mock for every request, but none answers: #{unmocked(run).join(', ')}. " \
+      'Add them to tests/mocks.json; without one the screen shows the error state.'
+  end
+end
+
+# Dark mode recolors the Framework's text and lines; anything drawn in a fixed black stays black on the black screen.
+RSpec::Matchers.define :keep_the_content_of do |light|
+  match do |dark|
+    @light, @dark = [light, dark].map { TRMNLP::Testing::InkCount.new(it.png_path, area: content_box(it)).pixels }
+    @light.zero? || @dark >= @light * TRMNLP::Testing::DARK_MODE_MIN_INK_KEPT
+  end
+  # The layout only: a mashup slot's frame is too faint to count on white but stands out on black.
+  def content_box(screen) = screen.has_css?('.layout', wait: false) ? screen.box('.layout') : nil
+
+  failure_message do |dark|
+    "expected #{dark.inspect} in dark mode to keep its content, but it keeps #{(100 * @dark / @light).round}% of " \
+      "it (#{@dark} of #{@light} pixels that stand out): text, lines or icons drawn in a fixed black (#000, black) " \
+      'stay black on the black screen. Use currentColor or Framework classes.'
+  end
+end
+
+RSpec::Matchers.define :have_no_text_clamped_with_room_to_spare do
+  match { |screen| screen.clamped_with_room.empty? }
+  failure_message do |screen|
+    "expected no text cut short with room to spare on #{screen.inspect}, but it cuts: " \
+      "#{screen.clamped_with_room.join('; ')}."
+  end
+end
+
+RSpec::Matchers.define :have_no_overlapping_text do
+  match { |screen| screen.overlapping_text.empty? }
+  failure_message do |screen|
+    "expected no text drawn over other text on #{screen.inspect}, but it draws #{screen.overlapping_text.join('; ')} " \
+      'over each other.'
+  end
+end
+
 RSpec::Matchers.define :have_no_problems do
   match { |screen| screen.problems.empty? }
   failure_message { |screen| "expected no problems on #{screen.inspect}, but: #{screen.problems.join('; ')}" }

data/lib/trmnlp/testing/screen.rb

@@ -87,6 +87,34 @@ module TRMNLP
         }).map(describe);
       JS
 
+      # Each element the Framework clamped although its full text fits on one line of the width its parent gives it.
+      CLAMPED_WITH_ROOM_SCRIPT = <<~JS
+        const textMeasuringContext = document.createElement('canvas').getContext('2d');
+        const px = (value) => parseFloat(value) || 0;
+        const sharesItsRow = (style) => style.display.includes('grid') ||
+          (style.display.includes('flex') && !style.flexDirection.startsWith('column'));
+        const fullTextWidth = (el, text) => {
+          const style = getComputedStyle(el);
+          textMeasuringContext.font = `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+          const shown = style.textTransform === 'uppercase' ? text.toUpperCase() : text;
+          return textMeasuringContext.measureText(shown).width + px(style.letterSpacing) * shown.length +
+            px(style.paddingLeft) + px(style.paddingRight) + px(style.marginLeft) + px(style.marginRight);
+        };
+        return [...document.querySelectorAll('.view [data-clamp-original]')].filter((el) => {
+          const original = el.getAttribute('data-clamp-original').trim();
+          const parent = el.parentElement;
+          if (!original || el.innerText.trim() === original || !el.getClientRects().length || !parent) return false;
+          const parentStyle = getComputedStyle(parent);
+          if (sharesItsRow(parentStyle)) return false;
+          const room = parent.clientWidth - px(parentStyle.paddingLeft) - px(parentStyle.paddingRight);
+          return fullTextWidth(el, original) <= room - 2;
+        }).map((el) => `"${el.innerText.trim()}" (all of "${el.getAttribute('data-clamp-original').trim()}" fits)`);
+      JS
+
+      # Pairs of text whose ink is drawn over each other, and text drawn under the title bar. Each line's ink is cut
+      # to what its clipping parents show; two count when their glyphs share inked pixels.
+      OVERLAPPING_TEXT_SCRIPT = File.read(File.join(__dir__, 'overlapping_text.js')).freeze
+
       HIDDEN_MARK = 'data-trmnlp-hidden'
       # The DOM with every element Firefox does not draw marked, so Capybara's visible text is what is on screen.
       DRAWN_DOM_SCRIPT = <<~JS.freeze
@@ -126,6 +154,9 @@ module TRMNLP
 
       def overflowing(except: nil) = @browser.on(self) { it.execute_script(OVERFLOW_SCRIPT, except) }
 
+      def clamped_with_room = @browser.on(self) { it.execute_script(CLAMPED_WITH_ROOM_SCRIPT) }
+      def overlapping_text = @browser.on(self) { it.execute_script(OVERLAPPING_TEXT_SCRIPT) }
+
       # Script errors, unhandled rejections, console.error lines and files that failed to load.
       def problems = evaluate('window.__trmnlpProblems || []')
 

data/lib/trmnlp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.29.0
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -480,10 +480,12 @@ files:
 - lib/trmnlp/testing/certificate_authority.rb
 - lib/trmnlp/testing/device_models.rb
 - lib/trmnlp/testing/frozen_clock.rb
+- lib/trmnlp/testing/ink_count.rb
 - lib/trmnlp/testing/memory_sampler.rb
 - lib/trmnlp/testing/mock_proxy.rb
 - lib/trmnlp/testing/mock_table.rb
 - lib/trmnlp/testing/node_version.rb
+- lib/trmnlp/testing/overlapping_text.js
 - lib/trmnlp/testing/page_server.rb
 - lib/trmnlp/testing/plugin.rb
 - lib/trmnlp/testing/publishable_recipe.rb