@api-client/ui 0.5.0 → 0.5.2

package/test/README.md

@@ -0,0 +1,372 @@
+# Test Setup Guide
+
+This document explains how to use the test infrastructure for the UI component library.
+
+## Overview
+
+The test setup provides:
+
+- **Global test utilities** for common testing patterns
+- **Custom matchers** for better assertions
+- **UI interaction helpers** for simulating user actions
+- **Async helpers** for handling asynchronous operations
+- **Performance testing utilities**
+
+## Test Configuration
+
+### Web Test Runner
+
+Tests run using [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) with:
+
+- **Playwright** for browser automation
+- **OAuth2 mock server** for authentication testing
+- **Coverage reporting** with lcov format
+- **Custom test HTML** with Material Design 3 styles
+
+### File Structure
+
+```plain
+test/
+├── setup.ts                 # Global test setup
+├── setup.test.ts            # Example test demonstrating setup
+├── env.ts                   # Environment configuration
+├── helpers/
+│   ├── UiMock.ts            # UI interaction utilities
+│   └── TestUtils.ts         # Extended test utilities
+└── [component-tests]/       # Component-specific tests
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+npm run test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+## Global Test Utilities
+
+The setup provides global utilities accessible via `window.testUtils`:
+
+### waitForElement(selector, timeout?)
+
+Wait for an element to appear in the DOM:
+
+```typescript
+const element = await window.testUtils.waitForElement('#my-element', 5000)
+```
+
+### waitForCondition(condition, timeout?)
+
+Wait for a condition to become true:
+
+```typescript
+await window.testUtils.waitForCondition(() => someVariable === true, 5000)
+```
+
+## Custom Matchers
+
+Enhanced assertion helpers in `customMatchers`:
+
+### toHaveClasses(element, ...classes)
+
+Check if element has specific CSS classes:
+
+```typescript
+const result = customMatchers.toHaveClasses(element, 'active', 'highlighted')
+assert.isTrue(result.pass)
+```
+
+### toBeVisible(element)
+
+Check if element is visible (not hidden by CSS):
+
+```typescript
+const result = customMatchers.toBeVisible(element)
+assert.isTrue(result.pass)
+```
+
+### toHaveAttribute(element, attribute, value?)
+
+Check if element has specific attribute:
+
+```typescript
+const result = customMatchers.toHaveAttribute(element, 'data-test', 'value')
+assert.isTrue(result.pass)
+```
+
+## UI Interaction (UiMock)
+
+Simulate user interactions:
+
+### Keyboard Events
+
+```typescript
+// Single key events
+UiMock.keyDown(element, 'Enter')
+UiMock.keyUp(element, 'Escape')
+
+// Full key press (down + up)
+await UiMock.keyPress(element, 'Space', { ctrlKey: true })
+```
+
+### Mouse Events
+
+```typescript
+// Get element center
+const center = UiMock.getMiddleOfElement(element)
+
+// Move mouse between points
+await UiMock.moveMouse(fromPoint, toPoint, steps)
+
+// Drag and drop
+await UiMock.dragAndDrop(sourceElement, targetElement)
+```
+
+### File Drag Events
+
+```typescript
+const file = new File(['content'], 'test.txt', { type: 'text/plain' })
+const dragEvent = UiMock.getFileDragEvent('drop', { file })
+element.dispatchEvent(dragEvent)
+```
+
+## Async Helpers
+
+Handle asynchronous operations:
+
+### waitForAll(conditions, timeout?)
+
+Wait for multiple conditions:
+
+```typescript
+await asyncHelpers.waitForAll([
+  () => condition1,
+  () => condition2,
+], 5000)
+```
+
+### waitForAny(conditions, timeout?)
+
+Wait for any condition to be true:
+
+```typescript
+const index = await asyncHelpers.waitForAny([
+  () => condition1,
+  () => condition2,
+])
+```
+
+### retry(operation, maxAttempts?, baseDelay?)
+
+Retry failed operations with exponential backoff:
+
+```typescript
+const result = await asyncHelpers.retry(async () => {
+  const response = await fetch('/api/data')
+  if (!response.ok) throw new Error('Failed')
+  return response.json()
+}, 3, 100)
+```
+
+## Test Factories
+
+Create reusable test data and element factories:
+
+### Data Factory
+
+```typescript
+const userFactory = testFactory.createDataFactory({
+  id: 1,
+  name: 'Test User',
+  email: 'test@example.com',
+})
+
+const user1 = userFactory() // Uses defaults
+const user2 = userFactory({ name: 'Custom User' }) // Override specific fields
+```
+
+### Element Test Suite
+
+```typescript
+const suite = testFactory.createElementTestSuite('my-element', '../src/my-element.js')
+
+// In tests:
+await suite.setup()
+const element = await suite.createElement({ attribute: 'value' }, 'content')
+// ... test element ...
+suite.cleanup()
+```
+
+## Performance Testing
+
+Measure and assert performance:
+
+### measureTime(fn)
+
+```typescript
+const { result, duration } = await performanceHelpers.measureTime(async () => {
+  return await someExpensiveOperation()
+})
+
+console.log(`Operation took ${duration}ms`)
+```
+
+### expectWithinTime(operation, maxDuration, message?)
+
+```typescript
+const result = await performanceHelpers.expectWithinTime(
+  () => renderLargeList(),
+  1000, // max 1 second
+  'List rendering should be fast'
+)
+```
+
+## Writing Component Tests
+
+### Basic Structure
+
+```typescript
+import { assert, fixture, html } from '@open-wc/testing'
+import { customMatchers } from '../helpers/TestUtils.js'
+import { UiMock } from '../helpers/UiMock.js'
+
+// Import test setup
+import '../setup.js'
+
+// Import component
+import '../src/my-component.js'
+
+describe('MyComponent', () => {
+  async function basicFixture() {
+    return fixture(html`<my-component></my-component>`)
+  }
+
+  it('should render correctly', async () => {
+    const element = await basicFixture()
+    
+    // Use custom matchers
+    const result = customMatchers.toBeVisible(element)
+    assert.isTrue(result.pass)
+    
+    // Test functionality
+    await UiMock.keyPress(element, 'Enter')
+    
+    // Wait for changes
+    await window.testUtils.waitForCondition(() => 
+      element.hasAttribute('data-processed')
+    )
+    
+    assert.isTrue(element.hasAttribute('data-processed'))
+  })
+})
+```
+
+### Testing Custom Elements
+
+```typescript
+describe('CustomElement', () => {
+  let element: HTMLElement
+
+  beforeEach(async () => {
+    element = await fixture(html`<custom-element 
+      .property="${'value'}"
+      @event="${(e) => console.log(e)}"
+    ></custom-element>`)
+  })
+
+  it('should handle properties', () => {
+    // Test property binding
+    assert.equal(element.property, 'value')
+  })
+
+  it('should handle events', async () => {
+    let eventFired = false
+    element.addEventListener('custom-event', () => {
+      eventFired = true
+    })
+
+    // Trigger event
+    element.dispatchEvent(new CustomEvent('trigger'))
+    
+    await window.testUtils.waitForCondition(() => eventFired)
+    assert.isTrue(eventFired)
+  })
+})
+```
+
+## Environment Variables
+
+Test environment configuration is available through the mock server:
+
+- OAuth2 server details available in test environment
+- Custom environment setup via `env.ts`
+
+## Coverage Reports
+
+Coverage reports are generated in `coverage/` directory:
+
+- `lcov.info` - Machine-readable coverage data
+- `lcov-report/` - Human-readable HTML reports
+
+Open `coverage/lcov-report/index.html` to view detailed coverage information.
+
+## Best Practices
+
+1. **Use the global setup**: Import `../setup.js` in test files
+2. **Leverage custom matchers**: Use `customMatchers` for better assertions
+3. **Simulate real interactions**: Use `UiMock` for realistic user interactions
+4. **Handle async operations**: Use `asyncHelpers` for waiting and retrying
+5. **Create reusable factories**: Use `testFactory` for common test data
+6. **Test performance**: Use `performanceHelpers` for timing-critical code
+7. **Clean up properly**: The global setup handles cleanup automatically
+8. **Use meaningful assertions**: Prefer descriptive custom matchers over generic ones
+
+## DOM Element Assertions
+
+When comparing DOM elements, always use the special DOM assertion methods from `@open-wc/testing`:
+
+### assert.dom.equal(actual, expected)
+
+Compare DOM elements for equality:
+
+```typescript
+const element1 = document.querySelector('#test')
+const element2 = await window.testUtils.waitForElement('#test')
+assert.dom.equal(element1, element2)
+```
+
+### assert.dom.notEqual(actual, expected)
+
+Assert that DOM elements are not the same:
+
+```typescript
+const element1 = document.querySelector('#test1')
+const element2 = document.querySelector('#test2')
+assert.dom.notEqual(element1, element2)
+```
+
+### assert.dom.equalSnapshot(element, snapshot)
+
+Compare element with a snapshot:
+
+```typescript
+const element = await fixture(html`<div>Content</div>`)
+assert.dom.equalSnapshot(element, '<div>Content</div>')
+```
+
+### assert.dom.notEqualSnapshot(element, snapshot)
+
+Assert element doesn't match snapshot:
+
+```typescript
+const element = await fixture(html`<div>Changed</div>`)
+assert.dom.notEqualSnapshot(element, '<div>Original</div>')
+```
+
+> ⚠️ **Important**: Never use regular `assert.equal()` for DOM elements as it won't work correctly. Always use `assert.dom.*` methods for DOM comparisons.

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)
+    })
+  })
+})