trmnl_preview 0.15.0 → 0.17.0

data/lib/trmnlp/testing/mock_table.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module TRMNLP
+  module Testing
+    # A test's canned answers for the requests a run makes, and the record of those requests. Polling asks it
+    # through #call, standing in for OutboundRequest; the transform's requests reach it through MockProxy.
+    #
+    # Keys are urls: exact, with `*` wildcards, or a Regexp; a key may start with a method ("POST https://...").
+    # A value is an answer ({ json:, body:, status:, headers:, delay:, body_delay:, advance_clock:, error: :reset }),
+    # in seconds where it is a time; a String body,
+    # a lambda that takes the request and returns an answer, or an Array of answers used in order.
+    class MockTable
+      Response = Struct.new(:status, :headers, :body, :body_delay, :record)
+      UNMOCKED_STATUS = 599
+      METHOD_PREFIX = /\A(GET|POST|PUT|PATCH|DELETE|HEAD) /
+
+      attr_reader :requests
+
+      def initialize(mocks, on_advance_clock: nil)
+        @on_advance_clock = on_advance_clock
+        @mocks = (mocks || {}).map { |key, value| { key:, answers: value.is_a?(Array) ? value.dup : [value] } }
+        @requests = []
+        @lock = Mutex.new
+      end
+
+      # [response, failure], as OutboundRequest#call answers.
+      def call(verb, url, headers:, body:)
+        response = answer(verb, url, headers:, body:, via: :polling)
+        response&.record&.[]=(:delivered, true)
+        response ? [response, nil] : [nil, 'the connection was reset']
+      end
+
+      # Once the run is over: a request whose answer never reached the transform was abandoned by it.
+      def finish
+        @lock.synchronize do
+          @requests.each { |request| request[:aborted] = !request.delete(:delivered) && !request[:reset] }
+        end
+      end
+
+      # nil when the mock resets the connection. The request is recorded before it is answered, so one the
+      # transform abandons during a delay is still there; MockProxy marks it aborted.
+      def answer(verb, url, headers: {}, body: nil, via: :polling)
+        request = { method: verb.upcase, url:, headers:, body:, via: }
+        answer = claim(request)
+        entry = record(request.merge(mocked: !answer.nil?, status: nil, aborted: false))
+        response = answer.nil? ? unmocked(request) : respond(answer, request)
+        response&.record = entry
+        entry[:status] = response&.status
+        entry[:reset] = true if answer && response.nil?
+        response
+      end
+
+      private
+
+      def claim(request)
+        @lock.synchronize do
+          mock = @mocks.find { matches?(it[:key], request) }
+          mock && (mock[:answers].size > 1 ? mock[:answers].shift : mock[:answers].first)
+        end
+      end
+
+      def respond(answer, request)
+        answer = answer.call(request) if answer.respond_to?(:call)
+        answer = { body: answer } if answer.is_a?(String)
+        sleep(answer[:delay]) if answer[:delay]
+        @on_advance_clock&.call(answer[:advance_clock]) if answer[:advance_clock]
+        answer[:error] == :reset ? nil : build(answer)
+      end
+
+      def build(answer)
+        json = answer.key?(:json)
+        body = json ? JSON.generate(answer[:json]) : answer[:body].to_s
+        type = json ? 'application/json' : 'text/plain; charset=utf-8'
+        Response.new(answer[:status] || 200, { 'content-type' => type }.merge(answer[:headers] || {}), body,
+                     answer[:body_delay])
+      end
+
+      def unmocked(request)
+        Response.new(UNMOCKED_STATUS, { 'content-type' => 'text/plain' },
+                     "trmnlp test: no mock for #{request[:method]} #{request[:url]}")
+      end
+
+      def matches?(key, request)
+        return key.match?(request[:url]) if key.is_a?(Regexp)
+
+        verb = key[METHOD_PREFIX, 1]
+        return false if verb && verb != request[:method]
+
+        pattern = key.sub(METHOD_PREFIX, '')
+        target = pattern.include?('?') ? request[:url] : request[:url].split('?', 2).first
+        /\A#{Regexp.escape(pattern).gsub('\*', '.*')}\z/.match?(target)
+      end
+
+      def record(entry)
+        @lock.synchronize { @requests << entry }
+        entry
+      end
+    end
+  end
+end

