trmnlp-test 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cfefb51546891c33222e11f7c2ba094168787d9207966a1addbc307462290fd2
+  data.tar.gz: 4323d3400e827f4d88913f1d624ccf7d64bd65e0f15428add123b8c3af01e782
+SHA512:
+  metadata.gz: 2b4b67e735b844dc2510eac564e98a825217516709ef67fd68e78294ffddb40bdc99075045e1390b09dde904e3bc2311b8974ffa1d70bf230f4ab6d36b1996a1
+  data.tar.gz: 6b590003ac56c97e22392b85376d3fcce7bb22d172e25636a02489ac9a0304b8c3d6ed83c7c8b9f5e8a06b2598379607b872e4bdf82085827686f617a78f9a67

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ExcuseMi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# trmnlp-test
+
+Test framework for TRMNL plugins in the trmnlp format (`src/*.liquid`, `settings.yml`, `.trmnlp.yml`), in Docker.
+
+- **Every data path:** webhook (`deep_merge`, `stream`, 2 kB / 5 kB limits), webhook + serverless (the transform runs when data arrives and its output is stored), polling (URLs, headers and body rendered with custom fields; JSON/XML), static, serverless transforms in Python, Ruby, Node and PHP, and `trmnl_state` carried between runs.
+- **Same code as trmnlp:** trmnlp's own Liquid environment, settings parsing, polling parser and serverless wrapper. The image is rebuilt on every new trmnlp release (`:latest`, `:trmnlp-X.Y.Z`) once the self-tests pass on it.
+- **Every device and setting:** every model from `/api/models`, their palettes from `/api/palettes`, portrait, real mashup slots, dark mode, themes, scale, text scale, fonts, and every framework version.
+- **Deterministic:** frozen clock (transform via libfaketime, Liquid `now`, browser `Date`); HTTP(S) mocks for transforms (a MITM proxy, so they work with any library) and for polling and browser requests; cached framework assets and fonts.
+- **Assertions on HTML or PNG:** Playwright locators on the rendered page, plus a picture reduced to the device palette for pixel checks, QR decoding, snapshots and the device image size limit.
+- **Report:** a gallery `index.html` with every device picture, transform time and memory, and problems found, linked to the Playwright HTML report.
+
+## Install
+
+```sh
+gem install trmnlp-test        # needs Ruby and Docker; runs ghcr.io/excusemi/trmnlp-test
+```
+
+## Use
+
+```sh
+cd my-plugin
+trmnlp-test init               # trmnlp-test.config.js + test/trmnl/plugin.spec.js
+trmnlp-test                    # run; Playwright args pass through (-g, --update-snapshots)
+trmnlp-test models | versions  # device models / framework versions
+trmnlp-test update             # pull the image now (otherwise at most once a day)
+```
+
+`--repo DIR` runs against another directory. `--mount DIR` mounts an extra directory.
+
+**Parallel:** tests run in parallel workers, each with its own harness and browser (default: half the CPUs). Set the number with `workers: 4` (or `'50%'`) in the config, `TRMNLP_TEST_WORKERS=4`, or `--workers 4` / `-j 4`, in increasing priority. Separate runs can also go at the same time, for other plugins or the same one: the shared cache is safe for concurrent use. Give each run of the same repo its own `--report DIR`. The cache (assets, dependencies, mock CA) is kept in `~/.cache/trmnlp-test`.
+
+From a clone, `bin/trmnlp-test` builds the image from source on the newest trmnlp (`TRMNLP_TEST_BUILD=1` rebuilds it; `TRMNLP_VERSION=x.y.z` picks another).
+
+## Release
+
+Pushing to `main`, and a daily check for a new trmnlp release, publish the image as `:latest` and `:trmnlp-X.Y.Z`. Pushing a tag `vX.Y.Z` (matching `lib/trmnlp_test/version.rb`) runs the self-tests, publishes `:X.Y.Z` and pushes the gem through rubygems.org trusted publishing (no stored key).
+
+## Config: `trmnlp-test.config.js`
+
+See [templates/trmnlp-test.config.js](templates/trmnlp-test.config.js). Transform dependencies:
+
+```js
+serverless: { dependencies: { python: ['icalendar==6.1.0'], ruby: 'Gemfile', node: ['date-fns@4'], php: ['nesbot/carbon:^3'] } }
+```
+
+`requests` (Python) and `httparty` (Ruby) are always installed, as on the hosted runtime. Each distinct list is installed once.
+
+## Tests
+
+```js
+const { test, expect, matrix, VIEWS, DEVICES, FRAMEWORK } = require('trmnlp-test');
+
+test('menu', async ({ trmnl }) => {
+  const screen = await trmnl.render({
+    device: 'og_plus', view: 'full',          // any model, orientation: 'portrait', palette, darkMode, theme, scale, textScale, fonts, framework
+    fields: { data_source: 'webhook' },       // custom field values (defaults + .trmnlp.yml + these)
+    webhook: { merge_variables: {...} },      // or data: {...} to render given data as is
+    mocks: { 'https://api.example.com/*': { temp: 21 } },
+    transform: true,                          // false: skip the transform
+    now: '2026-10-02T08:00:00Z',
+  });
+  expect(screen).toRenderCleanly();                         // Liquid, transform, page JS, assets, unmocked requests, screen size
+  await expect(screen.locator('[data-row]')).toHaveCount(7); // any Playwright locator assertion
+  await expect(screen).toHaveNoOverflow();
+  await expect(screen).toHaveNoOverlap('.title', 'img');
+  await expect(screen).toHaveQr('BCD\n002...');
+  await expect(screen).toMatchScreen();                     // PNG snapshot (--update-snapshots)
+  await expect(screen).toFitDeviceImageLimit();
+  const png = await screen.png();                           // pixel(x,y), colors(), inkRatio(rect), inkBounds(), crop()
+});
+
+test('transform only', async ({ trmnl }) => {
+  const run = await trmnl.transform({ mocks, fields });
+  expect(run).toTransformCleanly();
+  expect(run).toStayWithinServerlessLimits();               // 5 s, 128 MB
+  expect(run).toHaveRequested('https://api.example.com/x', { headers: { 'x-key': 'abc' } });
+  expect(run.output).toMatchObject({ ... });
+});
+
+test('a device over time', async ({ trmnl }) => {
+  const s = trmnl.session({ mocks });
+  await s.webhook({ merge_variables: {...}, merge_strategy: 'deep_merge' });
+  const screen = await s.render();                          // stored webhook data + trmnl_state from the last run
+});
+
+for (const s of matrix({ device: DEVICES.representative, view: VIEWS, darkMode: [false, true] })) {
+  test(`fits · ${s.label}`, async ({ trmnl }) => { /* trmnl.render(s) */ });
+}
+```
+
+Other helpers: `trmnl.plugin('other/dir')`, `trmnl.lint()` with `toPassLint({ allow })`, `FRAMEWORK.majors()`, `FRAMEWORK.latestOf('2')`.
+
+## How it works
+
+See [docs/README.md](docs/README.md) for diagrams of the components, a render, sessions and the file structure.
+
+## Examples and self-tests
+
+- `examples/payment-qr`: the payment QR plugin, current Liquid version and the earlier webhook + serverless version (53 tests).
+- `test/self`: fixture plugins for every strategy and language (86 tests). Run with `bin/trmnlp-test run --root test/self`.

