@cronn/element-snapshot 0.28.0 → 0.30.0

package/dist/index.d.mts

@@ -158,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;
@@ -166,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;
@@ -224,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.
@@ -269,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
@@ -285,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

@@ -1,6 +1,7 @@
 import { expect } from "@playwright/test";
 import { defineJsonFileMatcher, defineTextFileMatcher } from "@cronn/playwright-file-snapshots";
 import { MarkdownTableSerializer } from "@cronn/lib-file-snapshots";
+import fs from "node:fs/promises";
 import path from "node:path";
 import { packageDirectory } from "package-directory";
 //#region src/utils/guards.ts
@@ -65,7 +66,8 @@ function hasChildren(snapshot) {
 }
 //#endregion
 //#region src/playwright/proxy.ts
-var ElementSnapshotProxy = class {
+var ElementSnapshotProxy = class ElementSnapshotProxy {
+	static browserLibSource = void 0;
 	page;
 	constructor(page) {
 		this.page = page;
@@ -80,30 +82,120 @@ var ElementSnapshotProxy = class {
 		return await this.page.evaluate(() => typeof window.snapshotElement === "function");
 	}
 	async loadLibrary() {
-		const packageRootDir = await this.resolvePackageRootDir();
-		const libPath = path.resolve(packageRootDir, "dist", "browser-lib.iife.js");
-		await this.page.addScriptTag({ path: libPath });
+		ElementSnapshotProxy.browserLibSource ??= await this.readBrowserLibSource();
+		await this.page.evaluate(ElementSnapshotProxy.browserLibSource);
 	}
-	async resolvePackageRootDir() {
-		const packageDir = await packageDirectory({ cwd: import.meta.dirname });
-		if (packageDir === void 0) throw new Error("Unable to resolve root directory of package");
-		return packageDir;
+	async readBrowserLibSource() {
+		const libPath = await this.resolveFromPackageRoot("dist", "browser-lib.iife.js");
+		return await fs.readFile(libPath, "utf8");
+	}
+	async resolveFromPackageRoot(...paths) {
+		const packageRoot = await packageDirectory({ cwd: import.meta.dirname });
+		if (packageRoot === void 0) throw new Error("Unable to resolve root directory of package");
+		return path.resolve(packageRoot, ...paths);
 	}
 };
 //#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 +207,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
@@ -205,7 +228,7 @@ var SemanticSnapshotTransformer = class {
 */
 async function semanticSnapshot(target, options) {
 	const snapshot = await rawSnapshot(target);
-	return new SemanticSnapshotTransformer(options).transform(snapshot);
+	return new SnapshotSerializer(options).transform(snapshot);
 }
 /**
 * Captures a raw snapshot of the element matched by the provided locator.
@@ -323,4 +346,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.28.0",
+  "version": "0.30.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/lib-file-snapshots": "1.2.2",
+    "@cronn/playwright-file-snapshots": "2.2.2",
+    "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.3",
     "@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.1",
+    "@vitest/coverage-v8": "4.1.11",
+    "eslint": "10.9.1",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-check-file": "3.3.2",
     "eslint-plugin-unused-imports": "4.4.1",
-    "publint": "0.3.23",
+    "publint": "0.3.24",
     "rimraf": "6.1.3",
     "tsdown": "0.22.14",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "8.67.0",
-    "vitest": "4.1.10",
-    "node": "runtime:24.19.0",
-    "@cronn/shared-configs": "0.0.0",
-    "@cronn/test-utils": "0.0.0",
-    "@cronn/vitest-file-snapshots": "2.1.2"
+    "typescript-eslint": "8.68.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.22.0",
+      "version": "11.25.0",
       "onFail": "download"
     },
     "runtime": {
       "name": "node",
-      "version": "24.19.0",
+      "version": "24.20.0",
       "onFail": "download"
     }
   },