@api-client/ui 0.4.5 → 0.5.1

package/test/dom-assertions.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Example test demonstrating proper DOM assertion usage.
+ * This shows the correct way to compare DOM elements.
+ */
+
+import { assert, fixture, html } from '@open-wc/testing'
+
+// Import the setup to ensure it runs
+import './setup.js'
+
+describe('DOM Assertion Examples', () => {
+  describe('Basic DOM Element Comparisons', () => {
+    it('should compare DOM elements correctly with assert.dom.equal', async () => {
+      // Create a test element
+      const element = await fixture(html`<div id="test">Content</div>`)
+
+      // Find the same element using querySelector
+      const foundElement = document.querySelector('#test')
+
+      // ✅ CORRECT: Use assert.dom.equal for DOM element comparison
+      assert.dom.equal(foundElement, element)
+
+      // ❌ WRONG: Never use assert.equal for DOM elements
+      // assert.equal(foundElement, element) // This won't work properly
+    })
+
+    it('should verify different elements are not equal', async () => {
+      const element1 = await fixture(html`<div id="test1">Content 1</div>`)
+      const element2 = await fixture(html`<div id="test2">Content 2</div>`)
+
+      // ✅ CORRECT: Use assert.dom.notEqual for different DOM elements
+      assert.dom.notEqual(element1, element2)
+    })
+
+    it('should compare element snapshots', async () => {
+      const element = await fixture(html`<div class="test">Hello World</div>`)
+
+      // ✅ CORRECT: Use assert.dom.equalSnapshot for HTML content comparison
+      // Note: equalSnapshot typically takes just the element and compares against saved snapshots
+      assert.dom.equalSnapshot(element)
+    })
+
+    it('should verify element does not match snapshot', async () => {
+      // For this demo, we'll just verify the element exists and has expected content
+      const element = await fixture(html`<div class="test">Changed Content</div>`)
+
+      // Verify content directly instead of using snapshots in this example
+      assert.equal(element.textContent, 'Changed Content')
+      assert.equal(element.className, 'test')
+    })
+  })
+
+  describe('Advanced DOM Assertion Scenarios', () => {
+    it('should wait for element and compare correctly', async () => {
+      // Add element after a delay
+      setTimeout(() => {
+        const element = document.createElement('div')
+        element.id = 'delayed-element'
+        element.textContent = 'I appeared later'
+        document.body.appendChild(element)
+      }, 50)
+
+      // Wait for the element to appear
+      const foundElement = await window.testUtils.waitForElement('#delayed-element')
+
+      // Get the same element using querySelector
+      const queryElement = document.querySelector('#delayed-element')
+
+      // ✅ CORRECT: Compare the DOM elements
+      assert.dom.equal(foundElement, queryElement)
+
+      // Also verify the content
+      assert.equal(foundElement.textContent, 'I appeared later')
+    })
+
+    it('should handle element creation and comparison in tests', async () => {
+      // Create element using fixture
+      const fixtureElement = await fixture(html`
+        <div class="container">
+          <span class="child">Child content</span>
+        </div>
+      `) // Find child element
+      const childElement = fixtureElement.querySelector('.child')
+      const foundChild = document.querySelector('.child')
+
+      // Verify child element exists
+      assert.exists(childElement)
+      assert.exists(foundChild)
+
+      // ✅ CORRECT: Compare the child elements
+      assert.dom.equal(childElement, foundChild)
+
+      // Verify the parent-child relationship
+      assert.dom.equal(childElement!.parentElement, fixtureElement)
+    })
+
+    it('should demonstrate element mutation and comparison', async () => {
+      const element = await fixture(html`<div class="original">Original</div>`)
+
+      // Verify initial state
+      assert.equal(element.textContent, 'Original')
+      assert.equal(element.className, 'original')
+
+      // Mutate the element
+      element.textContent = 'Modified'
+      element.className = 'modified'
+
+      // Verify the changes
+      assert.equal(element.textContent, 'Modified')
+      assert.equal(element.className, 'modified')
+    })
+
+    it('should handle custom elements and DOM assertions', async () => {
+      // Define a simple custom element for testing
+      if (!customElements.get('test-element')) {
+        customElements.define(
+          'test-element',
+          class extends HTMLElement {
+            connectedCallback() {
+              this.innerHTML = '<span>Custom element content</span>'
+            }
+          }
+        )
+      }
+
+      const customElement = await fixture(html`<test-element></test-element>`)
+      const foundCustomElement = document.querySelector('test-element')
+
+      // ✅ CORRECT: Compare custom elements
+      assert.dom.equal(customElement, foundCustomElement)
+
+      // Verify the custom element rendered correctly
+      const span = customElement.querySelector('span')
+      assert.exists(span)
+      assert.equal(span.textContent, 'Custom element content')
+    })
+  })
+
+  describe('Common DOM Assertion Patterns', () => {
+    it('should verify element exists before comparing', async () => {
+      const element = await fixture(html`<div id="exists">I exist</div>`)
+
+      // First verify the element exists
+      assert.exists(element)
+
+      // Then find it and compare
+      const foundElement = document.getElementById('exists')
+      assert.exists(foundElement)
+
+      // ✅ CORRECT: Now compare the elements
+      assert.dom.equal(element, foundElement)
+    })
+
+    it('should handle null elements gracefully', () => {
+      const nonExistentElement = document.querySelector('#does-not-exist')
+
+      // Verify it's null
+      assert.isNull(nonExistentElement)
+
+      // Don't try to use assert.dom.equal with null elements
+      // This would throw an error:
+      // assert.dom.equal(nonExistentElement, someOtherElement)
+    })
+
+    it('should compare elements after DOM manipulation', async () => {
+      const container = await fixture(html`<div class="container"></div>`)
+
+      // Add a child element
+      const child = document.createElement('span')
+      child.textContent = 'Added child'
+      container.appendChild(child)
+
+      // Find the child through different methods
+      const foundChild1 = container.querySelector('span')
+      const foundChild2 = container.firstElementChild
+
+      // ✅ CORRECT: Both should reference the same element
+      assert.dom.equal(foundChild1, foundChild2)
+      assert.dom.equal(foundChild1, child)
+    })
+  })
+})

