@cronn/element-snapshot 0.17.0 → 0.19.0

package/README.md

@@ -27,9 +27,9 @@ yarn add -D @cronn/element-snapshot
 
 ```ts
 import { semanticSnapshot } from "@cronn/element-snapshot";
-import { defineValidationFileExpect } from "@cronn/playwright-file-snapshots";
+import { defineFileSnapshotMatchers } from "@cronn/playwright-file-snapshots";
 
-const expect = defineValidationFileExpect();
+const expect = defineFileSnapshotMatchers();
 
 test("matches element snapshot", async ({ page }) => {
   await page.setContent(`

package/dist/browser-lib.iife.js

@@ -119,89 +119,6 @@
 		}, []);
 	}
 	//#endregion
-	//#region src/browser/text.ts
-	function snapshotTextNode(textNode) {
-		if (textNode.textContent === null) return null;
-		const normalizedText = normalizeText(textNode.textContent);
-		if (normalizedText.length === 0) return null;
-		return textSnapshot(normalizedText);
-	}
-	function snapshotPresentationalChildren(node) {
-		const accessibleTextContent = resolveAccessibleTextContent(node);
-		if (accessibleTextContent === void 0 || accessibleTextContent.length === 0) return [];
-		return [textSnapshot(accessibleTextContent)];
-	}
-	function resolveAccessibleTextContent(node, excludedNodes = []) {
-		const children = snapshotChildren(node, excludedNodes);
-		if (children === void 0) return;
-		const textContent = getTextContent(children);
-		return textContent.length > 0 ? textContent : void 0;
-	}
-	//#endregion
-	//#region src/browser/name.ts
-	function resolveAccessibleName(element, includeTextContent = true) {
-		const labelledByElement = resolveElementReference(element, "aria-labelledby");
-		if (labelledByElement !== null) return resolveAccessibleTextContent(labelledByElement);
-		if (element.ariaLabel !== null) return element.ariaLabel;
-		if (includeTextContent) return resolveAccessibleTextContent(element);
-	}
-	//#endregion
-	//#region src/browser/state.ts
-	function disableableAttributes(element) {
-		return { disabled: booleanAttribute(isNativeInputElement(element) || element instanceof HTMLButtonElement || element instanceof HTMLOptionElement ? element.hasAttribute("disabled") : false) ?? booleanAttribute(element.ariaDisabled) };
-	}
-	function selectableAttributes(element) {
-		return { selected: booleanAttribute(element instanceof HTMLOptionElement ? element.hasAttribute("selected") : false) ?? booleanAttribute(element.ariaSelected) };
-	}
-	function inputStateAttributes(element) {
-		const supportsHtmlAttributes = isNativeInputElement(element);
-		const readonly = booleanAttribute(supportsHtmlAttributes ? element.hasAttribute("readonly") : false);
-		const required = booleanAttribute(supportsHtmlAttributes ? element.hasAttribute("required") : false);
-		return {
-			readonly: readonly ?? booleanAttribute(element.ariaReadOnly),
-			...disableableAttributes(element),
-			required: required ?? booleanAttribute(element.ariaRequired),
-			invalid: booleanAttribute(element.ariaInvalid)
-		};
-	}
-	function isNativeInputElement(element) {
-		return element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement;
-	}
-	//#endregion
-	//#region src/browser/button.ts
-	const PRESSED_VALUES = new Set([
-		"true",
-		"mixed",
-		"false"
-	]);
-	function snapshotButton(element) {
-		return {
-			role: "button",
-			name: resolveAccessibleName(element),
-			attributes: {
-				...disableableAttributes(element),
-				expanded: booleanAttribute(element.ariaExpanded),
-				pressed: resolvePressedAttribute(element)
-			},
-			children: snapshotChildren(element)
-		};
-	}
-	function resolvePressedAttribute(element) {
-		const pressed = enumAttribute(element.ariaPressed, PRESSED_VALUES);
-		if (pressed === "mixed") return pressed;
-		return booleanAttribute(pressed === "true");
-	}
-	//#endregion
-	//#region src/browser/description.ts
-	function discribableAttributes(element) {
-		return { description: resolveDescription(element) };
-	}
-	function resolveDescription(element) {
-		const describedByElement = resolveElementReference(element, "aria-describedby");
-		if (describedByElement !== null) return resolveAccessibleTextContent(describedByElement);
-		if (element.ariaDescription !== null) return element.ariaDescription;
-	}
-	//#endregion
 	//#region src/types/elements/container.ts
 	const CONTAINER_ROLES = new Set([
 		"paragraph",
@@ -215,7 +132,6 @@
 		"form",
 		"main",
 		"navigation",
-		"region",
 		"search",
 		"descriptionlist",
 		"term",
@@ -235,12 +151,11 @@
 	]);
 	//#endregion
 	//#region src/browser/container.ts
