dsh-plugin-toolkit 0.8.6 → 0.8.7

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.8.7
+
+- `panel.aria(selector)` and `panel.expectAria(selector, expected)`: assert what a
+  screen reader reads, and get the attribute that differs named in the failure.
+  A missing attribute reports `nothing` rather than `""`.
+
 ## 0.8.6
 
 - `release --publish`: run `npm publish` locally instead of waiting for a

package/README.md

@@ -135,10 +135,22 @@ First run writes nothing: it tells you to re-run with `UPDATE_SNAPSHOTS=1`, so a
 ### Check what assistive tech sees
 
 ```js
-assert.equal(panel.attributes('[role="tab"][aria-selected="true"]').id, 'tab-protection');
+panel.expectAria('[role="tab"][aria-selected="true"]', { label: 'Protection', selected: 'true' });
 assert.match(panel.must('[role="status"]').textContent, /Score moved 71 → 77/);
 ```
 
+`expectAria()` compares the attributes a screen reader actually reads — `role`,
+`label`, `live`, `selected`, `expanded`, `checked`, `pressed`, `disabled` — and
+names the one that differs:
+
+```
+[aria-live="polite"]: expected aria text to be "9", but it is "0"
+```
+
+A missing attribute is reported as `nothing`, not as an empty string, because
+those are different bugs. `panel.aria(selector)` returns the same object when you
+want to assert on it yourself.
+
 `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".
 
 Every example below is a file in this repository, run by CI, and the output shown is the output it prints:

package/lib/testkit/mount.mjs

@@ -177,6 +177,35 @@ export async function mountClient(options) {
       const element = must(selector);
       return Object.fromEntries([...element.attributes].map((attribute) => [attribute.name, attribute.value]));
     },
+    // What a screen reader would report, in the same blunt vocabulary as the
+    // rest: the attributes, not a re-implementation of the accessibility tree.
+    aria: (selector) => {
+      const element = must(selector);
+      const read = (name) => element.getAttribute(name) ?? undefined;
+      return {
+        role: read('role'),
+        label: read('aria-label'),
+        labelledBy: read('aria-labelledby'),
+        describedBy: read('aria-describedby'),
+        live: read('aria-live'),
+        selected: read('aria-selected'),
+        expanded: read('aria-expanded'),
+        checked: read('aria-checked'),
+        pressed: read('aria-pressed'),
+        disabled: read('aria-disabled') ?? (element.disabled === true ? 'true' : undefined),
+        hidden: read('aria-hidden'),
+        text: element.textContent.replace(/\s+/g, ' ').trim(),
+      };
+    },
+    expectAria: (selector, expected) => {
+      const actual = helpers.aria(selector);
+      for (const [key, value] of Object.entries(expected)) {
+        if (actual[key] === value) continue;
+        const shown = actual[key] === undefined ? 'nothing' : `"${actual[key]}"`;
+        throw new Error(`${selector}: expected aria ${key} to be "${value}", but it is ${shown}`);
+      }
+      return actual;
+    },
     snapshot: (dir, name) => {
       const result = compare(dir, name, root.innerHTML);
       if (result.status === 'changed') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-toolkit",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "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": {