trmnl_preview 0.16.0 → 0.17.0

data/lib/trmnlp/testing/report.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'fileutils'
+require 'json'
+require 'rspec/core'
+
+module TRMNLP
+  module Testing
+    # What `trmnlp test --report DIR` writes: every example with each screen it rendered (the PNG, the boxes
+    # of everything drawn, the page's problems) and each transform it ran, as DIR/index.html and
+    # DIR/report.json. Under GitHub Actions the counts and failures go to the step summary too.
+    class Report
+      TEMPLATE = File.expand_path('report.html.erb', __dir__)
+      OUTLINES_SCRIPT = <<~JS
+        (() => [...document.querySelectorAll('.view *')].slice(0, 3000).map((el) => {
+          const box = el.getBoundingClientRect();
+          return { tag: el.tagName.toLowerCase(), class: String(el.className.baseVal ?? el.className),
+                   x: box.x, y: box.y, w: box.width, h: box.height };
+        }).filter((box) => box.w > 0 && box.h > 0))()
+      JS
+
+      class << self
+        attr_accessor :current
+      end
+
+      def initialize(dir)
+        @dir = dir
+        @examples = {}
+        @images = 0
+      end
+
+      def record_screen(screen)
+        entry&.fetch(:screens)&.push(
+          label: "#{screen.device.name} · #{screen.view}", width: screen.device.width, height: screen.device.height,
+          image: copy_image(screen.png_path), outlines: screen.evaluate(OUTLINES_SCRIPT), problems: screen.problems
+        )
+      end
+
+      def record_run(run)
+        return unless run.duration_ms
+
+        entry&.fetch(:runs)&.push(duration_ms: run.duration_ms, max_memory_mb: run.max_memory_mb, error: run.error,
+                                  requests: run.requests.map { it.slice(:method, :url, :status, :via, :aborted) })
+      end
+
+      def example_passed(notification) = finish(notification.example, 'passed')
+      def example_pending(notification) = finish(notification.example, 'pending')
+      def example_failed(notification) = finish(notification.example, 'failed', notification.example.exception&.message)
+
+      def close(_notification)
+        FileUtils.mkdir_p(@dir)
+        File.write(File.join(@dir, 'report.json'), JSON.pretty_generate(examples: examples))
+        File.write(File.join(@dir, 'index.html'), ERB.new(File.read(TEMPLATE)).result(binding))
+        write_step_summary if ENV['GITHUB_STEP_SUMMARY']
+      end
+
+      private
+
+      def examples = @examples.values
+
+      def entry(example = RSpec.current_example)
+        return unless example
+
+        @examples[example.id] ||= { description: example.full_description, location: example.location,
+                                    status: 'running', message: nil, screens: [], runs: [] }
+      end
+
+      def finish(example, status, message = nil) = entry(example).merge!(status:, message:)
+
+      def copy_image(path)
+        name = "images/#{@images += 1}.png"
+        FileUtils.mkdir_p(File.join(@dir, 'images'))
+        FileUtils.cp(path, File.join(@dir, name))
+        name
+      end
+
+      def count(status) = examples.count { it[:status] == status }
+
+      def write_step_summary
+        counts = "#{count('passed')} passed, #{count('failed')} failed, #{count('pending')} pending, " \
+                 "#{examples.sum { it[:screens].size }} screens"
+        lines = ["### trmnlp test\n", "#{counts}\n"]
+        examples.select { it[:status] == 'failed' }.each { lines << "- ❌ #{it[:description]} (`#{it[:location]}`)" }
+        File.write(ENV.fetch('GITHUB_STEP_SUMMARY'), "#{lines.join("\n")}\n", mode: 'a')
+      end
+
+      def h(text) = ERB::Util.html_escape(text.to_s)
+    end
+  end
+end

