dsh-plugin-toolkit 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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

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/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.2",
   "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": {