@cronn/element-snapshot 0.27.0 → 0.29.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Expect, Locator, MatcherReturnType } from "@playwright/test";
+import { Expect, Locator, MatcherReturnType, Page } from "@playwright/test";
 import { PlaywrightMatchJsonFileOptions, PlaywrightMatchTextFileOptions, PlaywrightValidationFileMatcherConfig } from "@cronn/playwright-file-snapshots";
 import { MarkdownTableNormalizer } from "@cronn/lib-file-snapshots";
 //#region src/playwright/markdown-table.d.ts
@@ -51,6 +51,7 @@ type PressedValue = true | "mixed";
 //#endregion
 //#region src/types/utils.d.ts
 type SetValues<TSet> = TSet extends Set<infer TValue> ? TValue : never;
+type PlaywrightTarget = Page | Locator;
 //#endregion
 //#region src/types/elements/container.d.ts
 declare const CONTAINER_ROLES: Set<"alert" | "article" | "banner" | "blockquote" | "code" | "complementary" | "contentinfo" | "definition" | "deletion" | "descriptionlist" | "emphasis" | "form" | "grid" | "insertion" | "label" | "list" | "listbox" | "listitem" | "log" | "main" | "mark" | "menu" | "navigation" | "note" | "paragraph" | "row" | "rowgroup" | "search" | "status" | "strong" | "subscript" | "superscript" | "table" | "tablist" | "tabpanel" | "term" | "tree">;
@@ -157,7 +158,7 @@ type NodeSnapshot = ElementSnapshot | TextSnapshot;
 type SnapshotByRole<TRole extends NodeRole> = NodeSnapshot & {
   role: TRole;
 };
-interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes = Record<string, unknown>> {
+interface GenericElementSnapshot<TRole extends ElementRole = ElementRole, TAttributes extends object = object> {
   role: TRole;
   name?: string;
   attributes: TAttributes;
@@ -165,6 +166,15 @@ interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes
 }
 type ElementSnapshot = ButtonSnapshot | CellSnapshot | ColumnHeaderSnapshot | ComboboxSnapshot | ContainerSnapshot | DialogSnapshot | GroupSnapshot | HeadingSnapshot | ImageSnapshot | InputSnapshot | LinkSnapshot | OptionSnapshot | ProgressbarSnapshot | RegionSnapshot | TabSnapshot | MenuItemSnapshot | RadioGroupSnapshot | SeparatorSnapshot | TreeItemSnapshot;
 //#endregion
+//#region src/types/transformer.d.ts
+type SnapshotTransformer = (snapshot: NodeSnapshot) => unknown;
+type RoleBasedSnapshotTransformer<TRole extends NodeRole = NodeRole> = (snapshot: SnapshotByRole<TRole>, context: SnapshotTransformerContext) => unknown;
+type DefaultSnapshotTransformer = (snapshot: NodeSnapshot, context: SnapshotTransformerContext) => unknown;
+interface SnapshotTransformerContext {
+  transform: SnapshotTransformer;
+}
+type RoleBasedSnapshotTransformers = { [TRole in NodeRole]?: RoleBasedSnapshotTransformer<TRole>; };
+//#endregion
 //#region src/utils/filter.d.ts
 type FilterPredicate = (snapshot: NodeSnapshot) => boolean;
 type GuardedFilterPredicate<TSnapshot extends NodeSnapshot> = (snapshot: NodeSnapshot) => snapshot is TSnapshot;
@@ -223,11 +233,29 @@ interface SemanticSnapshotOptions {
    */
   recurseFilter?: boolean;
   /**
-   * Include combobox options in the snapshot
+   * Replace the default transformation for specific roles
    *
-   * @default false
+   * Transformers are keyed by role and applied after the filter, but before
+   * the default serialization. A transformer may return any JSON-serializable
+   * value, which is written to the snapshot verbatim. The `transform` function
+   * of its context applies the default transformation to untransformed
+   * children.
+   *
+   * Entries override the built-in transformers for the same role.
+   *
+   * @default { combobox: comboboxTransformer() }
+   */
+  transformers?: RoleBasedSnapshotTransformers;
+  /**
+   * Replace the default transformation for all roles
+   *
+   * Applied to every snapshot passed to the default transformation, including
+   * the ones a transformer delegates via the `transform` function of its
+   * context. Transformers registered for a role take precedence.
+   *
+   * @default semanticSnapshotTransformer
    */
-  includeComboboxOptions?: boolean;
+  defaultTransformer?: DefaultSnapshotTransformer;
 }
 /**
  * Captures a semantic snapshot of the specified locator's DOM structure.
@@ -235,25 +263,25 @@ interface SemanticSnapshotOptions {
  * 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 target - The Page or 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 semanticSnapshot(locator: Locator, options?: SemanticSnapshotOptions): Promise<unknown>;
+declare function semanticSnapshot(target: PlaywrightTarget, options?: SemanticSnapshotOptions): Promise<unknown>;
 /**
  * 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 - The Locator instance used to identify the target element to snapshot
+ * @param target - The Page or 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 rawSnapshot(locator: Locator): Promise<Array<NodeSnapshot>>;
+declare function rawSnapshot(target: PlaywrightTarget): Promise<Array<NodeSnapshot>>;
 //#endregion
 //#region src/types/matchers.d.ts
 interface ElementSnapshotMatchers {
-  toMatchSemanticSnapshotFile: (actual: Locator, options?: MatchSemanticSnapshotFileOptions) => Promise<MatcherReturnType>;
+  toMatchSemanticSnapshotFile: (actual: PlaywrightTarget, options?: MatchSemanticSnapshotFileOptions) => Promise<MatcherReturnType>;
   toMatchMarkdownTableSnapshotFile: (actual: Locator, options?: MatchMarkdownTableSnapshotFileOptions) => Promise<MatcherReturnType>;
 }
 interface MatchSemanticSnapshotFileOptions extends PlaywrightMatchJsonFileOptions, SemanticSnapshotOptions {}
@@ -268,6 +296,23 @@ interface MatchMarkdownTableSnapshotFileOptions extends Omit<PlaywrightMatchText
  */
 declare function defineElementSnapshotMatchers(config?: PlaywrightValidationFileMatcherConfig): Expect<ElementSnapshotMatchers>;
 //#endregion
+//#region src/transformers/combobox-transformer.d.ts
+interface ComboboxTransformerOptions {
+  /**
+   * Include combobox options in the snapshot
+   *
+   * @default false
+   */
+  includeOptions?: boolean;
+}
+/**
+ * Returns a transformer controlling whether the options of a combobox are
+ * included in the snapshot
+ *
+ * Empty option lists are always omitted.
+ */
+declare function comboboxTransformer(options?: ComboboxTransformerOptions): RoleBasedSnapshotTransformer<"combobox">;
+//#endregion
 //#region src/utils/predicates.d.ts
 /**
  * Include only elements with the specified role
@@ -284,4 +329,4 @@ declare function excludeRole<TRole extends NodeRole>(role: TRole | Array<TRole>)
  */
 declare function getTextContent(snapshots: Array<NodeSnapshot>): string;
 //#endregion
-export { type ButtonSnapshot, type CellSnapshot, 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, type TreeItemSnapshot, defineElementSnapshotMatchers, excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };
+export { type ButtonSnapshot, type CellSnapshot, type ColumnHeaderSnapshot, type ComboboxSnapshot, type ComboboxTransformerOptions, type ContainerSnapshot, type DefaultSnapshotTransformer, 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 RoleBasedSnapshotTransformer, type RoleBasedSnapshotTransformers, type SemanticSnapshotOptions, type SeparatorSnapshot, type SnapshotByRole, type SnapshotTransformer, type SnapshotTransformerContext, type TabSnapshot, type TextSnapshot, type TreeItemSnapshot, comboboxTransformer, defineElementSnapshotMatchers, excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };

package/dist/index.mjs

@@ -91,19 +91,106 @@ var ElementSnapshotProxy = class {
 	}
 };
 //#endregion