data/lib/trmnlp/testing/rspec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Loaded by `trmnlp test`: gives each example `trmnl`, Capybara's matchers and trmnlp's own.
+require 'capybara/rspec/matchers'
+require 'rspec/core'
+require 'rspec/expectations'
+
+require_relative '../../trmnlp'
+require_relative '../browser_pool'
+require_relative '../firefox_driver'
+require_relative 'browser'
+require_relative 'certificate_authority'
+require_relative 'plugin'
+require_relative 'report'
+require_relative 'snapshot'
+
+module TRMNLP
+  module Testing
+    PLUGIN_DIR_ENV_KEY = 'TRMNLP_PLUGIN_DIR'
+
+    def self.plugin_dir = ENV.fetch(PLUGIN_DIR_ENV_KEY, Dir.pwd)
+
+    def self.authority
+      @authority ||= CertificateAuthority.new.tap { |authority| at_exit { authority.remove } }
+    end
+
+    def self.browser_pool
+      @browser_pool ||= BrowserPool.new(driver_factory: FirefoxDriver.method(:build), max_size: 1)
+    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)
+    end
+  end
+end
+
+RSpec::Matchers.define :have_no_overflow do
+  match { |screen| screen.overflowing.empty? }
+  failure_message do |screen|
+    "expected nothing to overflow on #{screen.inspect}, but: #{screen.overflowing.join(', ')}"
+  end
+end
+
+# TRMNL gives a transform 5 seconds and 128 MB (help.trmnl.com, Serverless).
+RSpec::Matchers.define :stay_within_serverless_limits do
+  match { |run| run.duration_ms.to_i <= 5000 && run.max_memory_mb.to_f <= 128 }
+  failure_message do |run|
+    "expected the transform to stay within 5000 ms and 128 MB, but it took #{run.duration_ms} ms " \
+      "and #{run.max_memory_mb} MB"
+  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('; ')}" }
+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|
+    "expected the #{screen.device.name} PNG to fit #{screen.device.image_size_limit} bytes, " \
+      "but it is #{screen.png_bytes.bytesize}"
+  end
+end
+
+RSpec::Matchers.define :match_snapshot do |name = nil|
+  match do |screen|
+    example = RSpec.current_example
+    name ||= [example.full_description, screen.device.name, screen.view].join(' ').downcase.gsub(/[^a-z0-9]+/, '-')
+    dir = File.join(TRMNLP::Testing.plugin_dir, 'tests', 'snapshots')
+    @mismatch = TRMNLP::Testing::Snapshot.new(screen, name:, dir:).mismatch
+    @mismatch.nil?
+  end
+  failure_message { @mismatch }
+end
+
+RSpec.configure do |config|
+  if (report_dir = ENV.fetch('TRMNLP_REPORT_DIR', nil))
+    TRMNLP::Testing::Report.current = TRMNLP::Testing::Report.new(report_dir)
+    config.reporter.register_listener(TRMNLP::Testing::Report.current, :example_passed, :example_failed,
+                                      :example_pending, :close)
+  end
+
+  config.include Capybara::RSpecMatchers
+  config.include TRMNLP::Testing::Helpers
+  config.after { @trmnl_browser&.release }
+end

