@treelocator/runtime 0.4.7 → 0.6.0

package/src/adapters/vue/vueAdapter.test.ts

@@ -0,0 +1,259 @@
+import { describe, expect, test } from "vitest";
+import { getElementInfo, VueTreeNodeElement } from "./vueAdapter";
+import type { ComponentInternalInstance } from "vue";
+
+function createMockVueElement(
+  props?: { file?: string; name?: string } | null
+): HTMLElement & { __vueParentComponent?: ComponentInternalInstance } {
+  const el = document.createElement("div") as any;
+  el.getBoundingClientRect = () => ({
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 50,
+    top: 0,
+    left: 0,
+    right: 100,
+    bottom: 50,
+    toJSON: () => ({}),
+  });
+
+  if (props) {
+    el.__vueParentComponent = {
+      type: {
+        __file: props.file,
+        __name: props.name,
+      },
+    } as ComponentInternalInstance;
+  }
+
+  return el;
+}
+
+describe("Vue Adapter - getElementInfo", () => {
+  test("returns null when element has no __vueParentComponent", () => {
+    const el = createMockVueElement(null);
+    expect(getElementInfo(el)).toBeNull();
+  });
+
+  test("returns FullElementInfo with correct filePath when __vueParentComponent has type.__file", () => {
+    const el = createMockVueElement({
+      file: "/src/MyComponent.vue",
+      name: "MyComponent",
+    });
+
+    const info = getElementInfo(el);
+    expect(info).not.toBeNull();
+    expect(info!.thisElement.link!.filePath).toBe("/src/MyComponent.vue");
+  });
+
+  test("returns FullElementInfo with correct component name when __vueParentComponent has type.__name", () => {
+    const el = createMockVueElement({
+      file: "/src/Button.vue",
+      name: "Button",
+    });
+
+    const info = getElementInfo(el);
+    expect(info).not.toBeNull();
+    expect(info!.componentsLabels[0]!.label).toBe("Button");
+  });
+
+  test("returns null when __vueParentComponent.type is missing", () => {
+    const el = createMockVueElement(null);
+    el.__vueParentComponent = {} as ComponentInternalInstance;
+    expect(getElementInfo(el)).toBeNull();
+  });
+
+  test("returns null when __vueParentComponent.type.__file is missing", () => {
+    const el = createMockVueElement(null);
+    el.__vueParentComponent = {
+      type: { __name: "MyComponent" },
+    } as ComponentInternalInstance;
+    expect(getElementInfo(el)).toBeNull();
+  });
+
+  test("returns null when __vueParentComponent.type.__name is missing", () => {
+    const el = createMockVueElement(null);
+    el.__vueParentComponent = {
+      type: { __file: "/src/MyComponent.vue" },
+    } as ComponentInternalInstance;
+    expect(getElementInfo(el)).toBeNull();
+  });
+
+  test("returns FullElementInfo with htmlElement pointing to the correct element", () => {
+    const el = createMockVueElement({
+      file: "/src/Card.vue",
+      name: "Card",
+    });
+
+    const info = getElementInfo(el);
+    expect(info).not.toBeNull();
+    expect(info!.htmlElement).toBe(el);
+  });
+
+  test("returns FullElementInfo with element label as lowercase nodeName", () => {
+    const el = createMockVueElement({
+      file: "/src/Button.vue",
+      name: "Button",
+    });
+
+    const info = getElementInfo(el);
+    expect(info).not.toBeNull();
+    expect(info!.thisElement.label).toBe("div"); // createElement creates a div
+  });
+
+  test("returns FullElementInfo with default line and column of 1", () => {
+    const el = createMockVueElement({
+      file: "/src/App.vue",
+      name: "App",
+    });
+
+    const info = getElementInfo(el);
+    expect(info).not.toBeNull();
+    expect(info!.thisElement.link!.line).toBe(1);
+    expect(info!.thisElement.link!.column).toBe(1);
+  });
+
+  test("handles nested Vue component structure with subTree", () => {
+    const el = createMockVueElement({
+      file: "/src/Layout.vue",
+      name: "Layout",
+    });
+
+    // Add a mock subTree (though getElementInfo doesn't use it in the basic case)
+    (el.__vueParentComponent as any).subTree = { el };
+
+    const info = getElementInfo(el);
+    expect(info).not.toBeNull();
+    expect(info!.componentsLabels[0]!.label).toBe("Layout");
+  });
+});
+
+describe("VueTreeNodeElement.getSource", () => {
+  test("returns null when element has no __vueParentComponent", () => {
+    const el = createMockVueElement(null);
+    const node = new VueTreeNodeElement(el);
+    expect(node.getSource()).toBeNull();
+  });
+
+  test("returns Source with correct fileName from __vueParentComponent.type.__file", () => {
+    const el = createMockVueElement({
+      file: "/src/MyComponent.vue",
+      name: "MyComponent",
+    });
+
+    const node = new VueTreeNodeElement(el);
+    const source = node.getSource();
+
+    expect(source).not.toBeNull();
+    expect(source!.fileName).toBe("/src/MyComponent.vue");
+  });
+
+  test("returns Source with lineNumber and columnNumber of 1", () => {
+    const el = createMockVueElement({
+      file: "/src/Button.vue",
+      name: "Button",
+    });
+
+    const node = new VueTreeNodeElement(el);
+    const source = node.getSource();
+
+    expect(source).not.toBeNull();
+    expect(source!.lineNumber).toBe(1);
+    expect(source!.columnNumber).toBe(1);
+  });
+
+  test("returns null when __vueParentComponent.type is missing", () => {
+    const el = createMockVueElement(null);
+    el.__vueParentComponent = {} as ComponentInternalInstance;
+    const node = new VueTreeNodeElement(el);
+    expect(node.getSource()).toBeNull();
+  });
+
+  test("returns null when __vueParentComponent.type.__file is missing", () => {
+    const el = createMockVueElement(null);
+    el.__vueParentComponent = {
+      type: { __name: "MyComponent" },
+    } as ComponentInternalInstance;
+    const node = new VueTreeNodeElement(el);
+    expect(node.getSource()).toBeNull();
+  });
+
+  test("returns Source from different Vue components", () => {
+    const el1 = createMockVueElement({
+      file: "/src/Header.vue",
+      name: "Header",
+    });
+    const el2 = createMockVueElement({
+      file: "/src/Footer.vue",
+      name: "Footer",
+    });
+
+    const node1 = new VueTreeNodeElement(el1);
+    const node2 = new VueTreeNodeElement(el2);
+
+    const source1 = node1.getSource();
+    const source2 = node2.getSource();
+
+    expect(source1!.fileName).toBe("/src/Header.vue");
+    expect(source2!.fileName).toBe("/src/Footer.vue");
+  });
+});
+
+describe("VueTreeNodeElement.getComponent", () => {
+  test("always returns null", () => {
+    const el = createMockVueElement({
+      file: "/src/MyComponent.vue",
+      name: "MyComponent",
+    });
+
+    const node = new VueTreeNodeElement(el);
+    expect(node.getComponent()).toBeNull();
+  });
+
+  test("returns null even when __vueParentComponent is present", () => {
+    const el = createMockVueElement({
+      file: "/src/Button.vue",
+      name: "Button",
+    });
+
+    const node = new VueTreeNodeElement(el);
+    expect(node.getComponent()).toBeNull();
+  });
+
+  test("returns null when element has no __vueParentComponent", () => {
+    const el = createMockVueElement(null);
+    const node = new VueTreeNodeElement(el);
+    expect(node.getComponent()).toBeNull();
+  });
+});
+
+describe("VueTreeNodeElement inheritance and structure", () => {
+  test("extends HtmlElementTreeNode with custom getSource and getComponent", () => {
+    const el = createMockVueElement({
+      file: "/src/App.vue",
+      name: "App",
+    });
+
+    const node = new VueTreeNodeElement(el);
+
+    // Should inherit from HtmlElementTreeNode
+    expect(node.type).toBe("element");
+    expect(node.name).toBe("div");
+    expect(node.element).toBe(el);
+  });
+
+  test("getBox returns element's bounding client rect", () => {
+    const el = createMockVueElement({
+      file: "/src/App.vue",
+      name: "App",
+    });
+
+    const node = new VueTreeNodeElement(el);
+    const box = node.getBox();
+
+    expect(box).not.toBeNull();
+    expect(box!.width).toBe(100);
+    expect(box!.height).toBe(50);
+  });
+});

