@cronn/element-snapshot 0.15.0 → 0.17.0

package/README.md

@@ -1,52 +1,52 @@
-# Element Snapshots
+# Playwright Element Snapshots
 
-Element Snapshots are a custom snapshot implementation inspired by [Playwright's ARIA Snapshots](https://playwright.dev/docs/aria-snapshots#aria-snapshots) and the [Accessibility Object Model](https://wicg.github.io/aom/explainer.html). They cover additional properties, e.g. validation attributes like `required` or `invalid` on form inputs, and are optimized to be serialized as JSON.
+Element snapshots for Playwright.
 
-Element Snapshots are designed to be used in combination with [playwright-file-snapshots](../playwright-file-snapshots/README.md) for writing Playwright tests.
+[Read the full documentation](https://cronn.github.io/file-snapshots/playwright/element-snapshots/)
 
 > [!NOTE]
 > Element Snapshots are currently experimental. Not all HTML elements, ARIA roles and attributes are covered. Breaking changes to the snapshot format are possible.
 
 ## Getting Started
 
-### Adding the library to your project
+### Installation
 
 ```shell
-npm install -D @cronn/element-snapshot
+pnpm add -D @cronn/element-snapshot
 ```
 
 ```shell
-yarn add -D @cronn/element-snapshot
+npm install -D @cronn/element-snapshot
 ```
 
 ```shell
-pnpm add -D @cronn/element-snapshot
+yarn add -D @cronn/element-snapshot
 ```
 
 ## Writing Tests
 
-This package provides multiple snapshot formats for different use cases:
-
-- **General-Purpose Snapshots**: Human-readable JSON format for all element types
-- **Markdown Table Snapshots**: Specialized format for tables and grids ([documentation](docs/markdown-table-snapshot.md))
-- **Custom Snapshots**: Build your own snapshot formats using raw element data and utility functions
-
-### General-Purpose Snapshots
-
-The function `snapshotElement` provides a general-purpose snapshot including all supported roles and attributes. It can be used to achieve a high test coverage, but can become hard to read for complex HTML structures.
-
 ```ts
-import { snapshotElement } from "@cronn/element-snapshot";
+import { semanticSnapshot } from "@cronn/element-snapshot";
 import { defineValidationFileExpect } from "@cronn/playwright-file-snapshots";
 
 const expect = defineValidationFileExpect();
 
 test("matches element snapshot", async ({ page }) => {
-  await expect(snapshotElement(page.getByRole("main"))).toMatchJsonFile();
+  await page.setContent(`
+    <main>
+      <h1>List</h1>
+      <ul>
+        <li>Apple</li>
+        <li>Peach</li>
+      </ul>
+    </main>
+  `);
+
+  await expect(semanticSnapshot(page.getByRole("main"))).toMatchJsonFile();
 });
 ```
 
-Element Snapshot Example:
+**Output (`matches_element_snapshot.json`):**
 
 ```json
 {
@@ -70,62 +70,3 @@ Element Snapshot Example:
   ]
 }
 ```
-
-To improve the specificity of certain tests, `snapshotElement` can be called on certain areas of the page only:
-
-```ts
-test("matches navigation snapshot", async ({ page }) => {
-  await expect(snapshotElement(page.getByRole("navigation"))).toMatchJsonFile({
-    name: "navigation",
-  });
-});
-```
-
-#### Snapshot Options
-
-Snapshot options can be passed when calling the snapshot function:
-
-```ts
-await expect(
-  snapshotElement(page.getByLabel("My select"), {
-    filter: (element) => element.role === "heading",
-  }),
-).toMatchJsonFile({
-  name: "headings",
-});
-```
-
-| Option                   | Default Value | Description                                                                                                                                                                                                                   |
-| ------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `filter`                 | `() => true`  | Include only elements in the snapshot for which the specified filter returns `true`.                                                                                                                                          |
-| `recurseFilter`          | `false`       | Recursively apply specified filter to children of filtered elements. By default, recursion ends when the filter returns `true` for an element. Should be `true` for filters intended to remove specific elements recursively. |
-| `includeComboboxOptions` | `false`       | Include combobox options in the snapshot.                                                                                                                                                                                     |
-
-### Custom Snapshots
-
-The function `snapshotElementRaw` provides the raw element snapshot in a strictly typed structure. This format is not well suited to be read by humans, but can be utilized to derive custom snapshot formats, e.g. for HTML tables.
-
-```ts
-import { snapshotElementRaw } from "@cronn/element-snapshot";
-
-test("matches custom snapshot", async ({ page }) => {
-  const tableSnapshot = await snapshotElementRaw(page.getByRole("table"));
-  const markdownTable = transformToMarkdownTable(tableSnapshot);
-
-  await expect(markdownTable).toMatchTextFile({ fileExtension: "md" });
-});
-
-function transformToMarkdownTable(snapshot: Array<NodeSnapshot>): string {
-  // transform table snapshot to markdown table
-}
-```
-
-#### Utility Functions for Custom Snapshots
-
-| Function         | Description                                                           |
-| ---------------- | --------------------------------------------------------------------- |
-| `filter`         | Filters node snapshots based on the provided predicate function.      |
-| `filterByRole`   | Filters node snapshots by the specified role.                         |
-| `includeRole`    | Includes only elements with the specified role.                       |
-| `excludeRole`    | Excludes elements with the specified role.                            |
-| `getTextContent` | Aggregates and normalizes the text content of all provided snapshots. |

package/dist/browser-lib.iife.js

@@ -28,6 +28,14 @@
 			name
 		};
 	}