data/lib/trmnlp/testing/run.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'delegate'
+require 'json'
+require 'tmpdir'
+
+require_relative '../context'
+require_relative '../reporter'
+require_relative '../transform_backend/subprocess'
+require_relative '../transform_backend/which'
+require_relative '../transform_client'
+require_relative '../transform_state'
+require_relative 'frozen_clock'
+require_relative 'memory_sampler'
+require_relative 'node_version'
+require_relative 'mock_proxy'
+require_relative 'mock_table'
+
+module TRMNLP
+  module Testing
+    # One transform or render of a plugin, through trmnlp's own pipeline, in a cache directory of its own:
+    # the test's custom fields, saved state and previous output go in, its mocks answer every request,
+    # and every clock starts at its `now`.
+    class Run
+      Result = Data.define(:data, :html, :state, :requests, :log, :error, :duration_ms, :max_memory_mb)
+
+      # The transform client, remembering how long its last run took.
+      class TimedClient < SimpleDelegator
+        attr_reader :duration_ms
+
+        def execute(**) = super.tap { @duration_ms = it.duration_ms }
+      end
+
+      # rubocop:disable-next Metrics/ParameterLists -- one keyword per input a test can set
+      def initialize(plugin:, authority:, now: nil, custom_fields: {}, variables: {}, state: nil,
+                     previous_merge_variables: nil, data: nil, mocks: {}, transform: true)
+        @plugin = plugin.to_s
+        @authority = authority
+        @now = now
+        @inputs = { custom_fields:, variables:, state:, previous_merge_variables:, data:, transform: }
+        @table = MockTable.new(mocks, on_advance_clock: method(:advance_clock))
+        @clock_offset = 0
+        @reporter = Reporter.new(quiet: true)
+      end
+
+      def transform(device: {})
+        call { |context| { data: context.user_data_assembler.call(device:) } }
+      end
+
+      def render(view:, device: {}, screen_classes: nil, theme: nil)
+        call do |context|
+          html = context.renderer.render_full_page(view, device.merge(screen_classes:, theme:))
+          { html:, data: context.renderer.last_data }
+        end
+      end
+
+      private
+
+      attr_reader :plugin, :authority, :now, :inputs, :table, :reporter
+
+      def call
+        Dir.mktmpdir('trmnlp-run-') do |cache_dir|
+          @clock_file = File.join(cache_dir, 'clock')
+          MockProxy.open(table:, authority:) do |proxy|
+            context = build_context(cache_dir, proxy)
+            parts = FrozenClock.around(now) do
+              load_source_data(context)
+              yield context
+            end
+            Result.new(data: nil, html: nil, **parts, **outcome(context))
+          end
+        end
+      end
+
+      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:)
+        seed(context.paths)
+        context
+      end
+
+      def project_overrides
+        overrides = { 'custom_fields' => stringify(inputs[:custom_fields]),
+                      'variables' => stringify(inputs[:variables]) }
+        inputs[:transform] ? overrides : overrides.merge('transform_runtime' => 'disabled')
+      end
+
+      def transform_client(proxy)
+        environment = proxy.environment
+        language = transform_language
+        NodeVersion.check!(interpreter(language)) if language.to_s == 'node'
+        if now && language
+          environment = environment.merge(FrozenClock.environment(now, interpreter: interpreter(language),
+                                                                       clock_file: @clock_file))
+        end
+        on_spawn = ->(pid) { @memory = MemorySampler.start(pid) }
+        backend = TransformBackend::Subprocess.new(environment:, on_spawn:)
+        @client = TimedClient.new(TransformClient.new(backend:))
+      end
+
+      def transform_language
+        paths = Paths.new(plugin)
+        _path, inferred = paths.transform_file
+        Config.new(paths).plugin.serverless_language || inferred
+      end
+
+      def interpreter(language)
+        commands = TransformBackend::Subprocess::INTERPRETERS.fetch(language.to_s, { cmds: [language.to_s] })[:cmds]
+        TransformBackend::Which.locate(TransformBackend::Which.resolve(commands)).to_s
+      end
+
+      def seed(paths)
+        write(paths.transform_state, inputs[:state]) if inputs[:state]
+        write(paths.transform_output, inputs[:previous_merge_variables]) if inputs[:previous_merge_variables]
+      end
+
+      def load_source_data(context)
+        if inputs[:data]
+          write(context.paths.user_data, inputs[:data])
+        elsif context.config.plugin.polling?
+          context.poller.poll_data
+        end
+        time = now || Time.now
+        File.utime(time, time, context.paths.user_data) if context.paths.user_data.exist?
+      end
+
+      # A mock's advance_clock: moves the transform's clock on from the test's now.
+      def advance_clock(seconds)
+        raise TestingError, 'advance_clock needs now: on the run' unless now
+
+        @clock_offset += seconds
+        FrozenClock.write(@clock_file, now + @clock_offset)
+      end
+
+      def outcome(context)
+        table.finish
+        { state: TransformState.new(paths: context.paths).read, requests: table.requests, log: reporter.messages,
+          error: context.transform_pipeline.error, duration_ms: @client&.duration_ms, max_memory_mb: @memory&.peak_mb }
+      end
+
+      def stringify(value) = JSON.parse(JSON.generate(value || {}))
+
+      def write(path, value)
+        path.dirname.mkpath
+        path.write(JSON.generate(value))
+      end
+    end
+  end
+end

