matchers

(no submodules)

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

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:

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.

2.4 KiB Raw Permalink Blame History