data/lib/trmnlp/testing/node_version.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+require_relative '../errors'
+
+module TRMNLP
+  module Testing
+    # Node sends fetch through HTTPS_PROXY only from version 24 (NODE_USE_ENV_PROXY); an older one would
+    # skip MockProxy and reach the real network, so a Node transform is refused there rather than run.
+    module NodeVersion
+      MINIMUM_MAJOR = 24
+
+      module_function
+
+      def check!(interpreter)
+        version = checked[interpreter] ||= Open3.capture2(interpreter, '--version').first.strip
+        return if version[/\Av?(\d+)/, 1].to_i >= MINIMUM_MAJOR
+
+        raise TestingError, "Mocking a Node transform's requests needs Node #{MINIMUM_MAJOR} or newer, " \
+                            "whose fetch honors HTTPS_PROXY; #{interpreter} is #{version}"
+      end
+
+      def checked = @checked ||= {}
+    end
+  end
+end

data/lib/trmnlp/testing/plugin.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'time'
+
+require_relative 'device_models'
+require_relative 'report'
+require_relative 'run'
+require_relative 'screen'
+
+module TRMNLP
+  module Testing
+    # What a test calls as `trmnl`: the plugin in the current directory, rendered or transformed with the test's
+    # inputs. Every input is optional: now:, custom_fields:, variables:, state:, previous_merge_variables:,
+    # data: (skips polling), mocks:, transform: false.
+    class Plugin
+      # Records what goes wrong on the page, for Screen#problems; it runs before anything else in it.
+      PROBLEMS_SCRIPT = <<~JS.gsub(/\s+/, ' ').strip
+        (() => {
+          const problems = window.__trmnlpProblems = [];
+          window.addEventListener('error', (event) => {
+            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})` : ''}`);
+          }, true);
+          window.addEventListener('unhandledrejection', (event) =>
+            problems.push(`unhandled rejection: ${(event.reason && event.reason.message) || event.reason}`));
+          const consoleError = console.error;
+          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; })();'
+
+      def initialize(dir, browser:, authority:)
+        @dir = dir
+        @browser = browser
+        @authority = authority
+      end
+
+      # The plugin in another folder, rendered in the same browser: a built copy, say.
+      def plugin(dir) = self.class.new(File.expand_path(dir), browser: @browser, authority: @authority)
+
+      def transform(device: 'og_plus', orientation: :landscape, now: nil, **)
+        device = DeviceModels.find(device, orientation:)
+        run(now, **).transform(device: device.render_params).tap { Report.current&.record_run(it) }
+      end
+
+      # A render also takes head: (markup for the page's <head>, before the Framework loads), wait_for: (a
+      # JavaScript expression the page must reach before it is captured) and wait_for_timeout: (seconds).
+      # rubocop:disable-next Metrics/ParameterLists -- one keyword per choice a render offers
+      def render(view: 'full', device: 'og_plus', orientation: :landscape, palette: nil, dark_mode: false, theme: nil,
+                 now: nil, head: nil, wait_for: nil, wait_for_timeout: 5, fresh_browser: false, **)
+        device = DeviceModels.find(device, orientation:, palette:)
+        classes = [device.screen_classes, ('screen--dark-mode' if dark_mode)].compact.join(' ')
+        result = run(now, **).render(view:, device: device.render_params, screen_classes: classes, theme:)
+        html = with_problems_trap(with_head(with_page_clock(result.html, now), head))
+        browser = fresh_browser ? @browser.fresh : @browser
+        Report.current&.record_run(result)
+        Screen.new(html:, device:, view:, browser:, result:, wait_for:, wait_for_timeout:)
+              .tap { Report.current&.record_screen(it) }
+      end
+
+      private
+
+      def run(now, **) = Run.new(plugin: @dir, authority: @authority, now: time(now), **)
+
+      def time(value)
+        case value
+        when nil then nil
+        when Time then value.utc
+        when Date then value.to_time.utc
+        else Time.iso8601(value.to_s).utc
+        end
+      end
+
+      def with_problems_trap(html) = html.sub(/<head>/i) { "<head><script>#{PROBLEMS_SCRIPT}</script>" }
+
+      def with_head(html, head) = head ? html.sub(%r{</head>}i) { "#{head}</head>" } : html
+
+      # Scripts in the markup see the test's time too; the page's clock then runs on from it.
+      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>" }
+      end
+    end
+  end
+end

