@cronn/element-snapshot 0.10.0 → 0.12.0

package/dist/index.d.mts

@@ -0,0 +1,191 @@
+import { Locator } from "@playwright/test";
+
+//#region src/browser/state.d.ts
+interface DisableableAttributes {
+  disabled?: boolean;
+}
+interface SelectableAttributes {
+  selected?: boolean;
+}
+interface InputStateAttributes extends DisableableAttributes {
+  readonly?: boolean;
+  required?: boolean;
+  invalid?: boolean;
+}
+//#endregion
+//#region src/browser/button.d.ts
+interface ButtonSnapshot extends GenericElementSnapshot<"button", ButtonAttributes> {}
+interface ButtonAttributes extends DisableableAttributes {
+  expanded?: boolean;
+  pressed?: PressedValue;
+}
+type PressedValue = true | "mixed";
+//#endregion
+//#region src/browser/description.d.ts
+interface DiscribableAttributes {
+  description?: string;
+}
+//#endregion
+//#region src/browser/input.d.ts
+interface InputSnapshot extends GenericElementSnapshot<CommonInputRole, InputAttributes> {}
+type InputRole = "button" | "combobox" | CommonInputRole;
+type CommonInputRole = "checkbox" | "radio" | "searchbox" | "slider" | "spinbutton" | "textbox";
+interface InputAttributes extends CommonInputAttributes {
+  value?: string;
+  checked?: boolean;
+}
+interface CommonInputAttributes extends InputStateAttributes, DiscribableAttributes {
+  placeholder?: string;
+}
+//#endregion
+//#region src/browser/combobox.d.ts
+interface ComboboxSnapshot extends GenericElementSnapshot<"combobox", ComboboxAttributes> {
+  options?: Array<OptionSnapshot>;
+}
+interface ComboboxAttributes extends CommonInputAttributes {
+  value?: string | Array<string>;
+}
+interface OptionSnapshot extends GenericElementSnapshot<"option", OptionAttributes> {}
+interface OptionAttributes {
+  selected?: boolean;
+}
+//#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" | "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
+//#region src/browser/dialog.d.ts
+interface DialogSnapshot extends GenericElementSnapshot<DialogRole, DialogAttributes> {}
+type DialogRole = "dialog" | "alertdialog";
+interface DialogAttributes extends DiscribableAttributes {
+  modal?: boolean;
+}
+//#endregion
+//#region src/browser/group.d.ts
+interface GroupSnapshot extends GenericElementSnapshot<"group"> {}
+interface RadiogroupSnapshot extends GenericElementSnapshot<"radiogroup", RadiogroupAttributes> {}
+interface RadiogroupAttributes extends DiscribableAttributes {}
+//#endregion
+//#region src/browser/heading.d.ts
+interface HeadingSnapshot extends GenericElementSnapshot<"heading", HeadingAttributes> {}
+interface HeadingAttributes {
+  level?: number;
+}
+//#endregion
+//#region src/browser/image.d.ts
+interface ImageSnapshot extends GenericElementSnapshot<"img"> {}
+//#endregion
+//#region src/browser/link.d.ts
+interface LinkSnapshot extends GenericElementSnapshot<"link", LinkAttributes> {}
+interface LinkAttributes {
+  url?: string;
+}
+//#endregion
+//#region src/browser/list.d.ts
+interface MenuitemSnapshot extends GenericElementSnapshot<"menuitem", MenuitemAttributes> {}
+interface MenuitemAttributes extends LinkAttributes, DisableableAttributes {}
+//#endregion
+//#region src/browser/progressbar.d.ts
+interface ProgressbarSnapshot extends GenericElementSnapshot<"progressbar", ProgressbarAttributes> {}
+interface ProgressbarAttributes {
+  value?: number;
+}
+//#endregion
+//#region src/browser/separator.d.ts
+interface SeparatorSnapshot extends GenericElementSnapshot<"separator"> {}
+//#endregion
+//#region src/browser/tab.d.ts
+interface TabSnapshot extends GenericElementSnapshot<"tab", TabAttributes> {}
+interface TabAttributes extends DisableableAttributes, SelectableAttributes {}
+//#endregion
+//#region src/browser/table.d.ts
+interface ColumnheaderSnapshot extends GenericElementSnapshot<"columnheader", ColumnheaderAttributes> {}
+interface ColumnheaderAttributes {
+  sort?: SortAttribute;
+}
+declare const SORT_ATTRIBUTES: Set<"ascending" | "descending" | "other">;
+type SortAttribute = SetValues<typeof SORT_ATTRIBUTES>;
+//#endregion
+//#region src/browser/text.d.ts
+interface TextSnapshot {
+  role: "text";
+  name: string;
+}
+//#endregion
+//#region src/browser/types.d.ts
+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> {
+  role: TRole;
+  name?: string;
+  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;
+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 {
+  /**
+   * Include only elements in the snapshot for which the specified filter returns `true`
+   *
+   * @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
+   *
+   * @default false
+   */
+  includeComboboxOptions?: boolean;
+}
+/**
+ * Creates an Element Snapshot of the specified element
+ *
+ * @example
+ * ```ts
+ * await expect(snapshotElement(page.getByRole("main"))).toMatchJsonSnapshot();
+ * ```
+ * @param locator Locator for the element to snapshot
+ * @experimental
+ */
+declare function snapshotElement(locator: Locator, options?: ElementSnapshotOptions): Promise<unknown>;
+/**
+ * Creates an Element Snapshot of the specified element, returning the raw snapshot data for custom transformations
+ *
+ * @param locator Locator for the element to snapshot
+ * @experimental
+ */
+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 };