data/lib/trmnlp/testing/screen.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'capybara'
+require 'delegate'
+require 'nokogiri'
+
+module TRMNLP
+  module Testing
+    # A rendered view, as Firefox drew it. Capybara's finders and matchers (have_text, have_css, within...)
+    # work on the DOM after the Framework's scripts ran; #box, #evaluate and #overflowing ask the live page.
+    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.
+      OVERFLOW_SCRIPT = <<~JS
+        const screen = document.documentElement.getBoundingClientRect();
+        const describe = (el) => el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') +
+          (el.classList.length ? '.' + [...el.classList].join('.') : '');
+        return [...document.querySelectorAll('.view *')].filter((el) => {
+          const box = el.getBoundingClientRect();
+          if (box.width === 0 && box.height === 0) 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;
+        }).map(describe);
+      JS
+
+      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
+        const hidden = [...document.querySelectorAll('body *')]
+          .filter((el) => !el.checkVisibility({ opacityProperty: true, visibilityProperty: true }));
+        hidden.forEach((el) => el.setAttribute('#{HIDDEN_MARK}', ''));
+        const copy = document.documentElement.cloneNode(true);
+        hidden.forEach((el) => el.removeAttribute('#{HIDDEN_MARK}'));
+        copy.querySelectorAll('script, style, noscript, template').forEach((el) => el.remove());
+        return copy.outerHTML;
+      JS
+
+      attr_reader :html, :device, :view, :png_path, :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)
+        @html = html
+        @wait_for = wait_for
+        @wait_for_timeout = wait_for_timeout
+        @device = device
+        @view = view
+        @browser = browser
+        @result = result
+        @png_path = browser.capture(self)
+        super(Capybara.string(drawn_dom(browser.on(self) { it.execute_script(DRAWN_DOM_SCRIPT) })))
+      end
+
+      def box(selector)
+        rect = evaluate("(() => { const el = document.querySelector(#{selector.to_json}); " \
+                        'return el && el.getBoundingClientRect().toJSON(); })()')
+        raise TestingError, "No element matches #{selector.inspect} on the #{view} view" unless rect
+
+        Box.new(**rect.slice('left', 'top', 'right', 'bottom', 'width', 'height').transform_keys(&:to_sym))
+      end
+
+      def evaluate(expression) = @browser.on(self) { it.execute_script("return (#{expression});") }
+
+      def overflowing = @browser.on(self) { it.execute_script(OVERFLOW_SCRIPT) }
+
+      # Script errors, unhandled rejections, console.error lines and files that failed to load.
+      def problems = evaluate('window.__trmnlpProblems || []')
+
+      def png_bytes = File.binread(png_path)
+
+      def drawn_dom(source)
+        document = Nokogiri::HTML(source)
+        document.css("[#{HIDDEN_MARK}]").each { it['hidden'] = 'hidden' }
+        document.to_html
+      end
+
+      def inspect = "#<#{self.class.name} #{device.name} #{view}>"
+    end
+  end
+end

data/lib/trmnlp/testing/snapshot.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'mini_magick'
+require 'rbconfig'
+
+module TRMNLP
+  module Testing
+    # A screen's PNG compared with the one stored for it. Fonts render differently per operating system,
+    # so each keeps its own copy; run tests in the trmnlp Docker image for snapshots CI can share.
+    class Snapshot
+      UPDATE_ENV_KEY = 'TRMNLP_UPDATE_SNAPSHOTS'
+
+      attr_reader :path
+
+      def initialize(screen, name:, dir:)
+        @screen = screen
+        @path = File.join(dir, operating_system, "#{name}.png")
+      end
+
+      # nil when they match (or the stored copy was just written), otherwise why not.
+      def mismatch
+        return store if ENV[UPDATE_ENV_KEY] || (!File.exist?(path) && !ENV['CI'])
+        return "no snapshot at #{path}; run `trmnlp test --update` to create it" unless File.exist?(path)
+
+        differing = differing_pixels
+        "#{differing} pixels differ from #{path}; run `trmnlp test --update` if the change is intended" if differing
+      end
+
+      private
+
+      attr_reader :screen
+
+      def store
+        FileUtils.mkdir_p(File.dirname(path))
+        FileUtils.cp(screen.png_path, path)
+        nil
+      end
+
+      def differing_pixels
+        expected = MiniMagick::Image.open(path)
+        actual = MiniMagick::Image.open(screen.png_path)
+        return 'all' unless expected.dimensions == actual.dimensions
+
+        tool = MiniMagick::Tool.new('compare', errors: false)
+        tool << '-metric' << 'AE' << path << screen.png_path << 'null:'
+        count = nil
+        tool.call { |_stdout, stderr, _status| count = stderr.to_f.round }
+        count.positive? ? count : nil
+      end
+
+      def operating_system = RbConfig::CONFIG['host_os'][/darwin|linux|mswin|mingw/] || 'other'
+    end
+  end
+end