+	function elementSnapshot(values) {
+		return {
+			role: values.role,
+			name: values.name,
+			attributes: values.attributes ?? {},
+			children: values.children ?? []
+		};
+	}
 	//#endregion
 	//#region src/utils/guards.ts
 	function isTextSnapshot(snapshot) {
@@ -38,6 +46,14 @@
 		return role.includes(snapshot.role);
 	}
 	//#endregion
+	//#region src/utils/predicates.ts
+	/**
+	* Include only elements with the specified role
+	*/
+	function includeRole(role) {
+		return (snapshot) => hasRole(role, snapshot);
+	}
+	//#endregion
 	//#region src/utils/filter.ts
 	function filter(options) {
 		const { predicate, snapshots, recurse = false } = options;
@@ -58,6 +74,16 @@
 			};
 		});
 	}
+	/**
+	* Filters node snapshots by a specific role
+	*/
+	function filterByRole(role, snapshots) {
+		return filter({
+			predicate: includeRole(role),
+			recurse: false,
+			snapshots
+		});
+	}
 	function hasChildren(snapshot) {
 		return "children" in snapshot && snapshot.children.length > 0;
 	}
@@ -98,18 +124,12 @@
 		if (textNode.textContent === null) return null;
 		const normalizedText = normalizeText(textNode.textContent);
 		if (normalizedText.length === 0) return null;
-		return {
-			role: "text",
-			name: normalizedText
-		};
+		return textSnapshot(normalizedText);
 	}
 	function snapshotPresentationalChildren(node) {
 		const accessibleTextContent = resolveAccessibleTextContent(node);
 		if (accessibleTextContent === void 0 || accessibleTextContent.length === 0) return [];
-		return [{
-			role: "text",
-			name: accessibleTextContent
-		}];
+		return [textSnapshot(accessibleTextContent)];
 	}
 	function resolveAccessibleTextContent(node, excludedNodes = []) {
 		const children = snapshotChildren(node, excludedNodes);
@@ -128,10 +148,10 @@
 	//#endregion
 	//#region src/browser/state.ts
 	function disableableAttributes(element) {
-		return { disabled: booleanAttribute(isNativeInputElement(element) || element instanceof HTMLButtonElement ? element.hasAttribute("disabled") : false) ?? booleanAttribute(element.ariaDisabled) };
+		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.ariaSelected) };
+		return { selected: booleanAttribute(element instanceof HTMLOptionElement ? element.hasAttribute("selected") : false) ?? booleanAttribute(element.ariaSelected) };
 	}
 	function inputStateAttributes(element) {
 		const supportsHtmlAttributes = isNativeInputElement(element);
@@ -182,7 +202,7 @@
 		if (element.ariaDescription !== null) return element.ariaDescription;
 	}
 	//#endregion
-	//#region src/browser/container.ts
+	//#region src/types/elements/container.ts
 	const CONTAINER_ROLES = new Set([
 		"paragraph",
 		"list",
@@ -213,15 +233,16 @@
 		"tabpanel",
 		"label"
 	]);
