Added getElementByDataTestIdDeep utility function for tests to find shadow dom elements (#172)

* Add getElementByDataTestIdDeep utility function for enhanced testing capabilities

* Update CHANGELOG to reflect the addition of getElementByDataTestIdDeep utility function for tests

* Refactor getElementByDataTestIdDeep to utilize walkShadowDom for improved shadow DOM traversal; add tests for walkShadowDom functionality

* Refactor shadow DOM traversal tests by removing unnecessary comments and improving clarity; streamline walkShadowDom function for better readability

* Refactor tests for getElementByDataTestIdDeep by removing redundant comments and enhancing code clarity; ensure consistent formatting in test cases.

---------

Co-authored-by: Tudor Morar <tudor.morar@multiversx.com>

Author: razvantomegea

CHANGELOG.md

@@ -7,7 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [[0.0.19](https://github.com/multiversx/mx-sdk-dapp-ui/pull/173)] - 2025-07-23
+- [Added getElementByDataTestIdDeep utility function for tests](https://github.com/multiversx/mx-sdk-dapp-ui/pull/172)
+
+## [[0.0.19](https://github.com/multiversx/mx-sdk-dapp-ui/pull/172)] - 2025-07-23
 
 - [Updated data-theme](https://github.com/multiversx/mx-sdk-dapp-ui/pull/171)
 

src/utils/tests/getElementByDataTestIdDeep.jest.ts

@@ -0,0 +1,36 @@
+import { createDataTestIdSelector, walkShadowDom } from './shadowDomTraversal';
+
+/**
+ * Recursively searches the document and all shadow roots for the first element
+ * matching the given data-testid using Jest/JSDOM.
+ *
+ * @param {string} dataTestId - The value of the data-testid attribute to search for.
+ * @param {Document|ShadowRoot} root - The root to search from (defaults to document).
+ * @returns {Element|null} - The found element, or null.
+ */
+export function getElementByDataTestIdDeep(dataTestId: string, root: Document | ShadowRoot = document): Element | null {
+  return walkShadowDom(root, createDataTestIdSelector(dataTestId));
+}
+
+/**
+ * Jest/Testing Library compatible version that works with screen queries
+ * @param {string} dataTestId - The value of the data-testid attribute to search for.
+ * @returns {Element|null} - The found element, or null.
+ */
+export function queryByDataTestIdDeep(dataTestId: string): Element | null {
+  return getElementByDataTestIdDeep(dataTestId);
+}
+
+/**
+ * Jest/Testing Library compatible version that throws if element not found
+ * @param {string} dataTestId - The value of the data-testid attribute to search for.
+ * @returns {Element} - The found element.
+ * @throws {Error} If element is not found.
+ */
+export function getByDataTestIdDeep(dataTestId: string): Element {
+  const element = getElementByDataTestIdDeep(dataTestId);
+  if (!element) {
+    throw new Error(`Unable to find element with data-testid: ${dataTestId}`);
+  }
+  return element;
+}

src/utils/tests/getElementByDataTestIdDeep.playwright.ts

@@ -0,0 +1,22 @@
+import { createDataTestIdSelector, walkShadowDom } from './shadowDomTraversal';
+
+/**
+ * Recursively searches the document and all shadow roots for the first element
+ * matching the given data-testid using Playwright.
+ *
+ * @param {import('@playwright/test').Page} page - The Playwright Page instance.
+ * @param {string} testId - The value of the data-testid attribute to search for.
+ * @returns {Promise<import('@playwright/test').Locator|null>} - Locator for the found element, or null.
+ */
+export async function getElementByDataTestIdDeep(page: any, dataTestId: string) {
+  const element = await page.evaluate(
+    (testId: string) => walkShadowDom(document, createDataTestIdSelector(testId)),
+    dataTestId,
+  );
+
+  if (!element) {
+    return null;
+  }
+
+  return page.locator(createDataTestIdSelector(dataTestId)).first();
+}

src/utils/tests/getElementByDataTestIdDeep.puppeteer.ts

@@ -0,0 +1,25 @@
+import { createDataTestIdSelector, walkShadowDom } from './shadowDomTraversal';
+
+/**
+ * Recursively searches the document and all shadow roots for the first element
+ * matching the given data-testid.
+ *
+ * @param {import('puppeteer').Page} page - The Puppeteer Page instance.
+ * @param {string} dataTestId - The value of the data-testid attribute to search for.
+ * @returns {Promise<import('puppeteer').ElementHandle|null>} - Handle to the found element, or null.
+ */
+export async function getElementByDataTestIdDeep(page: any, dataTestId: string) {
+  const handle = await page.evaluateHandle(
+    (testId: string) => walkShadowDom(document, createDataTestIdSelector(testId)),
+    dataTestId,
+  );
+
+  const element = handle.asElement();
+
+  if (!element) {
+    await handle.dispose();
+    return null;
+  }
+
+  return element;
+}

src/utils/tests/getElementByDataTestIdDeep.spec.ts

@@ -0,0 +1,111 @@
+import {
+  getByDataTestIdDeep,
+  getElementByDataTestIdDeep,
+  queryByDataTestIdDeep,
+} from './getElementByDataTestIdDeep.jest';
+
+describe('getElementByDataTestIdDeep', () => {
+  let mockElement: any;
+  let mockShadowRoot: any;
+  let mockDocument: any;
+
+  beforeEach(() => {
+    mockElement = {
+      querySelector: jest.fn(),
+      querySelectorAll: jest.fn(),
+      shadowRoot: null,
+    };
+
+    mockShadowRoot = {
+      querySelector: jest.fn(),
+      querySelectorAll: jest.fn(),
+    };
+
+    mockDocument = {
+      querySelector: jest.fn(),
+      querySelectorAll: jest.fn(),
+    };
+
+    global.document = mockDocument as any;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should find element in document root', () => {
+    const testElement = { id: 'test-element' };
+    mockDocument.querySelector.mockReturnValue(testElement);
+    mockDocument.querySelectorAll.mockReturnValue([]);
+
+    const result = getElementByDataTestIdDeep('test-id');
+
+    expect(mockDocument.querySelector).toHaveBeenCalledWith('[data-testid="test-id"]');
+    expect(result).toBe(testElement);
+  });
+
+  it('should find element in shadow root', () => {
+    const testElement = { id: 'shadow-element' };
+    const elementWithShadow = { ...mockElement, shadowRoot: mockShadowRoot };
+
+    mockDocument.querySelector.mockReturnValue(null);
+    mockDocument.querySelectorAll.mockReturnValue([elementWithShadow]);
+
+    mockShadowRoot.querySelector.mockReturnValue(testElement);
+    mockShadowRoot.querySelectorAll.mockReturnValue([]);
+
+    const result = getElementByDataTestIdDeep('test-id');
+
+    expect(result).toBe(testElement);
+    expect(mockShadowRoot.querySelector).toHaveBeenCalledWith('[data-testid="test-id"]');
+  });
+
+  it('should return null when element not found', () => {
+    mockDocument.querySelector.mockReturnValue(null);
+    mockDocument.querySelectorAll.mockReturnValue([]);
+
+    const result = getElementByDataTestIdDeep('non-existent');
+
+    expect(result).toBeNull();
+  });
+
+  it('queryByDataTestIdDeep should return null when element not found', () => {
+    mockDocument.querySelector.mockReturnValue(null);
+    mockDocument.querySelectorAll.mockReturnValue([]);
+
+    const result = queryByDataTestIdDeep('non-existent');
+
+    expect(result).toBeNull();
+  });
+
+  it('getByDataTestIdDeep should throw when element not found', () => {
+    mockDocument.querySelector.mockReturnValue(null);
+    mockDocument.querySelectorAll.mockReturnValue([]);
+
+    expect(() => getByDataTestIdDeep('non-existent')).toThrow('Unable to find element with data-testid: non-existent');
+  });
+
+  it('getByDataTestIdDeep should return element when found', () => {
+    const testElement = { id: 'test-element' };
+    mockDocument.querySelector.mockReturnValue(testElement);
+    mockDocument.querySelectorAll.mockReturnValue([]);
+
+    const result = getByDataTestIdDeep('test-id');
+
+    expect(result).toBe(testElement);
+  });
+});
+
+describe('getElementByDataTestIdDeep usage examples', () => {
+  it('should demonstrate typical usage patterns', () => {
+    const mockRoot = {
+      querySelector: jest.fn().mockReturnValue({ id: 'found-element' }),
+      querySelectorAll: jest.fn().mockReturnValue([]),
+    };
+
+    const result = getElementByDataTestIdDeep('test-id', mockRoot as any);
+
+    expect(result).toEqual({ id: 'found-element' });
+    expect(mockRoot.querySelector).toHaveBeenCalledWith('[data-testid="test-id"]');
+  });
+});

src/utils/tests/shadowDomTraversal.spec.ts

@@ -0,0 +1,55 @@
+import { walkShadowDom } from './shadowDomTraversal';
+
+describe('walkShadowDom', () => {
+  let root: Document;
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    root = document;
+  });
+
+  it('finds an element in the light DOM', () => {
+    const div = document.createElement('div');
+    div.setAttribute('data-testid', 'foo');
+    document.body.appendChild(div);
+    expect(walkShadowDom(root, '[data-testid="foo"]')).toBe(div);
+  });
+
+  it('finds an element in a simulated shadow DOM', () => {
+    const host = document.createElement('div');
+    const shadowRoot = document.createElement('div');
+    const shadowChild = document.createElement('span');
+    shadowChild.setAttribute('data-testid', 'bar');
+    shadowRoot.appendChild(shadowChild);
+    (host as any).shadowRoot = shadowRoot;
+    document.body.appendChild(host);
+    const origQuerySelectorAll = document.querySelectorAll;
+    document.querySelectorAll = function (sel) {
+      if (sel === '*') {
+        return [host] as any;
+      }
+
+      return origQuerySelectorAll.call(this, sel);
+    };
+
+    expect(walkShadowDom(document, '[data-testid="bar"]')).toBe(shadowChild);
+    document.querySelectorAll = origQuerySelectorAll;
+  });
+
+  it('throws if root is missing', () => {
+    expect(() => walkShadowDom(undefined as any, '[data-testid="foo"]')).toThrow('walkShadowDom: root is required');
+  });
+
+  it('throws if selector is missing', () => {
+    expect(() => walkShadowDom(document, undefined as any)).toThrow(
+      'walkShadowDom: selector must be a non-empty string',
+    );
+  });
+
+  it('throws if selector is not a string', () => {
+    expect(() => walkShadowDom(document, 123 as any)).toThrow('walkShadowDom: selector must be a non-empty string');
+  });
+
+  it('throws a clear error for invalid CSS selector', () => {
+    expect(() => walkShadowDom(document, '!!!invalid')).toThrow(/Invalid CSS selector/);
+  });
+});

src/utils/tests/shadowDomTraversal.ts

@@ -0,0 +1,64 @@
+/**
+ * Core shadow DOM traversal logic that can be reused across different testing frameworks.
+ * Note: Requires browser support for Shadow DOM APIs (customElements, shadowRoot, etc.).
+ */
+
+/**
+ * Walks a root node (Document or ShadowRoot) depth-first to find elements.
+ * @param {Document | ShadowRoot} root - The root node to start searching from
+ * @param {string} selector - CSS selector to search for
+ * @returns {Element | null} - The found element, or null
+ */
+export function walkShadowDom(root: Document | ShadowRoot, selector: string): Element | null {
+  if (!root) {
+    throw new Error('walkShadowDom: root is required');
+  }
+
+  if (!selector || typeof selector !== 'string') {
+    throw new Error('walkShadowDom: selector must be a non-empty string');
+  }
+
+  let found: Element | null = null;
+
+  try {
+    found = root.querySelector(selector);
+  } catch (err: any) {
+    if (
+      (typeof DOMException !== 'undefined' && err instanceof DOMException && err.name === 'SyntaxError') ||
+      (err && typeof err.message === 'string' && /syntax error|unrecognized expression/i.test(err.message))
+    ) {
+      throw new Error(`walkShadowDom: Invalid CSS selector: '${selector}'`);
+    }
+    throw err;
+  }
+
+  if (found) {
+    return found;
+  }
+
+  const all: Element[] = Array.from(root.querySelectorAll('*'));
+
+  for (const el of all) {
+    if (el.shadowRoot) {
+      const inShadow = walkShadowDom(el.shadowRoot, selector);
+      if (inShadow) {
+        return inShadow;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Helper function to create a data-testid selector
+ * @param {string} testId - The data-testid value
+ * @returns {string} - CSS selector for the data-testid
+ */
+export function createDataTestIdSelector(testId: string): string {
+  const escape =
+    window.CSS && typeof window.CSS.escape === 'function'
+      ? window.CSS.escape
+      : (s: string) => s.replace(/"/g, '"').replace(/'/g, "\\'");
+
+  return `[data-testid="${escape(testId)}"]`;
+}