Initial Commit

packages/devtools/tooling/test-vite/src/matchers/matchers.md

@@ -0,0 +1,61 @@
+# matchers
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`createMatchers` returns a bundle of typed `expect.extend` matchers used across suaveplan browser-tier test suites. The matchers cover three recurring assertions that come up often enough that hand-rolled equivalents drift across packages: accessibility hooks on rendered nodes, base64-encoded data URLs with a mime guard, and CSS-custom-property availability on a host element.
+
+## Features
+
+- `toBeAccessibleNode(node)` — passes when the node exposes `role`, `aria-label`, or `aria-labelledby` as a non-empty string.
+- `toMatchDataURL(value, mimePattern)` — passes when the value is a `data:<mime>;base64,<payload>` URL and `mime` matches the supplied regex.
+- `toHaveValidCSSVars(host, names)` — passes when every name in `names` is set on `host.style` as a non-empty string.
+- Each matcher returns the Vitest contract `{ pass, message }` so failures surface descriptive diagnostics.
+- Universal — works in node + jsdom + happy-dom without DOM lookups.
+
+## Usage: Basic
+
+```ts
+import { expect } from "vitest";
+import { createMatchers } from "@suaveplan/test-vite/matchers";
+
+expect.extend(createMatchers());
+
+const button = { role: "button", "aria-label": "Close" };
+expect(button).toBeAccessibleNode();
+```
+
+## Usage: Advanced
+
+Custom matchers in a server-rendered snapshot test:
+
+```ts
+import { createMatchers } from "@suaveplan/test-vite/matchers";
+
+const matchers = createMatchers();
+
+const widget = renderToObject();
+const accessibility = matchers.toBeAccessibleNode(widget);
+if (!accessibility.pass) {
+  throw new Error(accessibility.message());
+}
+
+const cssVars = matchers.toHaveValidCSSVars(widget, ["--brand", "--accent"]);
+if (!cssVars.pass) {
+  throw new Error(cssVars.message());
+}
+```
+
+## API Reference
+
+- `createMatchers(): TestViteMatchers`.
+- `TestViteMatchers.toBeAccessibleNode(received): MatcherResult`.
+- `TestViteMatchers.toMatchDataURL(received, mimePattern): MatcherResult`.
+- `TestViteMatchers.toHaveValidCSSVars(received, names): MatcherResult`.
+
+## Implementation Notes
+
+The data-URL parser uses a strict regex that allows only base64 payload characters (`A-Z`, `a-z`, `0-9`, `+`, `/`, `=`); URL-encoded data URLs are intentionally rejected because base64 is the only payload format suaveplan components emit. The CSS-vars matcher inspects the host's `style` record directly rather than calling `getComputedStyle`, so it works on both real DOM nodes and synthetic objects.