trmnl_preview 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2460473710692cd80df450f411bdf811e44a9da068600b45db871c9e00ce0651
-  data.tar.gz: b34619a0fccac692176089ae44fe45c4c040a04bb2ca7035031750f768adc73d
+  metadata.gz: e31acf7d3493227af9ab7f728969de7c882622102661528186d29dce67ca722a
+  data.tar.gz: 29761cde0d07f5a026ff7a0bc3b1342ea6ad924402236296215bb6f8edfc2e29
 SHA512:
-  metadata.gz: 8de469fd1f6f81023ac8b3ad25168dce59f68a731a5814fc845e8a6155996e0800a7d5871e0d89fbd009bc910ad6b497f5a4dc6186025f60a79f758df31aaab1
-  data.tar.gz: b0bf8c9737e32bb67b3489de471c29ce78b03a4a40fcef69916834477d5daa0d3a4a89dcdaca68e411f20a1cafb5e91142216ae85c2e3d3a6e42a94f5fe944cf
+  metadata.gz: c2a64c19c1fcbdd43c49f94e604e4e0f136f46469abf42a96d2c993f9594f2f4ba1801b3c243d71edc97dfc59e1801b882ee288fcc0184cd638e5917abbe1286
+  data.tar.gz: 40a4779d9e8694389ee0d087ec03081171a930c72341aee959e2cbea37ca1ef095006a8bc311ab4dd2bf0fd610f682fe5afbb93792c247c2f9f1b4ba7bc884c2

data/CHANGELOG.md

@@ -1,6 +1,16 @@
 
 # Changelog
 