-//#region src/playwright/semantic-snapshot-transformer.ts
-var SemanticSnapshotTransformer = class {
+//#region src/transformers/semantic-snapshot-transformer.ts
+function semanticSnapshotTransformer(snapshot, context) {
+	if (snapshot.role === "text") return snapshot.name;
+	return transformElementSnapshot(snapshot, context.transform);
+}
+function transformElementSnapshot(snapshot, transformRecursive) {
+	const normalizedSnapshot = normalizeElementSnapshot(snapshot, transformRecursive);
+	if (hasOnlyRole(normalizedSnapshot)) {
+		const { role } = normalizedSnapshot;
+		return transformedSnapshot(role, "");
+	}
+	if (hasOnlyName(normalizedSnapshot)) {
+		const { role, name } = normalizedSnapshot;
+		return transformedSnapshot(role, name);
+	}
+	if (hasOnlyChildren(normalizedSnapshot)) {
+		const { role, children } = normalizedSnapshot;
+		return transformedSnapshot(role, children.length === 1 ? children.at(0) : children);
+	}
+	const { role, name, attributes, children } = normalizedSnapshot;
+	return transformedSnapshot(role, name, {
+		...attributes,
+		children: children.length === 0 ? void 0 : children
+	});
+}
+function normalizeElementSnapshot(snapshot, transformRecursive) {
+	const normalizedName = snapshot.name ?? "";
+	const transformedAttributes = transformAttributes(snapshot.attributes ?? {});
+	const transformedChildren = (snapshot.children ?? []).map(transformRecursive);
+	const nameEqualsChildren = transformedChildren.length === 1 && normalizedName === transformedChildren.at(0);
+	return {
+		role: snapshot.role,
+		name: normalizedName,
+		attributes: transformedAttributes,
+		children: nameEqualsChildren ? [] : transformedChildren
+	};
+}
+function hasOnlyRole(snapshot) {
+	return isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && isEmpty(snapshot.children);
+}
+function hasOnlyName(snapshot) {
+	return !isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && isEmpty(snapshot.children);
+}
+function hasOnlyChildren(snapshot) {
+	return isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && !isEmpty(snapshot.children);
+}
+function transformAttributes(attributes) {
+	const filteredAttributes = {};
+	Object.entries(attributes).forEach(([attributeName, attributeValue]) => {
+		if (attributeValue === void 0) return;
+		filteredAttributes[attributeName] = attributeValue;
+	});
+	return filteredAttributes;
+}
+function transformedSnapshot(role, nameOrContent, additionalProperties) {
+	return {
+		[role]: nameOrContent,
+		...additionalProperties
+	};
+}
+//#endregion
+//#region src/transformers/combobox-transformer.ts
+/**
+* Returns a transformer controlling whether the options of a combobox are
+* included in the snapshot
+*
+* Empty option lists are always omitted.
+*/
+function comboboxTransformer(options = {}) {
+	const { includeOptions = false } = options;
+	return (snapshot, { transform }) => {
+		const { options: optionSnapshots, ...attributes } = snapshot.attributes;
+		const transformedOptions = optionSnapshots.map(transform);
+		return transformElementSnapshot({
+			...snapshot,
+			attributes: includeOptions && transformedOptions.length > 0 ? {
+				...attributes,
+				options: transformedOptions
+			} : attributes
+		}, transform);
+	};
+}
+//#endregion
+//#region src/playwright/snapshot-serializer.ts
+var SnapshotSerializer = class {
 	filter;
 	recurseFilter;
-	includeComboboxOptions;
+	transformers;
+	defaultTransformer;
 	constructor(options = {}) {
 		this.filter = options.filter;
 		this.recurseFilter = options.recurseFilter ?? false;
-		this.includeComboboxOptions = options.includeComboboxOptions ?? false;
+		this.transformers = {
+			combobox: comboboxTransformer(),
+			...options.transformers
+		};
+		this.defaultTransformer = options.defaultTransformer ?? semanticSnapshotTransformer;
 	}
 	transform(snapshots) {
-		const filteredSnapshots = this.filterSnapshots(snapshots);
-		const transformedSnapshots = this.transformSnapshots(filteredSnapshots);
+		const transformedSnapshots = this.filterSnapshots(snapshots).map(this.transformSnapshotRecursive);
 		if (transformedSnapshots.length === 1) return transformedSnapshots.at(0);
 		return transformedSnapshots;
 	}
@@ -115,81 +202,12 @@ var SemanticSnapshotTransformer = class {
 			recurse: this.recurseFilter
 		});
 	}
-	transformSnapshots(snapshots) {
-		return snapshots.map((snapshot) => this.transformSnapshotRecursive(snapshot));
-	}
-	transformSnapshotRecursive(snapshot) {
-		if (isTextSnapshot(snapshot)) return this.simplifyTextSnapshot(snapshot);
-		return this.simplifyElementSnapshot(snapshot);
-	}
-	simplifyTextSnapshot(snapshot) {
-		return snapshot.name;
-	}
-	simplifyElementSnapshot(snapshot) {
-		const normalizedSnapshot = this.normalizeElementSnapshot(snapshot);
-		if (this.isEmpty(normalizedSnapshot)) {
-			const { role } = normalizedSnapshot;
-			return this.transformedSnapshot(role, "");
-		}
-		if (this.hasOnlyName(normalizedSnapshot)) {
-			const { role, name } = normalizedSnapshot;
-			return this.transformedSnapshot(role, name);
-		}
-		if (this.hasOnlyChildren(normalizedSnapshot)) {
-			const { role, children } = normalizedSnapshot;
-			return this.transformedSnapshot(role, children.length === 1 ? children.at(0) : children);
-		}
-		const { role, name, attributes, children } = normalizedSnapshot;
-		return this.transformedSnapshot(role, name, {
-			...attributes,
-			children: children.length === 0 ? void 0 : children
-		});
-	}
-	normalizeElementSnapshot(snapshot) {
-		const normalizedName = snapshot.name ?? "";
-		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: transformedAttributes,
-			children: nameEqualsChildren ? [] : transformedChildren
-		};
-	}
-	isEmpty(snapshot) {
-		return isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && isEmpty(snapshot.children);
-	}
-	hasOnlyName(snapshot) {
-		return !isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && isEmpty(snapshot.children);
-	}
-	hasOnlyChildren(snapshot) {
-		return isEmpty(snapshot.name) && isEmpty(snapshot.attributes) && !isEmpty(snapshot.children);
-	}
-	transformAttributes(snapshot) {
-		const { attributes } = snapshot;
-		const filteredAttributes = {};
-		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, nameOrContent, additionalProperties) {
-		return {
-			[role]: nameOrContent,
-			...additionalProperties
-		};
-	}
+	boundDefaultTransformer = (snapshot) => this.defaultTransformer(snapshot, { transform: this.transformSnapshotRecursive });
+	transformSnapshotRecursive = (snapshot) => {
+		const transformer = this.transformers[snapshot.role];
+		if (transformer !== void 0) return transformer(snapshot, { transform: this.boundDefaultTransformer });
+		return this.defaultTransformer(snapshot, { transform: this.transformSnapshotRecursive });
+	};
 };
 //#endregion
 //#region src/playwright/snapshot.ts