data/exe/trmnlp-test

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Runs trmnlp-test (a Docker image) against a TRMNL plugin repository.
+#   trmnlp-test [--repo DIR] [--mount DIR]... [run|init|models|versions|refresh|update|shell|version] [playwright args]
+require 'etc'
+require 'fileutils'
+require_relative '../lib/trmnlp_test/version'
+
+# :latest follows the newest trmnlp release; TRMNLP_TEST_IMAGE pins one (e.g. ...:trmnlp-0.13.1)
+image = ENV.fetch('TRMNLP_TEST_IMAGE', "#{TrmnlpTest::IMAGE}:latest")
+repo = Dir.pwd
+mounts = []
+args = ARGV.dup
+while %w[--repo --mount].include?(args.first)
+  flag, dir = args.shift(2)
+  abort "trmnlp-test: #{flag} needs a directory" unless dir
+  path = File.realpath(dir)
+  flag == '--repo' ? repo = path : mounts += ['-v', "#{path}:#{path}"]
+end
+
+case args.first
+when 'version'
+  puts "trmnlp-test #{TrmnlpTest::VERSION} (#{image})"
+  exit
+when 'update'
+  exec 'docker', 'pull', image
+end
+
+abort 'trmnlp-test needs Docker: https://docs.docker.com/get-docker/' unless system('docker info', out: File::NULL, err: File::NULL)
+
+cache = ENV.fetch('TRMNLP_TEST_CACHE_DIR', File.join(Dir.home, '.cache', 'trmnlp-test'))
+FileUtils.mkdir_p(cache)
+
+# a missing image is pulled; a :latest image is refreshed at most once a day
+present = system('docker', 'image', 'inspect', image, out: File::NULL, err: File::NULL)
+stamp = File.join(cache, '.pulled-' + image.gsub(/[^A-Za-z0-9.]+/, '_'))
+stale = image.end_with?(':latest') && (!File.exist?(stamp) || Time.now - File.mtime(stamp) > 86_400)
+if !present || (stale && !ENV['TRMNLP_TEST_NO_PULL'])
+  warn "trmnlp-test: pulling #{image}"
+  pulled = system('docker', 'pull', '-q', image, out: File::NULL)
+  abort("trmnlp-test: could not pull #{image}") if !pulled && !present
+  FileUtils.touch(stamp) if pulled
+end
+entry = []
+if args.first == 'shell'
+  args.shift
+  entry = ['--entrypoint', 'bash']
+end
+tty = $stdout.tty? ? ['-t'] : []
+env = %w[CI TRMNLP_TEST_DEBUG TRMNLP_TEST_WORKERS FORCE_COLOR].flat_map { |k| ['-e', k] }
+exec 'docker', 'run', '--rm', '-i', *tty, '--init', '--ipc=host', '-u', "#{Process.uid}:#{Process.gid}",
+     '-v', "#{repo}:#{repo}", '-w', repo, '-v', "#{cache}:/cache", *mounts, *env, *entry, image, *args

data/lib/trmnlp_test/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module TrmnlpTest
+  VERSION = '0.1.2'
+  IMAGE = 'ghcr.io/excusemi/trmnlp-test'
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: trmnlp-test
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- ExcuseMi
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Runs Playwright tests against TRMNL plugins in the trmnlp format: webhook,
+  polling, static and serverless transforms (Python, Ruby, Node, PHP) with mocked
+  HTTP and a frozen clock, on every TRMNL device model and framework version. The
+  launcher runs the ghcr.io/excusemi/trmnlp-test Docker image.'
+executables:
+- trmnlp-test
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/trmnlp-test
+- lib/trmnlp_test/version.rb
+homepage: https://github.com/ExcuseMi/trmnlp-test
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ExcuseMi/trmnlp-test
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Test framework for TRMNL plugins (trmnlp projects, serverless, webhooks,
+  every device)
+test_files: []