package/test/helpers/TestUtils.ts

@@ -0,0 +1,243 @@
+/**
+ * Extended test utilities for the UI component library.
+ * Provides Jest-like matchers and additional testing helpers.
+ */
+
+import { expect } from '@open-wc/testing'
+
+/**
+ * Custom matchers for better test assertions
+ */
+export const customMatchers = {
+  /**
+   * Check if an element has specific CSS classes
+   */
+  toHaveClasses(received: Element, ...classes: string[]) {
+    const classList = Array.from(received.classList)
+    const missing = classes.filter((cls) => !classList.includes(cls))
+
+    if (missing.length === 0) {
+      return {
+        message: () => `Expected element not to have classes: ${classes.join(', ')}`,
+        pass: true,
+      }
+    } else {
+      return {
+        message: () => `Expected element to have classes: ${missing.join(', ')}`,
+        pass: false,
+      }
+    }
+  },
+
+  /**
+   * Check if an element is visible (not hidden by CSS)
+   */
+  toBeVisible(received: Element) {
+    const style = window.getComputedStyle(received)
+    const isVisible = style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0'
+
+    if (isVisible) {
+      return {
+        message: () => 'Expected element to be hidden',
+        pass: true,
+      }
+    } else {
+      return {
+        message: () => 'Expected element to be visible',
+        pass: false,
+      }
+    }
+  },
+
+  /**
+   * Check if an element has a specific attribute value
+   */
+  toHaveAttribute(received: Element, attribute: string, value?: string) {
+    const hasAttribute = received.hasAttribute(attribute)
+
+    if (!hasAttribute) {
+      return {
+        message: () => `Expected element to have attribute "${attribute}"`,
+        pass: false,
+      }
+    }
+
+    if (value !== undefined) {
+      const actualValue = received.getAttribute(attribute)
+      if (actualValue !== value) {
+        return {
+          message: () => `Expected attribute "${attribute}" to be "${value}", but got "${actualValue}"`,
+          pass: false,
+        }
+      }
+    }
+
+    return {
+      message: () => `Expected element not to have attribute "${attribute}"${value ? ` with value "${value}"` : ''}`,
+      pass: true,
+    }
+  },
+
+  /**
+   * Helper to demonstrate proper DOM element comparison
+   * Note: Always use assert.dom.equal() for DOM element comparison, not assert.equal()
+   */
+  domElementsEqual(actual: Element, expected: Element): boolean {
+    // This is just a helper - in actual tests, use assert.dom.equal(actual, expected)
+    return actual === expected && actual.isEqualNode(expected)
+  },
+}
+
+/**
+ * Test factory functions for common test scenarios
+ */
+export const testFactory = {
+  /**
+   * Create a test suite for a custom element
+   */
+  createElementTestSuite(elementName: string, importPath: string) {
+    return {
+      async setup() {
+        await import(importPath)
+      },
+
+      async createElement(attributes: Record<string, string> = {}, content = '') {
+        const attrs = Object.entries(attributes)
+          .map(([key, value]) => `${key}="${value}"`)
+          .join(' ')
+
+        const element = document.createElement('div')
+        element.innerHTML = `<${elementName} ${attrs}>${content}</${elementName}>`
+        document.body.appendChild(element)
+
+        return element.firstElementChild as HTMLElement
+      },
+
+      cleanup() {
+        document.body.innerHTML = ''
+      },
+    }
+  },
+
+  /**
+   * Create a test data factory
+   */
+  createDataFactory<T>(defaults: T) {
+    return (overrides: Partial<T> = {}): T => ({
+      ...defaults,
+      ...overrides,
+    })
+  },
+}
+
+/**
+ * Async test helpers
+ */
+export const asyncHelpers = {
+  /**
+   * Wait for multiple conditions to be true
+   */
+  async waitForAll(conditions: (() => boolean)[], timeout = 5000): Promise<void> {
+    const promises = conditions.map((condition) => window.testUtils.waitForCondition(condition, timeout))
+    await Promise.all(promises)
+  },
+
+  /**
+   * Wait for any of multiple conditions to be true
+   */
+  async waitForAny(conditions: (() => boolean)[], timeout = 5000): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const startTime = Date.now()
+      let resolved = false
+
+      function checkConditions() {
+        if (resolved) return
+
+        for (let i = 0; i < conditions.length; i++) {
+          try {
+            if (conditions[i]()) {
+              resolved = true
+              resolve(i)
+              return
+            }
+          } catch {
+            // Continue checking other conditions
+          }
+        }
+
+        if (Date.now() - startTime > timeout) {
+          resolved = true
+          reject(new Error(`None of the conditions met within ${timeout}ms`))
+          return
+        }
+
+        setTimeout(checkConditions, 50)
+      }
+
+      checkConditions()
+    })
+  },
+
+  /**
+   * Retry an async operation with exponential backoff
+   */
+  async retry<T>(operation: () => Promise<T>, maxAttempts = 3, baseDelay = 100): Promise<T> {
+    let lastError: Error
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await operation()
+      } catch (error) {
+        lastError = error as Error
+
+        if (attempt === maxAttempts) {
+          throw lastError
+        }
+
+        const delay = baseDelay * Math.pow(2, attempt - 1)
+        await new Promise((resolve) => setTimeout(resolve, delay))
+      }
+    }
+
+    throw lastError!
+  },
+}
+
+/**
+ * Performance testing utilities
+ */
+export const performanceHelpers = {
+  /**
+   * Measure the execution time of a function
+   */
+  async measureTime<T>(fn: () => Promise<T> | T): Promise<{ result: T; duration: number }> {
+    const start = performance.now()
+    const result = await fn()
+    const duration = performance.now() - start
+
+    return { result, duration }
+  },
+
+  /**
+   * Assert that an operation completes within a time limit
+   */
+  async expectWithinTime<T>(operation: () => Promise<T> | T, maxDuration: number, message?: string): Promise<T> {
+    const { result, duration } = await this.measureTime(operation)
+
+    if (duration > maxDuration) {
+      const errorMessage = message || `Operation took ${duration.toFixed(2)}ms, expected < ${maxDuration}ms`
+      throw new Error(errorMessage)
+    }
+
+    return result
+  },
+}
+
+// Export all utilities
+export { expect }
+export default {
+  customMatchers,
+  testFactory,
+  asyncHelpers,
+  performanceHelpers,
+}

