@cronn/element-snapshot 0.8.0 → 0.9.0

package/README.md

@@ -0,0 +1,109 @@
+# Element Snapshot
+
+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.
+
+Element Snapshots are designed to be used in combination with [playwright-file-snapshots](../playwright-file-snapshots/README.md) for writing Playwright tests.
+
+> [!NOTE]
+> Element Snapshots are currently experimental. Not all HTML elements, ARIA roles and attributes are covered. Breaking changes to the snapshot format are possible.
+
+## Getting Started
+
+### Adding the library to your project
+
+```shell
+npm install -D @cronn/element-snapshot
+```
+
+```shell
+yarn add -D @cronn/element-snapshot
+```
+
+```shell
+pnpm add -D @cronn/element-snapshot
+```
+
+## Writing Tests
+
+### 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.
+
+```ts
+import { snapshotElement } from "@cronn/element-snapshot";
+import { defineValidationFileExpect } from "@cronn/playwright-file-snapshots";
+
+const expect = defineValidationFileExpect();
+
+test("matches element snapshot", async ({ page }) => {
+  await expect(snapshotElement(page.getByRole("main"))).toMatchJsonFile();
+});
+```
+
+Element Snapshot Example:
+
+```json
+{
+  "main": [
+    {
+      "heading": {
+        "name": "List",
+        "level": 1
+      }
+    },
+    {
+      "list": [
+        {
+          "listitem": "Apple"
+        },
+        {
+          "listitem": "Peach"
+        }
+      ]
+    }
+  ]
+}
+```
+
+To improve the specificity of certain tests, `snapshotElement` can be called on certain areas of the page only:
+
+```ts
+test("matches navigation snapshot", async ({ page }) => {
+  await expect(snapshotElement(page.getByRole("navigation"))).toMatchJsonFile({
+    name: "navigation",
+  });
+});
+```
+
+#### Snapshot Options
+
+Snapshot options can be passed when calling the snapshot function:
+
+```ts
+await expect(
+  snapshotElement(page.getByLabel("My select"), {
+    includeComboboxOptions: true,
+  }),
+).toMatchJsonFile({
+  name: "select options",
+});
+```
+
+### 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.
+
+```ts
+import { snapshotElementRaw } from "@cronn/element-snapshot";
+
+test("matches custom snapshot", async ({ page }) => {
+  const tableSnapshot = await snapshotElementRaw(page.getByRole("table"));
+  const markdownTable = transformToMarkdownTable(tableSnapshot);
+
+  await expect(markdownTable).toMatchTextFile({ fileExtension: "md" });
+});
+
+function transformToMarkdownTable(snapshot: Array<NodeSnapshot>): string {
+  // transform table snapshot to markdown table
+}
+```

package/dist/{types.d.ts → browser-lib.d.ts}

@@ -46,11 +46,6 @@ 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">;
-interface ContainerSnapshot extends GenericElementSnapshot<ContainerRole> {
-}
-type ContainerRole = SetValues<typeof CONTAINER_ROLES>;
-
 interface DialogSnapshot extends GenericElementSnapshot<DialogRole, DialogAttributes> {
 }
 type DialogRole = "dialog" | "alertdialog";
@@ -106,6 +101,7 @@ interface TextSnapshot {
     name: string;
 }
 
+type SnapshotTargetElement = HTMLElement | SVGElement;
 type NodeRole = ElementRole | "text";
 type ElementRole = "heading" | "link" | "button" | "option" | "tab" | "menuitem" | "columnheader" | "group" | "radiogroup" | "progressbar" | ContainerRole | InputRole | DialogRole;
 type NodeSnapshot = ElementSnapshot | TextSnapshot;
@@ -118,4 +114,15 @@ interface GenericElementSnapshot<TRole extends NodeRole = NodeRole, TAttributes
 }
 type SetValues<TSet> = TSet extends Set<infer TValue> ? TValue : never;
 
