@treelocator/runtime 0.5.2 → 0.6.0

package/src/visualDiff/snapshot.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, test, beforeEach, afterEach, vi } from "vitest";
+import { takeSnapshot, MAX_SNAPSHOT_ELEMENTS } from "./snapshot";
+
+function stubRect(el: Element, rect: Partial<DOMRect>): void {
+  const full: DOMRect = {
+    x: rect.x ?? 0,
+    y: rect.y ?? 0,
+    width: rect.width ?? 100,
+    height: rect.height ?? 100,
+    top: rect.y ?? 0,
+    left: rect.x ?? 0,
+    right: (rect.x ?? 0) + (rect.width ?? 100),
+    bottom: (rect.y ?? 0) + (rect.height ?? 100),
+    toJSON() {
+      return this;
+    },
+  };
+  el.getBoundingClientRect = () => full;
+}
+
+describe("takeSnapshot", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    Object.defineProperty(window, "innerWidth", {
+      writable: true,
+      configurable: true,
+      value: 1280,
+    });
+    Object.defineProperty(window, "innerHeight", {
+      writable: true,
+      configurable: true,
+      value: 720,
+    });
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  test("returns ElementSnapshot array with expected fields", () => {
+    const div = document.createElement("div");
+    div.id = "hello";
+    div.className = "foo bar";
+    div.textContent = "Hi there";
+    document.body.appendChild(div);
+    stubRect(div, { x: 10, y: 20, width: 100, height: 50 });
+
+    const snaps = takeSnapshot();
+    const found = snaps.find((s) => s.id === "hello");
+    expect(found).toBeDefined();
+    expect(found!.tagName).toBe("div");
+    expect(found!.classes).toEqual(["foo", "bar"]);
+    expect(found!.x).toBe(10);
+    expect(found!.y).toBe(20);
+    expect(found!.width).toBe(100);
+    expect(found!.height).toBe(50);
+    expect(found!.text).toBe("Hi there");
+    expect(found!.visible).toBe(true);
+    expect(found!.inViewport).toBe(true);
+    expect(typeof found!.key).toBe("string");
+  });
+
+  test("excludes elements inside #locatorjs-wrapper", () => {
+    const wrapper = document.createElement("div");
+    wrapper.id = "locatorjs-wrapper";
+    const child = document.createElement("span");
+    child.id = "overlay-child";
+    wrapper.appendChild(child);
+    document.body.appendChild(wrapper);
+    stubRect(child, { x: 0, y: 0, width: 50, height: 50 });
+
+    const snaps = takeSnapshot();
+    expect(snaps.find((s) => s.id === "overlay-child")).toBeUndefined();
+    expect(snaps.find((s) => s.id === "locatorjs-wrapper")).toBeUndefined();
+  });
+
+  test("elements outside viewport have inViewport: false and are skipped", () => {
+    const div = document.createElement("div");
+    div.id = "off-screen";
+    document.body.appendChild(div);
+    stubRect(div, { x: 5000, y: 5000, width: 100, height: 100 });
+
+    const snaps = takeSnapshot();
+    expect(snaps.find((s) => s.id === "off-screen")).toBeUndefined();
+  });
+
+  test("text is trimmed and capped at 80 chars", () => {
+    const div = document.createElement("div");
+    div.id = "long-text";
+    div.textContent = "   " + "x".repeat(200) + "   ";
+    document.body.appendChild(div);
+    stubRect(div, { x: 0, y: 0, width: 100, height: 100 });
+
+    const snaps = takeSnapshot();
+    const found = snaps.find((s) => s.id === "long-text");
+    expect(found).toBeDefined();
+    expect(found!.text!.length).toBe(80);
+    expect(found!.text!.startsWith("x")).toBe(true);
+  });
+
+  test("display:none elements have visible: false", () => {
+    const div = document.createElement("div");
+    div.id = "hidden";
+    div.style.display = "none";
+    document.body.appendChild(div);
+    stubRect(div, { x: 0, y: 0, width: 100, height: 100 });
+
+    const snaps = takeSnapshot();
+    const found = snaps.find((s) => s.id === "hidden");
+    expect(found?.visible).toBe(false);
+  });
+
+  test("disabled form elements have disabled: true", () => {
+    const btn = document.createElement("button");
+    btn.id = "btn";
+    btn.disabled = true;
+    document.body.appendChild(btn);
+    stubRect(btn, { x: 0, y: 0, width: 80, height: 30 });
+
+    const snaps = takeSnapshot();
+    const found = snaps.find((s) => s.id === "btn");
+    expect(found?.disabled).toBe(true);
+  });
+
+  test("caps at MAX_SNAPSHOT_ELEMENTS", () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    for (let i = 0; i < MAX_SNAPSHOT_ELEMENTS + 200; i++) {
+      const d = document.createElement("div");
+      document.body.appendChild(d);
+      stubRect(d, { x: 0, y: 0, width: 10, height: 10 });
+    }
+    const snaps = takeSnapshot();
+    expect(snaps.length).toBeLessThanOrEqual(MAX_SNAPSHOT_ELEMENTS);
+  });
+
+  test("text is only captured for leaf elements (no element children)", () => {
+    const parent = document.createElement("div");
+    parent.id = "parent";
+    const child = document.createElement("span");
+    child.id = "child";
+    child.textContent = "leaf text";
+    parent.appendChild(child);
+    document.body.appendChild(parent);
+    stubRect(parent, { x: 0, y: 0, width: 100, height: 100 });
+    stubRect(child, { x: 0, y: 0, width: 50, height: 20 });
+
+    const snaps = takeSnapshot();
+    const parentSnap = snaps.find((s) => s.id === "parent");
+    const childSnap = snaps.find((s) => s.id === "child");
+    expect(parentSnap?.text).toBeUndefined();
+    expect(childSnap?.text).toBe("leaf text");
+  });
+
+  test("scoped snapshot only includes root + descendants", () => {
+    const outside = document.createElement("div");
+    outside.id = "outside";
+    document.body.appendChild(outside);
+    stubRect(outside, { x: 0, y: 0, width: 100, height: 100 });
+
+    const root = document.createElement("div");
+    root.id = "root";
+    const child = document.createElement("span");
+    child.id = "inside-child";
+    root.appendChild(child);
+    document.body.appendChild(root);
+    stubRect(root, { x: 10, y: 10, width: 100, height: 100 });
+    stubRect(child, { x: 10, y: 10, width: 50, height: 20 });
+
+    const snaps = takeSnapshot(root);
+    const ids = snaps.map((s) => s.id).filter(Boolean);
+    expect(ids).toContain("root");
+    expect(ids).toContain("inside-child");
+    expect(ids).not.toContain("outside");
+  });
+
+  test("strips locatorjs-* classes from the classes array", () => {
+    const div = document.createElement("div");
+    div.id = "with-locator-class";
+    div.className = "foo locatorjs-active-pointer bar";
+    document.body.appendChild(div);
+    stubRect(div, { x: 0, y: 0, width: 50, height: 50 });
+
+    const snaps = takeSnapshot();
+    const found = snaps.find((s) => s.id === "with-locator-class");
+    expect(found?.classes).toEqual(["foo", "bar"]);
+  });
+
+  test("assigns stable keys for the same element across snapshots", () => {
+    const div = document.createElement("div");
+    div.id = "stable";
+    document.body.appendChild(div);
+    stubRect(div, { x: 0, y: 0, width: 50, height: 50 });
+
+    const a = takeSnapshot();
+    const b = takeSnapshot();
+    const aKey = a.find((s) => s.id === "stable")!.key;
+    const bKey = b.find((s) => s.id === "stable")!.key;
+    expect(aKey).toBe(bKey);
+  });
+});

