@vesk/testing 0.2.50-canary.4

package/dist/harness.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=harness.test.d.ts.map

package/dist/harness.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.test.d.ts","sourceRoot":"","sources":["../src/harness.test.ts"],"names":[],"mappings":""}

package/dist/harness.test.js

@@ -0,0 +1,145 @@
+/**
+ * The testing harness, tested with the harness.
+ *
+ * A test helper that is wrong is worse than none: it produces confident green
+ * runs. So the SSR render, the DOM mount and every assertion helper are
+ * exercised here, including the failure messages.
+ *
+ * Run with: npx tsx packages/testing/src/harness.test.ts
+ */
+import { attrOf, mount, renderComponent } from '@vesk/testing';
+let passed = 0;
+let failed = 0;
+const failures = [];
+function assert(cond, msg) {
+    if (!cond)
+        throw new Error(msg);
+}
+let chain = Promise.resolve();
+function it(name, fn) {
+    chain = chain.then(async () => {
+        try {
+            await fn();
+            passed++;
+            console.log(`  ✓ ${name}`);
+        }
+        catch (e) {
+            failed++;
+            console.log(`  ✗ ${name}`);
+            console.log(`    ${e.message}`);
+            failures.push({ name, message: e.message });
+        }
+    });
+}
+const COUNTER = `component Counter(props: { start: number }) {
+	const &[count, setCount] = track(props.start)
+	const doubled = derived(() => get(count) * 2)
+	<Head><title>Counter: {count}</title></Head>
+	<div class="wrap">
+		<p class="label">{count}</p>
+		<button class="bump" onclick={() => setCount(count + 1)}>bump</button>
+		<slot name="after" />
+	</div>
+}`;
+console.log('\n=== @vesk/testing harness ===');
+it('renderComponent SSRs a component and returns its head', () => {
+    const r = renderComponent(COUNTER, 'Counter', { start: 1 });
+    assert(r.html.includes('class="label"'), `no markup rendered: ${r.html.slice(0, 120)}`);
+    assert(r.html.includes('>1<'), `props did not reach the render: ${r.html.slice(0, 200)}`);
+    assert(r.head.includes('<title'), `the <Head> block was not serialized: ${r.head}`);
+    assert(r.props.start === 1, 'props were not echoed back');
+});
+it('renderComponent can render the non-hydrate mode too', () => {
+    const r = renderComponent(COUNTER, 'Counter', { start: 2 }, { hydrate: false });
+    assert(r.html.includes('>2<'), 'the non-hydrate render is empty');
+});
+it('a compile error surfaces as a throw, not an empty string', () => {
+    let threw = false;
+    try {
+        renderComponent('component Broken( { <<<', 'Broken');
+    }
+    catch {
+        threw = true;
+    }
+    assert(threw, 'a source that cannot compile rendered as empty instead of failing the test');
+});
+it('mount puts the SSR output in a real DOM', () => {
+    const m = mount(COUNTER, 'Counter', { start: 3 });
+    try {
+        assert(m.text('.label') === '3', `label was ${JSON.stringify(m.text('.label'))}`);
+        assert(m.has('.bump'), 'the button is missing from the DOM');
+        assert(m.attr('.wrap', 'class') === 'wrap', `class attribute was ${m.attr('.wrap', 'class')}`);
+        assert(m.all('.label').length === 1, 'all() returned the wrong number of matches');
+        assert(m.text('.nope') === null, 'a missing selector should read null, not throw');
+        assert(m.has('.nope') === false, 'has() is wrong for a missing selector');
+    }
+    finally {
+        m.unmount();
+    }
+});
+it('click dispatches a real event the component can hear', async () => {
+    const m = mount(COUNTER, 'Counter', { start: 1 });
+    try {
+        await m.click('.bump');
+        // A click with no listener attached changes nothing — the point is that the
+        // event fires without throwing and the DOM is still readable.
+        assert(typeof m.text('.label') === 'string', 'the DOM became unreadable after a click');
+    }
+    finally {
+        m.unmount();
+    }
+});
+it('waitFor polls until the predicate holds and gives up with the HTML', async () => {
+    const m = mount(COUNTER, 'Counter', { start: 5 });
+    try {
+        let calls = 0;
+        await m.waitFor(() => ++calls >= 3, 1000);
+        assert(calls >= 3, 'waitFor returned before the predicate held');
+        let failed = false;
+        try {
+            await m.waitFor(() => false, 60);
+        }
+        catch (e) {
+            failed = e.message.includes('waitFor timed out');
+        }
+        assert(failed, 'waitFor did not time out on a predicate that never holds');
+    }
+    finally {
+        m.unmount();
+    }
+});
+it('mount installs and restores the ambient DOM', () => {
+    const before = globalThis.document;
+    const m = mount(COUNTER, 'Counter', { start: 1 });
+    assert(globalThis.document !== before, 'the DOM was not installed');
+    m.unmount();
+    assert(globalThis.document === before, 'the previous global was not restored');
+});
+it('a missing mount root fails loudly instead of returning an empty driver', () => {
+    // `mount` always provides a `#root`, so the only way to hit this is a custom
+    // selector that the output does not contain — and a test that then asserts
+    // against an empty DOM is a test that passes for the wrong reason.
+    let threw = false;
+    try {
+        mount('<p>no app root</p>', 'App', {}, { html: '<p>no app root</p>', rootSelector: '#app' });
+    }
+    catch (e) {
+        threw = e.message.includes('no #app');
+    }
+    assert(threw, 'mounting with a root selector the output lacks did not say so');
+});
+it('attrOf reads a head attribute out of a fragment', () => {
+    const html = renderComponent(COUNTER, 'Counter', { start: 9 }).html;
+    assert(attrOf(html, '.label', 'class') === 'label', 'attrOf could not find the element');
+    assert(attrOf(html, '.missing', 'class') === null, 'attrOf invented an attribute');
+});
+void chain.then(() => {
+    console.log(`\n${'='.repeat(50)}`);
+    console.log(`Results: ${passed} passed, ${failed} failed, ${passed + failed} total`);
+    if (failed > 0) {
+        for (const f of failures)
+            console.log(`  FAIL: ${f.name} — ${f.message}`);
+        process.exit(1);
+    }
+    console.log('All @vesk/testing harness tests passed!');
+});

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+/** One rendered component: its HTML plus the props it was rendered with. */
+export interface RenderedComponent {
+    /** The SSR body HTML (no `<html>` wrapper). */
+    html: string;
+    /** The `<head>` the component declared, if any. */
+    head: string;
+    /** The props the component actually saw, after any load() merge. */
+    props: Record<string, unknown>;
+}
+export interface RenderOptions {
+    /**
+     * Render as if hydrating. Hydrate mode is the default in a real app, and it
+     * changes the emitted markup (markerless SSR), so a test that renders the
+     * wrong mode is testing the wrong thing. Default: true.
+     */
+    hydrate?: boolean;
+    /** File name used in error messages and source paths. */
+    fileName?: string;
+}
+/**
+ * Compile and server-render a component from `.vsk` source.
+ *
+ * Throws with the compiler's own diagnostic (code frame and all) when the
+ * source does not compile — a test failure should read like a compile error,
+ * not like an empty string.
+ */
+export declare function renderComponent(source: string, componentName?: string, props?: Record<string, unknown>, options?: RenderOptions): RenderedComponent;
+/** A mounted component in a real DOM, with the assertions people keep writing. */
+export interface MountedComponent {
+    /** The document the component is mounted in. */
+    document: Document;
+    /** The element the component was mounted into. */
+    root: Element;
+    /** Current HTML of the mount root. */
+    html(): string;
+    /** `textContent` of the first match, trimmed; `null` when absent. */
+    text(selector: string): string | null;
+    /** Attribute of the first match, or `null`. */
+    attr(selector: string, name: string): string | null;
+    /** Does a match exist? */
+    has(selector: string): boolean;
+    /** All matches, for list assertions. */
+    all(selector: string): Element[];
+    /** Click the first match and flush effects. */
+    click(selector: string): Promise<MountedComponent>;
+    /** Set an input's value, dispatch `input`, and flush. */
+    input(selector: string, value: string): Promise<MountedComponent>;
+    /** Run pending microtasks and effects, then let the DOM settle. */
+    flush(): Promise<MountedComponent>;
+    /** Poll `fn` until it is truthy or the budget runs out. */
+    waitFor(fn: () => unknown, timeoutMs?: number): Promise<void>;
+}
+export interface MountOptions extends RenderOptions {
+    /** HTML to mount instead of rendering (e.g. to hydrate a prerendered page). */
+    html?: string;
+    /** Selector for the mount root inside the document. Default `#root`. */
+    rootSelector?: string;
+}
+/**
+ * Mount a component's SSR output into a real DOM and return a driver.
+ *
+ * The DOM is a linkedom document installed as the ambient `document` for the
+ * duration of the returned driver's lifetime — `restore()` puts the previous
+ * globals back, and `unmount()` also calls it.
+ */
+export declare function mount(source: string, componentName?: string, props?: Record<string, unknown>, options?: MountOptions): MountedComponent & {
+    unmount(): void;
+};
+/**
+ * Read a value out of an attribute, decoded the way a browser would.
+ * Small convenience for meta/link assertions (`content="a &amp; b"`).
+ */
+export declare function attrOf(html: string, selector: string, attribute: string): string | null;
+//# 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":"AAwBA,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,EACtB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACnC,OAAO,GAAE,aAAkB,GAC1B,iBAAiB,CAOnB;AAED,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,QAAQ,EAAE,QAAQ,CAAC;IACnB,kDAAkD;IAClD,IAAI,EAAE,OAAO,CAAC;IACd,sCAAsC;IACtC,IAAI,IAAI,MAAM,CAAC;IACf,qEAAqE;IACrE,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACtC,+CAA+C;IAC/C,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpD,0BAA0B;IAC1B,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,wCAAwC;IACxC,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,CAAC;IACjC,+CAA+C;IAC/C,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnD,yDAAyD;IACzD,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAClE,mEAAmE;IACnE,KAAK,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,2DAA2D;IAC3D,OAAO,CAAC,EAAE,EAAE,MAAM,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;;;;GAMG;AACH,wBAAgB,KAAK,CACnB,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,MAAM,EACtB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACnC,OAAO,GAAE,YAAiB,GACzB,gBAAgB,GAAG;IAAE,OAAO,IAAI,IAAI,CAAA;CAAE,CAmFxC;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIvF"}