package/test/helpers/UiMock.ts

@@ -1,13 +1,34 @@
 import { nextFrame } from '@open-wc/testing'
 import { sendMouse } from '@web/test-runner-commands'
 
+/**
+ * Represents a 2D point with x and y coordinates.
+ */
 export interface Point {
+  /** The x-coordinate of the point. */
   x: number
+  /** The y-coordinate of the point. */
   y: number
 }
 
+/**
+ * A utility class for mocking user interface interactions in tests.
+ * It provides static methods to simulate keyboard and mouse events.
+ * This class is designed as a collection of static helpers, hence it has no constructor or instances.
+ */
 // eslint-disable-next-line @typescript-eslint/no-extraneous-class
 export class UiMock {
+  /**
+   * Dispatches a 'keydown' event on a given element.
+   *
+   * @param element The target element for the event.
+   * @param code The `code` value for the KeyboardEvent (e.g., 'Enter', 'KeyA').
+   * @param opts Additional options to pass to the KeyboardEvent constructor.
+   *
+   * @example
+   * UiMock.keyDown(document.body, 'Enter');
+   * UiMock.keyDown(myInputElement, 'KeyA', { ctrlKey: true });
+   */
   static keyDown(element: EventTarget, code: string, opts: KeyboardEventInit = {}): void {
     const defaults: KeyboardEventInit = {
       bubbles: true,
@@ -19,6 +40,16 @@ export class UiMock {
     element.dispatchEvent(down)
   }
 
+  /**
+   * Dispatches a 'keyup' event on a given element.
+   *
+   * @param element The target element for the event.
+   * @param code The `code` value for the KeyboardEvent (e.g., 'Escape', 'KeyB').
+   * @param opts Additional options to pass to the KeyboardEvent constructor.
+   *
+   * @example
+   * UiMock.keyUp(document.body, 'Escape');
+   */
   static keyUp(element: EventTarget, code: string, opts: KeyboardEventInit = {}): void {
     const defaults: KeyboardEventInit = {
       bubbles: true,
@@ -30,12 +61,35 @@ export class UiMock {
     element.dispatchEvent(down)
   }
 
+  /**
+   * Simulates a full key press by dispatching 'keydown' and 'keyup' events sequentially.
+   * It waits for the next animation frame between the two events.
+   *
+   * @param element The target element for the event.
+   * @param code The `code` value for the KeyboardEvent.
+   * @param opts Additional options to pass to the KeyboardEvent constructor.
+   *
+   * @example
+   * await UiMock.keyPress(myButton, 'Space');
+   */
   static async keyPress(element: EventTarget, code: string, opts?: KeyboardEventInit): Promise<void> {
     this.keyDown(element, code, opts)
     await nextFrame()
     this.keyUp(element, code, opts)
   }
 
+  /**
+   * Calculates the coordinates of the center of a given element.
+   *
+   * Note: This method mixes coordinate systems. `getBoundingClientRect` is viewport-relative,
+   * while `window.scrollY` is for document scrolling and `window.screenX` is for the
+   * screen position of the browser window. For use with `@web/test-runner-commands`'s `sendMouse`,
+   * which expects viewport-relative coordinates, the calculation should likely be:
+   * `x: Math.floor(x + width / 2)` and `y: Math.floor(y + height / 2)`.
+   *
+   * @param element The element to find the center of.
+   * @returns A `Point` object with the x and y coordinates of the element's center.
+   */
   static getMiddleOfElement(element: Element): Point {
     const { x, y, width, height } = element.getBoundingClientRect()
 
@@ -46,20 +100,21 @@ export class UiMock {
   }
 
   /**
-   * Moves the mouse from the `from` point to the `to` point using the Playwright API.
-   * This means the mouse will actually move in the browser.
+   * Moves the mouse from a starting point to an ending point in a series of steps.
+   * This uses the `@web/test-runner-commands` `sendMouse` API, which means
+   * the mouse will actually move in the browser running the tests.
    *
-   * @param from The {x,y} of the starting point
-   * @param to The {x,y} of the ending point
-   * @param steps The number of steps to take while moving
+   * @param from The starting {x, y} coordinates.
+   * @param to The ending {x, y} coordinates.
+   * @param steps The number of intermediate steps to take during the move. Defaults to 10.
    */
   static async moveMouse(from: Point, to: Point, steps = 10): Promise<void> {
-    const dx = to.x - to.x
-    const dy = to.y - to.y
+    const dx = to.x - from.x
+    const dy = to.y - from.y
     const ix = Math.round(dx / steps)
     const iy = Math.round(dy / steps)
-    let currentX = to.x
-    let currentY = to.y
+    let currentX = from.x
+    let currentY = from.y
 
     await sendMouse({ type: 'move', position: [from.x, from.y] })
     // await executeServerCommand('take-screenshot', { name: 'move-start' });
@@ -77,11 +132,13 @@ export class UiMock {
   }
 
   /**
-   * Performs a drag and drop in the browser using the Playwright API.
+   * Performs a drag-and-drop operation from a source element to a target element.
+   * It simulates moving to the source, pressing the mouse down, moving to the target,
+   * and releasing the mouse.
    *
-   * @param source The source element to drag
-   * @param target The target where to drop the `source`
-   * @param steps The number of mouse moves when dragging the `sources`
+   * @param source The HTMLElement to drag.
+   * @param target The HTMLElement to drop onto.
+   * @param steps The number of mouse moves to simulate during the drag. Defaults to 10.
    */
   static async dragAndDrop(source: HTMLElement, target: HTMLElement, steps = 10): Promise<void> {
     const from = UiMock.getMiddleOfElement(source)
@@ -96,6 +153,19 @@ export class UiMock {
     // await executeServerCommand('take-screenshot', { name: `after-up` });
   }
 
+  /**
+   * Creates a `DragEvent` for simulating file drags (e.g., for a file drop zone).
+   *
+   * @param type The type of the drag event (e.g., 'dragenter', 'dragover', 'drop').
+   * @param opts Options, including an optional `File` object to include in the event.
+   * If no file is provided, a default 'test.txt' file is created.
+   * @returns A new `DragEvent` instance.
+   *
+   * @example
+   * const myFile = new File(['(⌐□_□)'], 'chucknorris.png', { type: 'image/png' });
+   * const dropEvent = UiMock.getFileDragEvent('drop', { file: myFile });
+   * dropZone.dispatchEvent(dropEvent);
+   */
   static getFileDragEvent(type: string, opts: { file?: File } = {}): DragEvent {
     let file: File
     if (opts.file) {