@cronn/element-snapshot 0.9.0 → 0.10.0

package/README.md

@@ -1,4 +1,4 @@
-# Element Snapshot
+# Element Snapshots
 
 Element Snapshots are a custom snapshot implementation inspired by [Playwright's ARIA Snapshots](https://playwright.dev/docs/aria-snapshots#aria-snapshots) and the [Accessibility Object Model](https://wicg.github.io/aom/explainer.html). They cover additional properties, e.g. validation attributes like `required` or `invalid` on form inputs, and are optimized to be serialized as JSON.
 
@@ -82,13 +82,18 @@ Snapshot options can be passed when calling the snapshot function:
 ```ts
 await expect(
   snapshotElement(page.getByLabel("My select"), {
-    includeComboboxOptions: true,
+    filter: (element) => element.role === "heading",
   }),
 ).toMatchJsonFile({
-  name: "select options",
+  name: "headings",
 });
 ```
 
+| 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.                                            |
+
 ### Custom Snapshots
 
 The function `snapshotElementRaw` provides the raw element snapshot in a strictly typed structure. This format is not well suited to be read by humans, but can be utilized to derive custom snapshot formats, e.g. for HTML tables.

package/dist/browser-lib.d.ts

@@ -66,6 +66,9 @@ interface HeadingAttributes {
     level?: number;
 }
 
+interface ImageSnapshot extends GenericElementSnapshot<"img"> {
+}
+
 interface LinkSnapshot extends GenericElementSnapshot<"link", LinkAttributes> {
 }
 interface LinkAttributes {
@@ -103,9 +106,9 @@ interface TextSnapshot {
 
 type SnapshotTargetElement = HTMLElement | SVGElement;
 type NodeRole = ElementRole | "text";
-type ElementRole = "heading" | "link" | "button" | "option" | "tab" | "menuitem" | "columnheader" | "group" | "radiogroup" | "progressbar" | ContainerRole | InputRole | DialogRole;
+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;
+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;
@@ -114,7 +117,7 @@ interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes
 }
 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">;
+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>;

package/dist/browser-lib.global.js

@@ -172,7 +172,8 @@
     "alert",
     "menu",
     "tablist",
-    "tabpanel"
+    "tabpanel",
+    "separator"
   ]);
   function snapshotContainer(role, element) {
     const children = snapshotChildren(element);
@@ -242,7 +243,10 @@
     th: resolveTableHeaderCellRole,
     td: "cell",
     fieldset: "group",
-    progress: "progressbar"
+    progress: "progressbar",
+    hr: "separator",
+    img: "img",
+    svg: "img"
   };
   var CONTEXT_DEPENDENT_ROLES = {
     banner: isTopLevelBanner,
@@ -606,6 +610,20 @@
     return numericAttribute(levelAsString);
   }
 