package/src/visualDiff/snapshot.ts

@@ -0,0 +1,119 @@
+import { getReferenceId } from "../functions/getReferenceId";
+import { isLocatorsOwnElement } from "../functions/isLocatorsOwnElement";
+import type { ElementSnapshot } from "./types";
+
+export const MAX_SNAPSHOT_ELEMENTS = 2000;
+const TEXT_LIMIT = 80;
+
+let warnedOverflow = false;
+
+function truncateText(raw: string | null): string | undefined {
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  return trimmed.length > TEXT_LIMIT ? trimmed.slice(0, TEXT_LIMIT) : trimmed;
+}
+
+function snapshotElement(el: HTMLElement | SVGElement): ElementSnapshot | null {
+  const rect = el.getBoundingClientRect();
+  const style = getComputedStyle(el);
+
+  const viewportWidth =
+    typeof window !== "undefined" ? window.innerWidth : 0;
+  const viewportHeight =
+    typeof window !== "undefined" ? window.innerHeight : 0;
+
+  const inViewport =
+    rect.x + rect.width > 0 &&
+    rect.y + rect.height > 0 &&
+    rect.x < viewportWidth &&
+    rect.y < viewportHeight;
+
+  if (!inViewport) return null;
+
+  const opacity = parseFloat(style.opacity || "1");
+  const displayNone = style.display === "none";
+  const hidden = style.visibility === "hidden";
+  const zeroSize = rect.width <= 0 || rect.height <= 0;
+  const visible = !displayNone && !hidden && !zeroSize;
+
+  const rawClasses =
+    typeof el.className === "string"
+      ? el.className.split(/\s+/).filter(Boolean)
+      : Array.from(el.classList);
+  const classes = rawClasses.filter((c) => !c.startsWith("locatorjs-"));
+
+  const disabled =
+    (el as HTMLInputElement | HTMLButtonElement).disabled === true;
+
+  const hasElementChildren = el.children.length > 0;
+  const text = hasElementChildren ? undefined : truncateText(el.textContent);
+
+  return {
+    key: String(getReferenceId(el)),
+    tagName: el.tagName.toLowerCase(),
+    id: el.id || undefined,
+    classes,
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height,
+    visible,
+    opacity: Number.isFinite(opacity) ? opacity : 1,
+    inViewport,
+    pointerEvents: style.pointerEvents || "auto",
+    disabled,
+    text,
+  };
+}
+
+export function takeSnapshot(
+  root?: HTMLElement | SVGElement | null
+): ElementSnapshot[] {
+  if (typeof document === "undefined") return [];
+
+  const out: ElementSnapshot[] = [];
+  const candidates: Array<HTMLElement | SVGElement> = [];
+
+  if (root) {
+    if (root instanceof HTMLElement || root instanceof SVGElement) {
+      candidates.push(root);
+    }
+    const descendants = root.querySelectorAll<HTMLElement | SVGElement>("*");
+    for (let i = 0; i < descendants.length; i++) {
+      candidates.push(descendants[i]!);
+    }
+  } else {
+    const all = document.querySelectorAll<HTMLElement | SVGElement>("*");
+    for (let i = 0; i < all.length; i++) {
+      candidates.push(all[i]!);
+    }
+  }
+
+  for (let i = 0; i < candidates.length; i++) {
+    const el = candidates[i]!;
+    if (!(el instanceof HTMLElement) && !(el instanceof SVGElement)) continue;
+    if (el instanceof HTMLElement && isLocatorsOwnElement(el)) continue;
+
+    const snap = snapshotElement(el);
+    if (!snap) continue;
+    out.push(snap);
+
+    if (out.length >= MAX_SNAPSHOT_ELEMENTS) {
+      if (!warnedOverflow) {
+        warnedOverflow = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[treelocator/visualDiff] snapshot capped at ${MAX_SNAPSHOT_ELEMENTS} elements`
+        );
+      }
+      break;
+    }
+  }
+
+  return out;
+}
+
+export function __resetSnapshotWarningForTests(): void {
+  warnedOverflow = false;
+}

package/src/visualDiff/types.ts

@@ -0,0 +1,40 @@
+export interface ElementSnapshot {
+  key: string;
+  tagName: string;
+  id?: string;
+  classes: string[];
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  visible: boolean;
+  opacity: number;
+  inViewport: boolean;
+  pointerEvents: string;
+  disabled: boolean;
+  text?: string;
+}
+
+export type DeltaChangeType = "+" | "-" | "~" | "→";
+
+export interface DeltaEntry {
+  type: DeltaChangeType;
+  key: string;
+  label: string;
+  before?: ElementSnapshot;
+  after?: ElementSnapshot;
+  changedFields?: string[];
+}
+
+export interface DeltaReport {
+  elapsedMs: number;
+  settle: "clean" | "timeout";
+  counts: {
+    added: number;
+    removed: number;
+    changed: number;
+    moved: number;
+  };
+  entries: DeltaEntry[];
+  text: string;
+}

package/tsconfig.json

@@ -15,6 +15,8 @@
     "strictNullChecks": true,
     "noImplicitAny": true,
     "esModuleInterop": true,
-    "skipLibCheck": true
+    "skipLibCheck": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
   }
 }

package/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    include: ["src/**/*.test.ts", "src/**/*.test.tsx"],
+    exclude: ["src/_generated_*"],
+    coverage: {
+      provider: "v8",
+      include: ["src/**/*.ts", "src/**/*.tsx"],
+      exclude: ["src/**/*.test.*", "src/_generated_*"],
+      thresholds: {
+        lines: 5,
+        functions: 5,
+      },
+    },
+  },
+});

package/jest.config.ts

@@ -1,195 +0,0 @@
-/*
- * For a detailed explanation regarding each configuration property and type check, visit:
- * https://jestjs.io/docs/configuration
- */
-
-export default {
-  // All imported modules in your tests should be mocked automatically
-  // automock: false,
-
-  // Stop running tests after `n` failures
-  // bail: 0,
-
-  // The directory where Jest should store its cached dependency information
-  // cacheDirectory: "/private/var/folders/05/1z3zrcyx19jchm73d29d5kjr0000gn/T/jest_dx",
-
-  // Automatically clear mock calls, instances, contexts and results before every test
-  // clearMocks: false,
-
-  // Indicates whether the coverage information should be collected while executing the test
-  // collectCoverage: false,
-
-  // An array of glob patterns indicating a set of files for which coverage information should be collected
-  // collectCoverageFrom: undefined,
-
-  // The directory where Jest should output its coverage files
-  // coverageDirectory: undefined,
-
-  // An array of regexp pattern strings used to skip coverage collection
-  // coveragePathIgnorePatterns: [
-  //   "/node_modules/"
-  // ],
-
-  // Indicates which provider should be used to instrument code for coverage
-  // coverageProvider: "babel",
-
-  // A list of reporter names that Jest uses when writing coverage reports
-  // coverageReporters: [
-  //   "json",
-  //   "text",
-  //   "lcov",
-  //   "clover"
-  // ],
-
-  // An object that configures minimum threshold enforcement for coverage results
-  // coverageThreshold: undefined,
-
-  // A path to a custom dependency extractor
-  // dependencyExtractor: undefined,
-
-  // Make calling deprecated APIs throw helpful error messages
-  // errorOnDeprecated: false,
-
-  // The default configuration for fake timers
-  // fakeTimers: {
-  //   "enableGlobally": false
-  // },
-
-  // Force coverage collection from ignored files using an array of glob patterns
-  // forceCoverageMatch: [],
-
-  // A path to a module which exports an async function that is triggered once before all test suites
-  // globalSetup: undefined,
-
-  // A path to a module which exports an async function that is triggered once after all test suites
-  // globalTeardown: undefined,
-
-  // A set of global variables that need to be available in all test environments
-  // globals: {},
-
-  // The maximum amount of workers used to run your tests. Can be specified as % or a number. E.g. maxWorkers: 10% will use 10% of your CPU amount + 1 as the maximum worker number. maxWorkers: 2 will use a maximum of 2 workers.
-  // maxWorkers: "50%",
-
-  // An array of directory names to be searched recursively up from the requiring module's location
-  // moduleDirectories: [
-  //   "node_modules"
-  // ],
-
-  // An array of file extensions your modules use
-  // moduleFileExtensions: [
-  //   "js",
-  //   "mjs",
-  //   "cjs",
-  //   "jsx",
-  //   "ts",
-  //   "tsx",
-  //   "json",
-  //   "node"
-  // ],
-
-  // A map from regular expressions to module names or to arrays of module names that allow to stub out resources with a single module
-  // moduleNameMapper: {},
-
-  // An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader
-  // modulePathIgnorePatterns: [],
-
-  // Activates notifications for test results
-  // notify: false,
-
-  // An enum that specifies notification mode. Requires { notify: true }
-  // notifyMode: "failure-change",
-
-  // A preset that is used as a base for Jest's configuration
-  // preset: undefined,
-
-  // Run tests from one or more projects
-  // projects: undefined,
-
-  // Use this configuration option to add custom reporters to Jest
-  // reporters: undefined,
-
-  // Automatically reset mock state before every test
-  // resetMocks: false,
-
-  // Reset the module registry before running each individual test
-  // resetModules: false,
-
-  // A path to a custom resolver
-  // resolver: undefined,
-
-  // Automatically restore mock state and implementation before every test
-  // restoreMocks: false,
-
-  // The root directory that Jest should scan for tests and modules within
-  // rootDir: undefined,
-
-  // A list of paths to directories that Jest should use to search for files in
-  // roots: [
-  //   "<rootDir>"
-  // ],
-
-  // Allows you to use a custom runner instead of Jest's default test runner
-  // runner: "jest-runner",
-
-  // The paths to modules that run some code to configure or set up the testing environment before each test
-  // setupFiles: [],
-
-  // A list of paths to modules that run some code to configure or set up the testing framework before each test
-  // setupFilesAfterEnv: [],
-
-  // The number of seconds after which a test is considered as slow and reported as such in the results.
-  // slowTestThreshold: 5,
-
-  // A list of paths to snapshot serializer modules Jest should use for snapshot testing
-  // snapshotSerializers: [],
-
-  // The test environment that will be used for testing
-  testEnvironment: "jsdom",
-
-  // Options that will be passed to the testEnvironment
-  // testEnvironmentOptions: {},
-
-  // Adds a location field to test results
-  // testLocationInResults: false,
-
-  // The glob patterns Jest uses to detect test files
-  testMatch: ["**/__tests__/**/*.ts?(x)", "**/?(*.)+(spec|test).ts?(x)"],
-
-  // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
-  // testPathIgnorePatterns: [
-  //   "/node_modules/"
-  // ],
-
-  // The regexp pattern or array of patterns that Jest uses to detect test files
-  // testRegex: [],
-
-  // This option allows the use of a custom results processor
-  // testResultsProcessor: undefined,
-
-  // This option allows use of a custom test runner
-  // testRunner: "jest-circus/runner",
-
-  // A map from regular expressions to paths to transformers
-  // transform: undefined,
-  transform: {
-    "\\.tsx?$": "babel-jest",
-  },
-
-  // An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
-  // transformIgnorePatterns: [
-  //   "/node_modules/",
-  //   "\\.pnp\\.[^\\/]+$"
-  // ],
-
-  // An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them
-  // unmockedModulePathPatterns: undefined,
-
-  // Indicates whether each individual test should be reported during the run
-  // verbose: undefined,
-
-  // An array of regexp patterns that are matched against all source file paths before re-running tests in watch mode
-  // watchPathIgnorePatterns: [],
-
-  // Whether to use watchman for file crawling
-  // watchman: true,
-};