package/src/browserApi.test.ts

@@ -0,0 +1,329 @@
+import { describe, expect, test, vi, beforeEach, afterEach } from "vitest";
+import { createBrowserAPI, installBrowserAPI } from "./browserApi";
+
+// Mock the heavy dependencies
+vi.mock("./adapters/createTreeNode", () => ({
+  createTreeNode: vi.fn(),
+}));
+vi.mock("./functions/enrichAncestrySourceMaps", () => ({
+  enrichAncestryWithSourceMaps: vi.fn(),
+}));
+
+import { createTreeNode } from "./adapters/createTreeNode";
+import { enrichAncestryWithSourceMaps } from "./functions/enrichAncestrySourceMaps";
+
+describe("browserApi", () => {
+  beforeEach(() => {
+    // Reset window.__treelocator__ before each test
+    delete (window as any).__treelocator__;
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("createBrowserAPI", () => {
+    test("returns an object with all expected method names", () => {
+      const api = createBrowserAPI();
+      expect(api).toHaveProperty("getPath");
+      expect(api).toHaveProperty("getAncestry");
+      expect(api).toHaveProperty("getPathData");
+      expect(api).toHaveProperty("help");
+      expect(api).toHaveProperty("replay");
+      expect(api).toHaveProperty("replayWithRecord");
+      expect(api).toHaveProperty("diff");
+    });
+
+    test("all methods are functions", () => {
+      const api = createBrowserAPI();
+      expect(typeof api.getPath).toBe("function");
+      expect(typeof api.getAncestry).toBe("function");
+      expect(typeof api.getPathData).toBe("function");
+      expect(typeof api.help).toBe("function");
+      expect(typeof api.replay).toBe("function");
+      expect(typeof api.replayWithRecord).toBe("function");
+      expect(typeof api.diff.snapshot).toBe("function");
+      expect(typeof api.diff.computeDiff).toBe("function");
+      expect(typeof api.diff.captureDiff).toBe("function");
+    });
+  });
+
+  describe("diff namespace", () => {
+    beforeEach(() => {
+      if (typeof (document as any).getAnimations !== "function") {
+        (document as any).getAnimations = () => [];
+      }
+    });
+
+    test("snapshot() returns an array", () => {
+      const api = createBrowserAPI();
+      const snaps = api.diff.snapshot();
+      expect(Array.isArray(snaps)).toBe(true);
+    });
+
+    test("computeDiff of identical snapshots has empty entries", () => {
+      const api = createBrowserAPI();
+      const snaps = api.diff.snapshot();
+      const report = api.diff.computeDiff(snaps, snaps);
+      expect(report.entries).toHaveLength(0);
+      expect(report.counts.added).toBe(0);
+    });
+
+    test("captureDiff returns a DeltaReport with settle and text populated", async () => {
+      const api = createBrowserAPI();
+      const report = await api.diff.captureDiff(() => {
+        // no-op action
+      }, { settleTimeoutMs: 200 });
+      expect(report).toHaveProperty("entries");
+      expect(report).toHaveProperty("counts");
+      expect(report).toHaveProperty("text");
+      expect(typeof report.text).toBe("string");
+      expect(["clean", "timeout"]).toContain(report.settle);
+    });
+  });
+
+  describe("help()", () => {
+    test("returns a non-empty string", () => {
+      const api = createBrowserAPI();
+      const help = api.help();
+      expect(typeof help).toBe("string");
+      expect(help.length).toBeGreaterThan(0);
+    });
+
+    test("help text contains 'TreeLocatorJS'", () => {
+      const api = createBrowserAPI();
+      const help = api.help();
+      expect(help).toContain("TreeLocatorJS");
+    });
+
+    test("help text contains method descriptions", () => {
+      const api = createBrowserAPI();
+      const help = api.help();
+      expect(help).toContain("getPath");
+      expect(help).toContain("getAncestry");
+      expect(help).toContain("getPathData");
+    });
+  });
+
+  describe("replay()", () => {
+    test("does not throw when called", () => {
+      const api = createBrowserAPI();
+      expect(() => api.replay()).not.toThrow();
+    });
+
+    test("is a stub that does nothing", () => {
+      const api = createBrowserAPI();
+      // Should not throw and should return undefined
+      const result = api.replay();
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("replayWithRecord()", () => {
+    test("returns a Promise that resolves to null (stub)", async () => {
+      const api = createBrowserAPI();
+      const result = api.replayWithRecord("div");
+      expect(result).toBeInstanceOf(Promise);
+      const resolved = await result;
+      expect(resolved).toBeNull();
+    });
+
+    test("handles both element and selector arguments without error", async () => {
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+
+      // Test with selector
+      const result1 = api.replayWithRecord("div");
+      expect(await result1).toBeNull();
+
+      // Test with element
+      const result2 = api.replayWithRecord(div);
+      expect(await result2).toBeNull();
+    });
+  });
+
+  describe("getPath()", () => {
+    test("returns Promise<string | null>", async () => {
+      const api = createBrowserAPI();
+      const result = api.getPath(document.body);
+      expect(result).toBeInstanceOf(Promise);
+      const resolved = await result;
+      expect(typeof resolved === "string" || resolved === null).toBe(true);
+    });
+
+    test("returns null when selector doesn't match any element", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getPath(".non-existent-selector-xyz");
+      expect(result).toBeNull();
+    });
+
+    test("returns null when passed invalid selector string", async () => {
+      const api = createBrowserAPI();
+      // querySelector with invalid selector will throw; the function should handle it
+      const result = await api.getPath("div > > div");
+      expect(result).toBeNull();
+    });
+
+    test("returns null when createTreeNode returns null", async () => {
+      const mockCreateTreeNode = createTreeNode as any;
+      const mockEnrich = enrichAncestryWithSourceMaps as any;
+
+      mockCreateTreeNode.mockReturnValue(null);
+      mockEnrich.mockResolvedValue(null);
+
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      const result = await api.getPath(div);
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("getAncestry()", () => {
+    test("returns Promise<AncestryItem[] | null>", async () => {
+      const api = createBrowserAPI();
+      const result = api.getAncestry(document.body);
+      expect(result).toBeInstanceOf(Promise);
+      const resolved = await result;
+      expect(Array.isArray(resolved) || resolved === null).toBe(true);
+    });
+
+    test("returns null when selector doesn't match any element", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getAncestry(".non-existent-selector-xyz");
+      expect(result).toBeNull();
+    });
+
+    test("returns null when createTreeNode returns null", async () => {
+      const mockCreateTreeNode = createTreeNode as any;
+      const mockEnrich = enrichAncestryWithSourceMaps as any;
+
+      mockCreateTreeNode.mockReturnValue(null);
+      mockEnrich.mockResolvedValue(null);
+
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      const result = await api.getAncestry(div);
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("getPathData()", () => {
+    test("returns Promise with path and ancestry properties or null", async () => {
+      const api = createBrowserAPI();
+      const result = api.getPathData(document.body);
+      expect(result).toBeInstanceOf(Promise);
+      const resolved = await result;
+      if (resolved !== null) {
+        expect(resolved).toHaveProperty("path");
+        expect(resolved).toHaveProperty("ancestry");
+      }
+    });
+
+    test("returns null when selector doesn't match any element", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getPathData(".non-existent-selector-xyz");
+      expect(result).toBeNull();
+    });
+
+    test("returns null when createTreeNode returns null", async () => {
+      const mockCreateTreeNode = createTreeNode as any;
+      const mockEnrich = enrichAncestryWithSourceMaps as any;
+
+      mockCreateTreeNode.mockReturnValue(null);
+      mockEnrich.mockResolvedValue(null);
+
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      const result = await api.getPathData(div);
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("installBrowserAPI()", () => {
+    test("sets window.__treelocator__ to the created API object", () => {
+      expect((window as any).__treelocator__).toBeUndefined();
+      installBrowserAPI();
+      expect((window as any).__treelocator__).toBeDefined();
+      expect(typeof (window as any).__treelocator__.getPath).toBe("function");
+    });
+
+    test("window.__treelocator__ has all expected methods after installation", () => {
+      installBrowserAPI();
+      const api = (window as any).__treelocator__;
+      expect(api).toHaveProperty("getPath");
+      expect(api).toHaveProperty("getAncestry");
+      expect(api).toHaveProperty("getPathData");
+      expect(api).toHaveProperty("help");
+      expect(api).toHaveProperty("replay");
+      expect(api).toHaveProperty("replayWithRecord");
+      expect(api).toHaveProperty("diff");
+      expect(typeof api.diff.snapshot).toBe("function");
+    });
+
+    test("installBrowserAPI passes adapterId to createBrowserAPI", () => {
+      // We can't directly test this without spying on createBrowserAPI,
+      // but we can verify that the API is created with or without an adapterId
+      installBrowserAPI("react");
+      expect((window as any).__treelocator__).toBeDefined();
+      expect(typeof (window as any).__treelocator__.help).toBe("function");
+    });
+  });
+
+  describe("API accepts HTMLElement or selector string", () => {
+    test("getPath accepts HTMLElement", async () => {
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      document.body.appendChild(div);
+
+      const mockCreateTreeNode = createTreeNode as any;
+      const mockEnrich = enrichAncestryWithSourceMaps as any;
+      mockCreateTreeNode.mockReturnValue(null);
+      mockEnrich.mockResolvedValue(null);
+
+      const result = await api.getPath(div);
+      // With null ancestry, should return null
+      expect(result).toBeNull();
+
+      document.body.removeChild(div);
+    });
+
+    test("getPath accepts CSS selector string", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getPath("body");
+      // Should not throw, result is either string or null
+      expect(typeof result === "string" || result === null).toBe(true);
+    });
+
+    test("getAncestry accepts HTMLElement", async () => {
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      const result = await api.getAncestry(div);
+      expect(result === null || Array.isArray(result)).toBe(true);
+    });
+
+    test("getAncestry accepts CSS selector string", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getAncestry("div");
+      expect(result === null || Array.isArray(result)).toBe(true);
+    });
+
+    test("getPathData accepts HTMLElement", async () => {
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      const result = await api.getPathData(div);
+      if (result !== null) {
+        expect(result).toHaveProperty("path");
+        expect(result).toHaveProperty("ancestry");
+      }
+    });
+
+    test("getPathData accepts CSS selector string", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getPathData("body");
+      if (result !== null) {
+        expect(result).toHaveProperty("path");
+        expect(result).toHaveProperty("ancestry");
+      }
+    });
+  });
+});