+	//#endregion
+	//#region src/browser/container.ts
 	const NAMEABLE_CONTAINER_ROLES = new Set(["label"]);
 	function snapshotContainer(role, element) {
 		const children = snapshotChildren(element);
-		return {
+		return elementSnapshot({
 			role,
 			name: resolveAccessibleName(element, NAMEABLE_CONTAINER_ROLES.has(role)),
-			attributes: {},
 			children
-		};
+		});
 	}
 	function isContainerRole(role) {
 		return CONTAINER_ROLES.has(role);
@@ -248,62 +269,62 @@
 	//#endregion
 	//#region src/browser/role.ts
 	const ELEMENT_ROLES = {
-		main: "main",
-		nav: "navigation",
-		form: "form",
-		header: "banner",
-		section: "region",
+		a: "link",
 		article: "article",
 		aside: "complementary",
-		search: "search",
+		button: "button",
+		dd: "definition",
+		dl: "descriptionlist",
+		dt: "term",
+		fieldset: "group",
 		footer: "contentinfo",
-		p: "paragraph",
+		form: "form",
 		h1: "heading",
 		h2: "heading",
 		h3: "heading",
 		h4: "heading",
 		h5: "heading",
 		h6: "heading",
-		ul: "list",
-		ol: "list",
-		li: "listitem",
-		a: "link",
-		button: "button",
+		header: "banner",
+		hr: "separator",
+		img: "img",
 		input: resolveInputRole,
-		textarea: "textbox",
-		select: "combobox",
+		label: "label",
+		legend: "label",
+		li: "listitem",
+		main: "main",
+		nav: "navigation",
+		ol: "list",
 		option: "option",
-		dl: "descriptionlist",
-		dt: "term",
-		dd: "definition",
+		p: "paragraph",
+		progress: "progressbar",
+		search: "search",
+		section: "region",
+		select: "combobox",
 		table: "table",
-		thead: "rowgroup",
 		tbody: "rowgroup",
+		textarea: "textbox",
+		td: "cell",
 		tfoot: "rowgroup",
-		tr: "row",
 		th: resolveTableHeaderCellRole,
-		td: "cell",
-		fieldset: "group",
-		progress: "progressbar",
-		hr: "separator",
-		img: "img",
-		label: "label",
-		legend: "label"
+		thead: "rowgroup",
+		tr: "row",
+		ul: "list"
 	};
 	const CONTEXT_DEPENDENT_ROLES = {
 		banner: isTopLevelBanner,
-		region: hasAccessibleName,
-		term: isWithinDescriptionList,
+		cell: isWithinTableRow,
+		columnheader: isWithinTableRowOrGridRow,
 		definition: isWithinDescriptionList,
+		gridcell: isWithinGridRow,
 		listitem: isWithinList,
 		menuitem: isWithinMenu,
-		rowgroup: isWithinTableOrGrid,
+		region: hasAccessibleName,
 		row: isWithinTableOrGrid,
-		columnheader: isWithinTableRowOrGridRow,
+		rowgroup: isWithinTableOrGrid,
 		rowheader: isWithinTableRowOrGridRow,
-		cell: isWithinTableRow,
-		gridcell: isWithinGridRow,
-		tab: isWithinTablist
+		tab: isWithinTablist,
+		term: isWithinDescriptionList
 	};
 	const INPUT_ROLES = {
 		button: "button",
@@ -416,34 +437,30 @@
 	function snapshotInputElement(element) {
 		const inputRole = resolveInputRole(element);
 		if (inputRole === void 0 || inputRole === "button" || inputRole === "combobox") return null;
-		const value = resolveInputValue(element);
-		return {
+		return elementSnapshot({
 			role: inputRole,
 			name: resolveInputLabel(element),
 			attributes: {
-				value,
+				value: resolveInputValue(element),
 				checked: resolveChecked(element),
-				...snapshotCommonInputAttributes(element, value === void 0)
-			},
-			children: []
-		};
+				...snapshotCommonInputAttributes(element)
+			}
+		});
 	}
 	function snapshotTextareaElement(element) {
-		const value = resolveInputValue(element);
-		return {
+		return elementSnapshot({
 			role: "textbox",
 			name: resolveInputLabel(element),
 			attributes: {
-				value,
-				...snapshotCommonInputAttributes(element, value === void 0)
-			},
-			children: []
-		};
+				value: resolveInputValue(element),
+				...snapshotCommonInputAttributes(element)
+			}
+		});
 	}
