@cronn/element-snapshot 0.13.0 → 0.14.0

package/README.md

@@ -25,6 +25,12 @@ pnpm 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.
@@ -113,3 +119,13 @@ 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

@@ -32,23 +32,28 @@
 //#endregion
 //#region src/utils/guards.ts
 	function isTextSnapshot(snapshot) {
-		return snapshot.role === "text";
+		return hasRole("text", snapshot);
+	}
+	function hasRole(role, snapshot) {
+		if (typeof role === "string") return role === snapshot.role;
+		return role.includes(snapshot.role);
 	}
 
 //#endregion
-//#region src/utils/snapshot.ts
-	function filterSnapshots(options) {
-		const { filter, snapshots, recurse = false } = options;
+//#region src/utils/filter.ts
+	function filter(options) {
+		const { predicate, snapshots, recurse = false } = options;
 		return snapshots.flatMap((snapshot) => {
-			const isFilteredIn = filter(snapshot);
+			const isFilteredIn = predicate(snapshot);
 			if (isFilteredIn && !recurse) return snapshot;
 			if (!isFilteredIn && recurse) return [];
-			const filteredChildren = hasChildren(snapshot) ? filterSnapshots({
-				filter,
+			const filteredChildren = hasChildren(snapshot) ? filter({
+				predicate,
 				snapshots: snapshot.children ?? [],
 				recurse
 			}) : [];
 			if (!isFilteredIn) return filteredChildren;
+			if (isTextSnapshot(snapshot)) return snapshot;
 			return {
 				...snapshot,
 				children: filteredChildren
@@ -59,6 +64,21 @@
 		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 normalizeText(filter({
+			snapshots,
+			predicate: isTextSnapshot
+		}).map((textNode) => textNode.name).join(" "));
+	}
+	function normalizeText(text) {
+		return text.replaceAll(/\s+/g, " ").trim();
+	}
+
 //#endregion
 //#region src/browser/text.ts
 	function snapshotTextNode(textNode) {
@@ -81,14 +101,8 @@
 	function resolveAccessibleTextContent(node, excludedNodes = []) {
 		const children = snapshotChildren(node, excludedNodes);
 		if (children === void 0) return;
-		const normalizedText = normalizeText(filterSnapshots({
-			snapshots: children,
-			filter: isTextSnapshot
-		}).map((textNode) => textNode.name).join(" "));
-		return normalizedText.length > 0 ? normalizedText : void 0;
-	}
-	function normalizeText(text) {
-		return text.replaceAll(/\s+/g, " ").trim();
+		const textContent = getTextContent(children);
+		return textContent.length > 0 ? textContent : void 0;
 	}
 
 //#endregion
@@ -641,7 +655,7 @@
 
 //#endregion
 //#region src/browser/table.ts
-	const SORT_ATTRIBUTES = new Set([
+	const SORT_TYPES = new Set([
 		"ascending",
 		"descending",
 		"other"
@@ -650,7 +664,7 @@
 		return {
 			role: "columnheader",
 			name: resolveAccessibleName(element),
-			attributes: { sort: enumAttribute(element.ariaSort, SORT_ATTRIBUTES) },
+			attributes: { sort: enumAttribute(element.ariaSort, SORT_TYPES) },
 			children: snapshotChildren(element)
 		};
 	}

package/dist/index.d.mts

@@ -102,10 +102,10 @@ interface TabAttributes extends DisableableAttributes, SelectableAttributes {}
 //#region src/browser/table.d.ts
 interface ColumnheaderSnapshot extends GenericElementSnapshot<"columnheader", ColumnheaderAttributes> {}
 interface ColumnheaderAttributes {
-  sort?: SortAttribute;
+  sort?: SortType;
 }
-declare const SORT_ATTRIBUTES: Set<"ascending" | "descending" | "other">;
-type SortAttribute = SetValues<typeof SORT_ATTRIBUTES>;
+declare const SORT_TYPES: Set<"ascending" | "descending" | "other">;
+type SortType = SetValues<typeof SORT_TYPES>;
 //#endregion
 //#region src/browser/text.d.ts
 interface TextSnapshot {
@@ -126,21 +126,50 @@ interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes
 }
 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;
+//#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;
+interface FilterOptions extends FilterBaseOptions {
+  /**
+   * Include only elements in the snapshot for which the specified predicate returns `true`
+   */
+  predicate: FilterPredicate;
+}
+interface GuardedFilterOptions<TSnapshot extends NodeSnapshot> extends FilterBaseOptions {
+  /**
+   * Include only elements in the snapshot for which the specified predicate returns `true`
+   */
+  predicate: GuardedFilterPredicate<TSnapshot>;
 }
-interface GuardedSnapshotFilterOptions<TSnapshot extends NodeSnapshot> {
-  filter: GuardedSnapshotFilter<TSnapshot>;
+interface FilterBaseOptions {
+  /**
+   * Array of snapshots to filter.
+   */
   snapshots: Array<NodeSnapshot>;
+  /**
+   * 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
+   */
   recurse?: boolean;
 }
-declare function filterSnapshots<TSnapshot extends NodeSnapshot = NodeSnapshot>(options: GuardedSnapshotFilterOptions<TSnapshot>): Array<TSnapshot>;
-declare function filterSnapshots(options: SnapshotFilterOptions): Array<NodeSnapshot>;
+/**
+ * Filters node snapshots based on the provided predicate function
+ */
+declare function filter<TSnapshot extends NodeSnapshot = NodeSnapshot>(options: GuardedFilterOptions<TSnapshot>): Array<TSnapshot>;
+declare function filter(options: FilterOptions): Array<NodeSnapshot>;
+/**
+ * Filters node snapshots by a specific role
+ */
+declare function filterByRole<TRole extends NodeRole>(role: TRole, snapshots: Array<NodeSnapshot>): Array<SnapshotByRole<TRole>>;
 //#endregion
 //#region src/playwright/snapshot.d.ts
 interface ElementSnapshotOptions {
@@ -149,7 +178,7 @@ interface ElementSnapshotOptions {
    *
    * @default () => true
    */
-  filter?: SnapshotFilter;
+  filter?: FilterPredicate;
   /**
    * Recursively apply specified filter to children of filtered elements
    *
@@ -185,4 +214,20 @@ 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 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 };
+//#region src/utils/predicates.d.ts
+/**
+ * Include only elements with the specified role
+ */
+declare function includeRole<TRole extends NodeRole>(role: TRole | Array<TRole>): GuardedFilterPredicate<SnapshotByRole<TRole>>;
+/**
+ * Exclude elements with the specified role
+ */
+declare function excludeRole<TRole extends NodeRole>(role: TRole | Array<TRole>): GuardedFilterPredicate<SnapshotByRole<TRole>>;
+//#endregion
+//#region src/utils/text.d.ts
+/**
+ * Aggregates and normalizes the text content of all provided snapshots
+ */
+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 MenuitemSnapshot, type NodeRole, type NodeSnapshot, type OptionSnapshot, type ProgressbarSnapshot, type RadiogroupSnapshot, type SeparatorSnapshot, type TabSnapshot, type TextSnapshot, excludeRole, filter, filterByRole, getTextContent, includeRole, snapshotElement, snapshotElementRaw };

package/dist/index.mjs

@@ -31,7 +31,11 @@ var ElementSnapshotProxy = class {
 //#endregion
 //#region src/utils/guards.ts
 function isTextSnapshot(snapshot) {
-	return snapshot.role === "text";
+	return hasRole("text", snapshot);
+}
+function hasRole(role, snapshot) {
+	if (typeof role === "string") return role === snapshot.role;
+	return role.includes(snapshot.role);
 }
 function isEmpty(value) {
 	if (typeof value === "string" || Array.isArray(value)) return value.length === 0;
@@ -39,25 +43,51 @@ function isEmpty(value) {
 }
 
 //#endregion
-//#region src/utils/snapshot.ts
-function filterSnapshots(options) {
-	const { filter, snapshots, recurse = false } = options;
+//#region src/utils/predicates.ts
+/**
+* Include only elements with the specified role
+*/
+function includeRole(role) {
+	return (snapshot) => hasRole(role, snapshot);
+}
+/**
+* Exclude elements with the specified role
+*/
+function excludeRole(role) {
+	return (snapshot) => !hasRole(role, snapshot);
+}
+
+//#endregion
+//#region src/utils/filter.ts
+function filter(options) {
+	const { predicate, snapshots, recurse = false } = options;
 	return snapshots.flatMap((snapshot) => {
-		const isFilteredIn = filter(snapshot);
+		const isFilteredIn = predicate(snapshot);
 		if (isFilteredIn && !recurse) return snapshot;
 		if (!isFilteredIn && recurse) return [];
-		const filteredChildren = hasChildren(snapshot) ? filterSnapshots({
-			filter,
+		const filteredChildren = hasChildren(snapshot) ? filter({
+			predicate,
 			snapshots: snapshot.children ?? [],
 			recurse
 		}) : [];
 		if (!isFilteredIn) return filteredChildren;
+		if (isTextSnapshot(snapshot)) return snapshot;
 		return {
 			...snapshot,
 			children: filteredChildren
 		};
 	});
 }
+/**
+* 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;
 }
@@ -81,8 +111,8 @@ var ElementSnapshotTransformer = class {
 	}
 	filterSnapshots(snapshots) {
 		if (this.filter === void 0) return snapshots;
-		return filterSnapshots({
-			filter: this.filter,
+		return filter({
+			predicate: this.filter,
 			snapshots,
 			recurse: this.recurseFilter
 		});
@@ -188,4 +218,19 @@ async function snapshotElementRaw(locator) {
 }
 
 //#endregion
-export { filterSnapshots, snapshotElement, snapshotElementRaw };
+//#region src/utils/text.ts
+/**
+* Aggregates and normalizes the text content of all provided snapshots
+*/
+function getTextContent(snapshots) {
+	return normalizeText(filter({
+		snapshots,
+		predicate: isTextSnapshot
+	}).map((textNode) => textNode.name).join(" "));
+}
+function normalizeText(text) {
+	return text.replaceAll(/\s+/g, " ").trim();
+}
+
+//#endregion
+export { excludeRole, filter, filterByRole, getTextContent, includeRole, snapshotElement, snapshotElementRaw };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/element-snapshot",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Element snapshots for Playwright",
   "bugs": {
     "url": "https://github.com/cronn/file-snapshots/issues"
@@ -40,26 +40,29 @@
     "dist"
   ],
   "dependencies": {
+    "markdown-table": "3.0.4",
     "package-directory": "8.2.0"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.2",
     "@playwright/test": "1.58.2",
     "@trivago/prettier-plugin-sort-imports": "6.0.2",
-    "@typescript/native-preview": "7.0.0-dev.20260218.1",
-    "@types/node": "24.10.13",
+    "@types/node": "24.11.0",
+    "@typescript/native-preview": "7.0.0-dev.20260302.1",
     "@vitest/coverage-v8": "4.0.18",
-    "eslint": "10.0.1",
+    "eslint": "10.0.2",
     "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.17",
+    "publint": "0.3.18",
     "tsdown": "0.20.3",
-    "typescript-eslint": "8.56.0",
+    "typescript-eslint": "8.56.1",
     "vitest": "4.0.18",
-    "@cronn/playwright-file-snapshots": "1.0.0",
     "@cronn/shared-configs": "0.0.0",
-    "@cronn/test-utils": "0.0.0"
+    "@cronn/playwright-file-snapshots": "1.0.1",
+    "@cronn/test-utils": "0.0.0",
+    "@cronn/vitest-file-snapshots": "1.0.1"
   },
   "peerDependencies": {
     "@playwright/test": "^1.55"