@kpmck/ag-grid-core 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @kpmck/ag-grid-core
+
+## 1.0.0
+
+### Major Changes
+
+- 2a7e5d7: Move to monorepo structure to support more node-based testing tools for ag grid interactions and validations

package/README.md

@@ -0,0 +1,11 @@
+# @kpmck/ag-grid-core
+
+Framework-agnostic AG Grid helpers shared by the adapter packages in this monorepo.
+
+Planned responsibilities:
+
+- DOM traversal and extraction
+- AG Grid animation waiting helpers
+- Shared types and selectors
+
+Framework-specific command registration and assertions stay in adapter packages such as `cypress-ag-grid` and `playwright-ag-grid`.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@kpmck/ag-grid-core",
+  "version": "1.0.0",
+  "description": "Framework-agnostic AG Grid DOM helpers for Node-based test tooling",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kpmck/cypress-ag-grid.git"
+  },
+  "keywords": [
+    "ag-grid",
+    "aggrid",
+    "testing",
+    "dom",
+    "playwright",
+    "cypress"
+  ],
+  "author": "Kerry McKeever <kerry@kerrymckeever.com>",
+  "license": "MIT"
+}

package/src/index.d.ts

@@ -0,0 +1,44 @@
+export interface AgGridExtractionOptions {
+  onlyColumns?: string[];
+  valuesArray?: boolean;
+  returnElements?: boolean;
+  timeoutMs?: number;
+}
+
+export declare const filterOperator: Record<string, string>;
+export declare const sort: Record<string, string>;
+export declare const filterTab: Record<string, string>;
+
+export declare function isRowNotDestroyed(rowElement: Element): boolean;
+
+export declare function waitForAgGridAnimation(
+  agGridRootElement: Element,
+  options?: AgGridExtractionOptions
+): Promise<void>;
+
+export declare function getAgGridHeaders(tableElement: Element): string[];
+
+export declare function extractAgGrid(
+  agGridRootElement: Element,
+  options?: AgGridExtractionOptions
+): Array<Record<string, string | Element>> | { headers: string[]; rows: Array<Array<string | Element>> };
+
+export declare function extractAgGridData(
+  agGridRootElement: Element,
+  options?: AgGridExtractionOptions
+): Promise<Array<Record<string, string>> | { headers: string[]; rows: string[][] }>;
+
+export declare function extractAgGridElements(
+  agGridRootElement: Element,
+  options?: AgGridExtractionOptions
+): Promise<Array<Record<string, Element>> | { headers: string[]; rows: Element[][] }>;
+
+export declare function browserExtractAgGrid(
+  agGridRootElement: Element,
+  options?: AgGridExtractionOptions
+): Array<Record<string, string>> | { headers: string[]; rows: string[][] };
+
+export declare function browserWaitForAgGridAnimation(
+  agGridRootElement: Element,
+  options?: AgGridExtractionOptions
+): Promise<void>;

package/src/index.js