+  // src/browser/image.ts
+  function snapshotImage(element) {
+    return {
+      role: "img",
+      name: resolveImageName(element)
+    };
+  }
+  function resolveImageName(element) {
+    if (element instanceof HTMLImageElement) {
+      return stringAttribute(element.alt);
+    }
+    return resolveAccessibleName(element, true);
+  }
+
   // src/browser/link.ts
   function snapshotLink(element) {
     return {
@@ -696,7 +714,8 @@
     columnheader: snapshotColumnheader,
     group: snapshotGroup,
     radiogroup: snapshotRadiogroup,
-    progressbar: snapshotProgressbar
+    progressbar: snapshotProgressbar,
+    img: snapshotImage
   };
   function snapshotElement(element) {
     return snapshotNodeRecursive(element);
@@ -732,7 +751,6 @@
     "style",
     "script",
     "noscript",
-    "img",
     "picture",
     "audio",
     "video",
@@ -740,7 +758,7 @@
     "template"
   ]);
   function isSupportedElement(node) {
-    if (!(node instanceof HTMLElement)) {
+    if (!(node instanceof HTMLElement || node instanceof SVGElement)) {
       return false;
     }
     const tagName = getElementTagName(node);

package/dist/index.d.ts

@@ -48,7 +48,7 @@ interface OptionAttributes {
     selected?: boolean;
 }
 
-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" | "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>;
@@ -73,6 +73,9 @@ interface HeadingAttributes {
     level?: number;
 }
 
+interface ImageSnapshot extends GenericElementSnapshot<"img"> {
+}
+
 interface LinkSnapshot extends GenericElementSnapshot<"link", LinkAttributes> {
 }
 interface LinkAttributes {
@@ -109,9 +112,9 @@ interface TextSnapshot {
 }
 
 type NodeRole = ElementRole | "text";
-type ElementRole = "heading" | "link" | "button" | "option" | "tab" | "menuitem" | "columnheader" | "group" | "radiogroup" | "progressbar" | ContainerRole | InputRole | DialogRole;
+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;
+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;
@@ -120,7 +123,15 @@ interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes
 }
 type SetValues<TSet> = TSet extends Set<infer TValue> ? TValue : never;
 
+type SnapshotFilter = (node: NodeSnapshot) => boolean;
+
 interface ElementSnapshotOptions {
+    /**
+     * Include only elements in the snapshot for which the specified filter returns `true`
+     *
+     * @default () => true
+     */
+    filter?: SnapshotFilter;
     /**
      * Include combobox options in the snapshot
      *

package/dist/index.js

@@ -43,19 +43,30 @@ var ElementSnapshotProxy = class {
 
 // src/playwright/transformer.ts
 var ElementSnapshotTransformer = class {
+  filter;
   includeComboboxOptions;
   constructor(options = {}) {
+    this.filter = options.filter ?? (() => true);
     this.includeComboboxOptions = options.includeComboboxOptions ?? false;
   }
   transform(snapshots) {
-    const transformedSnapshots = snapshots.map(
-      (snapshot) => this.transformSnapshotRecursive(snapshot)
-    );
+    const transformedSnapshots = this.filterAndTransformSnapshots(snapshots);
     if (transformedSnapshots.length === 1) {
       return transformedSnapshots.at(0);
     }
     return transformedSnapshots;
   }
+  filterAndTransformSnapshots(snapshots) {
+    return snapshots.flatMap((snapshot) => {
+      if (this.filter(snapshot)) {
+        return this.transformSnapshotRecursive(snapshot);
+      }
+      if ("children" in snapshot) {
+        return this.filterAndTransformSnapshots(snapshot.children ?? []);
+      }
+      return [];
+    });
+  }
   transformSnapshotRecursive(snapshot) {
     if (snapshot.role === "text") {
       return this.simplifyTextSnapshot(snapshot);
@@ -96,15 +107,15 @@ var ElementSnapshotTransformer = class {
     const sparseAttributes = this.removeUndefinedProperties(
       snapshot.attributes ?? {}
     );
-    const transformedChildren = snapshot.children?.map(
-      (childSnaphot) => this.transformSnapshotRecursive(childSnaphot)
+    const transformedChildren = this.filterAndTransformSnapshots(
+      snapshot?.children ?? []
     );
-    const nameEqualsChildren = transformedChildren?.length === 1 && snapshot.name === transformedChildren.at(0);
+    const nameEqualsChildren = transformedChildren.length === 1 && snapshot.name === transformedChildren.at(0);
     return {
       role: snapshot.role,
       name: snapshot.name,
       attributes: sparseAttributes,
-      children: nameEqualsChildren ? void 0 : transformedChildren
+      children: nameEqualsChildren ? void 0 : transformedChildren.length === 0 ? void 0 : transformedChildren
     };
   }
   simplifyComboboxSnapshot(snapshot) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/element-snapshot",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Element snapshots for Playwright",
   "author": "cronn",
   "license": "Apache-2.0",
@@ -16,17 +16,18 @@
   "devEngines": {
     "runtime": {
       "name": "node",
-      "version": ">=24.11 <25",
+      "version": ">=24.13 <25",
       "onFail": "error"
     },
     "packageManager": {
       "name": "pnpm",
-      "version": ">=10.27 <11",
+      "version": ">=10.28.2 <11",
       "onFail": "error"
     }
   },
   "type": "module",
   "exports": {
+    "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
@@ -39,16 +40,16 @@
     "package-directory": "8.1.0"
   },
   "devDependencies": {
-    "@trivago/prettier-plugin-sort-imports": "6.0.0",
-    "@types/node": "24.10.4",
+    "@trivago/prettier-plugin-sort-imports": "6.0.2",
+    "@types/node": "24.10.9",
     "eslint": "9.39.2",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-unused-imports": "4.3.0",
-    "@playwright/test": "1.56.1",
-    "prettier": "3.7.4",
+    "@playwright/test": "1.58.0",
+    "prettier": "3.8.1",
     "tsup": "8.5.1",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.50.1",
+    "typescript-eslint": "8.54.0",
     "@cronn/shared-configs": "0.0.0"
   },
   "peerDependencies": {