dsh-plugin-toolkit 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.
+- The README links `dsh-plugin-example` and documents that `unmount()` is async.
+
 ## 0.3.0
 
 - `dsh-plugin dev`: copy a rebuilt bundle into the installed plugin, then confirm the reload from the host's `/plugins/events` stream. Subscribing happens *before* the write, because a copy made first is reported to nobody.

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.
 
 ```
@@ -49,8 +51,33 @@ console.assert(panel.must('[role="status"]').textContent.includes('92'));
 await panel.unmount();
 ```
 
+`unmount()` is async: it lets React finish the work its own unmount schedules before the DOM goes away. Skipping the `await` surfaces as `ReferenceError: window is not defined` *after* the test has already passed, which is a confusing way to learn it.
+
 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
@@ -65,6 +92,14 @@ $ npx dsh-plugin mount ../ai-context-doctor/plugin/client.js
 AIignore No workspace yet Could not read the report …
 ```
 
+## Start from the example
+
+[`dsh-plugin-example`](https://github.com/WJDdidi-1/dsh-plugin-example) is a ~70-line plugin: one sidebar tab, two languages, one behaviour test, CI that runs `doctor` through the composite action. It is the shape this toolkit expects, so it is also the fastest way to see whether the toolkit fits your plugin.
+
+```sh
+dsh plugin add dsh-plugin-example
+```
+
 ## Edit a plugin that is already installed
 
 The host already swaps a rebuilt bundle without a page reload: it watches each plugin's entry artifact and reports a `rebuilt` frame on `/plugins/events`. `dev` puts the new file where the host is looking, then **proves** the frame arrived instead of asking you to check by eye.

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/mount.mjs

@@ -184,7 +184,14 @@ export async function mountClient(options) {
     },
     writeSnapshot: (dir, name) => write(dir, name, root.innerHTML),
     unmount: async () => {
-      await act(async () => clientRoot.unmount());
+      await act(async () => {
+        clientRoot.unmount();
+        // React schedules follow-up work, and a polling panel schedules timers.
+        // One macrotask lets that land while the DOM is still alive; closing the
+        // window first turns it into "ReferenceError: window is not defined"
+        // after the test has already passed.
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      });
       globalThis.fetch = previousFetch;
       restoreGlobals();
       // A panel polls; jsdom's timers and rAF would keep the test process alive

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.0",
+  "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": {