test: add Vitest unit tests and Playwright e2e smoke test

Two complementary layers:

Vitest covers the pure JS paths that don't need wasm:
- Utils.string2Uint8Data, fetchRemoteData, fetchRemoteDataBlob
  (fetch is stubbed via vi.fn so no network is touched)
- ARFset constructor (option handling, defaults, initial fields,
  version banner) with the wasm wrapper mocked out so importing
  src/ARFset.js stays cheap

Playwright drives a real Chromium against example_es6.html, waits
for the canvas to be populated by display(), and asserts the canvas
has non-empty pixel content. This exercises the full wasm -> JS ->
canvas path end to end.

Scripts:
  npm test                 -> vitest run
  npm run test:watch       -> vitest in watch mode
  npm run test:e2e:install -> playwright install --with-deps chromium
                              (one-shot per machine)
  npm run test:e2e         -> playwright test

devDependencies added: vitest, @playwright/test, http-server
(needed for Playwright's webServer block).

Refs #28
Refs #31

Author: claude

package.json

@@ -31,14 +31,21 @@
     "url": "https://github.com/webarkit/FeatureSET-Display/issues"
   },
   "devDependencies": {
-    "vite": "^8.0.16"
+    "@playwright/test": "^1.50.0",
+    "http-server": "^14.1.1",
+    "vite": "^8.0.16",
+    "vitest": "^2.1.0"
   },
   "scripts": {
     "build": "node tools/makem.cjs",
     "build-no-libar": "node tools/makem.cjs --no-libar",
     "dev-es6": "vite build --watch",
     "build-es6": "vite build",
-    "serve": "npx http-server -c -1"
+    "serve": "npx http-server -c -1",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "test:e2e:install": "playwright install --with-deps chromium"
   },
   "license": "LGPL-3.0"
 }

playwright.config.js

@@ -0,0 +1,23 @@
+import { defineConfig, devices } from '@playwright/test';
+
+// Runs against the built artifacts in dist/ and build/. CI sequences
+// `npm run build && npm run build-es6 && npm run test:e2e`. Locally
+// the same applies.
+export default defineConfig({
+  testDir: 'tests/e2e',
+  fullyParallel: false,
+  reporter: 'list',
+  use: {
+    baseURL: 'http://127.0.0.1:8765',
+    trace: 'retain-on-failure',
+  },
+  webServer: {
+    command: 'npx http-server -c-1 -p 8765 --silent',
+    url: 'http://127.0.0.1:8765',
+    reuseExistingServer: !process.env.CI,
+    timeout: 30_000,
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+});

tests/e2e/marker-load.spec.js

@@ -0,0 +1,48 @@
+import { test, expect } from '@playwright/test';
+
+// End-to-end smoke test: load example_es6.html, wait for the wasm
+// runtime to fetch + decode the pinball marker, then verify the
+// canvas has actually been painted (non-empty pixel data).
+test('example_es6.html loads the pinball marker and renders the canvas', async ({ page }) => {
+  const consoleErrors = [];
+  page.on('pageerror', (err) => consoleErrors.push(err.message));
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text());
+  });
+
+  await page.goto('/example/example_es6.html');
+
+  // ARFset.display() inserts <canvas id="iSet"> and dispatches 'imageEv'
+  // once the marker has been drawn. Wait for the canvas to appear and
+  // for the event to fire.
+  const canvas = page.locator('#iSet');
+  await canvas.waitFor({ state: 'attached', timeout: 30_000 });
+
+  await page.waitForFunction(() => {
+    return new Promise((resolve) => {
+      // imageEv may have already fired between locator wait and here.
+      const c = document.getElementById('iSet');
+      if (c && c.width > 0 && c.height > 0) return resolve(true);
+      document.addEventListener('imageEv', () => resolve(true), { once: true });
+    });
+  }, undefined, { timeout: 30_000 });
+
+  const dimensions = await canvas.evaluate((el) => ({ w: el.width, h: el.height }));
+  expect(dimensions.w).toBeGreaterThan(0);
+  expect(dimensions.h).toBeGreaterThan(0);
+
+  // Sample a few pixels: at least one must be non-black, confirming the
+  // marker image was actually painted (not just a blank canvas).
+  const hasContent = await canvas.evaluate((el) => {
+    const ctx = el.getContext('2d');
+    const data = ctx.getImageData(0, 0, el.width, el.height).data;
+    // step coarsely to keep this fast for big markers
+    for (let i = 0; i < data.length; i += 4 * 100) {
+      if (data[i] > 0 || data[i + 1] > 0 || data[i + 2] > 0) return true;
+    }
+    return false;
+  });
+  expect(hasContent).toBe(true);
+
+  expect(consoleErrors, `unexpected errors: ${consoleErrors.join(' | ')}`).toEqual([]);
+});