data/lib/trmnlp/transform_backend/subprocess.rb

@@ -32,6 +32,12 @@ module TRMNLP
         'php' => { cmds: %w[php],                  ext: 'php' }
       }.freeze
 
+      # on_spawn is called with the transform's process id, as soon as it starts.
+      def initialize(environment: {}, on_spawn: nil)
+        @environment = environment
+        @on_spawn = on_spawn
+      end
+
       def execute(code:, language:, stdin: '', timeout_seconds: DEFAULT_TIMEOUT)
         spec = INTERPRETERS[language.to_s]
         return failure("unsupported language: #{language}") unless spec
@@ -55,7 +61,8 @@ module TRMNLP
       def run_process(cmd, src_path, stdin, timeout_seconds, output_path)
         started = monotonic_ms
 
-        Open3.popen3(cmd, src_path) do |stdin_io, stdout_io, stderr_io, wait_thr|
+        Open3.popen3(@environment, cmd, src_path) do |stdin_io, stdout_io, stderr_io, wait_thr|
+          @on_spawn&.call(wait_thr.pid)
           stdin_io.write(stdin)
           stdin_io.close
 

data/lib/trmnlp/transform_pipeline.rb

@@ -19,7 +19,8 @@ module TRMNLP
 
     attr_reader :error
 
-    def initialize(config:, paths:, reporter: Reporter.new)
+    def initialize(config:, paths:, reporter: Reporter.new, client: nil)
+      @given_client = client
       @config = config
       @paths = paths
       @reporter = reporter
@@ -43,13 +44,13 @@ module TRMNLP
       {}
     end
 
-    def reset! = @client = nil
+    def reset! = @client = @given_client
 
     private
 
     attr_reader :config, :paths, :reporter, :transform_state
 
-    def client = @client ||= TransformClient.from_config(config.project)
+    def client = @client ||= @given_client || TransformClient.from_config(config.project)
 
     def run(path, inferred_language, data)
       language = config.plugin.serverless_language || inferred_language
@@ -81,7 +82,7 @@ module TRMNLP
       transformed = JSON.parse(output)
       return reject_non_object_output unless transformed.is_a?(Hash)
 
-      transform_state.extract!(transformed)
+      transform_state.extract!(transformed, fetch_failed: config.plugin.polling? && paths.fetch_failed_marker.exist?)
       store_output(without_previous_merge_variables(transformed))
     rescue JSON::ParserError => e
       @error = "transform produced non-JSON output: #{e.message}"

data/lib/trmnlp/transform_state.rb

@@ -21,10 +21,13 @@ module TRMNLP
       {}
     end
 
-    def extract!(output)
+    def extract!(output, fetch_failed: false)
       return unless output.is_a?(Hash) && output.key?(KEY)
 
       state = output.delete(KEY)
+      # Like TRMNL: a state built from a failed fetch would replace the last good one.
+      return if fetch_failed
+
       rejection = rejection_reason(state)
       rejection ? reporter.info(reporter.yellow("Ignored #{KEY}: #{rejection}")) : write(state)
     end

data/lib/trmnlp/version.rb

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

data/lib/trmnlp.rb

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