@@ -0,0 +1,452 @@
+const AG_GRID_COLUMN_SELECTORS = [
+  ".ag-pinned-left-cols-container",
+  ".ag-center-cols-clipper",
+  ".ag-center-cols-viewport",
+  ".ag-pinned-right-cols-container",
+];
+
+const DEFAULT_ANIMATION_TIMEOUT_MS = 5000;
+
+export const filterOperator = {
+  contains: "Contains",
+  notContains: "Does not contain",
+  equals: "Equals",
+  notEquals: "Does not equal",
+  startsWith: "Begins with",
+  endsWith: "Ends with",
+  lessThan: "Less than",
+  lessThanOrEquals: "Less than or equal to",
+  greaterThan: "Greater than",
+  greaterThanOrEquals: "Greater than or equal to",
+  inRange: "Between",
+  blank: "Blank",
+  notBlank: "Not blank",
+};
+
+export const sort = {
+  ascending: "asc",
+  descending: "desc",
+  none: "none",
+};
+
+export const filterTab = {
+  columns: "columns",
+  filter: "filter",
+  search: "search",
+  general: "menu",
+};
+
+function isElementNode(value) {
+  return Boolean(value && value.nodeType === 1);
+}
+
+function getAttributeValue(element, attribute) {
+  const attributeNode = element?.attributes?.[attribute];
+
+  if (!attributeNode) {
+    return undefined;
+  }
+
+  if (typeof attributeNode.value === "string") {
+    return attributeNode.value;
+  }
+
+  if (typeof attributeNode.nodeValue === "string") {
+    return attributeNode.nodeValue;
+  }
+
+  return undefined;
+}
+
+function sortElementsByAttributeValue(attribute) {
+  return (a, b) => {
+    const contentA = parseInt(getAttributeValue(a, attribute), 10).valueOf();
+    const contentB = parseInt(getAttributeValue(b, attribute), 10).valueOf();
+    return contentA < contentB ? -1 : contentA > contentB ? 1 : 0;
+  };
+}
+
+function getTrimmedTextContent(element) {
+  return element?.textContent?.trim?.() ?? "";
+}
+
+export function isRowNotDestroyed(rowElement) {
+  const rect = rowElement.getBoundingClientRect();
+  const viewPortRect = rowElement.parentElement.getBoundingClientRect();
+
+  return (
+    rect.top >= viewPortRect.top &&
+    rect.left >= viewPortRect.left &&
+    rect.bottom <= viewPortRect.bottom &&
+    rect.right <= viewPortRect.right
+  );
+}
+
+export async function waitForAgGridAnimation(
+  agGridRootElement,
+  options = {}
+) {
+  if (!isElementNode(agGridRootElement)) {
+    throw new Error(`Couldn't find a valid AG Grid root element.`);
+  }
+
+  const timeoutMs = options.timeoutMs ?? DEFAULT_ANIMATION_TIMEOUT_MS;
+  const animations = agGridRootElement.getAnimations?.({ subtree: true }) ?? [];
+
+  const agGridAnimations = animations.filter((animation) => {
+    const animationTarget = animation.effect?.target;
+
+    if (
+      !isElementNode(animationTarget) ||
+      !animationTarget.classList
+    ) {
+      return false;
+    }
+
+    const hasAgGridClass = [...animationTarget.classList].some((className) =>
+      className.startsWith("ag-")
+    );
+
+    return animationTarget === agGridRootElement || hasAgGridClass;
+  });
+
+  const finiteAnimations = agGridAnimations.filter((animation) => {
+    const iterations = animation.effect?.getTiming?.()?.iterations;
+    return iterations !== Infinity;
+  });
+
+  await Promise.race([
+    Promise.all(
+      finiteAnimations.map(async (animation) => {
+        try {
+          await animation.finished;
+        } catch (error) {
+          if (error?.name === "AbortError") {
+            return;
+          }
+
+          throw error;
+        }
+      })
+    ),
+    new Promise((resolve) => {
+      setTimeout(resolve, timeoutMs);
+    }),
+  ]);
+}
+
+export function getAgGridHeaders(tableElement) {
+  return [
+    ...tableElement.querySelectorAll(".ag-header-row-column [aria-colindex]"),
+  ]
+    .sort(sortElementsByAttributeValue("aria-colindex"))
+    .map((headerElement) => {
+      const headerCells = [
+        ...headerElement.querySelectorAll(".ag-header-cell-text"),
+      ];
+
+      if (headerCells.length === 0) {
+        return [getTrimmedTextContent(headerElement)];
+      }
+
+      return headerCells.map((element) => getTrimmedTextContent(element));
+    })
+    .flat();
+}
+
+function getRowCells(rowElement) {
+  const rowCells = [...rowElement.querySelectorAll(".ag-cell[aria-colindex]")];
+
+  if (rowCells.length > 0) {
+    return rowCells;
+  }
+
+  return [...rowElement.querySelectorAll(".ag-cell")];
+}
+
+function getStructuredRows(allRows, returnElements) {
+  if (!allRows.length) {
+    return [];
+  }
+
+  return allRows
+    .filter((rowCells) => rowCells.length)
+    .map((rowCells) =>
+      rowCells
+        .sort(sortElementsByAttributeValue("aria-colindex"))
+        .map((element) =>
+          returnElements ? element : getTrimmedTextContent(element)
+        )
+    );
+}
+
+function mapRowsToObjects(headers, rows, options = {}) {
+  return rows.map((row) =>
+    row.reduce((acc, curr, idx) => {
+      if (
+        (options.onlyColumns && !options.onlyColumns.includes(headers[idx])) ||
+        headers[idx] === undefined
+      ) {
+        return acc;
+      }
+
+      return { ...acc, [headers[idx]]: curr };
+    }, {})
+  );
+}
+
+export function extractAgGrid(tableRootElement, options = {}) {
+  if (!isElementNode(tableRootElement)) {
+    throw new Error(`Couldn't find a valid AG Grid element.`);
+  }
+
+  const returnElements = options.returnElements ?? false;
+  const tableElement = tableRootElement.querySelectorAll(".ag-root")[0];
+
+  if (!tableElement) {
+    throw new Error("The provided element does not contain an .ag-root node.");
+  }
+
+  const headers = getAgGridHeaders(tableElement);
+  let allRows = [];
+
+  AG_GRID_COLUMN_SELECTORS.forEach((selector) => {
+    [
+      ...tableElement.querySelectorAll(
+        `${selector}:not(.ag-hidden) .ag-row:not(.ag-opacity-zero)`
+      ),
+    ]
+      .filter(isRowNotDestroyed)
+      .sort(sortElementsByAttributeValue("row-index"))
+      .forEach((rowElement) => {
+        const rowCells = getRowCells(rowElement);
+        const rowIndex = parseInt(getAttributeValue(rowElement, "row-index"), 10);
+
+        if (allRows[rowIndex]) {
+          allRows[rowIndex] = [...allRows[rowIndex], ...rowCells];
+        } else {
+          allRows[rowIndex] = rowCells;
+        }
+      });
+  });
+
+  allRows = allRows
+    .filter((row) => row.length)
+    .map((row) => row.filter((cell, index) => row.indexOf(cell) === index));
+
+  const rows = getStructuredRows(allRows, returnElements);
+
+  if (options.valuesArray) {
+    return { headers, rows };
+  }
+
+  return mapRowsToObjects(headers, rows, options);
+}
+
+export async function extractAgGridData(agGridRootElement, options = {}) {
+  await waitForAgGridAnimation(agGridRootElement, options);
+  return extractAgGrid(agGridRootElement, options);
+}
+
+export async function extractAgGridElements(agGridRootElement, options = {}) {
+  await waitForAgGridAnimation(agGridRootElement, options);
+  return extractAgGrid(agGridRootElement, { ...options, returnElements: true });
+}
+
+// Self-contained exports that can be serialized into a browser context by Playwright.
+export async function browserWaitForAgGridAnimation(
+  agGridRootElement,
+  options = {}
+) {
+  function isElementNode(value) {
+    return Boolean(value && value.nodeType === 1);
+  }
+
+  if (!isElementNode(agGridRootElement)) {
+    throw new Error(`Couldn't find a valid AG Grid root element.`);
+  }
+
+  const timeoutMs = options.timeoutMs ?? 5000;
+  const animations = agGridRootElement.getAnimations?.({ subtree: true }) ?? [];
+
+  const agGridAnimations = animations.filter((animation) => {
+    const animationTarget = animation.effect?.target;
+
+    if (!isElementNode(animationTarget) || !animationTarget.classList) {
+      return false;
+    }
+
+    const hasAgGridClass = [...animationTarget.classList].some((className) =>
+      className.startsWith("ag-")
+    );
+
+    return animationTarget === agGridRootElement || hasAgGridClass;
+  });
+
+  const finiteAnimations = agGridAnimations.filter((animation) => {
+    const iterations = animation.effect?.getTiming?.()?.iterations;
+    return iterations !== Infinity;
+  });
+
+  await Promise.race([
+    Promise.all(
+      finiteAnimations.map(async (animation) => {
+        try {
+          await animation.finished;
+        } catch (error) {
+          if (error?.name === "AbortError") {
+            return;
+          }
+
+          throw error;
+        }
+      })
+    ),
+    new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+  ]);
+}
+
+export function browserExtractAgGrid(agGridRootElement, options = {}) {
+  const agGridColumnSelectors = [
+    ".ag-pinned-left-cols-container",
+    ".ag-center-cols-clipper",
+    ".ag-center-cols-viewport",
+    ".ag-pinned-right-cols-container",
+  ];
+
+  function isElementNode(value) {
+    return Boolean(value && value.nodeType === 1);
+  }
+
+  function getAttributeValue(element, attribute) {
+    const attributeNode = element?.attributes?.[attribute];
+
+    if (!attributeNode) {
+      return undefined;
+    }
+
+    if (typeof attributeNode.value === "string") {
+      return attributeNode.value;
+    }
+
+    if (typeof attributeNode.nodeValue === "string") {
+      return attributeNode.nodeValue;
+    }
+
+    return undefined;
+  }
+
+  function sortElementsByAttributeValue(attribute) {
+    return (a, b) => {
+      const contentA = parseInt(getAttributeValue(a, attribute), 10).valueOf();
+      const contentB = parseInt(getAttributeValue(b, attribute), 10).valueOf();
+      return contentA < contentB ? -1 : contentA > contentB ? 1 : 0;
+    };
+  }
+
+  function getTrimmedTextContent(element) {
+    return element?.textContent?.trim?.() ?? "";
+  }
+
+  function isRowNotDestroyedLocal(rowElement) {
+    const rect = rowElement.getBoundingClientRect();
+    const viewPortRect = rowElement.parentElement.getBoundingClientRect();
+
+    return (
+      rect.top >= viewPortRect.top &&
+      rect.left >= viewPortRect.left &&
+      rect.bottom <= viewPortRect.bottom &&
+      rect.right <= viewPortRect.right
+    );
+  }
+
+  function getRowCells(rowElement) {
+    const rowCells = [...rowElement.querySelectorAll(".ag-cell[aria-colindex]")];
+    if (rowCells.length > 0) {
+      return rowCells;
+    }
+
+    return [...rowElement.querySelectorAll(".ag-cell")];
+  }
+
+  if (!isElementNode(agGridRootElement)) {
+    throw new Error(`Couldn't find a valid AG Grid element.`);
+  }
+
+  const returnElements = options.returnElements ?? false;
+  const tableElement = agGridRootElement.querySelectorAll(".ag-root")[0];
+
+  if (!tableElement) {
+    throw new Error("The provided element does not contain an .ag-root node.");
+  }
+
+  const headers = [
+    ...tableElement.querySelectorAll(".ag-header-row-column [aria-colindex]"),
+  ]
+    .sort(sortElementsByAttributeValue("aria-colindex"))
+    .map((headerElement) => {
+      const headerCells = [
+        ...headerElement.querySelectorAll(".ag-header-cell-text"),
+      ];
+
+      if (headerCells.length === 0) {
+        return [getTrimmedTextContent(headerElement)];
+      }
+
+      return headerCells.map((element) => getTrimmedTextContent(element));
+    })
+    .flat();
+
+  let allRows = [];
+
+  agGridColumnSelectors.forEach((selector) => {
+    [
+      ...tableElement.querySelectorAll(
+        `${selector}:not(.ag-hidden) .ag-row:not(.ag-opacity-zero)`
+      ),
+    ]
+      .filter(isRowNotDestroyedLocal)
+      .sort(sortElementsByAttributeValue("row-index"))
+      .forEach((rowElement) => {
+        const rowCells = getRowCells(rowElement);
+        const rowIndex = parseInt(getAttributeValue(rowElement, "row-index"), 10);
+
+        if (allRows[rowIndex]) {
+          allRows[rowIndex] = [...allRows[rowIndex], ...rowCells];
+        } else {
+          allRows[rowIndex] = rowCells;
+        }
+      });
+  });
+
+  allRows = allRows
+    .filter((row) => row.length)
+    .map((row) => row.filter((cell, index) => row.indexOf(cell) === index));
+
+  const rows = allRows
+    .filter((rowCells) => rowCells.length)
+    .map((rowCells) =>
+      rowCells
+        .sort(sortElementsByAttributeValue("aria-colindex"))
+        .map((element) =>
+          returnElements ? getAttributeValue(element, "col-id") ?? getTrimmedTextContent(element) : getTrimmedTextContent(element)
+        )
+    );
+
+  if (options.valuesArray) {
+    return { headers, rows };
+  }
+
+  return rows.map((row) =>
+    row.reduce((acc, curr, idx) => {
+      if (
+        (options.onlyColumns && !options.onlyColumns.includes(headers[idx])) ||
+        headers[idx] === undefined
+      ) {
+        return acc;
+      }
+
+      return { ...acc, [headers[idx]]: curr };
+    }, {})
+  );
+}