package/dist/index.js

@@ -0,0 +1,143 @@
+/**
+ * `@vesk/testing` — a component test harness.
+ *
+ * A framework whose whole pitch is "no VDOM" has to be testable without a
+ * browser. Before this, testing a `.vsk` component meant either booting a server
+ * and driving Chrome, or hand-rolling a DOM shim — which is why so much of this
+ * repo's own suite asserts on markup strings.
+ *
+ * The harness is deliberately small and honest about what it covers:
+ *
+ *   renderComponent() — compile + SSR a `.vsk` source string and give you the
+ *     HTML, so a component's server output can be asserted with no server and
+ *     no browser. This is the assertion most component tests actually want.
+ *   mount() — take that SSR HTML, put it in a real DOM (linkedom), and drive
+ *     it: text, attributes, click, input, effects flushed. Hydration runs when
+ *     the runtime can be installed in that DOM.
+ *
+ * Anything that genuinely needs a browser (layout, service workers, real
+ * event dispatch semantics) still belongs in `tests/hydration-test.mjs`. This
+ * is for the other 90%.
+ */
+import { parseHTML } from 'linkedom';
+import { renderPage } from '@vesk/compiler/src/server-codegen';
+/**
+ * Compile and server-render a component from `.vsk` source.
+ *
+ * Throws with the compiler's own diagnostic (code frame and all) when the
+ * source does not compile — a test failure should read like a compile error,
+ * not like an empty string.
+ */
+export function renderComponent(source, componentName, props = {}, options = {}) {
+    const hydrate = options.hydrate !== false;
+    const result = renderPage(source, componentName || 'App', props, new Map(), {
+        hydrate,
+        sourcePath: options.fileName,
+    });
+    return { html: result.body, head: result.head, props: result.props };
+}
+const DEFAULT_WAIT_MS = 2000;
+/**
+ * Mount a component's SSR output into a real DOM and return a driver.
+ *
+ * The DOM is a linkedom document installed as the ambient `document` for the
+ * duration of the returned driver's lifetime — `restore()` puts the previous
+ * globals back, and `unmount()` also calls it.
+ */
+export function mount(source, componentName, props = {}, options = {}) {
+    const html = options.html ?? renderComponent(source, componentName, props, options).html;
+    const { document, window } = parseHTML(`<!DOCTYPE html><html><head></head><body><div id="root">${html}</div></body></html>`);
+    const previous = {
+        document: globalThis.document,
+        window: globalThis.window,
+        Event: globalThis.Event,
+        Node: globalThis.Node,
+    };
+    const g = globalThis;
+    g.document = document;
+    g.window = window;
+    g.Event = window.Event;
+    g.Node = window.Node;
+    const root = document.querySelector(options.rootSelector || '#root');
+    if (!root)
+        throw new Error(`mount: no ${options.rootSelector || '#root'} in the rendered output`);
+    const q = (selector) => root.querySelector(selector);
+    const flush = async () => {
+        // Two turns: effects scheduled by an effect need a turn of their own, which
+        // is exactly why a hand-written `await Promise.resolve()` is not enough.
+        await Promise.resolve();
+        await Promise.resolve();
+    };
+    const driver = {
+        document: document,
+        root: root,
+        html: () => root.innerHTML,
+        text: (selector) => {
+            const el = q(selector);
+            return el ? String(el.textContent || '').trim() : null;
+        },
+        attr: (selector, name) => {
+            const el = q(selector);
+            if (!el)
+                return null;
+            const v = el.getAttribute ? el.getAttribute(name) : null;
+            return v === null ? null : v;
+        },
+        has: (selector) => q(selector) !== null,
+        all: (selector) => Array.from(root.querySelectorAll(selector)),
+        click: async (selector) => {
+            const el = q(selector);
+            if (!el)
+                throw new Error(`mount: no element for ${selector}`);
+            if (typeof el.click === 'function')
+                el.click();
+            else
+                el.dispatchEvent(new window.Event('click', { bubbles: true }));
+            await flush();
+            return driver;
+        },
+        input: async (selector, value) => {
+            const el = q(selector);
+            if (!el)
+                throw new Error(`mount: no element for ${selector}`);
+            el.value = value;
+            el.dispatchEvent(new window.Event('input', { bubbles: true }));
+            await flush();
+            return driver;
+        },
+        flush: async () => {
+            await flush();
+            return driver;
+        },
+        waitFor: async (fn, timeoutMs = DEFAULT_WAIT_MS) => {
+            const deadline = Date.now() + timeoutMs;
+            for (;;) {
+                if (fn())
+                    return;
+                if (Date.now() > deadline) {
+                    throw new Error(`mount: waitFor timed out after ${timeoutMs}ms\n  html: ${driver.html().slice(0, 400)}`);
+                }
+                await flush();
+                await new Promise((r) => setTimeout(r, 5));
+            }
+        },
+        unmount: () => {
+            for (const [key, value] of Object.entries(previous)) {
+                if (value === undefined)
+                    delete g[key];
+                else
+                    g[key] = value;
+            }
+        },
+    };
+    return driver;
+}
+/**
+ * Read a value out of an attribute, decoded the way a browser would.
+ * Small convenience for meta/link assertions (`content="a &amp; b"`).
+ */
+export function attrOf(html, selector, attribute) {
+    const { document } = parseHTML(`<!DOCTYPE html><html><body>${html}</body></html>`);
+    const el = document.querySelector(selector);
+    return el ? el.getAttribute(attribute) : null;
+}

package/dist/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@vesk/testing",
+  "version": "0.2.50-canary.4",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./src/*": "./*.js",
+    "./package.json": "./package.json"
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@vesk/testing",
+  "version": "0.2.50-canary.4",
+  "description": "Test harness for Vesk components: SSR a .vsk file, hydrate it in a real DOM, drive it, assert on the result.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@vesk/adapter": "^0.2.50-canary.4",
+    "@vesk/compiler": "^0.2.50-canary.4",
+    "@vesk/runtime": "^0.2.50-canary.4",
+    "@vesk/types": "^0.2.50-canary.4",
+    "linkedom": "^0.18.13"
+  },
+  "license": "MIT"
+}