@firsthandjs/testing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Firsthand contributors
+
+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.

package/README.md

@@ -0,0 +1,38 @@
+# @firsthandjs/testing
+
+Mounting, cleanup and leak probes. Deliberately small: Firsthand renders real DOM,
+so the DOM is the API — there is no wrapper object to learn and no query
+language re-implemented on top of `querySelector`.
+
+**Documentation:** [guide](https://github.com/firsthandjs/firsthand/blob/main/docs/guide/12-testing.md) · [API reference](https://github.com/firsthandjs/firsthand/blob/main/docs/reference/testing.md) · [all docs](https://github.com/firsthandjs/firsthand/blob/main/docs/README.md)
+
+```ts
+import { afterEach } from 'vitest';
+import { cleanup, mount } from '@firsthandjs/testing';
+
+afterEach(cleanup);
+
+it('counts up', () => {
+  const view = mount(() => <Counter initial={0} />);
+  view.get<HTMLButtonElement>('button').click();
+  expect(view.text()).toBe('1');   // no await: writes are synchronous
+});
+```
+
+| Export                    | What it is for                                                                                      |
+| ------------------------- | --------------------------------------------------------------------------------------------------- |
+| `mount(view, parent?)`    | Renders into a fresh container attached to the document, with `text()`, `get()` and `all()` helpers |
+| `cleanup()`               | Unmounts everything still standing                                                                  |
+| `autoCleanup()`           | Registers `cleanup` with whatever `afterEach` the environment has                                   |
+| `withRoot(fn)`            | A reactive root with no DOM, for testing signals and context in plain Node                          |
+| `subscriberCount(source)` | How many live subscribers a signal has — the number a leak test wants                               |
+| `tick(ms?)`               | Waits for asynchronous _application_ code. Never needed after a signal write                        |
+
+The container is attached to the document rather than detached: layout, focus,
+events and `:hover` all behave differently in a detached tree, and a test that
+only passes detached is a test of something else.
+
+Full guide, including Vitest environments and Playwright:
+[the testing guide](../../docs/guide/12-testing.md).
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * `@firsthandjs/testing` — mounting, cleanup and leak probes.
+ *
+ * Deliberately small. Firsthand renders real DOM, so the DOM is the API: there is
+ * no wrapper object to learn and no query language to re-implement. What a test
+ * actually needs from a framework is somewhere to mount, a guarantee that the
+ * previous test's tree is gone, and a way to ask whether disposal really
+ * released everything. That is what is here.
+ *
+ * It is runner-agnostic. `autoCleanup()` hooks into whatever `afterEach` the
+ * environment provides — Vitest, Jest, Mocha, Playwright's component runner —
+ * and does nothing if there is none.
+ */
+import { type Dispose } from '@firsthandjs/core';
+import { type View } from '@firsthandjs/dom';
+/** What `mount` hands back. */
+export interface Mounted {
+    /** The element the view was rendered into. */
+    readonly container: HTMLElement;
+    /** Disposes the view and removes its container. Idempotent. */
+    readonly unmount: Dispose;
+    /** Shorthand for `container.textContent`, which most assertions want. */
+    text(): string;
+    /** `querySelector` that throws instead of returning null. */
+    get<E extends Element = HTMLElement>(selector: string): E;
+    /** `querySelectorAll` as a real array. */
+    all<E extends Element = HTMLElement>(selector: string): E[];
+}
+/**
+ * Renders a view into a fresh container attached to the document.
+ *
+ * Attached, not detached: layout, focus, events and `:hover` all behave
+ * differently in a detached tree, and a test that passes only detached is a
+ * test of something else.
+ */
+export declare function mount(view: () => View, parent?: ParentNode): Mounted;
+/** Unmounts everything `mount` created and still holds. */
+export declare function cleanup(): void;
+/**
+ * Registers `cleanup` with the surrounding test framework, if there is one.
+ *
+ * Call it once in a setup file. A test that forgets to unmount then cannot
+ * leak into the next one, which is the failure mode that makes a suite
+ * mysteriously order-dependent.
+ */
+export declare function autoCleanup(): boolean;
+/**
+ * Runs `fn` in its own reactive root and returns the result with a disposer.
+ *
+ * For testing reactivity without any DOM — signals, computeds, effects and
+ * context all work in a plain Node environment, because the core has no DOM
+ * dependency.
+ */
+export declare function withRoot<T>(fn: () => T): {
+    value: T;
+    dispose: Dispose;
+};
+/**
+ * How many live subscribers a signal or computed currently has.
+ *
+ * The number a leak test wants: after disposing whatever was watching it, a
+ * source that still has subscribers is still reachable from the graph, and
+ * nothing it references can be collected. This reads the graph rather than
+ * guessing from the heap, so it is deterministic in every engine.
+ */
+export declare function subscriberCount(source: object): number;
+/**
+ * Waits for pending microtasks and, optionally, a timer.
+ *
+ * Firsthand updates the DOM synchronously (ADR-0006), so this is *not* needed
+ * after a signal write. It is here for the ordinary reason any test needs it:
+ * an `await` in application code, a `fetch`, a `queueMicrotask`.
+ */
+export declare function tick(ms?: number): 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":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAU,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAUrD,+BAA+B;AAC/B,MAAM,WAAW,OAAO;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,IAAI,IAAI,MAAM,CAAC;IACf,6DAA6D;IAC7D,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAAC;IAC1D,0CAA0C;IAC1C,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;CAC7D;AAID;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,IAAI,EAAE,MAAM,GAAE,UAA0B,GAAG,OAAO,CAkCnF;AAED,2DAA2D;AAC3D,wBAAgB,OAAO,IAAI,IAAI,CAI9B;AAID;;;;;;GAMG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAOrC;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAOvE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQtD;AAED;;;;;;GAMG;AACH,wBAAsB,IAAI,CAAC,EAAE,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhD"}