-export type { ButtonSnapshot, ColumnheaderSnapshot, ComboboxSnapshot, ContainerSnapshot, DialogSnapshot, ElementRole, ElementSnapshot, GroupSnapshot, HeadingSnapshot, InputSnapshot, LinkSnapshot, MenuitemSnapshot, NodeRole, NodeSnapshot, OptionSnapshot, ProgressbarSnapshot, TabSnapshot, TextSnapshot };
+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">;
+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;
+    }
+}

package/dist/{index.global.js → browser-lib.global.js}

@@ -1,6 +1,6 @@
 "use strict";
 (() => {
-  // src/snapshots/attribute.ts
+  // src/browser/attribute.ts
   function stringAttribute(value) {
     return value !== null && value !== "" ? value : void 0;
   }
@@ -31,13 +31,13 @@
     return element.ownerDocument.getElementById(referenceId);
   }
 
-  // src/snapshots/children.ts
+  // src/browser/children.ts
   function snapshotChildren(element) {
     const children = Array.from(element.childNodes).map(snapshotNodeRecursive).filter((childSnapshot) => childSnapshot !== null).flat();
     return children.length > 0 ? children : void 0;
   }
 
-  // src/snapshots/text.ts
+  // src/browser/text.ts
   function snapshotTextNode(textNode) {
     const textContent = snapshotTextContent(textNode);
     if (textContent === void 0) {
@@ -56,7 +56,7 @@
     return normalizedText !== "" ? normalizedText : void 0;
   }
 
-  // src/snapshots/name.ts
+  // src/browser/name.ts
   function resolveAccessibleName(element, includeTextContent = true) {
     const labelledByElement = resolveElementReference(element, "aria-labelledby");
     if (labelledByElement !== null) {
@@ -71,7 +71,7 @@
     return void 0;
   }
 
-  // src/snapshots/state.ts
+  // src/browser/state.ts
   function disableableAttributes(element) {
     const supportsHtmlAttribute = isNativeInputElement(element) || element instanceof HTMLButtonElement;
     const disabled = booleanAttribute(
@@ -103,7 +103,7 @@
     return element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement;
   }
 
-  // src/snapshots/button.ts
+  // src/browser/button.ts
   var PRESSED_VALUES = /* @__PURE__ */ new Set(["true", "mixed", "false"]);
   function snapshotButton(element) {
     return {
@@ -125,7 +125,7 @@
     return booleanAttribute(pressed === "true");
   }
 
-  // src/snapshots/description.ts
+  // src/browser/description.ts
   function discribableAttributes(element) {
     return {
       description: resolveDescription(element)
@@ -145,7 +145,7 @@
     return void 0;
   }
 
-  // src/snapshots/container.ts
+  // src/browser/container.ts
   var CONTAINER_ROLES = /* @__PURE__ */ new Set([
     "paragraph",
     "list",
@@ -186,7 +186,7 @@
     return CONTAINER_ROLES.has(role);
   }
 
-  // src/snapshots/selector.ts
+  // src/browser/selector.ts
   function selectorList(...selectors) {
     return selectors.join(",");
   }
@@ -197,7 +197,7 @@
     return `[${name}='${value}']`;
   }
 
-  // src/snapshots/utils.ts
+  // src/browser/utils.ts
   function getElementTagName(element) {
     return element.tagName.toLowerCase();
   }
@@ -205,7 +205,7 @@
     return element.closest(containerSelector) !== null;
   }
 
-  // src/snapshots/role.ts
+  // src/browser/role.ts
   var ELEMENT_ROLES = {
     main: "main",
     nav: "navigation",
@@ -394,7 +394,7 @@
     return isWithinElement(element, roleSelector("tablist"));
   }
 
-  // src/snapshots/input.ts
+  // src/browser/input.ts
   function snapshotInput(element) {
     if (element instanceof HTMLInputElement) {
       return snapshotInputElement(element);
@@ -477,7 +477,7 @@
     return stringAttribute(element.placeholder);
   }
 
-  // src/snapshots/combobox.ts
+  // src/browser/combobox.ts
   function snapshotCombobox(element) {
     if (!isCombobox(element)) {
       return null;
@@ -546,7 +546,7 @@
     };
   }
 
-  // src/snapshots/dialog.ts
+  // src/browser/dialog.ts
   function snapshotDialogWithRole(role) {
     return (element) => snapshotDialog(role, element);
   }
@@ -562,7 +562,7 @@
     };
   }
 
-  // src/snapshots/group.ts
+  // src/browser/group.ts
   function snapshotGroup(element) {
     return {
       role: "group",
@@ -586,7 +586,7 @@
     };
   }
 
-  // src/snapshots/heading.ts
+  // src/browser/heading.ts
   var LEVEL_REGEXP = /^H([1-6])$/;
   function snapshotHeading(element) {
     if (!(element instanceof HTMLHeadingElement)) {
@@ -606,7 +606,7 @@
     return numericAttribute(levelAsString);
   }
 
-  // src/snapshots/link.ts
+  // src/browser/link.ts
   function snapshotLink(element) {
     return {
       role: "link",
@@ -619,7 +619,7 @@
     return { url: stringAttribute(element.getAttribute("href")) };
   }
 
-  // src/snapshots/list.ts
+  // src/browser/list.ts
   function snapshotMenuitem(element) {
     return {
       role: "menuitem",
@@ -632,7 +632,7 @@
     };
   }
 
-  // src/snapshots/progressbar.ts
+  // src/browser/progressbar.ts
   function snapshotProgressbar(element) {
     return {
       role: "progressbar",
@@ -650,7 +650,7 @@
     return numericAttribute(element.ariaValueNow);
   }
 
-  // src/snapshots/tab.ts
+  // src/browser/tab.ts
   function snapshotTab(element) {
     return {
       role: "tab",
@@ -663,7 +663,7 @@
     };
   }
 
-  // src/snapshots/table.ts
+  // src/browser/table.ts
   var SORT_ATTRIBUTES = /* @__PURE__ */ new Set(["ascending", "descending", "other"]);
   function snapshotColumnheader(element) {
     return {
@@ -676,7 +676,7 @@
     };
   }
 
-  // src/snapshots/element.ts
+  // src/browser/element.ts
   var ROLE_SNAPSHOTS = {
     button: snapshotButton,
     checkbox: snapshotInput,
@@ -761,6 +761,6 @@
     return cssStyles.display === "none" || cssStyles.visibility === "hidden" || cssStyles.visibility === "collapse";
   }
 
-  // src/index.ts
+  // src/browser-lib.ts
   window.snapshotElement = snapshotElement;
 })();

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { Locator } from '@playwright/test';
+
 interface DisableableAttributes {
     disabled?: boolean;
 }
@@ -46,6 +48,11 @@ 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">;
+interface ContainerSnapshot extends GenericElementSnapshot<ContainerRole> {
+}
+type ContainerRole = SetValues<typeof CONTAINER_ROLES>;
+
 interface DialogSnapshot extends GenericElementSnapshot<DialogRole, DialogAttributes> {
 }
 type DialogRole = "dialog" | "alertdialog";
@@ -101,7 +108,6 @@ interface TextSnapshot {
     name: string;
 }
 
-type SnapshotTargetElement = HTMLElement | SVGElement;
 type NodeRole = ElementRole | "text";
 type ElementRole = "heading" | "link" | "button" | "option" | "tab" | "menuitem" | "columnheader" | "group" | "radiogroup" | "progressbar" | ContainerRole | InputRole | DialogRole;
 type NodeSnapshot = ElementSnapshot | TextSnapshot;
@@ -114,15 +120,31 @@ 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">;
-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;
-    }
-}
+interface ElementSnapshotOptions {
+    /**
+     * 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>>;
+
+export { type ButtonSnapshot, type ColumnheaderSnapshot, type ComboboxSnapshot, type ContainerSnapshot, type DialogSnapshot, type ElementRole, type ElementSnapshot, type GroupSnapshot, type HeadingSnapshot, type InputSnapshot, type LinkSnapshot, type MenuitemSnapshot, type NodeRole, type NodeSnapshot, type OptionSnapshot, type ProgressbarSnapshot, type RadiogroupSnapshot, type TabSnapshot, type TextSnapshot, snapshotElement, snapshotElementRaw };

package/dist/index.js

@@ -0,0 +1,158 @@
+// src/playwright/proxy.ts
+import path from "path";
+import { packageDirectory } from "package-directory";
+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.global.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;
+  }
+};
+
+// src/playwright/transformer.ts
+var ElementSnapshotTransformer = class {
+  includeComboboxOptions;
+  constructor(options = {}) {
+    this.includeComboboxOptions = options.includeComboboxOptions ?? false;
+  }
+  transform(snapshots) {
+    const transformedSnapshots = snapshots.map(
+      (snapshot) => this.transformSnapshotRecursive(snapshot)
+    );
+    if (transformedSnapshots.length === 1) {
+      return transformedSnapshots.at(0);
+    }
+    return transformedSnapshots;
+  }
+  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: role2 } = normalizedSnapshot;
+      return this.transformedSnapshot(role2, "");
+    }
+    if (this.hasOnlyName(normalizedSnapshot)) {
+      const { role: role2, name: name2 } = normalizedSnapshot;
+      return this.transformedSnapshot(role2, name2);
+    }
+    if (this.hasOnlyChildren(normalizedSnapshot)) {
+      const { role: role2, children: children2 } = normalizedSnapshot;
+      return this.transformedSnapshot(
+        role2,
+        children2.length === 1 ? children2.at(0) : children2
+      );
+    }
+    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 = snapshot.children?.map(
+      (childSnaphot) => this.transformSnapshotRecursive(childSnaphot)
+    );
+    const nameEqualsChildren = transformedChildren?.length === 1 && snapshot.name === transformedChildren.at(0);
+    return {
+      role: snapshot.role,
+      name: snapshot.name,
+      attributes: sparseAttributes,
+      children: nameEqualsChildren ? void 0 : transformedChildren
+    };
+  }
+  simplifyComboboxSnapshot(snapshot) {
+    const { role, name, attributes } = this.normalizeElementSnapshot(snapshot);
+    const options = snapshot.options ?? [];
+    const transformedOptions = 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 };
+  }
+};
+
+// src/playwright/snapshot.ts
+async function snapshotElement(locator, options) {
+  const snapshot = await snapshotElementRaw(locator);
+  return new ElementSnapshotTransformer(options).transform(snapshot);
+}
+async function snapshotElementRaw(locator) {
+  return await new ElementSnapshotProxy(locator.page()).snapshotElement(
+    locator
+  );
+}
+export {
+  snapshotElement,
+  snapshotElementRaw
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/element-snapshot",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Element snapshots for Playwright",
   "author": "cronn",
   "license": "Apache-2.0",
@@ -21,7 +21,7 @@
     },
     "packageManager": {
       "name": "pnpm",
-      "version": ">=10.21 <11",
+      "version": ">=10.27 <11",
       "onFail": "error"
     }
   },
@@ -29,27 +29,31 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.global.js"
-    },
-    "./types": {
-      "types": "./dist/types.d.ts",
-      "default": "./dist/types.js"
+      "default": "./dist/index.js"
     }
   },
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "package-directory": "8.1.0"
+  },
   "devDependencies": {
     "@trivago/prettier-plugin-sort-imports": "6.0.0",
-    "eslint": "9.39.1",
+    "@types/node": "24.10.4",
+    "eslint": "9.39.2",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-unused-imports": "4.3.0",
-    "prettier": "3.6.2",
+    "@playwright/test": "1.56.1",
+    "prettier": "3.7.4",
     "tsup": "8.5.1",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.47.0",
+    "typescript-eslint": "8.50.1",
     "@cronn/shared-configs": "0.0.0"
   },
+  "peerDependencies": {
+    "@playwright/test": "^1.55"
+  },
   "scripts": {
     "lint:check": "eslint src/ --max-warnings=0",
     "lint:fix": "eslint src/ --max-warnings=0 --fix",