@@ -199,13 +217,13 @@ var SemanticSnapshotTransformer = class {
 * 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 target - The Page or 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 semanticSnapshot(locator, options) {
-	const snapshot = await rawSnapshot(locator);
-	return new SemanticSnapshotTransformer(options).transform(snapshot);
+async function semanticSnapshot(target, options) {
+	const snapshot = await rawSnapshot(target);
+	return new SnapshotSerializer(options).transform(snapshot);
 }
 /**
 * Captures a raw snapshot of the element matched by the provided locator.
@@ -213,12 +231,16 @@ async function semanticSnapshot(locator, options) {
 * 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 - The Locator instance used to identify the target element to snapshot
+* @param target - The Page or 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 rawSnapshot(locator) {
+async function rawSnapshot(target) {
+	const locator = isPage(target) ? target.locator("body") : target;
 	return await new ElementSnapshotProxy(locator.page()).snapshotElement(locator);
 }
+function isPage(target) {
+	return "goto" in target && typeof target.goto === "function";
+}
 //#endregion
 //#region src/playwright/markdown-table.ts
 const tableRoles = ["table", "grid"];
@@ -319,4 +341,4 @@ function mergeTexts(texts) {
 	return normalizeText(texts.map((textNode) => textNode.name).join(" "));
 }
 //#endregion
-export { defineElementSnapshotMatchers, excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };
+export { comboboxTransformer, defineElementSnapshotMatchers, excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/element-snapshot",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Element snapshots for Playwright",
   "homepage": "https://cronn.github.io/file-snapshots/playwright/element-snapshots/",
   "bugs": {
@@ -25,30 +25,30 @@
     }
   },
   "dependencies": {
-    "package-directory": "8.2.0",
     "@cronn/lib-file-snapshots": "1.2.1",
-    "@cronn/playwright-file-snapshots": "2.2.1"
+    "@cronn/playwright-file-snapshots": "2.2.1",
+    "package-directory": "8.2.0"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
+    "@cronn/shared-configs": "0.0.0",
+    "@cronn/test-utils": "0.0.0",
+    "@cronn/vitest-file-snapshots": "2.1.2",
     "@playwright/test": "1.62.1",
     "@types/node": "24.13.3",
     "@typescript/native": "npm:typescript@^7.0.2",
-    "@vitest/coverage-v8": "4.1.10",
-    "eslint": "10.8.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "eslint": "10.9.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-check-file": "3.3.2",
     "eslint-plugin-unused-imports": "4.4.1",
-    "publint": "0.3.22",
+    "publint": "0.3.24",
     "rimraf": "6.1.3",
     "tsdown": "0.22.14",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "8.65.0",
-    "vitest": "4.1.10",
-    "node": "runtime:24.18.1",
-    "@cronn/shared-configs": "0.0.0",
-    "@cronn/test-utils": "0.0.0",
-    "@cronn/vitest-file-snapshots": "2.1.2"
+    "typescript-eslint": "8.67.0",
+    "vitest": "4.1.11",
+    "node": "runtime:24.20.0"
   },
   "peerDependencies": {
     "@playwright/test": "^1.55"
@@ -56,12 +56,12 @@
   "devEngines": {
     "packageManager": {
       "name": "pnpm",
-      "version": "11.18.0",
+      "version": "11.25.0",
       "onFail": "download"
     },
     "runtime": {
       "name": "node",
-      "version": "24.18.1",
+      "version": "24.20.0",
       "onFail": "download"
     }
   },