package/dist/index.mjs

@@ -0,0 +1,180 @@
+import path from "node:path";
+import { packageDirectory } from "package-directory";
+
+//#region src/playwright/proxy.ts
+var ElementSnapshotProxy = class {
+	page;
+	constructor(page) {
+		this.page = page;
+	}
+	async snapshotElement(locator) {
+		if (!await this.isLibraryLoaded()) await this.loadLibrary();
+		return await locator.evaluate((element) => {
+			return window.snapshotElement(element);
+		});
+	}
+	async isLibraryLoaded() {
+		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 });
+	}
+	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;
+	}
+};
+
+//#endregion
+//#region src/utils/snapshot.ts
+function filterSnapshots(options) {
+	const { filter, snapshots, recurse = false } = options;
+	return snapshots.flatMap((snapshot) => {
+		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
+		};
+	});
+}
+function hasChildren(snapshot) {
+	return "children" in snapshot && snapshot.children !== void 0 && 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) {
+		const filteredSnapshots = this.filterSnapshots(snapshots);
+		const transformedSnapshots = this.transformSnapshots(filteredSnapshots);
+		if (transformedSnapshots.length === 1) return transformedSnapshots.at(0);
+		return transformedSnapshots;
+	}
+	filterSnapshots(snapshots) {
+		if (this.filter === void 0) return snapshots;
+		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);
+		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);
+		}
+		if (snapshot.role === "combobox") return this.simplifyComboboxSnapshot(snapshot);
+		const { role, name, attributes, children } = normalizedSnapshot;
+		return this.transformedSnapshot(role, {
+			name,
+			...attributes,
+			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);
+		return {
+			role: snapshot.role,
+			name: snapshot.name,
+			attributes: sparseAttributes,
+			children: nameEqualsChildren ? void 0 : transformedChildren.length === 0 ? void 0 : transformedChildren
+		};
+	}
+	simplifyComboboxSnapshot(snapshot) {
+		const { role, name, attributes } = this.normalizeElementSnapshot(snapshot);
+		const transformedOptions = (snapshot.options ?? []).map((optionSnapshot) => this.simplifyElementSnapshot(optionSnapshot));
+		return this.transformedSnapshot(role, {
+			name,
+			...attributes,
+			options: this.includeComboboxOptions && transformedOptions.length > 0 ? transformedOptions : void 0
+		});
+	}
+	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);
+	}
+	hasOnlyName(snapshot) {
+		return snapshot.name !== void 0 && snapshot.attributes === void 0 && snapshot.children === void 0;
+	}
+	hasOnlyChildren(snapshot) {
+		return snapshot.name === void 0 && snapshot.attributes === void 0 && snapshot.children !== void 0;
+	}
+	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;
+	}
+	transformedSnapshot(role, content) {
+		return { [role]: content };
+	}
+};
+
+//#endregion
+//#region src/playwright/snapshot.ts
+/**
+* Creates an Element Snapshot of the specified element
+*
+* @example
+* ```ts
+* await expect(snapshotElement(page.getByRole("main"))).toMatchJsonSnapshot();
+* ```
+* @param locator Locator for the element to snapshot
+* @experimental
+*/
+async function snapshotElement(locator, options) {
+	const snapshot = await snapshotElementRaw(locator);
+	return new ElementSnapshotTransformer(options).transform(snapshot);
+}
+/**
+* Creates an Element Snapshot of the specified element, returning the raw snapshot data for custom transformations
+*
+* @param locator Locator for the element to snapshot
+* @experimental
+*/
+async function snapshotElementRaw(locator) {
+	return await new ElementSnapshotProxy(locator.page()).snapshotElement(locator);
+}
+
+//#endregion
+export { filterSnapshots, snapshotElement, snapshotElementRaw };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/element-snapshot",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Element snapshots for Playwright",
   "author": "cronn",
   "license": "Apache-2.0",