+## 0.17.0
+
+- `trmnlp init` adds a starter `tests/plugin_spec.rb`, and its GitHub workflow gains a `test` job: `trmnlp test --report` in the `trmnl/trmnlp` image (one `TRMNLP_IMAGE` setting picks the tag), the report uploaded, a manual `update_snapshots` run, and the push to TRMNL waiting for lint and tests. (#168)
+- `trmnlp test --report DIR` writes a report of the run: every example with each screen it rendered (the PNG, an outline of every drawn box, the page's problems) and each transform it ran (time, memory, requests), as `DIR/index.html` and `DIR/report.json`. Under GitHub Actions it adds the counts and the failures to the run's summary. (#167)
+- A polling plugin with no polling url runs its transform on empty data, as TRMNL does, instead of warning "config must specify polling_url" and counting it as a failed fetch, which stopped the transform's state being saved. A plugin whose transform fetches everything itself has no polling url. (#166)
+- `trmnlp test` runs a plugin's RSpec files in `tests/` through trmnlp's own pipeline: `trmnl.transform` and `trmnl.render` with fake APIs (the transform's own HTTPS requests included, in any language), a fixed clock (libfaketime, macOS and Linux), saved state, any TRMNL device, Capybara's matchers on what Firefox drew, layout boxes, overflow checks and PNG snapshots. See the README's Testing Plugins section. (#165)
+- A responsive `qr_code` keeps its own size, as on TRMNL. The hosted service gives the SVG a width, a height and `max-width:100%;height:auto` (core's `trmnl_liquid_qr_code_intrinsic_size` initializer), and trmnlp now does the same. Without it, a code in a shrink-to-fit container such as a `flex flex--col` column shrank to the width of its neighbors, or to nothing. (#162)
+- The Framework script loads as a module, as on TRMNL. A module runs after the page is parsed, so a plugin script that calls the Framework straight away now fails locally the way it fails on the device, instead of only on the device. (#163)
+- A transform's `trmnl_state` is not saved when the poll before it failed, as on TRMNL: a state built from an error or an empty response would replace the last good one. The key is still kept out of the rendered data. (#163)
+
 ## 0.16.0
 
 - Webhook posts must wrap their data in `merge_variables`, as TRMNL requires, and `merge_strategy` (`replace`, `deep_merge`, or `stream` with `stream_limit`) works from the body or the query string. A post without the wrapper is refused with TRMNL's message and a 422; a body that is not JSON gets a 400. Before, trmnlp stored the raw body and always answered 200, so a correct post rendered its data under `merge_variables.*`. A post over 5 kB is stored with a warning, since trmnlp cannot know your plan's limit. (#155)

data/README.md

@@ -470,6 +470,43 @@ The `settings.yml` file is part of the plugin definition, and is uploaded and do
 See [TRMNL documentation](https://help.trmnl.com/en/articles/10542599-importing-and-exporting-private-plugins#h_581fb988f0) for details on this file's contents.
 
 
+
+## Testing Plugins
+
+`trmnlp init` starts a plugin with `tests/plugin_spec.rb` (each view draws without overflow or page errors, and the transform stays within TRMNL's limits) and a GitHub workflow that runs it in the `trmnl/trmnlp` image, uploads the report, can rewrite the snapshots on a manual run, and pushes to TRMNL only once lint and tests pass. `trmnlp test` runs the RSpec files in your plugin's `tests/` folder, through the same pipeline `serve` and `build` use, with fake APIs and a fixed clock:
+
+```ruby
+# tests/weather_spec.rb
+RSpec.describe 'Weather' do
+  let(:mocks) { { 'https://api.weather.example/*' => { json: { temp: 12 } } } }
+
+  %w[og_plus v2].each do |device|
+    it "shows the temperature on #{device}" do
+      screen = trmnl.render(device:, now: '2030-01-02T08:00:00Z', custom_fields: { city: 'Amsterdam' }, mocks:)
+
+      expect(screen).to have_text('12°')
+      expect(screen).to have_no_overflow
+      expect(screen.box('.title').bottom).to be <= screen.box('.content').top
+      expect(screen).to match_snapshot
+    end
+  end
+
+  it 'keeps its state when the API has nothing new' do
+    run = trmnl.transform(state: { etag: 'abc' }, mocks: { 'https://api.weather.example/*' => { status: 304 } })
+
+    expect(run.state).to eq('etag' => 'abc')
+  end
+end
+```
+
+- `trmnl.transform(...)` runs the transform and answers `data`, `state`, `requests`, `log`, `error`, `duration_ms` and `max_memory_mb`; `expect(run).to stay_within_serverless_limits` checks TRMNL's 5 seconds and 128 MB. `trmnl.render(view: 'full', ...)` renders a view in Firefox and answers a screen: Capybara's matchers (`have_text`, `have_css`, `within`...) see what is drawn, and `box(selector)`, `evaluate(js)`, `overflowing` and `problems` (script errors, unhandled rejections, `console.error` and files that failed to load; `have_no_problems`) ask the live page; `fresh_browser: true` renders in a new Firefox with nothing cached; `screen.result` holds the run's `data`, `state` and `requests`. `trmnl.plugin(dir)` tests the plugin in another folder, such as a built copy.
+- Inputs, all optional: `device:` (a TRMNL model name, or `{ width:, height:, bit_depth: }`), `palette:`, `orientation: :portrait`, `dark_mode:`, `theme:`, `now:`, `custom_fields:`, `variables:`, `state:`, `previous_merge_variables:`, `data:` (skips polling), `transform: false`. A test's `custom_fields` and `variables` replace those in `.trmnlp.yml`, so development values there never reach a test; the field defaults in `settings.yml` still apply, as on TRMNL.
+- A board drawn by its own script takes `head:` (markup added to the page's `<head>`) and `wait_for:` (a JavaScript expression the page must reach before it is captured, within `wait_for_timeout:` seconds); without it, the capture freezes timers once TRMNL's readiness flags are set.
+- `mocks:` answer every request the run makes: polling urls, and the transform's own requests in any language, HTTPS included. Keys are urls, with `*` wildcards, a Regexp, or a method first (`'POST https://...'`). Values are `{ json:, body:, status:, headers:, delay:, body_delay:, advance_clock:, error: :reset }` (times in seconds: `body_delay:` sends the headers first and the body later, `advance_clock:` moves the transform's clock on when it answers), a string body, a lambda that takes the request, or an array of answers used in order. An unmocked request gets a 599. `requests` lists every request with its `status`, and `aborted: true` for one the transform gave up on before its answer arrived; `duration_ms` is how long the transform ran.
+- `now:` starts every clock: Liquid's, the markup's scripts', and the transform's, through libfaketime (`brew install libfaketime` or `apt-get install libfaketime`; already in the Docker image). On macOS the interpreter must come from brew, mise or similar, since macOS will not hand libfaketime to its own `/usr/bin` binaries.
+- `trmnlp test --report report` also writes `report/index.html` and `report/report.json`: every example with each screen it rendered (with a switch that outlines every drawn box, and the page's problems) and each transform it ran (time, memory, requests). Under GitHub Actions the counts and failures go to the run's summary too.
+- `match_snapshot` stores a missing snapshot under `tests/snapshots/<os>/` and fails one on CI; `trmnlp test --update` rewrites them. Fonts render differently per operating system, so run tests in the Docker image when CI should share your snapshots. `fit_image_size_limit` checks the PNG against the model's limit.
+
 ## Development
 
 To run trmnlp from a checkout of this repo — handy for trying unreleased changes or contributing:

data/lib/trmnlp/browser_pool.rb

@@ -34,13 +34,19 @@ module TRMNLP
       end
     end
 
-    private
-
     def checkout
       driver = acquire
       healthy?(driver) ? driver : recycle(driver)
     end
 
+    def checkin(driver)
+      return if @shutdown
+
+      @available.push(driver)
+    end
+
+    private
+
     def acquire
       pop_available || build_new || @available.pop
     end
@@ -72,11 +78,5 @@ module TRMNLP
         @driver_factory.call.tap { |d| @drivers << d }
       end
     end
-
-    def checkin(driver)
-      return if @shutdown
-
-      @available.push(driver)
-    end
   end
 end

data/lib/trmnlp/cli.rb

@@ -86,6 +86,13 @@ module TRMNLP
       Commands::Serve.run(options)
     end
 
+    desc 'test [PATHS]', "Run the plugin's tests in tests/ (RSpec, with `trmnl` and screen matchers)"
+    method_option :update, type: :boolean, default: false, desc: 'Rewrite the stored snapshots'
+    method_option :report, type: :string, banner: 'DIR', desc: 'Write a report of every screen and transform to DIR'
+    def test(*paths)
+      exit(1) unless Commands::Test.run(options, paths)
+    end
+
     desc 'version', 'Show version'
     def version
       puts VERSION

data/lib/trmnlp/commands/test.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module TRMNLP
+  module Commands
+    # Runs the plugin's RSpec files (tests/**/*_spec.rb) with `trmnl` and the screen matchers loaded.
+    class Test < Base
+      Options = Data.define(:dir, :quiet, :update, :report)
+      HELPERS = File.expand_path('../testing/rspec.rb', __dir__)
+
+      def call(paths = [])
+        context.validate!
+        require 'rspec/core'
+
+        ENV['TRMNLP_PLUGIN_DIR'] = context.paths.root_dir.to_s
+        ENV['TRMNLP_UPDATE_SNAPSHOTS'] = '1' if options.update
+        ENV['TRMNLP_REPORT_DIR'] = File.expand_path(options.report) if options.report
+        Dir.chdir(context.paths.root_dir) do
+          RSpec::Core::Runner.run(['--require', HELPERS, *(paths.empty? ? ['tests'] : paths)]).zero?
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/config/project.rb

@@ -11,17 +11,14 @@ module TRMNLP
     class Project
       attr_reader :paths
 
-      def initialize(paths)
+      def initialize(paths, overrides: {})
         @paths = paths
+        @overrides = overrides
         reload!
       end
 
       def reload!
-        @config = if paths.trmnlp_config.exist?
-                    YAML.safe_load_file(paths.trmnlp_config, permitted_classes: [Date, Time]) || {}
-                  else
-                    {}
-                  end
+        @config = read_config.merge(@overrides)
       rescue Psych::SyntaxError => e
         raise InvalidConfig, ".trmnlp.yml is not valid YAML: #{e.message}"
       end
@@ -90,6 +87,12 @@ module TRMNLP
 
       private
 
+      def read_config
+        return {} unless paths.trmnlp_config.exist?
+
+        YAML.safe_load_file(paths.trmnlp_config, permitted_classes: [Date, Time]) || {}
+      end
+
       # NOTE: arrays (multi-select fields) and hashes are preserved as-is;
       # only their leaf values are stringified to match production
       # behavior.

data/lib/trmnlp/config.rb

@@ -8,9 +8,9 @@ module TRMNLP
   class Config
     attr_reader :app, :project, :plugin
 
-    def initialize(path)
+    def initialize(path, project_overrides: {})
       @app = App.new(path)
-      @project = Project.new(path)
+      @project = Project.new(path, overrides: project_overrides)
       @plugin = Plugin.new(path, @project)
     end
   end

data/lib/trmnlp/context.rb

@@ -15,10 +15,15 @@ module TRMNLP
   class Context
     attr_reader :config, :paths, :reporter
 
-    def initialize(root_dir, reporter: Reporter.new)
-      @paths = Paths.new(root_dir)
-      @config = Config.new(paths)
+    # The keywords after reporter let `trmnlp test` run the real pipeline with a test's inputs.
+    # rubocop:disable-next Metrics/ParameterLists -- the composition root takes what it wires
+    def initialize(root_dir, reporter: Reporter.new, cache_dir: nil, project_overrides: {}, outbound_request: nil,
+                   transform_client: nil)
+      @paths = Paths.new(root_dir, cache_dir:)
+      @config = Config.new(paths, project_overrides:)
       @reporter = reporter
+      @outbound_request = outbound_request
+      @transform_client = transform_client
     end
 
     # Context is the composition root: it wires and memoizes the runtime
@@ -26,6 +31,7 @@ module TRMNLP
     # directly — Context does not forward methods on their behalf.
     def poller
       @poller ||= Poller.new(config:, paths:, oauth_session:, reporter:, async_callback:,
+                             outbound_request: @outbound_request,
                              trmnl_variables: -> { user_data_assembler.polling_variables })
     end
 
@@ -40,7 +46,9 @@ module TRMNLP
       end
     end
 
-    def transform_pipeline = @transform_pipeline ||= TransformPipeline.new(config:, paths:, reporter:)
+    def transform_pipeline
+      @transform_pipeline ||= TransformPipeline.new(config:, paths:, reporter:, client: @transform_client)
+    end
 
     def user_data_assembler
       @user_data_assembler ||= UserDataAssembler.new(config:, paths:, transform_pipeline:, oauth_session:)

data/lib/trmnlp/errors.rb

@@ -13,4 +13,5 @@ module TRMNLP
   class InvalidConfig       < Error; end
   class InvalidCustomFields < Error; end
   class RenderError         < Error; end
+  class TestingError        < Error; end
 end

data/lib/trmnlp/paths.rb

@@ -7,8 +7,9 @@ module TRMNLP
   class Paths
     attr_reader :root_dir
 
-    def initialize(root_dir)
+    def initialize(root_dir, cache_dir: nil)
       @root_dir = Pathname.new(root_dir).expand_path
+      @cache_dir = cache_dir && Pathname.new(cache_dir)
       @xdg = XDG.new
     end
 
@@ -27,7 +28,7 @@ module TRMNLP
 
     def app_config_dir = xdg.config_home.join('trmnlp')
 
-    def cache_dir = xdg.cache_home.join('trmnl')
+    def cache_dir = @cache_dir || xdg.cache_home.join('trmnl')
 
     def valid? = trmnlp_config.exist?
 
@@ -50,6 +51,7 @@ module TRMNLP
     def oauth_tokens = cache_dir.join('oauth', "#{project_key}.json")
 
     def transform_state = cache_dir.join('state', "#{project_key}.json")
+    def fetch_failed_marker = cache_dir.join('state', "#{project_key}.fetch_failed")
 
     def transform_output = cache_dir.join('transform_output', "#{project_key}.json")
 

data/lib/trmnlp/poller.rb

@@ -14,8 +14,9 @@ module TRMNLP
     # trmnl_variables answers the trmnl namespace TRMNL renders polling urls, headers and bodies with.
     # rubocop:disable-next Metrics/ParameterLists -- keyword collaborators Context wires once
     def initialize(config:, paths:, oauth_session:, trmnl_variables: -> { {} }, reporter: Reporter.new,
-                   async_callback: nil)
+                   async_callback: nil, outbound_request: nil)
       @config = config
+      @given_outbound_request = outbound_request
       @paths = paths
       @oauth_session = oauth_session
       @trmnl_variables = trmnl_variables
@@ -29,16 +30,19 @@ module TRMNLP
 
       missing = config.plugin.missing_required_fields
       return report_warning("Plugin is not configured — fill in: #{missing.join(', ')}") if missing.any?
-      raise InvalidConfig, 'config must specify polling_url or polling_urls' if config.plugin.polling_urls.empty?
 
-      data = aggregate_responses
+      @fetch_failed = false
+      # Like TRMNL: no url is nothing to fetch, and the transform runs on {}.
+      data = config.plugin.polling_urls.empty? ? {} : aggregate_responses
       write_user_data(data)
+      record_fetch_outcome
       data
     # NOTE: trmnlp is a dev tool — a flaky upstream API should surface a warning
     # and keep the preview server alive, not crash the user's session. We
     # deliberately swallow here and return {} so the renderer keeps rendering.
     rescue StandardError => e
       report_warning(e.message)
+      record_fetch_outcome
       {}
     end
 
@@ -52,7 +56,7 @@ module TRMNLP
         return report_warning('async_polling needs `trmnlp serve` to receive the callback')
       end
       return report_warning('Waiting for the async callback; the last data posted renders') if async_callback.awaiting?
-      raise InvalidConfig, 'config must specify polling_url' if config.plugin.polling_urls.empty?
+      return if config.plugin.polling_urls.empty?
 
       report_warning('Async callback not received within 15 minutes') if async_callback.expired?
       response, url = send_async_request(async_callback.start)
@@ -99,7 +103,7 @@ module TRMNLP
     end
 
     def outbound_request
-      OutboundRequest.new(on_private_address: lambda { |url|
+      @given_outbound_request || OutboundRequest.new(on_private_address: lambda { |url|
         report_warning("TRMNL refuses #{without_query(url)}: the url resolves to a private address")
       })
     end
@@ -107,7 +111,7 @@ module TRMNLP
     # Like the hosted service: a client error is reported, but its body still reaches the data.
     def parse_response(response, url)
       success = (200..299).cover?(response.status)
-      reporter.info(reporter.yellow("warning: HTTP #{response.status} from #{url}")) unless success
+      report_warning("HTTP #{response.status} from #{url}") unless success
       parse_body(without_byte_order_mark(response.body.to_s), response.headers['content-type'])
     rescue JSON::ParserError, CSV::MalformedCSVError => e
       report_warning("Malformed #{e.is_a?(CSV::MalformedCSVError) ? 'CSV' : 'JSON'} from url: #{url}")
@@ -144,10 +148,20 @@ module TRMNLP
     def wrap_array(json) = json.is_a?(Array) ? { data: json } : json
 
     def report_warning(message)
+      @fetch_failed = true
       reporter.info(reporter.yellow("warning: #{message}"))
       nil
     end
 
+    # The transform runs later, from the cached data, so whether this poll failed is kept beside it.
+    def record_fetch_outcome
+      marker = paths.fetch_failed_marker
+      return marker.delete if !@fetch_failed && marker.exist?
+
+      marker.dirname.mkpath
+      marker.write('') if @fetch_failed
+    end
+
     def write_user_data(data)
       paths.user_data.dirname.mkpath
       paths.user_data.write(JSON.generate(data))

data/lib/trmnlp/qr_code_intrinsic_size.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'trmnl/liquid'
+
+module TRMNLP
+  # Mirrors core's config/initializers/trmnl_liquid_qr_code_intrinsic_size.rb: a view box alone
+  # gives the code no size of its own, so it renders at zero width in a shrink-to-fit container.
+  module QrCodeIntrinsicSize
+    def qr_code(data, size = 11, level = '', view = 'responsive')
+      svg = super
+      root_element = svg[/<svg[^>]*>/].to_s
+      return svg if root_element.include?('width=')
+
+      side_length = root_element[/viewBox="0 0 (\d+)/, 1]
+      return svg unless side_length
+
+      svg.sub('<svg ', %(<svg width="#{side_length}" height="#{side_length}" style="max-width:100%;height:auto" ))
+    end
+  end
+end
+
+TRMNL::Liquid::Filters.prepend(TRMNLP::QrCodeIntrinsicSize)

data/lib/trmnlp/renderer.rb

@@ -29,6 +29,9 @@ module TRMNLP
 
     def framework = config.plugin.framework_version
 
+    # The data the last page was rendered from, for a test to read back.
+    attr_reader :last_data
+
     def screen_classes(classes = 'screen', theme: nil)
       classes = (classes || 'screen').split # an explicit nil (omitted screen_classes param) still needs a base
       # The picker marks every render 1x, which sets the dither ratio; TRMNL's device render has no such class.
@@ -66,7 +69,7 @@ module TRMNLP
     end
 
     def parse_and_render(template_path, device:)
-      data = user_data_assembler.call(device:)
+      data = @last_data = user_data_assembler.call(device:)
       size = JSON.generate(data.except('trmnl')).bytesize
       if size > MAX_MERGE_VARIABLES_KB * 1024
         raise RenderError, "Large payload received (#{size} bytes), should be less than #{MAX_MERGE_VARIABLES_KB}kb."

data/lib/trmnlp/screenshot.rb

@@ -45,11 +45,25 @@ module TRMNLP
       end
     end
 
+    # Loads html into driver at width x height and waits until TRMNL would capture it, and until wait_for
+    # (a JavaScript expression) is true when given: a page still drawing would be stopped by the frozen timers.
+    # rubocop:disable-next Metrics/ParameterLists -- the page, its size, and what to wait for
+    def show(driver, html, width, height, wait_for: nil, wait_for_timeout: READINESS_TIMEOUT_SECONDS)
+      resize(driver, width, height)
+      load_page(driver, html) { wait_for_expression(driver, wait_for, wait_for_timeout) if wait_for }
+    end
+
+    def capture(driver)
+      file = Tempfile.new(['screenshot', '.png'])
+      driver.save_screenshot(file.path)
+      file.close
+      file
+    end
+
     private
 
     def render(driver, html, width, height)
-      resize(driver, width, height)
-      load_page(driver, html)
+      show(driver, html, width, height)
       capture(driver)
     end
 
@@ -108,6 +122,7 @@ module TRMNLP
       JS
 
       wait_until_ready(driver, html)
+      yield if block_given?
       driver.execute_script('return document.fonts && document.fonts.ready')
 
       driver.execute_script(<<~JS)
@@ -117,18 +132,17 @@ module TRMNLP
       driver.execute_script(FREEZE_TIMERS)
     end
 
+    def wait_for_expression(driver, expression, timeout)
+      Selenium::WebDriver::Wait.new(timeout:, interval: 0.05).until { driver.execute_script("return !!(#{expression});") }
+    rescue Selenium::WebDriver::Error::TimeoutError
+      raise RenderError, "The page did not reach #{expression} within #{timeout}s"
+    end
+
     def wait_until_ready(driver, html)
       timeout = html.match?(MAPS_DOCUMENT_PATTERN) ? READINESS_TIMEOUT_WITH_MAPS_SECONDS : READINESS_TIMEOUT_SECONDS
       Selenium::WebDriver::Wait.new(timeout:, interval: 0.05).until { driver.execute_script(READINESS_CHECK_SCRIPT) }
     rescue Selenium::WebDriver::Error::TimeoutError
       nil
     end
-
-    def capture(driver)
-      file = Tempfile.new(['screenshot', '.png'])
-      driver.save_screenshot(file.path)
-      file.close
-      file
-    end
   end
 end

data/lib/trmnlp/testing/browser.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tmpdir'
+
+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.
+    class Browser
+      def initialize(pool:)
+        @pool = pool
+        @screenshot = Screenshot.new(pool:)
+        @pages = {}.compare_by_identity
+        @fresh_browsers = []
+      end
+
+      # 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] }
+      end
+
+      # The PNG path, quantized to the device's bit depth like a build's.
+      def capture(screen)
+        @capturing = screen
+        keep(generate(screen))
+      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
+
+      # Yields the driver with screen's page loaded, reloading it if a later render replaced it.
+      def on(screen)
+        show(screen) unless @showing.equal?(screen)
+        yield driver
+      end
+
+      def release
+        @fresh_browsers.each do |browser, pool|
+          browser.release
+          pool.shutdown
+        end
+        @fresh_browsers.clear
+        @pool.checkin(@driver) if @driver
+        @driver = nil
+        @showing = nil
+      end
+
+      private
+
+      def generate(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
+      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)
+        @showing = screen
+      end
+
+      def keep(image)
+        path = File.join(Dir.mktmpdir('trmnlp-screen-'), 'screen.png')
+        FileUtils.cp(image.path, path)
+        path
+      ensure
+        image.close!
+      end
+    end
+  end
+end

data/lib/trmnlp/testing/certificate_authority.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'openssl'
+require 'tmpdir'
+
+module TRMNLP
+  module Testing
+    # A throwaway authority the transform process is told to trust, so MockProxy can answer HTTPS.
+    # Lives for one server process; nothing is written outside its temp directory.
+    class CertificateAuthority
+      # Wide enough for any time a test freezes the clock at.
+      VALID_FROM = Time.utc(2000, 1, 1)
+      VALID_UNTIL = Time.utc(2099, 12, 31)
+
+      attr_reader :pem_path, :bundle_path, :php_ini_dir
+
+      def initialize
+        @key = OpenSSL::PKey::RSA.new(2048)
+        @certificate = sign(subject: 'trmnlp test CA', public_key: @key.public_key, authority: true)
+        @leaves = {}
+        @lock = Mutex.new
+        write_files(Dir.mktmpdir('trmnlp-ca-'))
+      end
+
+      # The variables that make Node, Python, Ruby and PHP trust this authority.
+      def environment
+        { 'NODE_EXTRA_CA_CERTS' => pem_path, 'SSL_CERT_FILE' => bundle_path, 'REQUESTS_CA_BUNDLE' => bundle_path,
+          'CURL_CA_BUNDLE' => bundle_path, 'PHP_INI_SCAN_DIR' => ":#{php_ini_dir}" }
+      end
+
+      def remove = FileUtils.remove_entry(File.dirname(pem_path))
+
+      def ssl_context_for(host)
+        @lock.synchronize do
+          @leaves[host] ||= OpenSSL::SSL::SSLContext.new.tap do |context|
+            context.key = @key
+            context.cert = sign(subject: host, public_key: @key.public_key, authority: false, host:)
+          end
+        end
+      end
+
+      private
+
+      def sign(subject:, public_key:, authority:, host: nil)
+        certificate = OpenSSL::X509::Certificate.new
+        certificate.version = 2
+        certificate.serial = OpenSSL::BN.rand(64)
+        certificate.subject = OpenSSL::X509::Name.parse("/CN=#{subject}")
+        certificate.issuer = authority ? certificate.subject : @certificate.subject
+        certificate.public_key = public_key
+        certificate.not_before = VALID_FROM
+        certificate.not_after = VALID_UNTIL
+        add_extensions(certificate, authority, host)
+        certificate.sign(@key, OpenSSL::Digest.new('SHA256'))
+      end
+
+      def add_extensions(certificate, authority, host)
+        factory = OpenSSL::X509::ExtensionFactory.new(authority ? certificate : @certificate, certificate)
+        if authority
+          certificate.add_extension(factory.create_extension('basicConstraints', 'CA:TRUE', true))
+          certificate.add_extension(factory.create_extension('keyUsage', 'keyCertSign,cRLSign', true))
+        else
+          name = host.match?(/\A[\d.]+\z/) ? "IP:#{host}" : "DNS:#{host}"
+          certificate.add_extension(factory.create_extension('subjectAltName', name))
+          certificate.add_extension(factory.create_extension('extendedKeyUsage', 'serverAuth'))
+        end
+      end
+
+      def write_files(dir)
+        @pem_path = File.join(dir, 'ca.pem')
+        @bundle_path = File.join(dir, 'bundle.pem')
+        @php_ini_dir = File.join(dir, 'php')
+        File.write(pem_path, @certificate.to_pem)
+        system_file = OpenSSL::X509::DEFAULT_CERT_FILE
+        system_bundle = File.exist?(system_file) ? File.read(system_file) : ''
+        File.write(bundle_path, system_bundle + @certificate.to_pem)
+        Dir.mkdir(php_ini_dir)
+        php_settings = "curl.cainfo=#{bundle_path}\nopenssl.cafile=#{bundle_path}\n"
+        File.write(File.join(php_ini_dir, 'trmnlp-ca.ini'), php_settings)
+      end
+    end
+  end
+end