@cronn/element-snapshot 0.11.0 → 0.13.0

package/README.md

@@ -89,10 +89,11 @@ await expect(
 });
 ```
 
-| Option                   | Default Value | Description                                                                          |
-| ------------------------ | ------------- | ------------------------------------------------------------------------------------ |
-| `filter`                 | `() => true`  | Include only elements in the snapshot for which the specified filter returns `true`. |
-| `includeComboboxOptions` | `false`       | Include combobox options in the snapshot.                                            |
+| 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
 

package/dist/browser-lib.iife.js

@@ -26,24 +26,37 @@
 //#endregion
 //#region src/browser/children.ts
 	function snapshotChildren(node, excludedNodes = []) {
-		const children = Array.from(node.childNodes).map((node) => snapshotNodeRecursive(node, excludedNodes)).filter((childSnapshot) => childSnapshot !== null).flat();
-		return children.length > 0 ? children : void 0;
+		return Array.from(node.childNodes).map((childNode) => snapshotNodeRecursive(childNode, excludedNodes)).filter((childSnapshot) => childSnapshot !== null).flat();
+	}
+
+//#endregion
+//#region src/utils/guards.ts
+	function isTextSnapshot(snapshot) {
+		return snapshot.role === "text";
 	}
 
 //#endregion
 //#region src/utils/snapshot.ts
-	function filterSnapshots(snapshots, filter) {
+	function filterSnapshots(options) {
+		const { filter, snapshots, recurse = false } = options;
 		return snapshots.flatMap((snapshot) => {
-			const filteredChildren = hasChildren(snapshot) ? filterSnapshots(snapshot.children ?? [], filter) : [];
-			if (filter(snapshot)) return {
+			const isFilteredIn = filter(snapshot);
+			if (isFilteredIn && !recurse) return snapshot;
+			if (!isFilteredIn && recurse) return [];
+			const filteredChildren = hasChildren(snapshot) ? filterSnapshots({
+				filter,
+				snapshots: snapshot.children ?? [],
+				recurse
+			}) : [];
+			if (!isFilteredIn) return filteredChildren;
+			return {
 				...snapshot,
-				children: filteredChildren.length > 0 ? filteredChildren : void 0
+				children: filteredChildren
 			};
-			return filteredChildren;
 		});
 	}
 	function hasChildren(snapshot) {
-		return "children" in snapshot && snapshot.children !== void 0 && snapshot.children.length > 0;
+		return "children" in snapshot && snapshot.children.length > 0;
 	}
 
 //#endregion
@@ -59,7 +72,7 @@
 	}
 	function snapshotPresentationalChildren(node) {
 		const accessibleTextContent = resolveAccessibleTextContent(node);
-		if (accessibleTextContent === void 0 || accessibleTextContent.length === 0) return;
+		if (accessibleTextContent === void 0 || accessibleTextContent.length === 0) return [];
 		return [{
 			role: "text",
 			name: accessibleTextContent
@@ -68,7 +81,10 @@
 	function resolveAccessibleTextContent(node, excludedNodes = []) {
 		const children = snapshotChildren(node, excludedNodes);
 		if (children === void 0) return;
-		const normalizedText = normalizeText(filterSnapshots(children, (element) => element.role === "text").map((textNode) => textNode.name).join(" "));
+		const normalizedText = normalizeText(filterSnapshots({
+			snapshots: children,
+			filter: isTextSnapshot
+		}).map((textNode) => textNode.name).join(" "));
 		return normalizedText.length > 0 ? normalizedText : void 0;
 	}
 	function normalizeText(text) {
@@ -159,6 +175,7 @@
 		"navigation",
 		"region",
 		"search",
+		"descriptionlist",
 		"term",
 		"definition",
 		"table",
@@ -178,6 +195,7 @@
 		return {
 			role,
 			name: resolveAccessibleName(element, false),
+			attributes: {},
 			children
 		};
 	}
@@ -234,6 +252,7 @@
 		textarea: "textbox",
 		select: "combobox",
 		option: "option",
+		dl: "descriptionlist",
 		dt: "term",
 		dd: "definition",
 		table: "table",
@@ -246,8 +265,7 @@
 		fieldset: "group",
 		progress: "progressbar",
 		hr: "separator",
-		img: "img",
-		svg: "img"
+		img: "img"
 	};
 	const CONTEXT_DEPENDENT_ROLES = {
 		banner: isTopLevelBanner,
@@ -384,7 +402,8 @@
 				value,
 				checked: resolveChecked(element),
 				...snapshotCommonInputAttributes(element, value === void 0)
-			}
+			},
+			children: []
 		};
 	}
 	function snapshotTextareaElement(element) {
@@ -395,7 +414,8 @@
 			attributes: {
 				value,
 				...snapshotCommonInputAttributes(element, value === void 0)
-			}
+			},
+			children: []
 		};
 	}
 	function snapshotCommonInputAttributes(element, isEmpty) {
@@ -442,6 +462,7 @@
 				value,
 				...snapshotCommonInputAttributes(element, value === void 0)
 			},
+			children: [],
 			options
 		};
 	}
@@ -500,6 +521,7 @@
 		return {
 			role: "group",
 			name: resolveGroupName(element),
+			attributes: {},
 			children: snapshotChildren(element)
 		};
 	}
@@ -536,9 +558,13 @@
 //#endregion
 //#region src/browser/image.ts
 	function snapshotImage(element) {
+		const imageName = resolveImageName(element);
+		if (imageName === void 0) return null;
 		return {
 			role: "img",
-			name: resolveImageName(element)
+			name: imageName,
+			attributes: {},
+			children: []
 		};
 	}
 	function resolveImageName(element) {
@@ -594,6 +620,7 @@
 	function snapshotSeparator(element) {
 		return {
 			role: "separator",
+			attributes: {},
 			children: snapshotPresentationalChildren(element)
 		};
 	}

package/dist/index.d.mts

@@ -40,7 +40,7 @@ interface CommonInputAttributes extends InputStateAttributes, DiscribableAttribu
 //#endregion
 //#region src/browser/combobox.d.ts
 interface ComboboxSnapshot extends GenericElementSnapshot<"combobox", ComboboxAttributes> {
-  options?: Array<OptionSnapshot>;
+  options: Array<OptionSnapshot>;
 }
 interface ComboboxAttributes extends CommonInputAttributes {
   value?: string | Array<string>;
@@ -51,7 +51,7 @@ interface OptionAttributes {
 }
 //#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" | "term" | "definition" | "table" | "grid" | "rowgroup" | "row" | "rowheader" | "cell" | "gridcell" | "alert" | "menu" | "tablist" | "tabpanel">;
+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">;
 interface ContainerSnapshot extends GenericElementSnapshot<ContainerRole> {}
 type ContainerRole = SetValues<typeof CONTAINER_ROLES>;
 //#endregion
@@ -118,16 +118,29 @@ type NodeRole = ElementRole | "text";
 type ElementRole = "heading" | "link" | "button" | "option" | "tab" | "menuitem" | "columnheader" | "group" | "radiogroup" | "progressbar" | "img" | "separator" | ContainerRole | InputRole | DialogRole;
 type NodeSnapshot = ElementSnapshot | TextSnapshot;
 type ElementSnapshot = ContainerSnapshot | HeadingSnapshot | LinkSnapshot | ButtonSnapshot | InputSnapshot | ComboboxSnapshot | OptionSnapshot | DialogSnapshot | TabSnapshot | MenuitemSnapshot | ColumnheaderSnapshot | GroupSnapshot | RadiogroupSnapshot | ProgressbarSnapshot | ImageSnapshot | SeparatorSnapshot;
-interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes = unknown> {
+interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes = Record<string, unknown>> {
   role: TRole;
   name?: string;
-  attributes?: TAttributes;
-  children?: Array<NodeSnapshot>;
+  attributes: TAttributes;
+  children: Array<NodeSnapshot>;
 }
 type SetValues<TSet> = TSet extends Set<infer TValue> ? TValue : never;
 //#endregion
 //#region src/utils/snapshot.d.ts
 type SnapshotFilter = (snapshot: NodeSnapshot) => boolean;
+type GuardedSnapshotFilter<TSnapshot extends NodeSnapshot> = (snapshot: NodeSnapshot) => snapshot is TSnapshot;
+interface SnapshotFilterOptions {
+  filter: SnapshotFilter;
+  snapshots: Array<NodeSnapshot>;
+  recurse: boolean;
+}
+interface GuardedSnapshotFilterOptions<TSnapshot extends NodeSnapshot> {
+  filter: GuardedSnapshotFilter<TSnapshot>;
+  snapshots: Array<NodeSnapshot>;
+  recurse?: boolean;
+}
+declare function filterSnapshots<TSnapshot extends NodeSnapshot = NodeSnapshot>(options: GuardedSnapshotFilterOptions<TSnapshot>): Array<TSnapshot>;
+declare function filterSnapshots(options: SnapshotFilterOptions): Array<NodeSnapshot>;
 //#endregion
 //#region src/playwright/snapshot.d.ts
 interface ElementSnapshotOptions {
@@ -137,6 +150,15 @@ interface ElementSnapshotOptions {
    * @default () => true
    */
   filter?: SnapshotFilter;
+  /**
+   * 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.
+   *
+   * @default false
+   */
+  recurseFilter?: boolean;
   /**
    * Include combobox options in the snapshot
    *
@@ -163,4 +185,4 @@ declare function snapshotElement(locator: Locator, options?: ElementSnapshotOpti
  */
 declare function snapshotElementRaw(locator: Locator): Promise<Array<NodeSnapshot>>;
 //#endregion
-export { type ButtonSnapshot, type ColumnheaderSnapshot, type ComboboxSnapshot, type ContainerSnapshot, type DialogSnapshot, type ElementRole, type ElementSnapshot, type GroupSnapshot, type HeadingSnapshot, type InputSnapshot, type LinkSnapshot, type MenuitemSnapshot, type NodeRole, type NodeSnapshot, type OptionSnapshot, type ProgressbarSnapshot, type RadiogroupSnapshot, type TabSnapshot, type TextSnapshot, 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 MenuitemSnapshot, type NodeRole, type NodeSnapshot, type OptionSnapshot, type ProgressbarSnapshot, type RadiogroupSnapshot, type SeparatorSnapshot, type TabSnapshot, type TextSnapshot, filterSnapshots, snapshotElement, snapshotElementRaw };

package/dist/index.mjs

@@ -28,29 +28,49 @@ var ElementSnapshotProxy = class {
 	}
 };
 
+//#endregion
+//#region src/utils/guards.ts
+function isTextSnapshot(snapshot) {
+	return snapshot.role === "text";
+}
+function isEmpty(value) {
+	if (typeof value === "string" || Array.isArray(value)) return value.length === 0;
+	return Object.keys(value).length === 0;
+}
+
 //#endregion
 //#region src/utils/snapshot.ts
-function filterSnapshots(snapshots, filter) {
+function filterSnapshots(options) {
+	const { filter, snapshots, recurse = false } = options;
 	return snapshots.flatMap((snapshot) => {
-		const filteredChildren = hasChildren(snapshot) ? filterSnapshots(snapshot.children ?? [], filter) : [];
-		if (filter(snapshot)) return {
+		const isFilteredIn = filter(snapshot);
+		if (isFilteredIn && !recurse) return snapshot;
+		if (!isFilteredIn && recurse) return [];
+		const filteredChildren = hasChildren(snapshot) ? filterSnapshots({
+			filter,
+			snapshots: snapshot.children ?? [],
+			recurse
+		}) : [];
+		if (!isFilteredIn) return filteredChildren;
+		return {
 			...snapshot,
-			children: filteredChildren.length > 0 ? filteredChildren : void 0
+			children: filteredChildren
 		};
-		return filteredChildren;
 	});
 }
 function hasChildren(snapshot) {
-	return "children" in snapshot && snapshot.children !== void 0 && snapshot.children.length > 0;
+	return "children" in snapshot && snapshot.children.length > 0;
 }
 
 //#endregion
 //#region src/playwright/transformer.ts
 var ElementSnapshotTransformer = class {
 	filter;
+	recurseFilter;
 	includeComboboxOptions;
 	constructor(options = {}) {
 		this.filter = options.filter;
+		this.recurseFilter = options.recurseFilter ?? false;
 		this.includeComboboxOptions = options.includeComboboxOptions ?? false;
 	}
 	transform(snapshots) {
@@ -61,13 +81,17 @@ var ElementSnapshotTransformer = class {
 	}
 	filterSnapshots(snapshots) {
 		if (this.filter === void 0) return snapshots;
-		return filterSnapshots(snapshots, this.filter);
+		return filterSnapshots({
+			filter: this.filter,
+			snapshots,
+			recurse: this.recurseFilter
+		});
 	}
 	transformSnapshots(snapshots) {
 		return snapshots.map((snapshot) => this.transformSnapshotRecursive(snapshot));
 	}
 	transformSnapshotRecursive(snapshot) {
-		if (snapshot.role === "text") return this.simplifyTextSnapshot(snapshot);
+		if (isTextSnapshot(snapshot)) return this.simplifyTextSnapshot(snapshot);
 		return this.simplifyElementSnapshot(snapshot);
 	}
 	simplifyTextSnapshot(snapshot) {
@@ -90,25 +114,26 @@ var ElementSnapshotTransformer = class {
 		if (snapshot.role === "combobox") return this.simplifyComboboxSnapshot(snapshot);
 		const { role, name, attributes, children } = normalizedSnapshot;
 		return this.transformedSnapshot(role, {
-			name,
+			name: name.length === 0 ? void 0 : name,
 			...attributes,
-			children
+			children: children.length === 0 ? void 0 : children
 		});
 	}
 	normalizeElementSnapshot(snapshot) {
-		const sparseAttributes = this.removeUndefinedProperties(snapshot.attributes ?? {});
-		const transformedChildren = this.transformSnapshots(snapshot?.children ?? []);
-		const nameEqualsChildren = transformedChildren.length === 1 && snapshot.name === transformedChildren.at(0);
+		const normalizedName = snapshot.name ?? "";
+		const sparseAttributes = this.removeUndefinedProperties(snapshot.attributes);
+		const transformedChildren = this.transformSnapshots(snapshot.children);
+		const nameEqualsChildren = transformedChildren.length === 1 && normalizedName === transformedChildren.at(0);
 		return {
 			role: snapshot.role,
-			name: snapshot.name,
+			name: normalizedName,
 			attributes: sparseAttributes,
-			children: nameEqualsChildren ? void 0 : transformedChildren.length === 0 ? void 0 : transformedChildren
+			children: nameEqualsChildren ? [] : transformedChildren
 		};
 	}
 	simplifyComboboxSnapshot(snapshot) {
 		const { role, name, attributes } = this.normalizeElementSnapshot(snapshot);
-		const transformedOptions = (snapshot.options ?? []).map((optionSnapshot) => this.simplifyElementSnapshot(optionSnapshot));
+		const transformedOptions = snapshot.options.map((optionSnapshot) => this.simplifyElementSnapshot(optionSnapshot));
 		return this.transformedSnapshot(role, {
 			name,
 			...attributes,
@@ -116,20 +141,20 @@ var ElementSnapshotTransformer = class {
 		});
 	}
 	isEmpty(snapshot) {
-		return snapshot.name === void 0 && (snapshot.attributes === void 0 || Object.keys(snapshot.attributes).length === 0) && (snapshot.children === void 0 || snapshot.children.length === 0);
+		return isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && isEmpty(snapshot.children);
 	}
 	hasOnlyName(snapshot) {
-		return snapshot.name !== void 0 && snapshot.attributes === void 0 && snapshot.children === void 0;
+		return !isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && isEmpty(snapshot.children);
 	}
 	hasOnlyChildren(snapshot) {
-		return snapshot.name === void 0 && snapshot.attributes === void 0 && snapshot.children !== void 0;
+		return isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && !isEmpty(snapshot.children);
 	}
 	removeUndefinedProperties(attributes) {
 		const sparseAttributes = {};
 		Object.entries(attributes).forEach(([key, value]) => {
 			if (value !== void 0) sparseAttributes[key] = value;
 		});
-		return Object.keys(sparseAttributes).length > 0 ? sparseAttributes : void 0;
+		return sparseAttributes;
 	}
 	transformedSnapshot(role, content) {
 		return { [role]: content };
@@ -163,4 +188,4 @@ async function snapshotElementRaw(locator) {
 }
 
 //#endregion
-export { snapshotElement, snapshotElementRaw };
+export { filterSnapshots, snapshotElement, snapshotElementRaw };

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@cronn/element-snapshot",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Element snapshots for Playwright",
+  "bugs": {
+    "url": "https://github.com/cronn/file-snapshots/issues"
+  },
   "author": "cronn",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/cronn/file-snapshots.git",
+    "url": "git+https://github.com/cronn/file-snapshots.git",
     "directory": "packages/element-snapshot"
   },
   "homepage": "https://github.com/cronn/file-snapshots",
@@ -40,33 +43,35 @@
     "package-directory": "8.2.0"
   },
   "devDependencies": {
+    "@arethetypeswrong/core": "0.18.2",
     "@playwright/test": "1.58.2",
     "@trivago/prettier-plugin-sort-imports": "6.0.2",
-    "@types/node": "24.10.12",
+    "@typescript/native-preview": "7.0.0-dev.20260218.1",
+    "@types/node": "24.10.13",
     "@vitest/coverage-v8": "4.0.18",
-    "eslint": "9.39.2",
+    "eslint": "10.0.1",
     "eslint-config-prettier": "10.1.8",
-    "eslint-plugin-unused-imports": "4.3.0",
+    "eslint-plugin-unused-imports": "4.4.1",
     "prettier": "3.8.1",
+    "publint": "0.3.17",
     "tsdown": "0.20.3",
-    "typescript": "5.9.3",
-    "typescript-eslint": "8.54.0",
+    "typescript-eslint": "8.56.0",
     "vitest": "4.0.18",
-    "@cronn/playwright-file-snapshots": "0.38.1",
-    "@cronn/test-utils": "0.0.0",
-    "@cronn/shared-configs": "0.0.0"
+    "@cronn/playwright-file-snapshots": "1.0.0",
+    "@cronn/shared-configs": "0.0.0",
+    "@cronn/test-utils": "0.0.0"
   },
   "peerDependencies": {
     "@playwright/test": "^1.55"
   },
   "scripts": {
-    "lint:check": "eslint src/ --max-warnings=0",
-    "lint:fix": "eslint src/ --max-warnings=0 --fix",
+    "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": "tsc",
+    "compile": "tsgo",
     "build": "tsdown"
   }
 }