# 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.