@@ -29,28 +29,32 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "package-directory": "8.1.0"
+    "package-directory": "8.2.0"
   },
   "devDependencies": {
+    "@playwright/test": "1.58.2",
     "@trivago/prettier-plugin-sort-imports": "6.0.2",
-    "@types/node": "24.10.9",
+    "@types/node": "24.10.12",
+    "@vitest/coverage-v8": "4.0.18",
     "eslint": "9.39.2",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-unused-imports": "4.3.0",
-    "@playwright/test": "1.58.0",
     "prettier": "3.8.1",
-    "tsup": "8.5.1",
+    "tsdown": "0.20.3",
     "typescript": "5.9.3",
     "typescript-eslint": "8.54.0",
-    "@cronn/shared-configs": "0.0.0"
+    "vitest": "4.0.18",
+    "@cronn/playwright-file-snapshots": "0.38.1",
+    "@cronn/shared-configs": "0.0.0",
+    "@cronn/test-utils": "0.0.0"
   },
   "peerDependencies": {
     "@playwright/test": "^1.55"
@@ -58,7 +62,11 @@
   "scripts": {
     "lint:check": "eslint src/ --max-warnings=0",
     "lint:fix": "eslint src/ --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",
-    "build": "tsup"
+    "build": "tsdown"
   }
 }

package/dist/browser-lib.d.ts