-	const NAMEABLE_CONTAINER_ROLES = new Set(["label"]);
 	function snapshotContainer(role, element) {
 		const children = snapshotChildren(element);
 		return elementSnapshot({
 			role,
-			name: resolveAccessibleName(element, NAMEABLE_CONTAINER_ROLES.has(role)),
+			name: resolveAccessibleName(element),
 			children
 		});
 	}
@@ -319,7 +234,6 @@
 		gridcell: isWithinGridRow,
 		listitem: isWithinList,
 		menuitem: isWithinMenu,
-		region: hasAccessibleName,
 		row: isWithinTableOrGrid,
 		rowgroup: isWithinTableOrGrid,
 		rowheader: isWithinTableRowOrGridRow,
@@ -345,7 +259,7 @@
 		const resolvedElementRole = resolveElementRole(element);
 		if (resolvedElementRole === void 0) return;
 		const isValidInContext = CONTEXT_DEPENDENT_ROLES[resolvedElementRole];
-		if (isValidInContext !== void 0 && !isValidInContext(element)) return;
+		if (isValidInContext !== void 0 && !isValidInContext(element, resolvedElementRole)) return;
 		return resolvedElementRole;
 	}
 	function resolveElementRole(element) {
@@ -384,9 +298,6 @@
 	function isTopLevelBanner(element) {
 		return !isWithinElement(element, selectorList(...DISALLOWED_BANNER_CONTAINER_ELEMENTS, ...DISALLOWED_BANNER_CONTAINER_ROLES.map(roleSelector)));
 	}
-	function hasAccessibleName(element) {
-		return resolveAccessibleName(element, false) !== void 0;
-	}
 	function isWithinDescriptionList(element) {
 		return isWithinElement(element, "dl");
 	}
@@ -428,6 +339,144 @@
 		return isWithinElement(element, roleSelector("tablist"));
 	}
 	//#endregion
