@cronn/element-snapshot 0.11.0 → 0.12.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

@@ -32,14 +32,22 @@
 
 //#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
 			};
-			return filteredChildren;
 		});
 	}
 	function hasChildren(snapshot) {
@@ -68,7 +76,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: (element) => element.role === "text"
+		}).map((textNode) => textNode.name).join(" "));
 		return normalizedText.length > 0 ? normalizedText : void 0;
 	}
 	function normalizeText(text) {
@@ -159,6 +170,7 @@
 		"navigation",
 		"region",
 		"search",
+		"descriptionlist",
 		"term",
 		"definition",
 		"table",
@@ -234,6 +246,7 @@
 		textarea: "textbox",
 		select: "combobox",
 		option: "option",
+		dl: "descriptionlist",
 		dt: "term",
 		dd: "definition",
 		table: "table",
@@ -246,8 +259,7 @@
 		fieldset: "group",
 		progress: "progressbar",
 		hr: "separator",
-		img: "img",
-		svg: "img"
+		img: "img"
 	};
 	const CONTEXT_DEPENDENT_ROLES = {
 		banner: isTopLevelBanner,
@@ -536,9 +548,11 @@
 //#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
 		};
 	}
 	function resolveImageName(element) {

package/dist/index.d.mts

@@ -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
@@ -128,6 +128,22 @@ 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;
+type FilteredSnapshot<TSnapshot extends NodeSnapshot> = TSnapshot extends GenericElementSnapshot ? TSnapshot & {
+  children?: Array<TSnapshot>;
+} : 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<FilteredSnapshot<TSnapshot>>;
+declare function filterSnapshots(options: SnapshotFilterOptions): Array<NodeSnapshot>;
 //#endregion
 //#region src/playwright/snapshot.d.ts
 interface ElementSnapshotOptions {
@@ -137,6 +153,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 +188,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

@@ -30,14 +30,22 @@ var ElementSnapshotProxy = class {
 
 //#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
 		};
-		return filteredChildren;
 	});
 }
 function hasChildren(snapshot) {
@@ -48,9 +56,11 @@ function hasChildren(snapshot) {
 //#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,7 +71,11 @@ 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));
@@ -163,4 +177,4 @@ async function snapshotElementRaw(locator) {
 }
 
 //#endregion
-export { snapshotElement, snapshotElementRaw };
+export { filterSnapshots, snapshotElement, snapshotElementRaw };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/element-snapshot",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Element snapshots for Playwright",
   "author": "cronn",
   "license": "Apache-2.0",
@@ -53,8 +53,8 @@
     "typescript-eslint": "8.54.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/shared-configs": "0.0.0",
+    "@cronn/test-utils": "0.0.0"
   },
   "peerDependencies": {
     "@playwright/test": "^1.55"