package/dist/index.js

@@ -0,0 +1,79 @@
+// packages/testing/src/index.ts
+import { createRoot } from "@firsthandjs/core";
+import { render } from "@firsthandjs/dom";
+var active = /* @__PURE__ */ new Set();
+function mount(view, parent = document.body) {
+  const container = document.createElement("div");
+  parent.appendChild(container);
+  const dispose = render(view, container);
+  let done = false;
+  const unmount = () => {
+    if (done) {
+      return;
+    }
+    done = true;
+    active.delete(unmount);
+    dispose();
+    container.remove();
+  };
+  active.add(unmount);
+  return {
+    container,
+    unmount,
+    text: () => container.textContent,
+    get: (selector) => {
+      const found = container.querySelector(selector);
+      if (found === null) {
+        throw new Error(
+          `No element matched ${selector}. The container holds:
+${container.innerHTML}`
+        );
+      }
+      return found;
+    },
+    all: (selector) => [
+      ...container.querySelectorAll(selector)
+    ]
+  };
+}
+function cleanup() {
+  for (const unmount of [...active]) {
+    unmount();
+  }
+}
+function autoCleanup() {
+  const hook = globalThis.afterEach;
+  if (typeof hook !== "function") {
+    return false;
+  }
+  hook(cleanup);
+  return true;
+}
+function withRoot(fn) {
+  let dispose;
+  const value = createRoot((stop) => {
+    dispose = stop;
+    return fn();
+  });
+  return { value, dispose };
+}
+function subscriberCount(source) {
+  let link = source.subs;
+  let total = 0;
+  while (link !== void 0) {
+    total++;
+    link = link.nextSub;
+  }
+  return total;
+}
+async function tick(ms = 0) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+export {
+  autoCleanup,
+  cleanup,
+  mount,
+  subscriberCount,
+  tick,
+  withRoot
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@firsthandjs/testing",
+  "version": "0.1.0",
+  "description": "Test helpers for Firsthand: mounting, cleanup and leak probes. Works with any runner.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@firsthandjs/core": "0.1.0",
+    "@firsthandjs/dom": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firsthandjs/firsthand.git",
+    "directory": "packages/testing"
+  },
+  "bugs": {
+    "url": "https://github.com/firsthandjs/firsthand/issues"
+  },
+  "homepage": "https://github.com/firsthandjs/firsthand#readme",
+  "keywords": [
+    "firsthand",
+    "testing",
+    "vitest",
+    "playwright"
+  ]
+}