+	//#region src/browser/text.ts
+	function snapshotTextNode(textNode) {
+		if (textNode.textContent === null) return null;
+		const normalizedText = normalizeText(textNode.textContent);
+		if (normalizedText.length === 0) return null;
+		return textSnapshot(normalizedText);
+	}
+	function snapshotPresentationalChildren(node) {
+		const accessibleTextContent = resolveAccessibleTextContent(node);
+		if (accessibleTextContent === void 0 || accessibleTextContent.length === 0) return [];
+		return [textSnapshot(accessibleTextContent)];
+	}
+	function resolveAccessibleTextContent(node, excludedNodes = []) {
+		const children = snapshotChildren(node, excludedNodes);
+		if (children === void 0) return;
+		const textContent = getTextContent(children);
+		return textContent.length > 0 ? textContent : void 0;
+	}
+	//#endregion
+	//#region src/browser/name.ts
+	const prohibitsNaming = new Set([
+		"label",
+		"listitem",
+		"paragraph",
+		"rowgroup",
+		"term"
+	]);
+	const supportsNamingByLabel = new Set([
+		"checkbox",
+		"combobox",
+		"progressbar",
+		"radio",
+		"searchbox",
+		"slider",
+		"spinbutton",
+		"textbox"
+	]);
+	const supportsNamingFromChildContent = new Set([
+		"button",
+		"cell",
+		"columnheader",
+		"gridcell",
+		"heading",
+		"link",
+		"menuitem",
+		"option",
+		"rowheader",
+		"tab"
+	]);
+	const contextBasedNameResolvers = [resolveImageName, resolveLegendName];
+	function resolveAccessibleName(element) {
+		const role = parseElementRole(element);
+		if (role === void 0 || prohibitsNaming.has(role)) return;
+		const labelledByElement = resolveElementReference(element, "aria-labelledby");
+		if (labelledByElement !== null) return resolveAccessibleTextContent(labelledByElement);
+		if (element.ariaLabel !== null) return element.ariaLabel;
+		for (const resolveName of contextBasedNameResolvers) {
+			const name = resolveName(element, role);
+			if (name !== void 0) return name;
+		}
+		if (supportsNamingByLabel.has(role)) return resolveLabelName(element);
+		if (supportsNamingFromChildContent.has(role)) return resolveAccessibleTextContent(element);
+	}
+	function resolveLabelName(element) {
+		if (element.id !== null) {
+			const referencedElement = element.ownerDocument.querySelector(attributeSelector("for", element.id));
+			if (referencedElement !== null) return resolveAccessibleTextContent(referencedElement);
+		}
+		const closestLabel = element.closest("label");
+		if (closestLabel !== null) return resolveAccessibleTextContent(closestLabel, [element]);
+	}
+	function resolveLegendName(element) {
+		if (!(element instanceof HTMLFieldSetElement)) return;
+		const legendElement = element.querySelector("legend");
+		if (legendElement === null) return;
+		return resolveAccessibleTextContent(legendElement);
+	}
+	function resolveImageName(element, role) {
+		if (element instanceof HTMLImageElement) return stringAttribute(element.alt);
+		if (role === "img") return resolveAccessibleTextContent(element);
+	}
+	//#endregion
+	//#region src/browser/state.ts
+	function disableableAttributes(element) {
+		return { disabled: booleanAttribute(isNativeInputElement(element) || element instanceof HTMLButtonElement || element instanceof HTMLOptionElement ? element.hasAttribute("disabled") : false) ?? booleanAttribute(element.ariaDisabled) };
+	}
+	function selectableAttributes(element) {
+		return { selected: booleanAttribute(element instanceof HTMLOptionElement ? element.hasAttribute("selected") : false) ?? booleanAttribute(element.ariaSelected) };
+	}
+	function inputStateAttributes(element) {
+		const supportsHtmlAttributes = isNativeInputElement(element);
+		const readonly = booleanAttribute(supportsHtmlAttributes ? element.hasAttribute("readonly") : false);
+		const required = booleanAttribute(supportsHtmlAttributes ? element.hasAttribute("required") : false);
+		return {
+			readonly: readonly ?? booleanAttribute(element.ariaReadOnly),
+			...disableableAttributes(element),
+			required: required ?? booleanAttribute(element.ariaRequired),
+			invalid: booleanAttribute(element.ariaInvalid)
+		};
+	}
+	function isNativeInputElement(element) {
+		return element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement;
+	}
+	//#endregion
+	//#region src/browser/button.ts
+	const PRESSED_VALUES = new Set([
+		"true",
+		"mixed",
+		"false"
+	]);
+	function snapshotButton(element) {
+		return {
+			role: "button",
+			name: resolveAccessibleName(element),
+			attributes: {
+				...disableableAttributes(element),
+				expanded: booleanAttribute(element.ariaExpanded),
+				pressed: resolvePressedAttribute(element)
+			},
+			children: snapshotChildren(element)
+		};
+	}
+	function resolvePressedAttribute(element) {
+		const pressed = enumAttribute(element.ariaPressed, PRESSED_VALUES);
+		if (pressed === "mixed") return pressed;
+		return booleanAttribute(pressed === "true");
+	}
+	//#endregion
+	//#region src/browser/description.ts
+	function discribableAttributes(element) {
+		return { description: resolveDescription(element) };
+	}
+	function resolveDescription(element) {
+		const describedByElement = resolveElementReference(element, "aria-describedby");
+		if (describedByElement !== null) return resolveAccessibleTextContent(describedByElement);
+		if (element.ariaDescription !== null) return element.ariaDescription;
+	}
+	//#endregion
 	//#region src/browser/input.ts
 	function snapshotInput(element) {
 		if (element instanceof HTMLInputElement) return snapshotInputElement(element);
@@ -439,7 +488,7 @@
 		if (inputRole === void 0 || inputRole === "button" || inputRole === "combobox") return null;
 		return elementSnapshot({
 			role: inputRole,
-			name: resolveInputLabel(element),
+			name: resolveAccessibleName(element),
 			attributes: {
 				value: resolveInputValue(element),
 				checked: resolveChecked(element),
@@ -450,7 +499,7 @@
 	function snapshotTextareaElement(element) {
 		return elementSnapshot({
 			role: "textbox",
-			name: resolveInputLabel(element),
+			name: resolveAccessibleName(element),
 			attributes: {
 				value: resolveInputValue(element),
 				...snapshotCommonInputAttributes(element)
@@ -473,16 +522,6 @@
 		if (!(element instanceof HTMLInputElement)) return;
 		return element.checked ? true : void 0;
 	}
-	function resolveInputLabel(element) {
-		const accessibleName = resolveAccessibleName(element, false);
-		if (accessibleName !== void 0) return accessibleName;
-		if (element.id !== null) {
-			const referencedElement = element.ownerDocument.querySelector(`[for='${element.id}']`);
-			if (referencedElement !== null) return resolveAccessibleTextContent(referencedElement);
-		}
-		const closestLabel = element.closest("label");
-		if (closestLabel !== null) return resolveAccessibleTextContent(closestLabel, [element]);
-	}
 	function resolvePlaceholder(element) {
 		if (element instanceof HTMLSelectElement || element instanceof HTMLButtonElement) return;
 		return stringAttribute(element.placeholder);
@@ -494,7 +533,7 @@
 		const options = snapshotOptions(element);
 		return {
 			role: "combobox",
-			name: resolveInputLabel(element),
+			name: resolveAccessibleName(element),
 			attributes: {
 				value: resolveValue$1(element),
 				...snapshotCommonInputAttributes(element),
@@ -546,7 +585,7 @@
 	function snapshotDialog(role, element) {
 		return {
 			role,
-			name: resolveAccessibleName(element, false),
+			name: resolveAccessibleName(element),
 			attributes: {
 				...discribableAttributes(element),
 				modal: booleanAttribute(element.ariaModal)
@@ -559,19 +598,14 @@
 	function snapshotGroup(element) {
 		return elementSnapshot({
 			role: "group",
-			name: resolveGroupName(element),
+			name: resolveAccessibleName(element),
 			children: snapshotChildren(element)
 		});
 	}
-	function resolveGroupName(element) {
-		const legendElement = element instanceof HTMLFieldSetElement ? element.querySelector("legend") : null;
-		if (legendElement !== null) return resolveAccessibleTextContent(legendElement);
-		return resolveAccessibleName(element, false);
-	}
 	function snapshotRadioGroup(element) {
 		return {
 			role: "radiogroup",
-			name: resolveAccessibleName(element, false),
+			name: resolveAccessibleName(element),
 			attributes: discribableAttributes(element),
 			children: snapshotChildren(element)
 		};
@@ -594,17 +628,13 @@
 	//#endregion
 	//#region src/browser/image.ts
 	function snapshotImage(element) {
-		const imageName = resolveImageName(element);
+		const imageName = resolveAccessibleName(element);
 		if (imageName === void 0) return null;
 		return elementSnapshot({
 			role: "img",
 			name: imageName
 		});
 	}
-	function resolveImageName(element) {
-		if (element instanceof HTMLImageElement) return stringAttribute(element.alt);
-		return resolveAccessibleName(element, true);
-	}
 	//#endregion
 	//#region src/browser/link.ts
 	function snapshotLink(element) {
@@ -636,7 +666,7 @@
 	function snapshotProgressbar(element) {
 		return {
 			role: "progressbar",
-			name: resolveAccessibleName(element, false),
+			name: resolveAccessibleName(element),
 			attributes: { value: resolveValue(element) },
 			children: snapshotPresentationalChildren(element)
 		};
@@ -646,6 +676,18 @@
 		return numericAttribute(element.ariaValueNow);
 	}
 	//#endregion
+	//#region src/browser/region.ts
+	function snapshotRegion(element) {
+		const name = resolveAccessibleName(element);
+		const children = snapshotChildren(element);
+		if (name === void 0) return children;
+		return elementSnapshot({
+			role: "region",
+			name,
+			children
+		});
+	}
+	//#endregion
 	//#region src/browser/separator.ts
 	function snapshotSeparator(element) {
 		return elementSnapshot({
@@ -701,6 +743,7 @@
 		link: snapshotLink,
 		radio: snapshotInput,
 		radiogroup: snapshotRadioGroup,
+		region: snapshotRegion,
 		searchbox: snapshotInput,
 		separator: snapshotSeparator,
 		slider: snapshotInput,

package/dist/index.d.mts

@@ -1,5 +1,20 @@
-import { Locator } from "@playwright/test";
+import { Expect, Locator, MatcherReturnType } from "@playwright/test";
+import { PlaywrightMatchJsonFileOptions, PlaywrightMatchTextFileOptions, PlaywrightValidationFileMatcherConfig } from "@cronn/playwright-file-snapshots";
 
+//#region src/playwright/markdown-table.d.ts
+interface MarkdownTableSnapshotOptions {
+  /**
+   * Show sort indicator for column headers
+   *
+   * @default true
+   */
+  showSortIndicator?: boolean;
+}
+/**
+ * Creates a Markdown table snapshot from a table or grid element
+ */
+declare function markdownTableSnapshot(locator: Locator, options?: MarkdownTableSnapshotOptions): Promise<string>;
+//#endregion
 //#region src/types/attributes.d.ts
 interface DisableableAttributes {
   disabled?: boolean;
@@ -24,6 +39,15 @@ interface ButtonAttributes extends DisableableAttributes {
 }
 type PressedValue = true | "mixed";
 //#endregion
+//#region src/types/utils.d.ts
+type SetValues<TSet> = TSet extends Set<infer TValue> ? TValue : never;
+//#endregion
+//#region src/types/elements/container.d.ts
+declare const CONTAINER_ROLES: Set<"paragraph" | "list" | "listitem" | "listbox" | "article" | "banner" | "complementary" | "contentinfo" | "form" | "main" | "navigation" | "search" | "descriptionlist" | "term" | "definition" | "table" | "grid" | "rowgroup" | "row" | "rowheader" | "cell" | "gridcell" | "alert" | "menu" | "tablist" | "tabpanel" | "label">;
+interface ContainerSnapshot extends GenericElementSnapshot<ContainerRole> {}
+type ContainerRole = SetValues<typeof CONTAINER_ROLES>;
+interface RegionSnapshot extends GenericElementSnapshot<"region"> {}
+//#endregion
 //#region src/types/elements/dialog.d.ts
 interface DialogSnapshot extends GenericElementSnapshot<DialogRole, DialogAttributes> {}
 type DialogRole = "dialog" | "alertdialog";
@@ -87,9 +111,6 @@ interface SeparatorSnapshot extends GenericElementSnapshot<"separator"> {}
 interface TabSnapshot extends GenericElementSnapshot<"tab", TabAttributes> {}
 interface TabAttributes extends DisableableAttributes, SelectableAttributes {}
 //#endregion
-//#region src/types/utils.d.ts
-type SetValues<TSet> = TSet extends Set<infer TValue> ? TValue : never;
-//#endregion
 //#region src/types/elements/table.d.ts
 declare const SORT_TYPES: Set<"ascending" | "descending" | "other">;
 interface ColumnHeaderSnapshot extends GenericElementSnapshot<"columnheader", ColumnheaderAttributes> {}
@@ -104,6 +125,10 @@ interface TextSnapshot {
   name: string;
 }
 //#endregion
+//#region src/types/role.d.ts
+type TextRole = "text";
+type ElementRole = "button" | "columnheader" | "group" | "heading" | "img" | "link" | "menuitem" | "option" | "progressbar" | "radiogroup" | "region" | "separator" | "tab" | ContainerRole | DialogRole | InputRole;
+//#endregion
 //#region src/types/snapshot.d.ts
 type NodeRole = ElementRole | TextRole;
 type NodeSnapshot = ElementSnapshot | TextSnapshot;
@@ -116,30 +141,7 @@ interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes
   attributes: TAttributes;
   children: Array<NodeSnapshot>;
 }
-type ElementSnapshot = ButtonSnapshot | ColumnHeaderSnapshot | ComboboxSnapshot | ContainerSnapshot | DialogSnapshot | GroupSnapshot | HeadingSnapshot | ImageSnapshot | InputSnapshot | LinkSnapshot | OptionSnapshot | ProgressbarSnapshot | TabSnapshot | MenuItemSnapshot | RadioGroupSnapshot | SeparatorSnapshot;
-//#endregion
-//#region src/types/elements/container.d.ts
-declare const CONTAINER_ROLES: Set<"paragraph" | "list" | "listitem" | "listbox" | "article" | "banner" | "complementary" | "contentinfo" | "form" | "main" | "navigation" | "region" | "search" | "descriptionlist" | "term" | "definition" | "table" | "grid" | "rowgroup" | "row" | "rowheader" | "cell" | "gridcell" | "alert" | "menu" | "tablist" | "tabpanel" | "label">;
-interface ContainerSnapshot extends GenericElementSnapshot<ContainerRole> {}
-type ContainerRole = SetValues<typeof CONTAINER_ROLES>;
-//#endregion
-//#region src/types/role.d.ts
-type TextRole = "text";
-type ElementRole = "button" | "columnheader" | "group" | "heading" | "img" | "link" | "menuitem" | "option" | "progressbar" | "radiogroup" | "separator" | "tab" | ContainerRole | DialogRole | InputRole;
-//#endregion
-//#region src/playwright/markdown-table.d.ts
-interface MarkdownTableSnapshotOptions {
-  /**
-   * Show sort indicator for column headers
-   *
-   * @default true
-   */
-  showSortIndicator?: boolean;
-}
-/**
- * Creates a Markdown table snapshot from a table or grid element
- */
-declare function markdownTableSnapshot(locator: Locator, options?: MarkdownTableSnapshotOptions): Promise<string>;
+type ElementSnapshot = ButtonSnapshot | ColumnHeaderSnapshot | ComboboxSnapshot | ContainerSnapshot | DialogSnapshot | GroupSnapshot | HeadingSnapshot | ImageSnapshot | InputSnapshot | LinkSnapshot | OptionSnapshot | ProgressbarSnapshot | RegionSnapshot | TabSnapshot | MenuItemSnapshot | RadioGroupSnapshot | SeparatorSnapshot;
 //#endregion
 //#region src/utils/filter.d.ts
 type FilterPredicate = (snapshot: NodeSnapshot) => boolean;
@@ -227,6 +229,23 @@ declare function semanticSnapshot(locator: Locator, options?: SemanticSnapshotOp
  */
 declare function rawSnapshot(locator: Locator): Promise<Array<NodeSnapshot>>;
 //#endregion
+//#region src/types/matchers.d.ts
+interface ElementSnapshotMatchers {
+  toMatchSemanticSnapshotFile: (actual: Locator, options?: MatchSemanticSnapshotFileOptions) => Promise<MatcherReturnType>;
+  toMatchMarkdownTableSnapshotFile: (actual: Locator, options?: MatchMarkdownTableSnapshotFileOptions) => Promise<MatcherReturnType>;
+}
+interface MatchSemanticSnapshotFileOptions extends PlaywrightMatchJsonFileOptions, SemanticSnapshotOptions {}
+interface MatchMarkdownTableSnapshotFileOptions extends Omit<PlaywrightMatchTextFileOptions, "fileExtension">, MarkdownTableSnapshotOptions {}
+//#endregion
+//#region src/playwright/matchers.d.ts
+/**
+ * Defines a custom Playwright expect instance with element snapshot matchers for validating DOM elements against stored snapshots.
+ *
+ * @param {PlaywrightValidationFileMatcherConfig} config - Configuration options for file matching behavior
+ * @return {Expect<ElementSnapshotMatchers>} An extended expect instance that includes matcher methods for element snapshot validation.
+ */
+declare function defineElementSnapshotMatchers(config?: PlaywrightValidationFileMatcherConfig): Expect<ElementSnapshotMatchers>;
+//#endregion
 //#region src/utils/predicates.d.ts
 /**
  * Include only elements with the specified role
@@ -243,4 +262,4 @@ declare function excludeRole<TRole extends NodeRole>(role: TRole | Array<TRole>)
  */
 declare function getTextContent(snapshots: Array<NodeSnapshot>): string;
 //#endregion
-export { type ButtonSnapshot, type ColumnHeaderSnapshot, type ComboboxSnapshot, type ContainerSnapshot, type DialogSnapshot, type ElementRole, type ElementSnapshot, type GroupSnapshot, type HeadingSnapshot, type ImageSnapshot, type InputSnapshot, type LinkSnapshot, type MarkdownTableSnapshotOptions, type MenuItemSnapshot, type NodeRole, type NodeSnapshot, type OptionSnapshot, type ProgressbarSnapshot, type RadioGroupSnapshot, type SemanticSnapshotOptions, type SeparatorSnapshot, type SnapshotByRole, type TabSnapshot, type TextSnapshot, excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };
+export { type ButtonSnapshot, type ColumnHeaderSnapshot, type ComboboxSnapshot, type ContainerSnapshot, type DialogSnapshot, type ElementRole, type ElementSnapshot, type ElementSnapshotMatchers, type GroupSnapshot, type HeadingSnapshot, type ImageSnapshot, type InputSnapshot, type LinkSnapshot, type MarkdownTableSnapshotOptions, type MatchMarkdownTableSnapshotFileOptions, type MatchSemanticSnapshotFileOptions, type MenuItemSnapshot, type NodeRole, type NodeSnapshot, type OptionSnapshot, type ProgressbarSnapshot, type RadioGroupSnapshot, type RegionSnapshot, type SemanticSnapshotOptions, type SeparatorSnapshot, type SnapshotByRole, type TabSnapshot, type TextSnapshot, defineElementSnapshotMatchers, excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };

package/dist/index.mjs

@@ -1,3 +1,5 @@
+import { expect } from "@playwright/test";
+import { defineJsonFileMatcher, defineTextFileMatcher } from "@cronn/playwright-file-snapshots";
 import { MarkdownTableSerializer } from "@cronn/lib-file-snapshots";
 import path from "node:path";
 import { packageDirectory } from "package-directory";
@@ -62,23 +64,6 @@ function hasChildren(snapshot) {
 	return "children" in snapshot && snapshot.children.length > 0;
 }
 //#endregion
-//#region src/utils/text.ts
-/**
-* Aggregates and normalizes the text content of all provided snapshots
-*/
-function getTextContent(snapshots) {
-	return mergeTexts(filter({
-		snapshots,
-		predicate: isTextSnapshot
-	}));
-}
-function normalizeText(text) {
-	return text.replaceAll(/\s+/g, " ").trim();
-}
-function mergeTexts(texts) {
-	return normalizeText(texts.map((textNode) => textNode.name).join(" "));
-}
-//#endregion
 //#region src/playwright/proxy.ts
 var ElementSnapshotProxy = class {
 	page;
@@ -154,7 +139,6 @@ var SemanticSnapshotTransformer = class {
 			const { role, children } = normalizedSnapshot;
 			return this.transformedSnapshot(role, children.length === 1 ? children.at(0) : children);
 		}
-		if (snapshot.role === "combobox") return this.simplifyComboboxSnapshot(snapshot);
 		const { role, name, attributes, children } = normalizedSnapshot;
 		return this.transformedSnapshot(role, {
 			name: name.length === 0 ? void 0 : name,
@@ -162,27 +146,18 @@ var SemanticSnapshotTransformer = class {
 			children: children.length === 0 ? void 0 : children
 		});
 	}
-	normalizeElementSnapshot(snapshot, excludeAttributes = []) {
+	normalizeElementSnapshot(snapshot) {
 		const normalizedName = snapshot.name ?? "";
-		const filteredAttributes = this.filterAttributes(snapshot.attributes, excludeAttributes);
+		const transformedAttributes = this.transformAttributes(snapshot);
 		const transformedChildren = this.transformSnapshots(snapshot.children);
 		const nameEqualsChildren = transformedChildren.length === 1 && normalizedName === transformedChildren.at(0);
 		return {
 			role: snapshot.role,
 			name: normalizedName,
-			attributes: filteredAttributes,
+			attributes: transformedAttributes,
 			children: nameEqualsChildren ? [] : transformedChildren
 		};
 	}
-	simplifyComboboxSnapshot(snapshot) {
-		const { role, name, attributes } = this.normalizeElementSnapshot(snapshot, ["options"]);
-		const transformedOptions = snapshot.attributes.options.map((optionSnapshot) => this.simplifyElementSnapshot(optionSnapshot));
-		return this.transformedSnapshot(role, {
-			name,
-			...attributes,
-			options: this.includeComboboxOptions && transformedOptions.length > 0 ? transformedOptions : void 0
-		});
-	}
 	isEmpty(snapshot) {
 		return isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && isEmpty(snapshot.children);
 	}
@@ -192,14 +167,24 @@ var SemanticSnapshotTransformer = class {
 	hasOnlyChildren(snapshot) {
 		return isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && !isEmpty(snapshot.children);
 	}
-	filterAttributes(attributes, exclude) {
+	transformAttributes(snapshot) {
+		const { attributes } = snapshot;
 		const filteredAttributes = {};
-		Object.entries(attributes).forEach(([key, value]) => {
-			if (value === void 0 && !exclude.includes(key)) return;
-			filteredAttributes[key] = value;
+		Object.keys(attributes).forEach((attributeName) => {
+			const transformedAttribute = this.transformAttribute(attributeName, snapshot);
+			if (transformedAttribute === void 0) return;
+			filteredAttributes[attributeName] = transformedAttribute;
 		});
 		return filteredAttributes;
 	}
+	transformAttribute(name, snapshot) {
+		const { role, attributes } = snapshot;
+		if (role === "combobox" && name === "options") {
+			const transformedOptions = attributes.options.map((optionSnapshot) => this.simplifyElementSnapshot(optionSnapshot));
+			return this.includeComboboxOptions && transformedOptions.length > 0 ? transformedOptions : void 0;
+		}
+		return attributes[name];
+	}
 	transformedSnapshot(role, content) {
 		return { [role]: content };
 	}
@@ -271,7 +256,7 @@ function parseTable(snapshot, options) {
 	};
 }
 function getColumnHeaderText(columnHeader, showSortIndicator) {
-	const headerText = getTextContent([columnHeader]);
+	const headerText = getNameOrDefault(columnHeader);
 	const sortType = columnHeader.attributes.sort;
 	if (!showSortIndicator || sortType === void 0) return headerText;
 	return `${headerText} ${sortIndicators[sortType]}`;
@@ -280,7 +265,50 @@ function getCellTexts(row) {
 	return filter({
 		predicate: includeRole(cellRoles),
 		snapshots: row.children
-	}).map((cell) => getTextContent(cell.children));
+	}).map(getNameOrDefault);
+}
+function getNameOrDefault(snapshot) {
+	return snapshot.name ?? "";
+}
+//#endregion
+//#region src/playwright/matchers.ts
+/**
+* Defines a custom Playwright expect instance with element snapshot matchers for validating DOM elements against stored snapshots.
+*
+* @param {PlaywrightValidationFileMatcherConfig} config - Configuration options for file matching behavior
+* @return {Expect<ElementSnapshotMatchers>} An extended expect instance that includes matcher methods for element snapshot validation.
+*/
+function defineElementSnapshotMatchers(config = {}) {
+	async function toMatchSemanticSnapshotFile(actual, options = {}) {
+		return await defineJsonFileMatcher("toMatchSemanticSnapshotFile", config).bind(this)(() => semanticSnapshot(actual, options), options);
+	}
+	async function toMatchMarkdownTableSnapshotFile(actual, options = {}) {
+		return await defineTextFileMatcher("toMatchMarkdownTableSnapshotFile", config).bind(this)(() => markdownTableSnapshot(actual, options), {
+			...options,
+			fileExtension: "md"
+		});
+	}
+	return expect.extend({
+		toMatchSemanticSnapshotFile,
+		toMatchMarkdownTableSnapshotFile
+	});
+}
+//#endregion
+//#region src/utils/text.ts
+/**
+* Aggregates and normalizes the text content of all provided snapshots
+*/
+function getTextContent(snapshots) {
+	return mergeTexts(filter({
+		snapshots,
+		predicate: isTextSnapshot
+	}));
+}
+function normalizeText(text) {
+	return text.replaceAll(/\s+/g, " ").trim();
+}
+function mergeTexts(texts) {
+	return normalizeText(texts.map((textNode) => textNode.name).join(" "));
 }
 //#endregion
-export { excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };
+export { defineElementSnapshotMatchers, excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };

package/package.json

@@ -1,33 +1,21 @@
 {
   "name": "@cronn/element-snapshot",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Element snapshots for Playwright",
+  "homepage": "https://cronn.github.io/file-snapshots/playwright/element-snapshots/",
   "bugs": {
     "url": "https://github.com/cronn/file-snapshots/issues"
   },
-  "author": "cronn",
   "license": "Apache-2.0",
+  "author": "cronn",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cronn/file-snapshots.git",
     "directory": "packages/element-snapshot"
   },
-  "homepage": "https://cronn.github.io/file-snapshots/playwright/element-snapshots/",
-  "engines": {
-    "node": "^20 || ^22 || >=24"
-  },
-  "devEngines": {
-    "runtime": {
-      "name": "node",
-      "version": ">=24.14.1 <25",
-      "onFail": "error"
-    },
-    "packageManager": {
-      "name": "pnpm",
-      "version": ">=10.33.0 <11",
-      "onFail": "error"
-    }
-  },
+  "files": [
+    "dist"
+  ],
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -36,47 +24,58 @@
       "default": "./dist/index.mjs"
     }
   },
-  "files": [
-    "dist"
-  ],
   "dependencies": {
     "package-directory": "8.2.0",
-    "@cronn/lib-file-snapshots": "1.1.0"
+    "@cronn/lib-file-snapshots": "1.1.1",
+    "@cronn/playwright-file-snapshots": "2.0.0"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.2",
     "@playwright/test": "1.59.1",
-    "@trivago/prettier-plugin-sort-imports": "6.0.2",
     "@types/node": "24.12.2",
-    "@typescript/native-preview": "7.0.0-dev.20260406.1",
-    "@vitest/coverage-v8": "4.1.4",
-    "eslint": "10.2.0",
+    "@typescript/native-preview": "7.0.0-dev.20260427.1",
+    "@vitest/coverage-v8": "4.1.5",
+    "eslint": "10.2.1",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-check-file": "3.3.1",
     "eslint-plugin-unused-imports": "4.4.1",
-    "prettier": "3.8.1",
     "publint": "0.3.18",
     "rimraf": "6.1.3",
-    "tsdown": "0.21.7",
-    "typescript-eslint": "8.58.0",
-    "vitest": "4.1.4",
-    "@cronn/playwright-file-snapshots": "1.0.3",
+    "tsdown": "0.21.10",
+    "typescript-eslint": "8.59.0",
+    "vitest": "4.1.5",
+    "node": "runtime:>=24.14.1 <25",
     "@cronn/shared-configs": "0.0.0",
     "@cronn/test-utils": "0.0.0",
-    "@cronn/vitest-file-snapshots": "1.1.0"
+    "@cronn/vitest-file-snapshots": "2.0.0"
   },
   "peerDependencies": {
     "@playwright/test": "^1.55"
   },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.0.7",
+      "onFail": "download"
+    },
+    "runtime": {
+      "name": "node",
+      "version": ">=24.14.1 <25",
+      "onFail": "download"
+    }
+  },
+  "engines": {
+    "node": "^20 || ^22 || >=24"
+  },
   "scripts": {
+    "build": "tsdown",
+    "clean": "rimraf .turbo dist playwright-report test-results coverage",
+    "compile": "tsgo",
     "lint:check": "eslint src/ tests/ --max-warnings=0",
     "lint:fix": "eslint src/ tests/ --max-warnings=0 --fix",
-    "test:unit": "vitest run",
-    "test:unit:coverage": "vitest run --coverage",
-    "test:integration": "playwright test",
     "playwright:install": "playwright install chromium",
-    "compile": "tsgo",
-    "build": "tsdown",
-    "clean": "rimraf .turbo dist playwright-report test-results coverage"
+    "test:integration": "playwright test",
+    "test:unit": "vitest run",
+    "test:unit:coverage": "vitest run --coverage"
   }
 }