data/lib/trmnlp/testing/report.html.erb

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>trmnlp test report</title>
+<style>
+  :root { --ink: #1d1d1f; --muted: #6e6e73; --line: #d2d2d7; --pass: #1a7f37; --fail: #cf222e; --pending: #9a6700; --box: #0969da; }
+  body { font: 14px/1.5 system-ui, sans-serif; color: var(--ink); margin: 0 auto; padding: 24px 16px; max-width: 1400px; }
+  header { display: flex; flex-wrap: wrap; gap: 16px; align-items: baseline; border-bottom: 1px solid var(--line); padding-bottom: 12px; }
+  h1 { font-size: 20px; margin: 0; }
+  .counts span { margin-right: 12px; }
+  .passed { color: var(--pass); } .failed { color: var(--fail); } .pending { color: var(--pending); }
+  label { color: var(--muted); cursor: pointer; }
+  label::before { content: '☐ '; }
+  #outlines:checked ~ header label[for=outlines]::before, #failures:checked ~ header label[for=failures]::before { content: '☑ '; }
+  section { border-bottom: 1px solid var(--line); padding: 16px 0; }
+  section h2 { font-size: 15px; margin: 0 0 4px; }
+  .location, .run { color: var(--muted); font-size: 12px; }
+  pre { background: #f6f8fa; padding: 8px; overflow-x: auto; white-space: pre-wrap; }
+  .screens { display: flex; flex-wrap: wrap; gap: 16px; margin-top: 8px; }
+  figure { margin: 0; max-width: 100%; }
+  .frame { position: relative; border: 1px solid var(--line); max-width: min(100%, 640px); }
+  .frame img, .frame svg { display: block; width: 100%; height: auto; }
+  .frame svg { position: absolute; inset: 0; display: none; }
+  #outlines:checked ~ main .frame svg { display: block; }
+  #failures:checked ~ main section:not(.failed-example) { display: none; }
+  rect { fill: none; stroke: var(--box); stroke-width: 1; vector-effect: non-scaling-stroke; }
+  figcaption { color: var(--muted); font-size: 12px; margin-top: 4px; }
+  .problems { color: var(--fail); font-size: 12px; margin: 4px 0 0; padding-left: 16px; }
+  table { border-collapse: collapse; font-size: 12px; margin-top: 4px; }
+  td { border-top: 1px solid var(--line); padding: 2px 8px 2px 0; }
+</style>
+</head>
+<body>
+<input type="checkbox" id="outlines" hidden>
+<input type="checkbox" id="failures" hidden>
+<header>
+  <h1>trmnlp test</h1>
+  <div class="counts">
+    <span class="passed"><%= count('passed') %> passed</span>
+    <span class="failed"><%= count('failed') %> failed</span>
+    <span class="pending"><%= count('pending') %> pending</span>
+    <span><%= examples.sum { it[:screens].size } %> screens</span>
+  </div>
+  <label for="outlines">outline every drawn box</label>
+  <label for="failures">failures only</label>
+</header>
+<main>
+<% examples.each do |example| %>
+  <section class="<%= 'failed-example' if example[:status] == 'failed' %>">
+    <h2 class="<%= example[:status] %>"><%= h(example[:description]) %></h2>
+    <div class="location"><%= h(example[:location]) %> · <%= example[:status] %></div>
+    <% if example[:message] %><pre><%= h(example[:message]) %></pre><% end %>
+    <% example[:runs].each do |run| %>
+      <div class="run">transform: <%= run[:duration_ms] %> ms, <%= run[:max_memory_mb] || '?' %> MB<%= ", error: #{h(run[:error])}" if run[:error] %></div>
+      <% if run[:requests].any? %>
+        <table><% run[:requests].each do |request| %>
+          <tr><td><%= request[:via] %></td><td><%= request[:method] %></td><td><%= h(request[:url]) %></td><td><%= request[:status] %><%= ' aborted' if request[:aborted] %></td></tr>
+        <% end %></table>
+      <% end %>
+    <% end %>
+    <div class="screens">
+    <% example[:screens].each do |screen| %>
+      <figure>
+        <div class="frame">
+          <img src="<%= screen[:image] %>" alt="<%= h(screen[:label]) %>" width="<%= screen[:width] %>" height="<%= screen[:height] %>">
+          <svg viewBox="0 0 <%= screen[:width] %> <%= screen[:height] %>"><% screen[:outlines].each do |box| %><rect x="<%= box['x'] %>" y="<%= box['y'] %>" width="<%= box['w'] %>" height="<%= box['h'] %>"><title><%= h("#{box['tag']}.#{box['class']}") %></title></rect><% end %></svg>
+        </div>
+        <figcaption><%= h(screen[:label]) %></figcaption>
+        <% if screen[:problems].any? %><ul class="problems"><% screen[:problems].each do |problem| %><li><%= h(problem) %></li><% end %></ul><% end %>
+      </figure>
+    <% end %>
+    </div>
+  </section>
+<% end %>
+</main>
+</body>
+</html>

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