package/src/index.test.js

@@ -0,0 +1,203 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  extractAgGridData,
+  extractAgGridElements,
+  waitForAgGridAnimation,
+} from "./index.js";
+
+function createAttributes(attributes = {}) {
+  return Object.fromEntries(
+    Object.entries(attributes).map(([key, value]) => [
+      key,
+      { nodeValue: String(value), value: String(value) },
+    ])
+  );
+}
+
+class FakeElement {
+  constructor({
+    textContent = "",
+    attributes = {},
+    selectorMap = {},
+    rect = { top: 0, left: 0, bottom: 10, right: 10 },
+    classList = [],
+    nodeType = 1,
+  } = {}) {
+    this.textContent = textContent;
+    this.attributes = createAttributes(attributes);
+    this.selectorMap = selectorMap;
+    this._rect = rect;
+    this.classList = classList;
+    this.nodeType = nodeType;
+    this.parentElement = null;
+  }
+
+  querySelectorAll(selector) {
+    return this.selectorMap[selector] ?? [];
+  }
+
+  getBoundingClientRect() {
+    return this._rect;
+  }
+
+  setSelectorMap(selectorMap) {
+    this.selectorMap = selectorMap;
+    return this;
+  }
+}
+
+function connect(parent, children) {
+  children.forEach((child) => {
+    child.parentElement = parent;
+  });
+}
+
+function createCell(colIndex, text) {
+  return new FakeElement({
+    textContent: text,
+    attributes: { "aria-colindex": colIndex },
+  });
+}
+
+function createRow(rowIndex, cells, rect = { top: 0, left: 0, bottom: 10, right: 10 }) {
+  const row = new FakeElement({
+    attributes: { "row-index": rowIndex },
+    rect,
+  });
+
+  connect(row, cells);
+  row.setSelectorMap({
+    ".ag-cell[aria-colindex]": cells,
+    ".ag-cell": cells,
+  });
+
+  const viewport = new FakeElement({
+    rect: { top: 0, left: 0, bottom: 100, right: 100 },
+  });
+  row.parentElement = viewport;
+
+  return row;
+}
+
+function createHeader(colIndex, text) {
+  const textElement = new FakeElement({ textContent: text });
+  const header = new FakeElement({
+    attributes: { "aria-colindex": colIndex },
+  });
+
+  connect(header, [textElement]);
+  header.setSelectorMap({
+    ".ag-header-cell-text": [textElement],
+  });
+
+  return header;
+}
+
+function createGridFixture() {
+  const headerYear = createHeader(1, "Year");
+  const headerMake = createHeader(2, "Make");
+  const headerModel = createHeader(3, "Model");
+
+  const pinnedLeftRow0 = createRow(0, [createCell(1, "2020")]);
+  const centerRow0 = createRow(0, [createCell(2, "Toyota"), createCell(3, "Celica")]);
+  const centerRow1 = createRow(1, [createCell(1, "2021"), createCell(2, "Ford"), createCell(3, "Mondeo")]);
+  const destroyedRow = createRow(
+    2,
+    [createCell(1, "9999"), createCell(2, "Ghost"), createCell(3, "Row")],
+    { top: 200, left: 0, bottom: 210, right: 10 }
+  );
+
+  const agRoot = new FakeElement();
+  agRoot.setSelectorMap({
+    ".ag-header-row-column [aria-colindex]": [headerModel, headerYear, headerMake],
+    ".ag-pinned-left-cols-container:not(.ag-hidden) .ag-row:not(.ag-opacity-zero)": [pinnedLeftRow0],
+    ".ag-center-cols-clipper:not(.ag-hidden) .ag-row:not(.ag-opacity-zero)": [centerRow0, centerRow1, destroyedRow],
+    ".ag-center-cols-viewport:not(.ag-hidden) .ag-row:not(.ag-opacity-zero)": [],
+    ".ag-pinned-right-cols-container:not(.ag-hidden) .ag-row:not(.ag-opacity-zero)": [],
+  });
+
+  const gridRoot = new FakeElement();
+  gridRoot.setSelectorMap({
+    ".ag-root": [agRoot],
+  });
+
+  return { gridRoot, pinnedLeftRow0, centerRow0 };
+}
+
+test("extractAgGridData returns structured row data and filters destroyed rows", async () => {
+  const { gridRoot } = createGridFixture();
+  gridRoot.getAnimations = () => [];
+
+  const rows = await extractAgGridData(gridRoot);
+
+  assert.deepEqual(rows, [
+    { Year: "2020", Make: "Toyota", Model: "Celica" },
+    { Year: "2021", Make: "Ford", Model: "Mondeo" },
+  ]);
+});
+
+test("extractAgGridData supports onlyColumns and valuesArray", async () => {
+  const { gridRoot } = createGridFixture();
+  gridRoot.getAnimations = () => [];
+
+  const subset = await extractAgGridData(gridRoot, { onlyColumns: ["Make"] });
+  const arrays = await extractAgGridData(gridRoot, { valuesArray: true });
+
+  assert.deepEqual(subset, [{ Make: "Toyota" }, { Make: "Ford" }]);
+  assert.deepEqual(arrays.headers, ["Year", "Make", "Model"]);
+  assert.deepEqual(arrays.rows, [
+    ["2020", "Toyota", "Celica"],
+    ["2021", "Ford", "Mondeo"],
+  ]);
+});
+
+test("extractAgGridElements returns cell elements instead of text", async () => {
+  const { gridRoot, pinnedLeftRow0, centerRow0 } = createGridFixture();
+  gridRoot.getAnimations = () => [];
+
+  const rows = await extractAgGridElements(gridRoot);
+
+  assert.equal(rows[0].Year, pinnedLeftRow0.querySelectorAll(".ag-cell")[0]);
+  assert.equal(rows[0].Make, centerRow0.querySelectorAll(".ag-cell")[0]);
+});
+
+test("waitForAgGridAnimation waits for AG Grid animations and ignores aborts", async () => {
+  let resolved = false;
+
+  const target = new FakeElement({ classList: ["ag-root"] });
+  const root = new FakeElement();
+  root.getAnimations = () => [
+    {
+      effect: {
+        target,
+        getTiming: () => ({ iterations: 1 }),
+      },
+      finished: new Promise((resolve) => {
+        setTimeout(() => {
+          resolved = true;
+          resolve();
+        }, 10);
+      }),
+    },
+    {
+      effect: {
+        target,
+        getTiming: () => ({ iterations: 1 }),
+      },
+      finished: Promise.reject(Object.assign(new Error("aborted"), { name: "AbortError" })),
+    },
+    {
+      effect: {
+        target: new FakeElement({ classList: ["spinner"] }),
+        getTiming: () => ({ iterations: 1 }),
+      },
+      finished: Promise.resolve(),
+    },
+  ];
+
+  await waitForAgGridAnimation(root, { timeoutMs: 50 });
+
+  assert.equal(resolved, true);
+});