@@ -1,131 +0,0 @@
-interface DisableableAttributes {
-    disabled?: boolean;
-}
-interface SelectableAttributes {
-    selected?: boolean;
-}
-interface InputStateAttributes extends DisableableAttributes {
-    readonly?: boolean;
-    required?: boolean;
-    invalid?: boolean;
-}
-
-interface ButtonSnapshot extends GenericElementSnapshot<"button", ButtonAttributes> {
-}
-interface ButtonAttributes extends DisableableAttributes {
-    expanded?: boolean;
-    pressed?: PressedValue;
-}
-type PressedValue = true | "mixed";
-
-interface DiscribableAttributes {
-    description?: string;
-}
-
-interface InputSnapshot extends GenericElementSnapshot<CommonInputRole, InputAttributes> {
-}
-type InputRole = "button" | "combobox" | CommonInputRole;
-type CommonInputRole = "checkbox" | "radio" | "searchbox" | "slider" | "spinbutton" | "textbox";
-interface InputAttributes extends CommonInputAttributes {
-    value?: string;
-    checked?: boolean;
-}
-interface CommonInputAttributes extends InputStateAttributes, DiscribableAttributes {
-    placeholder?: string;
-}
-
-interface ComboboxSnapshot extends GenericElementSnapshot<"combobox", ComboboxAttributes> {
-    options?: Array<OptionSnapshot>;
-}
-interface ComboboxAttributes extends CommonInputAttributes {
-    value?: string | Array<string>;
-}
-interface OptionSnapshot extends GenericElementSnapshot<"option", OptionAttributes> {
-}
-interface OptionAttributes {
-    selected?: boolean;
-}
-
-interface DialogSnapshot extends GenericElementSnapshot<DialogRole, DialogAttributes> {
-}
-type DialogRole = "dialog" | "alertdialog";
-interface DialogAttributes extends DiscribableAttributes {
-    modal?: boolean;
-}
-
-interface GroupSnapshot extends GenericElementSnapshot<"group"> {
-}
-interface RadiogroupSnapshot extends GenericElementSnapshot<"radiogroup", RadiogroupAttributes> {
-}
-interface RadiogroupAttributes extends DiscribableAttributes {
-}
-
-interface HeadingSnapshot extends GenericElementSnapshot<"heading", HeadingAttributes> {
-}
-interface HeadingAttributes {
-    level?: number;
-}
-
-interface ImageSnapshot extends GenericElementSnapshot<"img"> {
-}
-
-interface LinkSnapshot extends GenericElementSnapshot<"link", LinkAttributes> {
-}
-interface LinkAttributes {
-    url?: string;
-}
-
-interface MenuitemSnapshot extends GenericElementSnapshot<"menuitem", MenuitemAttributes> {
-}
-interface MenuitemAttributes extends LinkAttributes, DisableableAttributes {
-}
-
-interface ProgressbarSnapshot extends GenericElementSnapshot<"progressbar", ProgressbarAttributes> {
-}
-interface ProgressbarAttributes {
-    value?: number;
-}
-
-interface TabSnapshot extends GenericElementSnapshot<"tab", TabAttributes> {
-}
-interface TabAttributes extends DisableableAttributes, SelectableAttributes {
-}
-
-interface ColumnheaderSnapshot extends GenericElementSnapshot<"columnheader", ColumnheaderAttributes> {
-}
-interface ColumnheaderAttributes {
-    sort?: SortAttribute;
-}
-declare const SORT_ATTRIBUTES: Set<"ascending" | "descending" | "other">;
-type SortAttribute = SetValues<typeof SORT_ATTRIBUTES>;
-
-interface TextSnapshot {
-    role: "text";
-    name: string;
-}
-
-type SnapshotTargetElement = HTMLElement | SVGElement;
-type NodeRole = ElementRole | "text";
-type ElementRole = "heading" | "link" | "button" | "option" | "tab" | "menuitem" | "columnheader" | "group" | "radiogroup" | "progressbar" | "img" | ContainerRole | InputRole | DialogRole;
-type NodeSnapshot = ElementSnapshot | TextSnapshot;
-type ElementSnapshot = ContainerSnapshot | HeadingSnapshot | LinkSnapshot | ButtonSnapshot | InputSnapshot | ComboboxSnapshot | OptionSnapshot | DialogSnapshot | TabSnapshot | MenuitemSnapshot | ColumnheaderSnapshot | GroupSnapshot | RadiogroupSnapshot | ProgressbarSnapshot | ImageSnapshot;
-interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes = unknown> {
-    role: TRole;
-    name?: string;
-    attributes?: TAttributes;
-    children?: Array<NodeSnapshot>;
-}
-type SetValues<TSet> = TSet extends Set<infer TValue> ? TValue : never;
-
-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" | "separator">;
-interface ContainerSnapshot extends GenericElementSnapshot<ContainerRole> {
-}
-type ContainerRole = SetValues<typeof CONTAINER_ROLES>;
-
-declare function snapshotElement(element: SnapshotTargetElement): Array<NodeSnapshot>;
-
-declare global {
-    interface Window {
-        snapshotElement: typeof snapshotElement;
-    }
-}