@sealpixel/plugin-testing 1.0.0-rc.0

package/README.md

@@ -0,0 +1,3 @@
+# @sealpixel/plugin-testing
+
+`checkPluginParity` pins render hashes in a goldens file; `fuzzPlugin` checks reducer totality, idempotent rendering and `upTo` consistency. Used by `create-sealpixel-plugin` scaffolds.

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { type AnyPlugin, type AssetResolver, type Operation, type RenderOptions } from '@sealpixel/core';
+import fc from 'fast-check';
+export interface PluginParityCase {
+    id: string;
+    /** Source image bytes (PNG, JPEG or WebP). */
+    image: Uint8Array;
+    /** Ops for the plugin under test (and any first-party ops). */
+    ops: Operation[];
+    output?: RenderOptions['output'];
+}
+export interface PluginParityOptions {
+    plugin: AnyPlugin | AnyPlugin[];
+    cases: PluginParityCase[];
+    /** Path of the JSON file holding `{ [id]: hash }`. Created on first run. */
+    goldens: string;
+    /** Additional plugins available to the cases. Defaults to the first-party set. */
+    basePlugins?: readonly AnyPlugin[];
+    assets?: AssetResolver;
+    /** Set to true (or `SEALPIXEL_UPDATE_GOLDENS=1`) to rewrite the goldens file. */
+    update?: boolean;
+}
+export interface PluginParityResult {
+    id: string;
+    hash: string;
+    expected: string | null;
+    ok: boolean;
+}
+/** Renders every case and compares with the goldens file. Returns all results; throws when one differs and `update` is off. */
+export declare function checkPluginParity(options: PluginParityOptions): Promise<PluginParityResult[]>;
+export interface FuzzPluginOptions {
+    plugin: AnyPlugin;
+    /** Generates valid ops for the plugin. */
+    ops: fc.Arbitrary<Operation>;
+    image: Uint8Array;
+    basePlugins?: readonly AnyPlugin[];
+    assets?: AssetResolver;
+    runs?: number;
+    maxOps?: number;
+}
+/**
+ * Properties: parse round-trip, reducer totality, render never throws, render
+ * is idempotent, `upTo` equals the sliced log.
+ */
+export declare function fuzzPlugin(options: FuzzPluginOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAIlB,KAAK,SAAS,EACd,KAAK,aAAa,EAEnB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,KAAK,EAAE,UAAU,CAAC;IAClB,+DAA+D;IAC/D,GAAG,EAAE,SAAS,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAChC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,WAAW,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACnC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,+HAA+H;AAC/H,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAsC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,SAAS,CAAC;IAClB,0CAA0C;IAC1C,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACnC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgC1E"}

package/dist/index.js

@@ -0,0 +1,84 @@
+/**
+ * Helpers for plugin authors. `describePluginParity` renders cases through
+ * `render()` and pins their hashes in a goldens file, so a kernel change is a
+ * visible diff and Node/browser/server outputs can be cross-checked.
+ * `fuzzPlugin` checks the reducer is total and rendering never throws.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { createEditLog, createRegistry, render, } from '@sealpixel/core';
+import { defaultPlugins } from '@sealpixel/plugins';
+import { loadSealpixelWasm } from '@sealpixel/wasm';
+import fc from 'fast-check';
+/** Renders every case and compares with the goldens file. Returns all results; throws when one differs and `update` is off. */
+export async function checkPluginParity(options) {
+    const plugins = Array.isArray(options.plugin) ? options.plugin : [options.plugin];
+    const registry = createRegistry([...(options.basePlugins ?? defaultPlugins), ...plugins]);
+    const wasm = await loadSealpixelWasm();
+    const update = options.update ?? process.env['SEALPIXEL_UPDATE_GOLDENS'] !== undefined;
+    const stored = existsSync(options.goldens)
+        ? JSON.parse(readFileSync(options.goldens, 'utf8'))
+        : {};
+    const results = [];
+    for (const c of options.cases) {
+        const decoded = wasm.decode(c.image);
+        const log = {
+            ...createEditLog({ id: c.id, width: decoded.width, height: decoded.height }, registry),
+            ops: c.ops,
+        };
+        const out = await render(c.image, log, {
+            output: c.output ?? { format: 'image/png' },
+            registry,
+            wasm,
+            ...(options.assets ? { assets: options.assets } : {}),
+        });
+        const expected = stored[c.id] ?? null;
+        results.push({ id: c.id, hash: out.hash, expected, ok: expected === out.hash });
+        if (update)
+            stored[c.id] = out.hash;
+    }
+    if (update) {
+        const next = `${JSON.stringify(stored, null, 2)}\n`;
+        if (!existsSync(options.goldens) || readFileSync(options.goldens, 'utf8') !== next)
+            writeFileSync(options.goldens, next);
+        return results.map((r) => ({ ...r, expected: r.hash, ok: true }));
+    }
+    const failures = results.filter((r) => !r.ok);
+    if (failures.length > 0) {
+        throw new Error(`plugin parity: ${failures.length} case(s) differ:\n${failures.map((f) => `  ${f.id}: expected ${f.expected ?? '(missing, run with SEALPIXEL_UPDATE_GOLDENS=1)'} got ${f.hash}`).join('\n')}`);
+    }
+    return results;
+}
+/**
+ * Properties: parse round-trip, reducer totality, render never throws, render
+ * is idempotent, `upTo` equals the sliced log.
+ */
+export async function fuzzPlugin(options) {
+    const registry = createRegistry([...(options.basePlugins ?? defaultPlugins), options.plugin]);
+    const wasm = await loadSealpixelWasm();
+    const decoded = wasm.decode(options.image);
+    const source = { id: 'fuzz', width: decoded.width, height: decoded.height };
+    const logs = fc
+        .uniqueArray(options.ops, { maxLength: options.maxOps ?? 6, selector: (op) => op.id })
+        .map((ops) => ({ ...createEditLog(source, registry), ops }));
+    const renderOptions = {
+        output: { format: 'image/png' },
+        registry,
+        wasm,
+        ...(options.assets ? { assets: options.assets } : {}),
+    };
+    await fc.assert(fc.asyncProperty(logs, async (log) => {
+        const parsed = registry.parseEditLog(JSON.parse(JSON.stringify(log)));
+        if (parsed.ops.length !== log.ops.length)
+            throw new Error('round trip changed the op count');
+        const a = await render(options.image, log, renderOptions);
+        const b = await render(options.image, log, renderOptions);
+        if (a.hash !== b.hash)
+            throw new Error('render is not idempotent');
+        const i = Math.floor(log.ops.length / 2);
+        const sliced = await render(options.image, { ...log, ops: log.ops.slice(0, i) }, renderOptions);
+        const upTo = await render(options.image, log, { ...renderOptions, upTo: i });
+        if (sliced.hash !== upTo.hash)
+            throw new Error('upTo differs from the sliced log');
+    }), { numRuns: options.runs ?? Number(process.env['FUZZ_RUNS'] ?? 25) });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@sealpixel/plugin-testing",
+  "version": "1.0.0-rc.0",
+  "description": "Test helpers for Sealpixel plugin authors: pinned render goldens (checkPluginParity) and property-based fuzzing (fuzzPlugin).",
+  "license": "BUSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/9feet/sealpixel.git",
+    "directory": "packages/plugin-testing"
+  },
+  "homepage": "https://docs.sealpixel.dev",
+  "bugs": "https://github.com/9feet/sealpixel/issues",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@sealpixel/core": "workspace:*",
+    "@sealpixel/plugins": "workspace:*",
+    "@sealpixel/wasm": "workspace:*",
+    "fast-check": "^4.0.0"
+  },
+  "devDependencies": {
+    "@sealpixel/config": "workspace:*",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}