-	function snapshotCommonInputAttributes(element, isEmpty) {
+	function snapshotCommonInputAttributes(element) {
 		return {
 			...discribableAttributes(element),
-			placeholder: isEmpty ? resolvePlaceholder(element) : void 0,
+			placeholder: resolvePlaceholder(element),
 			...inputStateAttributes(element)
 		};
 	}
@@ -475,16 +492,15 @@
 	function snapshotCombobox(element) {
 		if (!isCombobox(element)) return null;
 		const options = snapshotOptions(element);
-		const value = resolveValue$1(element);
 		return {
 			role: "combobox",
 			name: resolveInputLabel(element),
 			attributes: {
-				value,
-				...snapshotCommonInputAttributes(element, value === void 0)
+				value: resolveValue$1(element),
+				...snapshotCommonInputAttributes(element),
+				options
 			},
-			children: [],
-			options
+			children: []
 		};
 	}
 	function isCombobox(element) {
@@ -501,20 +517,24 @@
 		return selectedLabels;
 	}
 	function snapshotOptions(element) {
-		return resolveOptions(element).map(snapshotOption).filter((childSnapshot) => childSnapshot !== null);
+		const optionsContainer = resolveOptionsContainer(element);
+		if (optionsContainer === null) return [];
+		return filterByRole("option", snapshotChildren(optionsContainer));
 	}
-	function resolveOptions(element) {
-		if (element instanceof HTMLSelectElement) return Array.from(element.options);
+	function resolveOptionsContainer(element) {
+		if (element instanceof HTMLSelectElement) return element;
 		const controlledElement = resolveElementReference(element, "aria-controls");
-		if (controlledElement === null) return [];
-		const optionSelector = selectorList("option", roleSelector("option"));
-		return Array.from(controlledElement.querySelectorAll(optionSelector));
+		if (controlledElement === null) return null;
+		return controlledElement;
 	}
 	function snapshotOption(element) {
 		return {
 			role: "option",
 			name: resolveAccessibleName(element),
-			attributes: { selected: element instanceof HTMLOptionElement ? booleanAttribute(element.selected) : booleanAttribute(element.ariaSelected) },
+			attributes: {
+				...selectableAttributes(element),
+				...disableableAttributes(element)
+			},
 			children: snapshotChildren(element)
 		};
 	}
@@ -537,19 +557,18 @@
 	//#endregion
 	//#region src/browser/group.ts
 	function snapshotGroup(element) {
-		return {
+		return elementSnapshot({
 			role: "group",
 			name: resolveGroupName(element),
-			attributes: {},
 			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) {
+	function snapshotRadioGroup(element) {
 		return {
 			role: "radiogroup",
 			name: resolveAccessibleName(element, false),
@@ -577,12 +596,10 @@
 	function snapshotImage(element) {
 		const imageName = resolveImageName(element);
 		if (imageName === void 0) return null;
-		return {
+		return elementSnapshot({
 			role: "img",
-			name: imageName,
-			attributes: {},
-			children: []
-		};
+			name: imageName
+		});
 	}
 	function resolveImageName(element) {
 		if (element instanceof HTMLImageElement) return stringAttribute(element.alt);
@@ -631,11 +648,10 @@
 	//#endregion
 	//#region src/browser/separator.ts
 	function snapshotSeparator(element) {
-		return {
+		return elementSnapshot({
 			role: "separator",
-			attributes: {},
 			children: snapshotPresentationalChildren(element)
-		};
+		});
 	}
 	//#endregion
 	//#region src/browser/tab.ts
@@ -651,13 +667,15 @@
 		};
 	}
 	//#endregion
-	//#region src/browser/table.ts
+	//#region src/types/elements/table.ts
 	const SORT_TYPES = new Set([
 		"ascending",
 		"descending",
 		"other"
 	]);
-	function snapshotColumnheader(element) {
+	//#endregion
+	//#region src/browser/table.ts
+	function snapshotColumnHeader(element) {
 		return {
 			role: "columnheader",
 			name: resolveAccessibleName(element),
@@ -668,27 +686,27 @@
 	//#endregion
 	//#region src/browser/element.ts
 	const ROLE_SNAPSHOTS = {
+		alertdialog: snapshotDialogWithRole("alertdialog"),
 		button: snapshotButton,
 		checkbox: snapshotInput,
+		columnheader: snapshotColumnHeader,
 		combobox: snapshotCombobox,
-		option: snapshotOption,
+		dialog: snapshotDialogWithRole("dialog"),
+		group: snapshotGroup,
 		heading: snapshotHeading,
+		img: snapshotImage,
+		menuitem: snapshotMenuitem,
+		option: snapshotOption,
+		progressbar: snapshotProgressbar,
 		link: snapshotLink,
 		radio: snapshotInput,
+		radiogroup: snapshotRadioGroup,
 		searchbox: snapshotInput,
+		separator: snapshotSeparator,
 		slider: snapshotInput,
 		spinbutton: snapshotInput,
-		textbox: snapshotInput,
-		dialog: snapshotDialogWithRole("dialog"),
-		alertdialog: snapshotDialogWithRole("alertdialog"),
 		tab: snapshotTab,
-		menuitem: snapshotMenuitem,
-		columnheader: snapshotColumnheader,
-		group: snapshotGroup,
-		radiogroup: snapshotRadiogroup,
-		progressbar: snapshotProgressbar,
-		img: snapshotImage,
-		separator: snapshotSeparator
+		textbox: snapshotInput
 	};
 	function snapshotElement(element) {
 		return snapshotNodeRecursive(element);
@@ -712,14 +730,14 @@
 		return snapshotContainer(elementRole, node);
 	}
 	const UNSUPPORTED_ELEMENTS = new Set([
-		"style",
-		"script",
-		"noscript",
-		"picture",
 		"audio",
-		"video",
 		"figure",
-		"template"
+		"noscript",
+		"picture",
+		"script",
+		"style",
+		"template",
+		"video"
 	]);
 	function isSupportedElement(node) {
 		if (!(node instanceof HTMLElement || node instanceof SVGElement)) return false;

package/dist/index.d.mts

@@ -1,19 +1,22 @@
 import { Locator } from "@playwright/test";
 
-//#region src/browser/state.d.ts
+//#region src/types/attributes.d.ts
 interface DisableableAttributes {
   disabled?: boolean;
 }
 interface SelectableAttributes {
   selected?: boolean;
 }
+interface DiscribableAttributes {
+  description?: string;
+}
 interface InputStateAttributes extends DisableableAttributes {
   readonly?: boolean;
   required?: boolean;
   invalid?: boolean;
 }
 //#endregion
-//#region src/browser/button.d.ts
+//#region src/types/elements/button.d.ts
 interface ButtonSnapshot extends GenericElementSnapshot<"button", ButtonAttributes> {}
 interface ButtonAttributes extends DisableableAttributes {
   expanded?: boolean;
@@ -21,110 +24,108 @@ interface ButtonAttributes extends DisableableAttributes {
 }
 type PressedValue = true | "mixed";
 //#endregion
-//#region src/browser/description.d.ts
-interface DiscribableAttributes {
-  description?: string;
-}
-//#endregion
-//#region src/browser/input.d.ts
-interface InputSnapshot extends GenericElementSnapshot<CommonInputRole, InputAttributes> {}
-type InputRole = "button" | "combobox" | CommonInputRole;
-type CommonInputRole = "checkbox" | "radio" | "searchbox" | "slider" | "spinbutton" | "textbox";
-interface InputAttributes extends CommonInputAttributes {
-  value?: string;
-  checked?: boolean;
-}
-interface CommonInputAttributes extends InputStateAttributes, DiscribableAttributes {
-  placeholder?: string;
-}
-//#endregion
-//#region src/browser/combobox.d.ts
-interface ComboboxSnapshot extends GenericElementSnapshot<"combobox", ComboboxAttributes> {
-  options: Array<OptionSnapshot>;
-}
-interface ComboboxAttributes extends CommonInputAttributes {
-  value?: string | Array<string>;
-}
-interface OptionSnapshot extends GenericElementSnapshot<"option", OptionAttributes> {}
-interface OptionAttributes {
-  selected?: boolean;
-}
-//#endregion
-//#region src/browser/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/browser/dialog.d.ts
+//#region src/types/elements/dialog.d.ts
 interface DialogSnapshot extends GenericElementSnapshot<DialogRole, DialogAttributes> {}
 type DialogRole = "dialog" | "alertdialog";
 interface DialogAttributes extends DiscribableAttributes {
   modal?: boolean;
 }
 //#endregion
-//#region src/browser/group.d.ts
+//#region src/types/elements/group.d.ts
 interface GroupSnapshot extends GenericElementSnapshot<"group"> {}
-interface RadiogroupSnapshot extends GenericElementSnapshot<"radiogroup", RadiogroupAttributes> {}
+interface RadioGroupSnapshot extends GenericElementSnapshot<"radiogroup", RadiogroupAttributes> {}
 interface RadiogroupAttributes extends DiscribableAttributes {}
 //#endregion
-//#region src/browser/heading.d.ts
+//#region src/types/elements/heading.d.ts
 interface HeadingSnapshot extends GenericElementSnapshot<"heading", HeadingAttributes> {}
 interface HeadingAttributes {
   level?: number;
 }
 //#endregion
-//#region src/browser/image.d.ts
+//#region src/types/elements/image.d.ts
 interface ImageSnapshot extends GenericElementSnapshot<"img"> {}
 //#endregion
-//#region src/browser/link.d.ts
+//#region src/types/elements/input.d.ts
+interface InputSnapshot extends GenericElementSnapshot<CommonInputRole, InputAttributes> {}
+type InputRole = "combobox" | CommonInputRole;
+type CommonInputRole = "button" | "checkbox" | "radio" | "searchbox" | "slider" | "spinbutton" | "textbox";
+interface InputAttributes extends CommonInputAttributes {
+  value?: string;
+  checked?: boolean;
+}
+interface CommonInputAttributes extends InputStateAttributes, DiscribableAttributes {
+  placeholder?: string;
+}
+interface ComboboxSnapshot extends GenericElementSnapshot<"combobox", ComboboxAttributes> {}
+interface ComboboxAttributes extends CommonInputAttributes {
+  value?: string | Array<string>;
+  options: Array<OptionSnapshot>;
+}
+interface OptionSnapshot extends GenericElementSnapshot<"option", OptionAttributes> {}
+interface OptionAttributes extends SelectableAttributes, DisableableAttributes {}
+//#endregion
+//#region src/types/elements/link.d.ts
 interface LinkSnapshot extends GenericElementSnapshot<"link", LinkAttributes> {}
 interface LinkAttributes {
   url?: string;
 }
 //#endregion
-//#region src/browser/list.d.ts
-interface MenuitemSnapshot extends GenericElementSnapshot<"menuitem", MenuitemAttributes> {}
+//#region src/types/elements/list.d.ts
+interface MenuItemSnapshot extends GenericElementSnapshot<"menuitem", MenuitemAttributes> {}
 interface MenuitemAttributes extends LinkAttributes, DisableableAttributes {}
 //#endregion
-//#region src/browser/progressbar.d.ts
+//#region src/types/elements/progressbar.d.ts
 interface ProgressbarSnapshot extends GenericElementSnapshot<"progressbar", ProgressbarAttributes> {}
 interface ProgressbarAttributes {
   value?: number;
 }
 //#endregion
-//#region src/browser/separator.d.ts
+//#region src/types/elements/separator.d.ts
 interface SeparatorSnapshot extends GenericElementSnapshot<"separator"> {}
 //#endregion
-//#region src/browser/tab.d.ts
+//#region src/types/elements/tab.d.ts
 interface TabSnapshot extends GenericElementSnapshot<"tab", TabAttributes> {}
 interface TabAttributes extends DisableableAttributes, SelectableAttributes {}
 //#endregion
-//#region src/browser/table.d.ts
-interface ColumnheaderSnapshot extends GenericElementSnapshot<"columnheader", ColumnheaderAttributes> {}
+//#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> {}
 interface ColumnheaderAttributes {
   sort?: SortType;
 }
-declare const SORT_TYPES: Set<"ascending" | "descending" | "other">;
 type SortType = SetValues<typeof SORT_TYPES>;
 //#endregion
-//#region src/browser/text.d.ts
+//#region src/types/elements/text.d.ts
 interface TextSnapshot {
   role: "text";
   name: string;
 }
 //#endregion
-//#region src/browser/types.d.ts
-type NodeRole = ElementRole | "text";
-type ElementRole = "heading" | "link" | "button" | "option" | "tab" | "menuitem" | "columnheader" | "group" | "radiogroup" | "progressbar" | "img" | "separator" | ContainerRole | InputRole | DialogRole;
+//#region src/types/snapshot.d.ts
+type NodeRole = ElementRole | TextRole;
 type NodeSnapshot = ElementSnapshot | TextSnapshot;
-type ElementSnapshot = ContainerSnapshot | HeadingSnapshot | LinkSnapshot | ButtonSnapshot | InputSnapshot | ComboboxSnapshot | OptionSnapshot | DialogSnapshot | TabSnapshot | MenuitemSnapshot | ColumnheaderSnapshot | GroupSnapshot | RadiogroupSnapshot | ProgressbarSnapshot | ImageSnapshot | SeparatorSnapshot;
+type SnapshotByRole<TRole extends NodeRole> = NodeSnapshot & {
+  role: TRole;
+};
 interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes = Record<string, unknown>> {
   role: TRole;
   name?: string;
   attributes: TAttributes;
   children: Array<NodeSnapshot>;
 }
-type SetValues<TSet> = TSet extends Set<infer TValue> ? TValue : never;
+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 {
@@ -140,11 +141,6 @@ interface MarkdownTableSnapshotOptions {
  */
 declare function markdownTableSnapshot(locator: Locator, options?: MarkdownTableSnapshotOptions): Promise<string>;
 //#endregion
-//#region src/types/snapshot.d.ts
-type SnapshotByRole<TRole extends NodeRole> = NodeSnapshot & {
-  role: TRole;
-};
-//#endregion
 //#region src/utils/filter.d.ts
 type FilterPredicate = (snapshot: NodeSnapshot) => boolean;
 type GuardedFilterPredicate<TSnapshot extends NodeSnapshot> = (snapshot: NodeSnapshot) => snapshot is TSnapshot;
@@ -186,7 +182,7 @@ declare function filter(options: FilterOptions): Array<NodeSnapshot>;
 declare function filterByRole<TRole extends NodeRole>(role: TRole, snapshots: Array<NodeSnapshot>): Array<SnapshotByRole<TRole>>;
 //#endregion
 //#region src/playwright/snapshot.d.ts
-interface ElementSnapshotOptions {
+interface SemanticSnapshotOptions {
   /**
    * Include only elements in the snapshot for which the specified filter returns `true`
    *
@@ -210,23 +206,26 @@ interface ElementSnapshotOptions {
   includeComboboxOptions?: boolean;
 }
 /**
- * Creates an Element Snapshot of the specified element
+ * Captures a semantic snapshot of the specified locator's DOM structure.
  *
- * @example
- * ```ts
- * await expect(snapshotElement(page.getByRole("main"))).toMatchJsonSnapshot();
- * ```
- * @param locator Locator for the element to snapshot
- * @experimental
+ * This function creates a raw snapshot of the DOM element identified by the locator
+ * and transforms it into a semantic representation using the provided options.
+ *
+ * @param locator - The Locator instance that identifies the DOM element to snapshot
+ * @param options - Optional configuration settings for controlling the snapshot behavior
+ * @return A promise that resolves to the semantic snapshot
  */
-declare function snapshotElement(locator: Locator, options?: ElementSnapshotOptions): Promise<unknown>;
+declare function semanticSnapshot(locator: Locator, options?: SemanticSnapshotOptions): Promise<unknown>;
 /**
- * Creates an Element Snapshot of the specified element, returning the raw snapshot data for custom transformations
+ * Captures a raw snapshot of the element matched by the provided locator.
+ *
+ * Returns an array of node snapshots representing the current state of the matched elements
+ * in the DOM, including their properties, attributes, and structure.
  *
- * @param locator Locator for the element to snapshot
- * @experimental
+ * @param locator - The Locator instance used to identify the target element to snapshot
+ * @return A promise that resolves to an array of NodeSnapshot objects representing the captured element
  */
-declare function snapshotElementRaw(locator: Locator): Promise<Array<NodeSnapshot>>;
+declare function rawSnapshot(locator: Locator): Promise<Array<NodeSnapshot>>;
 //#endregion
 //#region src/utils/predicates.d.ts
 /**
@@ -244,4 +243,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 SeparatorSnapshot, type SnapshotByRole, type TabSnapshot, type TextSnapshot, excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, snapshotElement, snapshotElementRaw };
+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 };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { markdownTable } from "markdown-table";
+import { MarkdownTableSerializer } from "@cronn/lib-file-snapshots";
 import path from "node:path";
 import { packageDirectory } from "package-directory";
 //#region src/utils/guards.ts
@@ -106,8 +106,8 @@ var ElementSnapshotProxy = class {
 	}
 };
 //#endregion
-//#region src/playwright/transformer.ts
-var ElementSnapshotTransformer = class {
+//#region src/playwright/semantic-snapshot-transformer.ts
+var SemanticSnapshotTransformer = class {
 	filter;
 	recurseFilter;
 	includeComboboxOptions;
@@ -162,21 +162,21 @@ var ElementSnapshotTransformer = class {
 			children: children.length === 0 ? void 0 : children
 		});
 	}
-	normalizeElementSnapshot(snapshot) {
+	normalizeElementSnapshot(snapshot, excludeAttributes = []) {
 		const normalizedName = snapshot.name ?? "";
-		const sparseAttributes = this.removeUndefinedProperties(snapshot.attributes);
+		const filteredAttributes = this.filterAttributes(snapshot.attributes, excludeAttributes);
 		const transformedChildren = this.transformSnapshots(snapshot.children);
 		const nameEqualsChildren = transformedChildren.length === 1 && normalizedName === transformedChildren.at(0);
 		return {
 			role: snapshot.role,
 			name: normalizedName,
-			attributes: sparseAttributes,
+			attributes: filteredAttributes,
 			children: nameEqualsChildren ? [] : transformedChildren
 		};
 	}
 	simplifyComboboxSnapshot(snapshot) {
-		const { role, name, attributes } = this.normalizeElementSnapshot(snapshot);
-		const transformedOptions = snapshot.options.map((optionSnapshot) => this.simplifyElementSnapshot(optionSnapshot));
+		const { role, name, attributes } = this.normalizeElementSnapshot(snapshot, ["options"]);
+		const transformedOptions = snapshot.attributes.options.map((optionSnapshot) => this.simplifyElementSnapshot(optionSnapshot));
 		return this.transformedSnapshot(role, {
 			name,
 			...attributes,
@@ -192,12 +192,13 @@ var ElementSnapshotTransformer = class {
 	hasOnlyChildren(snapshot) {
 		return isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && !isEmpty(snapshot.children);
 	}
-	removeUndefinedProperties(attributes) {
-		const sparseAttributes = {};
+	filterAttributes(attributes, exclude) {
+		const filteredAttributes = {};
 		Object.entries(attributes).forEach(([key, value]) => {
-			if (value !== void 0) sparseAttributes[key] = value;
+			if (value === void 0 && !exclude.includes(key)) return;
+			filteredAttributes[key] = value;
 		});
-		return sparseAttributes;
+		return filteredAttributes;
 	}
 	transformedSnapshot(role, content) {
 		return { [role]: content };
@@ -206,26 +207,29 @@ var ElementSnapshotTransformer = class {
 //#endregion
 //#region src/playwright/snapshot.ts
 /**
-* Creates an Element Snapshot of the specified element
+* Captures a semantic snapshot of the specified locator's DOM structure.
 *
-* @example
-* ```ts
-* await expect(snapshotElement(page.getByRole("main"))).toMatchJsonSnapshot();
-* ```
-* @param locator Locator for the element to snapshot
-* @experimental
+* This function creates a raw snapshot of the DOM element identified by the locator
+* and transforms it into a semantic representation using the provided options.
+*
+* @param locator - The Locator instance that identifies the DOM element to snapshot
+* @param options - Optional configuration settings for controlling the snapshot behavior
+* @return A promise that resolves to the semantic snapshot
 */
-async function snapshotElement(locator, options) {
-	const snapshot = await snapshotElementRaw(locator);
-	return new ElementSnapshotTransformer(options).transform(snapshot);
+async function semanticSnapshot(locator, options) {
+	const snapshot = await rawSnapshot(locator);
+	return new SemanticSnapshotTransformer(options).transform(snapshot);
 }
 /**
-* Creates an Element Snapshot of the specified element, returning the raw snapshot data for custom transformations
+* Captures a raw snapshot of the element matched by the provided locator.
+*
+* Returns an array of node snapshots representing the current state of the matched elements
+* in the DOM, including their properties, attributes, and structure.
 *
-* @param locator Locator for the element to snapshot
-* @experimental
+* @param locator - The Locator instance used to identify the target element to snapshot
+* @return A promise that resolves to an array of NodeSnapshot objects representing the captured element
 */
-async function snapshotElementRaw(locator) {
+async function rawSnapshot(locator) {
 	return await new ElementSnapshotProxy(locator.page()).snapshotElement(locator);
 }
 //#endregion
@@ -245,8 +249,8 @@ const sortIndicators = {
 * Creates a Markdown table snapshot from a table or grid element
 */
 async function markdownTableSnapshot(locator, options = {}) {
-	const { columnHeaders, rows } = parseTable(await snapshotElementRaw(locator), options);
-	return markdownTable([columnHeaders, ...rows]);
+	const parsedTable = parseTable(await rawSnapshot(locator), options);
+	return new MarkdownTableSerializer().serialize(parsedTable);
 }
 function parseTable(snapshot, options) {
 	const { showSortIndicator = true } = options;
@@ -262,7 +266,7 @@ function parseTable(snapshot, options) {
 	const columnHeaders = filterByRole("columnheader", headerRow.children);
 	if (columnHeaders.length === 0) throw new Error("No column headers found");
 	return {
-		columnHeaders: columnHeaders.map((columnHeader) => getColumnHeaderText(columnHeader, showSortIndicator)),
+		columns: columnHeaders.map((columnHeader) => getColumnHeaderText(columnHeader, showSortIndicator)),
 		rows: bodyRows.map(getCellTexts)
 	};
 }
@@ -279,4 +283,4 @@ function getCellTexts(row) {
 	}).map((cell) => getTextContent(cell.children));
 }
 //#endregion
-export { excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, snapshotElement, snapshotElementRaw };
+export { excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/element-snapshot",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Element snapshots for Playwright",
   "bugs": {
     "url": "https://github.com/cronn/file-snapshots/issues"
@@ -12,19 +12,19 @@
     "url": "git+https://github.com/cronn/file-snapshots.git",
     "directory": "packages/element-snapshot"
   },
-  "homepage": "https://github.com/cronn/file-snapshots",
+  "homepage": "https://cronn.github.io/file-snapshots/playwright/element-snapshots/",
   "engines": {
     "node": "^20 || ^22 || >=24"
   },
   "devEngines": {
     "runtime": {
       "name": "node",
-      "version": ">=24.13 <25",
+      "version": ">=24.14.1 <25",
       "onFail": "error"
     },
     "packageManager": {
       "name": "pnpm",
-      "version": ">=10.28.2 <11",
+      "version": ">=10.33.0 <11",
       "onFail": "error"
     }
   },
@@ -40,29 +40,30 @@
     "dist"
   ],
   "dependencies": {
-    "markdown-table": "3.0.4",
-    "package-directory": "8.2.0"
+    "package-directory": "8.2.0",
+    "@cronn/lib-file-snapshots": "1.1.0"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.2",
-    "@playwright/test": "1.58.2",
+    "@playwright/test": "1.59.1",
     "@trivago/prettier-plugin-sort-imports": "6.0.2",
-    "@types/node": "24.12.0",
-    "@typescript/native-preview": "7.0.0-dev.20260309.1",
-    "@vitest/coverage-v8": "4.0.18",
-    "eslint": "10.0.3",
+    "@types/node": "24.12.2",
+    "@typescript/native-preview": "7.0.0-dev.20260406.1",
+    "@vitest/coverage-v8": "4.1.4",
+    "eslint": "10.2.0",
     "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",
-    "tsdown": "0.21.1",
-    "typescript-eslint": "8.56.1",
-    "vitest": "4.0.18",
-    "@cronn/playwright-file-snapshots": "1.0.1",
+    "rimraf": "6.1.3",
+    "tsdown": "0.21.7",
+    "typescript-eslint": "8.58.0",
+    "vitest": "4.1.4",
+    "@cronn/playwright-file-snapshots": "1.0.3",
     "@cronn/shared-configs": "0.0.0",
     "@cronn/test-utils": "0.0.0",
-    "@cronn/vitest-file-snapshots": "1.0.1"
+    "@cronn/vitest-file-snapshots": "1.1.0"
   },
   "peerDependencies": {
     "@playwright/test": "^1.55"
@@ -75,6 +76,7 @@
     "test:integration": "playwright test",
     "playwright:install": "playwright install chromium",
     "compile": "tsgo",
-    "build": "tsdown"
+    "build": "tsdown",
+    "clean": "rimraf .turbo dist playwright-report test-results coverage"
   }
 }