tests/unit/arfset.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Stub the emscripten wasm wrapper so importing ARFset doesn't try to
+// instantiate wasm in Node. The factory is only invoked from
+// ARFset.initialize(), which these tests deliberately avoid calling.
+vi.mock('../../build/arfset_ES6_wasm.js', () => ({
+  default: vi.fn(),
+}));
+
+const { default: ARFset } = await import('../../src/ARFset.js');
+
+describe('ARFset constructor', () => {
+  beforeEach(() => {
+    // Quiet the version banner the constructor logs.
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  it('uses the documented defaults when no options are passed', () => {
+    const ar = new ARFset();
+    expect(ar.width).toBe(893);
+    expect(ar.height).toBe(1117);
+  });
+
+  it('applies width and height from options', () => {
+    const ar = new ARFset({ width: 640, height: 480 });
+    expect(ar.width).toBe(640);
+    expect(ar.height).toBe(480);
+  });
+
+  it('uses defaults for any option that is omitted', () => {
+    expect(new ARFset({ width: 100 }).height).toBe(1117);
+    expect(new ARFset({ height: 100 }).width).toBe(893);
+  });
+
+  it('initialises bookkeeping counters to zero', () => {
+    const ar = new ARFset();
+    expect(ar.id).toBe(0);
+    expect(ar.nftMarkerCount).toBe(0);
+    expect(ar.numIset).toBe(0);
+  });
+
+  it('exposes the library version string', () => {
+    expect(new ARFset().version).toMatch(/^\d+\.\d+\.\d+$/);
+  });
+});

tests/unit/utils.test.js

@@ -0,0 +1,78 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import Utils from '../../src/Utils.js';
+
+describe('Utils.string2Uint8Data', () => {
+  it('encodes ASCII chars as their code points', () => {
+    const out = Utils.string2Uint8Data('abc');
+    expect(out).toBeInstanceOf(Uint8Array);
+    expect(Array.from(out)).toEqual([0x61, 0x62, 0x63]);
+  });
+
+  it('truncates non-ASCII chars to their low byte', () => {
+    // '€' is U+20AC; low byte is 0xAC.
+    const out = Utils.string2Uint8Data('a€');
+    expect(out.length).toBe(2);
+    expect(out[1]).toBe(0xAC);
+  });
+
+  it('returns an empty array for the empty string', () => {
+    expect(Utils.string2Uint8Data('').length).toBe(0);
+  });
+});
+
+describe('Utils.fetchRemoteData', () => {
+  let fetchMock;
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    globalThis.fetch = fetchMock;
+  });
+
+  afterEach(() => {
+    delete globalThis.fetch;
+  });
+
+  it('returns a Uint8Array for a 200 response', async () => {
+    fetchMock.mockResolvedValue({
+      ok: true,
+      arrayBuffer: () => Promise.resolve(new Uint8Array([1, 2, 3]).buffer),
+    });
+    const out = await Utils.fetchRemoteData('https://example/test');
+    expect(out).toBeInstanceOf(Uint8Array);
+    expect(Array.from(out)).toEqual([1, 2, 3]);
+    expect(fetchMock).toHaveBeenCalledWith('https://example/test');
+  });
+
+  it('throws on non-ok response with status info', async () => {
+    fetchMock.mockResolvedValue({
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+    });
+    await expect(Utils.fetchRemoteData('https://example/missing')).rejects.toThrow(/404/);
+  });
+});
+
+describe('Utils.fetchRemoteDataBlob', () => {
+  it('treats a multi-line string as inline data, not a URL', async () => {
+    const fetchSpy = vi.fn();
+    globalThis.fetch = fetchSpy;
+    const out = await Utils.fetchRemoteDataBlob('line one\nline two');
+    expect(out).toBeInstanceOf(Uint8Array);
+    expect(out.length).toBe('line one\nline two'.length);
+    expect(fetchSpy).not.toHaveBeenCalled();
+    delete globalThis.fetch;
+  });
+
+  it('falls through to fetch for a single-line URL', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue({
+      ok: true,
+      arrayBuffer: () => Promise.resolve(new Uint8Array([9]).buffer),
+    });
+    globalThis.fetch = fetchSpy;
+    const out = await Utils.fetchRemoteDataBlob('https://example/blob');
+    expect(out[0]).toBe(9);
+    expect(fetchSpy).toHaveBeenCalledWith('https://example/blob');
+    delete globalThis.fetch;
+  });
+});