data/templates/init/.github/workflows/trmnl.yml

@@ -3,6 +3,16 @@ on:
   pull_request:
   push:
     branches: [main]
+  workflow_dispatch:
+    inputs:
+      update_snapshots:
+        description: Rewrite the snapshots in tests/snapshots and upload them
+        type: boolean
+        default: false
+
+env:
+  # The trmnlp image the tests run in. Pin a release (trmnl/trmnlp:v0.17.0) to keep runs repeatable.
+  TRMNLP_IMAGE: trmnl/trmnlp:latest
 
 jobs:
   lint:
@@ -15,9 +25,30 @@ jobs:
       - run: gem install trmnl_preview
       - run: trmnlp lint
 
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: trmnlp test
+        run: >
+          docker run --rm -e CI=true -e GITHUB_STEP_SUMMARY=/summary.md
+          -v "$PWD":/plugin -v "$GITHUB_STEP_SUMMARY":/summary.md "$TRMNLP_IMAGE"
+          test --report report ${{ inputs.update_snapshots && '--update' || '' }}
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: trmnlp-report
+          path: report
+      - if: ${{ inputs.update_snapshots }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: snapshots
+          path: tests/snapshots
+
   push:
-    needs: lint
-    if: github.ref == 'refs/heads/main'
+    # Take test out of needs to push to TRMNL even when the tests fail.
+    needs: [lint, test]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6

data/templates/init/.gitignore

@@ -1,2 +1,5 @@
 # trmnlp build output
 _build/
+
+# trmnlp test --report output
+report/

data/templates/init/tests/plugin_spec.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# This plugin's tests, run with `trmnlp test` (add `--report report` for a page of every screen it drew).
+# Docs: https://github.com/usetrmnl/trmnlp#testing-plugins
+RSpec.describe 'My Plugin' do
+  # Canned answers for the requests the plugin makes, its polling urls and its transform's own, e.g.
+  #   { 'https://api.example.com/*' => { json: { temperature: 21 } } }
+  let(:mocks) { {} }
+
+  # The values of the custom fields in src/settings.yml to test with.
+  let(:custom_fields) { {} }
+
+  %w[full half_horizontal half_vertical quadrant].each do |view|
+    it "draws the #{view} view without overflow or page errors" do
+      screen = trmnl.render(view:, mocks:, custom_fields:)
+
+      expect(screen).to have_no_overflow
+      expect(screen).to have_no_problems
+    end
+  end
+
+  it "stays within TRMNL's serverless limits" do
+    expect(trmnl.transform(mocks:, custom_fields:)).to stay_within_serverless_limits
+  end
+
+  # A picture of the full view, compared pixel for pixel on every run. Record it once with
+  # `trmnlp test --update` (or the workflow's update_snapshots run) and commit tests/snapshots.
+  #
+  # it 'looks as it did' do
+  #   expect(trmnl.render(mocks:, custom_fields:)).to match_snapshot
+  # end
+end

data/trmnl_preview.gemspec

@@ -57,6 +57,11 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'mini_magick', '~> 5.3'
   spec.add_dependency 'selenium-webdriver', '~> 4.44'
 
+  # Plugin tests (`trmnlp test`)
+  spec.add_dependency 'capybara', '~> 3.40'
+  spec.add_dependency 'rspec-core', '~> 3.13'
+  spec.add_dependency 'rspec-expectations', '~> 3.13'
+
   # OAuth2 (local plugin preview auth flow)
   spec.add_dependency 'oauth2', '~> 2.0'
 

data/web/views/render_html.erb

@@ -38,7 +38,7 @@
     </script>
     <link rel="stylesheet" href="<%= @framework.css_url %>" />
     <% if @theme_css_url %><link rel="stylesheet" href="<%= @theme_css_url %>" /><% end %>
-    <script src="<%= @framework.js_url %>"></script>
+    <script type="module" src="<%= @framework.js_url %>"></script>
     <meta name="trmnl-framework-version" content="<%= @framework.number %>" />
     <meta name="trmnl-framework-pinned" content="<%= @framework.pinned? %>" />