@cronn/element-snapshot 0.15.0 → 0.16.0

package/README.md

@@ -1,52 +1,52 @@
-# Element Snapshots
+# Playwright 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.
+Element snapshots for Playwright.
 
-Element Snapshots are designed to be used in combination with [playwright-file-snapshots](../playwright-file-snapshots/README.md) for writing Playwright tests.
+[Read the full documentation](https://cronn.github.io/file-snapshots/playwright/element-snapshots/)
 
 > [!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
+### Installation
 
 ```shell
-npm install -D @cronn/element-snapshot
+pnpm add -D @cronn/element-snapshot
 ```
 
 ```shell
-yarn add -D @cronn/element-snapshot
+npm install -D @cronn/element-snapshot
 ```
 
 ```shell
-pnpm add -D @cronn/element-snapshot
+yarn add -D @cronn/element-snapshot
 ```
 
 ## Writing Tests
 
-This package provides multiple snapshot formats for different use cases:
-
-- **General-Purpose Snapshots**: Human-readable JSON format for all element types
-- **Markdown Table Snapshots**: Specialized format for tables and grids ([documentation](docs/markdown-table-snapshot.md))
-- **Custom Snapshots**: Build your own snapshot formats using raw element data and utility functions
-
-### 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 { semanticSnapshot } 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();
+  await page.setContent(`
+    <main>
+      <h1>List</h1>
+      <ul>
+        <li>Apple</li>
+        <li>Peach</li>
+      </ul>
+    </main>
+  `);
+
+  await expect(semanticSnapshot(page.getByRole("main"))).toMatchJsonFile();
 });
 ```
 
-Element Snapshot Example:
+**Output (`matches_element_snapshot.json`):**
 
 ```json
 {
@@ -70,62 +70,3 @@ Element Snapshot Example:
   ]
 }
 ```
-
-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"), {
-    filter: (element) => element.role === "heading",
-  }),
-).toMatchJsonFile({
-  name: "headings",
-});
-```
-
-| Option                   | Default Value | Description                                                                                                                                                                                                                   |
-| ------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `filter`                 | `() => true`  | Include only elements in the snapshot for which the specified filter returns `true`.                                                                                                                                          |
-| `recurseFilter`          | `false`       | 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. |
-| `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.
-
-```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
-}
-```
-
-#### Utility Functions for Custom Snapshots
-
-| Function         | Description                                                           |
-| ---------------- | --------------------------------------------------------------------- |
-| `filter`         | Filters node snapshots based on the provided predicate function.      |
-| `filterByRole`   | Filters node snapshots by the specified role.                         |
-| `includeRole`    | Includes only elements with the specified role.                       |
-| `excludeRole`    | Excludes elements with the specified role.                            |
-| `getTextContent` | Aggregates and normalizes the text content of all provided snapshots. |

package/dist/index.d.mts

@@ -186,7 +186,7 @@ declare function filter(options: FilterOptions): Array<NodeSnapshot>;
 declare function filterByRole<TRole extends NodeRole>(role: TRole, snapshots: Array<NodeSnapshot>): Array<SnapshotByRole<TRole>>;
 //#endregion
 //#region src/playwright/snapshot.d.ts
-interface ElementSnapshotOptions {
+interface SemanticSnapshotOptions {
   /**
    * Include only elements in the snapshot for which the specified filter returns `true`
    *
@@ -210,23 +210,26 @@ interface ElementSnapshotOptions {
   includeComboboxOptions?: boolean;
 }
 /**
- * Creates an Element Snapshot of the specified element
+ * Captures a semantic snapshot of the specified locator's DOM structure.
  *
- * @example
- * ```ts
- * await expect(snapshotElement(page.getByRole("main"))).toMatchJsonSnapshot();
- * ```
- * @param locator Locator for the element to snapshot
- * @experimental
+ * 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 options - Optional configuration settings for controlling the snapshot behavior
+ * @return A promise that resolves to the semantic snapshot
  */
-declare function snapshotElement(locator: Locator, options?: ElementSnapshotOptions): Promise<unknown>;
+declare function semanticSnapshot(locator: Locator, options?: SemanticSnapshotOptions): Promise<unknown>;
 /**
- * Creates an Element Snapshot of the specified element, returning the raw snapshot data for custom transformations
+ * 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 Locator for the element to snapshot
- * @experimental
+ * @param locator - The 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 snapshotElementRaw(locator: Locator): Promise<Array<NodeSnapshot>>;
+declare function rawSnapshot(locator: Locator): Promise<Array<NodeSnapshot>>;
 //#endregion
 //#region src/utils/predicates.d.ts
 /**
@@ -244,4 +247,4 @@ declare function excludeRole<TRole extends NodeRole>(role: TRole | Array<TRole>)
  */
 declare function getTextContent(snapshots: Array<NodeSnapshot>): string;
 //#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 MarkdownTableSnapshotOptions, type MenuitemSnapshot, type NodeRole, type NodeSnapshot, type OptionSnapshot, type ProgressbarSnapshot, type RadiogroupSnapshot, type SeparatorSnapshot, type SnapshotByRole, type TabSnapshot, type TextSnapshot, excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, snapshotElement, snapshotElementRaw };
+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 MarkdownTableSnapshotOptions, type MenuitemSnapshot, type NodeRole, type NodeSnapshot, type OptionSnapshot, type ProgressbarSnapshot, type RadiogroupSnapshot, type SeparatorSnapshot, type SnapshotByRole, type TabSnapshot, type TextSnapshot, excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };

package/dist/index.mjs

@@ -106,8 +106,8 @@ var ElementSnapshotProxy = class {
 	}
 };
 //#endregion
-//#region src/playwright/transformer.ts
-var ElementSnapshotTransformer = class {
+//#region src/playwright/semantic-snapshot-transformer.ts
+var SemanticSnapshotTransformer = class {
 	filter;
 	recurseFilter;
 	includeComboboxOptions;
@@ -206,26 +206,29 @@ var ElementSnapshotTransformer = class {
 //#endregion
 //#region src/playwright/snapshot.ts
 /**
-* Creates an Element Snapshot of the specified element
+* Captures a semantic snapshot of the specified locator's DOM structure.
 *
-* @example
-* ```ts
-* await expect(snapshotElement(page.getByRole("main"))).toMatchJsonSnapshot();
-* ```
-* @param locator Locator for the element to snapshot
-* @experimental
+* 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 options - Optional configuration settings for controlling the snapshot behavior
+* @return A promise that resolves to the semantic snapshot
 */
-async function snapshotElement(locator, options) {
-	const snapshot = await snapshotElementRaw(locator);
-	return new ElementSnapshotTransformer(options).transform(snapshot);
+async function semanticSnapshot(locator, options) {
+	const snapshot = await rawSnapshot(locator);
+	return new SemanticSnapshotTransformer(options).transform(snapshot);
 }
 /**
-* Creates an Element Snapshot of the specified element, returning the raw snapshot data for custom transformations
+* 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 Locator for the element to snapshot
-* @experimental
+* @param locator - The 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 snapshotElementRaw(locator) {
+async function rawSnapshot(locator) {
 	return await new ElementSnapshotProxy(locator.page()).snapshotElement(locator);
 }
 //#endregion
@@ -245,7 +248,7 @@ const sortIndicators = {
 * Creates a Markdown table snapshot from a table or grid element
 */
 async function markdownTableSnapshot(locator, options = {}) {
-	const { columnHeaders, rows } = parseTable(await snapshotElementRaw(locator), options);
+	const { columnHeaders, rows } = parseTable(await rawSnapshot(locator), options);
 	return markdownTable([columnHeaders, ...rows]);
 }
 function parseTable(snapshot, options) {
@@ -279,4 +282,4 @@ function getCellTexts(row) {
 	}).map((cell) => getTextContent(cell.children));
 }
 //#endregion
-export { excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, snapshotElement, snapshotElementRaw };
+export { excludeRole, filter, filterByRole, getTextContent, includeRole, markdownTableSnapshot, rawSnapshot, semanticSnapshot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cronn/element-snapshot",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Element snapshots for Playwright",
   "bugs": {
     "url": "https://github.com/cronn/file-snapshots/issues"
@@ -12,19 +12,19 @@
     "url": "git+https://github.com/cronn/file-snapshots.git",
     "directory": "packages/element-snapshot"
   },
-  "homepage": "https://github.com/cronn/file-snapshots",
+  "homepage": "https://cronn.github.io/file-snapshots/playwright/element-snapshots/",
   "engines": {
     "node": "^20 || ^22 || >=24"
   },
   "devEngines": {
     "runtime": {
       "name": "node",
-      "version": ">=24.13 <25",
+      "version": ">=24.14.1 <25",
       "onFail": "error"
     },
     "packageManager": {
       "name": "pnpm",
-      "version": ">=10.28.2 <11",
+      "version": ">=10.33.0 <11",
       "onFail": "error"
     }
   },
@@ -48,21 +48,21 @@
     "@playwright/test": "1.58.2",
     "@trivago/prettier-plugin-sort-imports": "6.0.2",
     "@types/node": "24.12.0",
-    "@typescript/native-preview": "7.0.0-dev.20260309.1",
-    "@vitest/coverage-v8": "4.0.18",
-    "eslint": "10.0.3",
+    "@typescript/native-preview": "7.0.0-dev.20260323.1",
+    "@vitest/coverage-v8": "4.1.0",
+    "eslint": "10.1.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-check-file": "3.3.1",
     "eslint-plugin-unused-imports": "4.4.1",
     "prettier": "3.8.1",
     "publint": "0.3.18",
-    "tsdown": "0.21.1",
-    "typescript-eslint": "8.56.1",
-    "vitest": "4.0.18",
-    "@cronn/playwright-file-snapshots": "1.0.1",
+    "tsdown": "0.21.4",
+    "typescript-eslint": "8.57.1",
+    "vitest": "4.1.0",
+    "@cronn/playwright-file-snapshots": "1.0.2",
     "@cronn/shared-configs": "0.0.0",
     "@cronn/test-utils": "0.0.0",
-    "@cronn/vitest-file-snapshots": "1.0.1"
+    "@cronn/vitest-file-snapshots": "1.0.2"
   },
   "peerDependencies": {
     "@playwright/test": "^1.55"