dsh-plugin-toolkit 0.3.1 → 0.3.3

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.3
+
+- `mount` on a path that is missing, or that is a directory, now says what to pass instead of raising `ENOENT: no such file or directory, open '…'`. Found by running the three commands in a clean HOME with a fresh clone.
+
+## 0.3.2
+
+- `expectSnapshot(html, dir, name)`: the assertion form of `compare`, so a baseline test reads like a test and fails with the element that moved.
+- README: how to keep a DOM baseline, and how to assert what assistive tech sees.
+
 ## 0.3.1
 
 - `unmount()` now waits one macrotask before the DOM goes away. React schedules work during its own unmount, and closing jsdom first turned that into `ReferenceError: window is not defined` after a passing test. Found by the example plugin's second test.

package/README.md

@@ -1,5 +1,7 @@
 # dsh-plugin-toolkit
 
+![dsh-plugin-toolkit](docs/card.png)
+
 A preflight and release tool for [DeepSeek Harness](https://github.com/deepseek-ai/dsh) plugins, plus the pieces of the publishing ritual that kept going wrong by hand.
 
 ```
@@ -53,6 +55,29 @@ await panel.unmount();
 
 What you get back: `text()`, `html()`, `query(selector)`, `must(selector)` (throws with the rendered HTML when it misses), `click(selector)`, `type(selector, value)`, `press(selector, key)`, `focus`, `attributes(selector)`, `snapshot(dir, name)` for a normalised DOM baseline, and `host` for assertions about what the bundle registered.
 
+### Keep a visual baseline
+
+The DOM is the baseline: normalising class order and whitespace gives a file that fails for the reasons a screenshot would — a lost label, a control that stopped rendering — and can be reviewed in a diff instead of by eye.
+
+```js
+import { expectSnapshot } from 'dsh-plugin-toolkit/testkit';
+
+const panel = await mountClient({ file: 'client.js' });
+expectSnapshot(panel.html(), '__snapshots__', 'panel');   // throws with the element that moved
+await panel.unmount();
+```
+
+First run writes nothing: it tells you to re-run with `UPDATE_SNAPSHOTS=1`, so a baseline is always a decision, never a side effect.
+
+### Check what assistive tech sees
+
+```js
+assert.equal(panel.attributes('[role="tab"][aria-selected="true"]').id, 'tab-protection');
+assert.match(panel.must('[role="status"]').textContent, /Score moved 71 → 77/);
+```
+
+`must()` throws with the rendered markup when the selector misses, which is the difference between "the assertion failed" and "here is what the user actually got".
+
 To look at a bundle by hand:
 
 ```sh
@@ -83,6 +108,10 @@ The host already swaps a rebuilt bundle without a page reload: it watches each p
 npx dsh-plugin dev . --host http://127.0.0.1:54133
 ```
 
+![dsh-plugin dev printing the revision the app reported](docs/dev.gif)
+
+*Recorded from a real run against the running app: the last line is the revision the app sent back on `/plugins/events`, not a message the tool printed on faith.*
+
 ```
 demo-aiignore: /work/plugin/client.js -> ~/.dsh/profiles/desktop/node_modules/dsh-aiignore/client.js
 initial: copied 163647 bytes at 1:18:43 AM

package/lib/testkit/index.mjs

@@ -9,4 +9,4 @@ export { createHost } from './host.mjs';
 export { createFetch } from './fetch.mjs';
 export { createModuleLoader, loadBundle } from './load.mjs';
 export { mountClient } from './mount.mjs';
-export { compare, normalize, snapshotPath, write } from './snapshot.mjs';
+export { compare, expectSnapshot, normalize, snapshotPath, write } from './snapshot.mjs';

package/lib/testkit/load.mjs

@@ -8,6 +8,23 @@
  */
 import fs from 'node:fs';
 
+/**
+ * Read the bundle, or say what is wrong with the path in the caller's words.
+ *
+ * A raw ENOENT is technically true and practically useless: the usual mistake is
+ * passing the plugin folder, or a path relative to the wrong directory.
+ */
+function readBundleSource(file) {
+  const resolved = String(file);
+  if (fs.existsSync(resolved) === false) {
+    throw new Error(`no such file: ${resolved} (mount takes the client bundle, e.g. ./client.js)`);
+  }
+  if (fs.statSync(resolved).isDirectory() === true) {
+    throw new Error(`${resolved} is a directory (mount takes the client bundle inside it, e.g. ${resolved}/client.js)`);
+  }
+  return fs.readFileSync(resolved, 'utf8');
+}
+
 export function createModuleLoader({ require: provide, onLoad } = {}) {
   const loaded = [];
   const loader = {
@@ -27,7 +44,7 @@ export function createModuleLoader({ require: provide, onLoad } = {}) {
 }
 
 export function loadBundle(file, options = {}) {
-  const source = fs.readFileSync(file, 'utf8');
+  const source = readBundleSource(file);
   const loader = createModuleLoader(options);
   const context = { window: { __ModuleLoader__: loader }, __ModuleLoader__: loader, ...(options.globals ?? {}) };
   // The bundle is an IIFE or a top-level statement list; the browser would run it

package/lib/testkit/snapshot.mjs

@@ -45,3 +45,24 @@ export function write(dir, name, html) {
   fs.writeFileSync(file, `${normalize(html)}\n`);
   return file;
 }
+
+/**
+ * The assertion form of `compare`, so a baseline test reads like a test and
+ * fails with the thing that moved rather than two walls of markup.
+ */
+export function expectSnapshot(html, dir, name) {
+  const result = compare(dir, name, html);
+  if (result.status === 'same') return result;
+  if (result.status === 'missing') {
+    throw new Error(`no baseline at ${result.file}; run with UPDATE_SNAPSHOTS=1 to create it`);
+  }
+  const expected = result.expected.split(/(?=<)/);
+  const actual = result.actual.split(/(?=<)/);
+  const position = result.firstDifference;
+  throw new Error([
+    `${name} changed at element ${position}`,
+    `  expected: ${expected[position] ?? '(nothing)'}`,
+    `  actual:   ${actual[position] ?? '(nothing)'}`,
+    `  baseline: ${result.file}`,
+  ].join('\n'));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Preflight, release and test DeepSeek Harness plugins: checks what the host needs, waits for npm to actually serve the version, and keeps the market index honest.",
   "type": "module",
   "bin": {