@coherent.js/testing 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Drouvin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,446 @@
+# @coherent.js/testing
+
+Complete testing utilities for Coherent.js applications.
+
+## Installation
+
+```bash
+npm install --save-dev @coherent.js/testing
+```
+
+## Features
+
+- ✅ **Test Renderer** - Render components in test environment
+- ✅ **Query Utilities** - Find elements by testId, text, className
+- ✅ **Event Simulation** - Simulate user interactions
+- ✅ **Async Testing** - Wait for conditions and elements
+- ✅ **Mock Functions** - Create mocks and spies
+- ✅ **Custom Matchers** - Coherent.js-specific assertions
+- ✅ **Snapshot Testing** - Component snapshot support
+- ✅ **User Events** - Realistic user interaction simulation
+
+## Quick Start
+
+```javascript
+import { describe, it, expect } from 'vitest';
+import { renderComponent, extendExpect } from '@coherent.js/testing';
+
+// Extend expect with custom matchers
+extendExpect(expect);
+
+describe('MyComponent', () => {
+  it('should render correctly', () => {
+    const component = {
+      div: {
+        'data-testid': 'my-div',
+        text: 'Hello World'
+      }
+    };
+
+    const { getByTestId } = renderComponent(component);
+    
+    expect(getByTestId('my-div')).toHaveText('Hello World');
+  });
+});
+```
+
+## API Reference
+
+### Rendering
+
+#### `renderComponent(component, options)`
+
+Render a component for testing.
+
+```javascript
+const { getByTestId, getByText } = renderComponent({
+  div: { 'data-testid': 'test', text: 'Hello' }
+});
+```
+
+#### `renderComponentAsync(component, props, options)`
+
+Render an async component.
+
+```javascript
+const result = await renderComponentAsync(asyncComponent, { name: 'World' });
+```
+
+#### `createTestRenderer(component, options)`
+
+Create a test renderer for component updates.
+
+```javascript
+const renderer = createTestRenderer(component);
+renderer.render();
+renderer.update(newComponent);
+```
+
+#### `shallowRender(component)`
+
+Shallow render (top-level only).
+
+```javascript
+const shallow = shallowRender(component);
+```
+
+### Queries
+
+#### `getByTestId(testId)`
+
+Get element by test ID (throws if not found).
+
+```javascript
+const element = getByTestId('submit-btn');
+```
+
+#### `queryByTestId(testId)`
+
+Query element by test ID (returns null if not found).
+
+```javascript
+const element = queryByTestId('submit-btn');
+```
+
+#### `getByText(text)`
+
+Get element by text content.
+
+```javascript
+const element = getByText('Submit');
+```
+
+#### `getByClassName(className)`
+
+Get element by class name.
+
+```javascript
+const element = getByClassName('btn-primary');
+```
+
+#### `getAllByTagName(tagName)`
+
+Get all elements by tag name.
+
+```javascript
+const items = getAllByTagName('li');
+```
+
+### Events
+
+#### `fireEvent(element, eventType, eventData)`
+
+Simulate an event.
+
+```javascript
+fireEvent(button, 'click');
+fireEvent(input, 'change', { target: { value: 'test' } });
+```
+
+#### `userEvent`
+
+Realistic user interactions.
+
+```javascript
+await userEvent.click(button);
+await userEvent.type(input, 'Hello');
+await userEvent.clear(input);
+```
+
+### Async Utilities
+
+#### `waitFor(condition, options)`
+
+Wait for a condition to be true.
+
+```javascript
+await waitFor(() => getByText('Loaded').exists, { timeout: 2000 });
+```
+
+#### `waitForElement(queryFn, options)`
+
+Wait for an element to appear.
+
+```javascript
+const element = await waitForElement(() => queryByTestId('loaded'));
+```
+
+#### `waitForElementToBeRemoved(queryFn, options)`
+
+Wait for an element to disappear.
+
+```javascript
+await waitForElementToBeRemoved(() => queryByTestId('loading'));
+```
+
+#### `act(callback)`
+
+Batch updates.
+
+```javascript
+await act(async () => {
+  // Perform updates
+});
+```
+
+### Mocks & Spies
+
+#### `createMock(implementation)`
+
+Create a mock function.
+
+```javascript
+const mock = createMock((x) => x * 2);
+mock(5); // returns 10
+
+expect(mock).toHaveBeenCalledWith(5);
+expect(mock).toHaveBeenCalledTimes(1);
+```
+
+#### `createSpy(object, method)`
+
+Spy on an object method.
+
+```javascript
+const spy = createSpy(obj, 'method');
+obj.method('test');
+expect(spy).toHaveBeenCalledWith('test');
+spy.mockRestore();
+```
+
+### Custom Matchers
+
+Extend expect with Coherent.js-specific matchers:
+
+```javascript
+import { extendExpect } from '@coherent.js/testing';
+extendExpect(expect);
+```
+
+Available matchers:
+
+- `toHaveText(text)` - Element has exact text
+- `toContainText(text)` - Element contains text
+- `toHaveClass(className)` - Element has class
+- `toBeInTheDocument()` - Element exists
+- `toBeVisible()` - Element has visible content
+- `toBeEmpty()` - Element is empty
+- `toContainHTML(html)` - HTML contains string
+- `toHaveAttribute(attr, value)` - Element has attribute
+- `toHaveTagName(tagName)` - Element has tag name
+- `toRenderSuccessfully()` - Component rendered
+- `toBeValidHTML()` - HTML is valid
+- `toHaveBeenCalled()` - Mock was called
+- `toHaveBeenCalledWith(...args)` - Mock called with args
+- `toHaveBeenCalledTimes(n)` - Mock called n times
+
+### Utilities
+
+#### `within(container)`
+
+Scope queries to a container.
+
+```javascript
+const container = getByTestId('container');
+const scoped = within(container);
+scoped.getByText('Inner text');
+```
+
+#### `screen`
+
+Global query utility.
+
+```javascript
+screen.setResult(result);
+screen.getByTestId('test');
+screen.debug();
+```
+
+#### `cleanup()`
+
+Clean up after tests.
+
+```javascript
+afterEach(() => {
+  cleanup();
+});
+```
+
+## Examples
+
+### Testing a Button Component
+
+```javascript
+import { renderComponent, fireEvent, createMock } from '@coherent.js/testing';
+
+it('should handle click events', () => {
+  const handleClick = createMock();
+  
+  const button = {
+    button: {
+      'data-testid': 'my-btn',
+      text: 'Click me',
+      onclick: handleClick
+    }
+  };
+
+  const { getByTestId } = renderComponent(button);
+  fireEvent(getByTestId('my-btn'), 'click');
+
+  expect(handleClick).toHaveBeenCalled();
+});
+```
+
+### Testing Async Components
+
+```javascript
+import { renderComponentAsync, waitForElement } from '@coherent.js/testing';
+
+it('should load data', async () => {
+  const AsyncComponent = async () => {
+    const data = await fetchData();
+    return { div: { text: data.message } };
+  };
+
+  const result = await renderComponentAsync(AsyncComponent);
+  const element = await waitForElement(() => result.queryByText('Loaded'));
+
+  expect(element).toBeInTheDocument();
+});
+```
+
+### Testing Forms
+
+```javascript
+import { renderComponent, userEvent } from '@coherent.js/testing';
+
+it('should submit form', async () => {
+  const handleSubmit = createMock();
+  
+  const form = {
+    form: {
+      onsubmit: handleSubmit,
+      children: [
+        { input: { 'data-testid': 'name-input', type: 'text' } },
+        { button: { 'data-testid': 'submit-btn', text: 'Submit' } }
+      ]
+    }
+  };
+
+  const { getByTestId } = renderComponent(form);
+  
+  await userEvent.type(getByTestId('name-input'), 'John');
+  await userEvent.click(getByTestId('submit-btn'));
+
+  expect(handleSubmit).toHaveBeenCalled();
+});
+```
+
+### Snapshot Testing
+
+```javascript
+import { renderComponent } from '@coherent.js/testing';
+
+it('should match snapshot', () => {
+  const component = {
+    div: {
+      className: 'card',
+      children: [
+        { h2: { text: 'Title' } },
+        { p: { text: 'Content' } }
+      ]
+    }
+  };
+
+  const result = renderComponent(component);
+  expect(result.toSnapshot()).toMatchSnapshot();
+});
+```
+
+## Best Practices
+
+### 1. Use Test IDs
+
+Add `data-testid` attributes for reliable querying:
+
+```javascript
+const component = {
+  button: {
+    'data-testid': 'submit-button',
+    text: 'Submit'
+  }
+};
+```
+
+### 2. Clean Up After Tests
+
+Always clean up to avoid test interference:
+
+```javascript
+afterEach(() => {
+  cleanup();
+});
+```
+
+### 3. Use Custom Matchers
+
+Extend expect for better assertions:
+
+```javascript
+extendExpect(expect);
+expect(element).toHaveText('Hello');
+```
+
+### 4. Test User Interactions
+
+Use `userEvent` for realistic interactions:
+
+```javascript
+await userEvent.click(button);
+await userEvent.type(input, 'text');
+```
+
+### 5. Wait for Async Updates
+
+Use `waitFor` for async operations:
+
+```javascript
+await waitFor(() => getByText('Loaded').exists);
+```
+
+## Integration with Testing Frameworks
+
+### Vitest
+
+```javascript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { renderComponent, extendExpect, cleanup } from '@coherent.js/testing';
+
+extendExpect(expect);
+
+describe('MyComponent', () => {
+  afterEach(cleanup);
+
+  it('should work', () => {
+    // Test code
+  });
+});
+```
+
+### Jest
+
+```javascript
+import { renderComponent, extendExpect, cleanup } from '@coherent.js/testing';
+
+extendExpect(expect);
+
+afterEach(cleanup);
+
+test('should work', () => {
+  // Test code
+});
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,746 @@
+// src/test-renderer.js
+import { render } from "@coherent.js/core";
+var TestRendererResult = class {
+  constructor(component, html, container = null) {
+    this.component = component;
+    this.html = html;
+    this.container = container;
+    this.queries = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Get element by test ID
+   * @param {string} testId - Test ID to search for
+   * @returns {Object|null} Element or null
+   */
+  getByTestId(testId) {
+    const regex = new RegExp(`data-testid="${testId}"[^>]*>([^<]*)<`, "i");
+    const match = this.html.match(regex);
+    if (!match) {
+      throw new Error(`Unable to find element with testId: ${testId}`);
+    }
+    return {
+      text: match[1],
+      html: match[0],
+      testId,
+      exists: true
+    };
+  }
+  /**
+   * Query element by test ID (returns null if not found)
+   * @param {string} testId - Test ID to search for
+   * @returns {Object|null} Element or null
+   */
+  queryByTestId(testId) {
+    try {
+      return this.getByTestId(testId);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get element by text content
+   * @param {string|RegExp} text - Text to search for
+   * @returns {Object} Element
+   */
+  getByText(text) {
+    const regex = typeof text === "string" ? new RegExp(`>([^<]*${text}[^<]*)<`, "i") : new RegExp(`>([^<]*)<`, "i");
+    const match = this.html.match(regex);
+    if (!match || typeof text === "string" && !match[1].includes(text)) {
+      throw new Error(`Unable to find element with text: ${text}`);
+    }
+    return {
+      text: match[1],
+      html: match[0],
+      exists: true
+    };
+  }
+  /**
+   * Query element by text (returns null if not found)
+   * @param {string|RegExp} text - Text to search for
+   * @returns {Object|null} Element or null
+   */
+  queryByText(text) {
+    try {
+      return this.getByText(text);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get element by class name
+   * @param {string} className - Class name to search for
+   * @returns {Object} Element
+   */
+  getByClassName(className) {
+    const regex = new RegExp(`class="[^"]*${className}[^"]*"[^>]*>([^<]*)<`, "i");
+    const match = this.html.match(regex);
+    if (!match) {
+      throw new Error(`Unable to find element with className: ${className}`);
+    }
+    return {
+      text: match[1],
+      html: match[0],
+      className,
+      exists: true
+    };
+  }
+  /**
+   * Query element by class name (returns null if not found)
+   * @param {string} className - Class name to search for
+   * @returns {Object|null} Element or null
+   */
+  queryByClassName(className) {
+    try {
+      return this.getByClassName(className);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get all elements by tag name
+   * @param {string} tagName - Tag name to search for
+   * @returns {Array<Object>} Array of elements
+   */
+  getAllByTagName(tagName) {
+    const regex = new RegExp(`<${tagName}[^>]*>([^<]*)</${tagName}>`, "gi");
+    const matches = [...this.html.matchAll(regex)];
+    return matches.map((match) => ({
+      text: match[1],
+      html: match[0],
+      tagName,
+      exists: true
+    }));
+  }
+  /**
+   * Check if element exists
+   * @param {string} selector - Selector (testId, text, className)
+   * @param {string} type - Type of selector ('testId', 'text', 'className')
+   * @returns {boolean} True if exists
+   */
+  exists(selector, type = "testId") {
+    switch (type) {
+      case "testId":
+        return this.queryByTestId(selector) !== null;
+      case "text":
+        return this.queryByText(selector) !== null;
+      case "className":
+        return this.queryByClassName(selector) !== null;
+      default:
+        return false;
+    }
+  }
+  /**
+   * Get the rendered HTML
+   * @returns {string} HTML string
+   */
+  getHTML() {
+    return this.html;
+  }
+  /**
+   * Get the component
+   * @returns {Object} Component object
+   */
+  getComponent() {
+    return this.component;
+  }
+  /**
+   * Create a snapshot of the rendered output
+   * @returns {string} Formatted HTML for snapshot testing
+   */
+  toSnapshot() {
+    return this.html.replace(/>\s+</g, "><").trim();
+  }
+  /**
+   * Debug: print the rendered HTML
+   */
+  debug() {
+    console.log("=== Rendered HTML ===");
+    console.log(this.html);
+    console.log("=== Component ===");
+    console.log(JSON.stringify(this.component, null, 2));
+  }
+};
+function renderComponent(component, options = {}) {
+  const html = render(component, options);
+  return new TestRendererResult(component, html);
+}
+async function renderComponentAsync(component, props = {}, options = {}) {
+  const resolvedComponent = typeof component === "function" ? await component(props) : component;
+  const html = render(resolvedComponent, options);
+  return new TestRendererResult(resolvedComponent, html);
+}
+var TestRenderer = class {
+  constructor(component, options = {}) {
+    this.component = component;
+    this.options = options;
+    this.result = null;
+    this.renderCount = 0;
+  }
+  /**
+   * Render the component
+   * @returns {TestRendererResult} Render result
+   */
+  render() {
+    this.renderCount++;
+    const html = render(this.component, this.options);
+    this.result = new TestRendererResult(this.component, html);
+    return this.result;
+  }
+  /**
+   * Update the component and re-render
+   * @param {Object} newComponent - Updated component
+   * @returns {TestRendererResult} Render result
+   */
+  update(newComponent) {
+    this.component = newComponent;
+    return this.render();
+  }
+  /**
+   * Get the current result
+   * @returns {TestRendererResult|null} Current result
+   */
+  getResult() {
+    return this.result;
+  }
+  /**
+   * Get render count
+   * @returns {number} Number of renders
+   */
+  getRenderCount() {
+    return this.renderCount;
+  }
+  /**
+   * Unmount the component
+   */
+  unmount() {
+    this.component = null;
+    this.result = null;
+  }
+};
+function createTestRenderer(component, options = {}) {
+  return new TestRenderer(component, options);
+}
+function shallowRender(component) {
+  const shallow = { ...component };
+  Object.keys(shallow).forEach((key) => {
+    if (shallow[key] && typeof shallow[key] === "object") {
+      if (shallow[key].children) {
+        shallow[key] = {
+          ...shallow[key],
+          children: Array.isArray(shallow[key].children) ? shallow[key].children.map(() => ({ _shallow: true })) : { _shallow: true }
+        };
+      }
+    }
+  });
+  return shallow;
+}
+
+// src/test-utils.js
+function fireEvent(element, eventType, eventData = {}) {
+  if (!element) {
+    throw new Error("Element is required for fireEvent");
+  }
+  const event = {
+    type: eventType,
+    target: element,
+    currentTarget: element,
+    preventDefault: () => {
+    },
+    stopPropagation: () => {
+    },
+    ...eventData
+  };
+  const handlerName = `on${eventType}`;
+  if (element[handlerName] && typeof element[handlerName] === "function") {
+    element[handlerName](event);
+  }
+  return event;
+}
+var fireEvent_click = (element, eventData) => fireEvent(element, "click", eventData);
+var fireEvent_change = (element, value) => fireEvent(element, "change", { target: { value } });
+var fireEvent_input = (element, value) => fireEvent(element, "input", { target: { value } });
+var fireEvent_keyDown = (element, key) => fireEvent(element, "keydown", { key });
+var fireEvent_keyUp = (element, key) => fireEvent(element, "keyup", { key });
+var fireEvent_focus = (element) => fireEvent(element, "focus");
+var fireEvent_blur = (element) => fireEvent(element, "blur");
+function waitFor(condition, options = {}) {
+  const { timeout = 1e3, interval = 50 } = options;
+  return new Promise((resolve, reject) => {
+    const startTime = Date.now();
+    const check = () => {
+      try {
+        if (condition()) {
+          resolve();
+          return;
+        }
+      } catch {
+      }
+      if (Date.now() - startTime >= timeout) {
+        reject(new Error(`Timeout waiting for condition after ${timeout}ms`));
+        return;
+      }
+      setTimeout(check, interval);
+    };
+    check();
+  });
+}
+async function waitForElement(queryFn, options = {}) {
+  let element = null;
+  await waitFor(() => {
+    element = queryFn();
+    return element !== null;
+  }, options);
+  return element;
+}
+async function waitForElementToBeRemoved(queryFn, options = {}) {
+  await waitFor(() => {
+    const element = queryFn();
+    return element === null;
+  }, options);
+}
+async function act(callback) {
+  await callback();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+function createMock(implementation) {
+  const calls = [];
+  const results = [];
+  const mockFn = function(...args) {
+    calls.push(args);
+    let result;
+    let error;
+    try {
+      result = implementation ? implementation(...args) : void 0;
+      results.push({ type: "return", value: result });
+    } catch (err) {
+      error = err;
+      results.push({ type: "throw", value: error });
+      throw error;
+    }
+    return result;
+  };
+  mockFn.mock = {
+    calls,
+    results,
+    instances: []
+  };
+  mockFn.mockClear = () => {
+    calls.length = 0;
+    results.length = 0;
+  };
+  mockFn.mockReset = () => {
+    mockFn.mockClear();
+    implementation = void 0;
+  };
+  mockFn.mockImplementation = (fn) => {
+    implementation = fn;
+    return mockFn;
+  };
+  mockFn.mockReturnValue = (value) => {
+    implementation = () => value;
+    return mockFn;
+  };
+  mockFn.mockResolvedValue = (value) => {
+    implementation = () => Promise.resolve(value);
+    return mockFn;
+  };
+  mockFn.mockRejectedValue = (error) => {
+    implementation = () => Promise.reject(error);
+    return mockFn;
+  };
+  return mockFn;
+}
+function createSpy(object, method) {
+  const original = object[method];
+  const spy = createMock(original.bind(object));
+  object[method] = spy;
+  spy.mockRestore = () => {
+    object[method] = original;
+  };
+  return spy;
+}
+function cleanup() {
+}
+function within(container) {
+  return {
+    getByTestId: (testId) => container.getByTestId(testId),
+    queryByTestId: (testId) => container.queryByTestId(testId),
+    getByText: (text) => container.getByText(text),
+    queryByText: (text) => container.queryByText(text),
+    getByClassName: (className) => container.getByClassName(className),
+    queryByClassName: (className) => container.queryByClassName(className)
+  };
+}
+var screen = {
+  _result: null,
+  setResult(result) {
+    this._result = result;
+  },
+  getByTestId(testId) {
+    if (!this._result) throw new Error("No component rendered");
+    return this._result.getByTestId(testId);
+  },
+  queryByTestId(testId) {
+    if (!this._result) return null;
+    return this._result.queryByTestId(testId);
+  },
+  getByText(text) {
+    if (!this._result) throw new Error("No component rendered");
+    return this._result.getByText(text);
+  },
+  queryByText(text) {
+    if (!this._result) return null;
+    return this._result.queryByText(text);
+  },
+  getByClassName(className) {
+    if (!this._result) throw new Error("No component rendered");
+    return this._result.getByClassName(className);
+  },
+  queryByClassName(className) {
+    if (!this._result) return null;
+    return this._result.queryByClassName(className);
+  },
+  debug() {
+    if (this._result) {
+      this._result.debug();
+    }
+  }
+};
+var userEvent = {
+  /**
+   * Simulate user typing
+   */
+  type: async (element, text, options = {}) => {
+    const { delay = 0 } = options;
+    for (const char of text) {
+      fireEvent_keyDown(element, char);
+      fireEvent_input(element, element.value + char);
+      fireEvent_keyUp(element, char);
+      if (delay > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  },
+  /**
+   * Simulate user click
+   */
+  click: async (element) => {
+    fireEvent_focus(element);
+    fireEvent_click(element);
+  },
+  /**
+   * Simulate user double click
+   */
+  dblClick: async (element) => {
+    await userEvent.click(element);
+    await userEvent.click(element);
+  },
+  /**
+   * Simulate user clearing input
+   */
+  clear: async (element) => {
+    fireEvent_input(element, "");
+    fireEvent_change(element, "");
+  },
+  /**
+   * Simulate user selecting option
+   */
+  selectOptions: async (element, values) => {
+    const valueArray = Array.isArray(values) ? values : [values];
+    fireEvent_change(element, valueArray[0]);
+  },
+  /**
+   * Simulate user tab navigation
+   */
+  tab: async () => {
+    const activeElement = document.activeElement;
+    if (activeElement) {
+      fireEvent_keyDown(activeElement, "Tab");
+      fireEvent_blur(activeElement);
+    }
+  }
+};
+
+// src/matchers.js
+var customMatchers = {
+  /**
+   * Check if element has specific text
+   */
+  toHaveText(received, expected) {
+    const pass = received && received.text === expected;
+    return {
+      pass,
+      message: () => pass ? `Expected element not to have text "${expected}"` : `Expected element to have text "${expected}", but got "${received?.text || "null"}"`
+    };
+  },
+  /**
+   * Check if element contains text
+   */
+  toContainText(received, expected) {
+    const pass = received && received.text && received.text.includes(expected);
+    return {
+      pass,
+      message: () => pass ? `Expected element not to contain text "${expected}"` : `Expected element to contain text "${expected}", but got "${received?.text || "null"}"`
+    };
+  },
+  /**
+   * Check if element has specific class
+   */
+  toHaveClass(received, expected) {
+    const pass = received && received.className && received.className.includes(expected);
+    return {
+      pass,
+      message: () => pass ? `Expected element not to have class "${expected}"` : `Expected element to have class "${expected}", but got "${received?.className || "null"}"`
+    };
+  },
+  /**
+   * Check if element exists
+   */
+  toBeInTheDocument(received) {
+    const pass = received && received.exists === true;
+    return {
+      pass,
+      message: () => pass ? "Expected element not to be in the document" : "Expected element to be in the document"
+    };
+  },
+  /**
+   * Check if element is visible (has content)
+   */
+  toBeVisible(received) {
+    const pass = received && received.text && received.text.trim().length > 0;
+    return {
+      pass,
+      message: () => pass ? "Expected element not to be visible" : "Expected element to be visible (have text content)"
+    };
+  },
+  /**
+   * Check if element is empty
+   */
+  toBeEmpty(received) {
+    const pass = !received || !received.text || received.text.trim().length === 0;
+    return {
+      pass,
+      message: () => pass ? "Expected element not to be empty" : "Expected element to be empty"
+    };
+  },
+  /**
+   * Check if HTML contains specific string
+   */
+  toContainHTML(received, expected) {
+    const html = received?.html || received;
+    const pass = typeof html === "string" && html.includes(expected);
+    return {
+      pass,
+      message: () => pass ? `Expected HTML not to contain "${expected}"` : `Expected HTML to contain "${expected}"`
+    };
+  },
+  /**
+   * Check if element has attribute
+   */
+  toHaveAttribute(received, attribute, value) {
+    const html = received?.html || "";
+    const regex = new RegExp(`${attribute}="([^"]*)"`, "i");
+    const match = html.match(regex);
+    const pass = value !== void 0 ? match && match[1] === value : match !== null;
+    return {
+      pass,
+      message: () => {
+        if (value !== void 0) {
+          return pass ? `Expected element not to have attribute ${attribute}="${value}"` : `Expected element to have attribute ${attribute}="${value}", but got "${match?.[1] || "none"}"`;
+        }
+        return pass ? `Expected element not to have attribute ${attribute}` : `Expected element to have attribute ${attribute}`;
+      }
+    };
+  },
+  /**
+   * Check if component matches snapshot
+   */
+  toMatchSnapshot(received) {
+    const _snapshot = received?.toSnapshot ? received.toSnapshot() : received;
+    return {
+      pass: true,
+      message: () => "Snapshot comparison"
+    };
+  },
+  /**
+   * Check if element has specific tag name
+   */
+  toHaveTagName(received, tagName) {
+    const html = received?.html || "";
+    const regex = new RegExp(`<${tagName}[^>]*>`, "i");
+    const pass = regex.test(html);
+    return {
+      pass,
+      message: () => pass ? `Expected element not to have tag name "${tagName}"` : `Expected element to have tag name "${tagName}"`
+    };
+  },
+  /**
+   * Check if render result contains element
+   */
+  toContainElement(received, element) {
+    const html = received?.html || received;
+    const elementHtml = element?.html || element;
+    const pass = typeof html === "string" && html.includes(elementHtml);
+    return {
+      pass,
+      message: () => pass ? "Expected not to contain element" : "Expected to contain element"
+    };
+  },
+  /**
+   * Check if mock was called
+   */
+  toHaveBeenCalled(received) {
+    const pass = received?.mock?.calls?.length > 0;
+    return {
+      pass,
+      message: () => pass ? "Expected mock not to have been called" : "Expected mock to have been called"
+    };
+  },
+  /**
+   * Check if mock was called with specific args
+   */
+  toHaveBeenCalledWith(received, ...expectedArgs) {
+    const calls = received?.mock?.calls || [];
+    const pass = calls.some(
+      (call) => call.length === expectedArgs.length && call.every((arg, i) => arg === expectedArgs[i])
+    );
+    return {
+      pass,
+      message: () => pass ? `Expected mock not to have been called with ${JSON.stringify(expectedArgs)}` : `Expected mock to have been called with ${JSON.stringify(expectedArgs)}`
+    };
+  },
+  /**
+   * Check if mock was called N times
+   */
+  toHaveBeenCalledTimes(received, times) {
+    const callCount = received?.mock?.calls?.length || 0;
+    const pass = callCount === times;
+    return {
+      pass,
+      message: () => pass ? `Expected mock not to have been called ${times} times` : `Expected mock to have been called ${times} times, but was called ${callCount} times`
+    };
+  },
+  /**
+   * Check if component rendered successfully
+   */
+  toRenderSuccessfully(received) {
+    const pass = received && received.html && received.html.length > 0;
+    return {
+      pass,
+      message: () => pass ? "Expected component not to render successfully" : "Expected component to render successfully"
+    };
+  },
+  /**
+   * Check if HTML is valid
+   */
+  toBeValidHTML(received) {
+    const html = received?.html || received;
+    const openTags = (html.match(/<[^/][^>]*>/g) || []).length;
+    const closeTags = (html.match(/<\/[^>]+>/g) || []).length;
+    const selfClosing = (html.match(/<[^>]+\/>/g) || []).length;
+    const pass = openTags === closeTags + selfClosing;
+    return {
+      pass,
+      message: () => pass ? "Expected HTML not to be valid" : `Expected HTML to be valid (open: ${openTags}, close: ${closeTags}, self-closing: ${selfClosing})`
+    };
+  }
+};
+function extendExpect(expect) {
+  if (expect && expect.extend) {
+    expect.extend(customMatchers);
+  } else {
+    console.warn("Could not extend expect - expect.extend not available");
+  }
+}
+var assertions = {
+  /**
+   * Assert element has text
+   */
+  assertHasText(element, text) {
+    if (!element || element.text !== text) {
+      throw new Error(`Expected element to have text "${text}", but got "${element?.text || "null"}"`);
+    }
+  },
+  /**
+   * Assert element exists
+   */
+  assertExists(element) {
+    if (!element || !element.exists) {
+      throw new Error("Expected element to exist");
+    }
+  },
+  /**
+   * Assert element has class
+   */
+  assertHasClass(element, className) {
+    if (!element || !element.className || !element.className.includes(className)) {
+      throw new Error(`Expected element to have class "${className}"`);
+    }
+  },
+  /**
+   * Assert HTML contains string
+   */
+  assertContainsHTML(html, substring) {
+    const htmlString = html?.html || html;
+    if (!htmlString || !htmlString.includes(substring)) {
+      throw new Error(`Expected HTML to contain "${substring}"`);
+    }
+  },
+  /**
+   * Assert component rendered
+   */
+  assertRendered(result) {
+    if (!result || !result.html || result.html.length === 0) {
+      throw new Error("Expected component to render");
+    }
+  }
+};
+
+// src/index.js
+var index_default = {
+  // Renderer
+  renderComponent,
+  renderComponentAsync,
+  createTestRenderer,
+  shallowRender,
+  // Utilities
+  fireEvent,
+  waitFor,
+  waitForElement,
+  waitForElementToBeRemoved,
+  act,
+  createMock,
+  createSpy,
+  cleanup,
+  within,
+  screen,
+  userEvent,
+  // Matchers
+  customMatchers,
+  extendExpect,
+  assertions
+};
+export {
+  TestRenderer,
+  TestRendererResult,
+  act,
+  assertions,
+  cleanup,
+  createMock,
+  createSpy,
+  createTestRenderer,
+  customMatchers,
+  index_default as default,
+  extendExpect,
+  fireEvent,
+  renderComponent,
+  renderComponentAsync,
+  screen,
+  shallowRender,
+  userEvent,
+  waitFor,
+  waitForElement,
+  waitForElementToBeRemoved,
+  within
+};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@coherent.js/testing",
+  "version": "1.0.0-beta.2",
+  "description": "Testing utilities for Coherent.js applications",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./renderer": "./dist/test-renderer.js",
+    "./utils": "./dist/test-utils.js",
+    "./matchers": "./dist/matchers.js"
+  },
+  "keywords": [
+    "coherent",
+    "testing",
+    "test-utils",
+    "component-testing"
+  ],
+  "author": "Coherent.js Team",
+  "license": "MIT",
+  "peerDependencies": {
+    "@coherent.js/core": "1.0.0-beta.2"
+  },
+  "devDependencies": {
+    "vitest": "^1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tomdrouv1/coherent.js.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./types/index.d.ts",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "types/"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Coherent.js Testing Utilities TypeScript Definitions
+ * @module @coherent.js/testing
+ */
+
+// ===== Test Renderer Types =====
+
+export interface RenderOptions {
+  wrapper?: any;
+  context?: Record<string, any>;
+  props?: Record<string, any>;
+}
+
+export interface TestRendererResult {
+  html: string;
+  component: any;
+  container: HTMLElement | null;
+  rerender(component: any): void;
+  unmount(): void;
+  debug(): void;
+}
+
+export class TestRenderer {
+  render(component: any, options?: RenderOptions): TestRendererResult;
+  renderAsync(component: any, options?: RenderOptions): Promise<TestRendererResult>;
+  shallow(component: any): TestRendererResult;
+  cleanup(): void;
+}
+
+export function renderComponent(component: any, options?: RenderOptions): TestRendererResult;
+export function renderComponentAsync(component: any, options?: RenderOptions): Promise<TestRendererResult>;
+export function createTestRenderer(): TestRenderer;
+export function shallowRender(component: any): TestRendererResult;
+
+// ===== Test Utilities Types =====
+
+export interface EventOptions {
+  bubbles?: boolean;
+  cancelable?: boolean;
+  composed?: boolean;
+  [key: string]: any;
+}
+
+export const fireEvent: {
+  (element: Element, event: Event): boolean;
+  click(element: Element, options?: EventOptions): boolean;
+  change(element: Element, options?: EventOptions & { target?: { value?: any } }): boolean;
+  input(element: Element, options?: EventOptions & { target?: { value?: any } }): boolean;
+  submit(element: Element, options?: EventOptions): boolean;
+  keyDown(element: Element, options?: EventOptions & { key?: string; code?: string }): boolean;
+  keyUp(element: Element, options?: EventOptions & { key?: string; code?: string }): boolean;
+  focus(element: Element, options?: EventOptions): boolean;
+  blur(element: Element, options?: EventOptions): boolean;
+  mouseEnter(element: Element, options?: EventOptions): boolean;
+  mouseLeave(element: Element, options?: EventOptions): boolean;
+  [key: string]: any;
+};
+
+export interface WaitOptions {
+  timeout?: number;
+  interval?: number;
+}
+
+export function waitFor<T>(callback: () => T | Promise<T>, options?: WaitOptions): Promise<T>;
+export function waitForElement(selector: string, options?: WaitOptions): Promise<Element>;
+export function waitForElementToBeRemoved(selector: string | Element, options?: WaitOptions): Promise<void>;
+
+export function act<T>(callback: () => T | Promise<T>): Promise<T>;
+
+export interface Mock<T extends (...args: any[]) => any = (...args: any[]) => any> {
+  (...args: Parameters<T>): ReturnType<T>;
+  mock: {
+    calls: Parameters<T>[];
+    results: Array<{ type: 'return' | 'throw'; value: any }>;
+    instances: any[];
+  };
+  mockClear(): void;
+  mockReset(): void;
+  mockRestore(): void;
+  mockImplementation(fn: T): this;
+  mockReturnValue(value: ReturnType<T>): this;
+  mockReturnValueOnce(value: ReturnType<T>): this;
+  mockResolvedValue(value: ReturnType<T> extends Promise<infer U> ? U : never): this;
+  mockRejectedValue(error: any): this;
+}
+
+export function createMock<T extends (...args: any[]) => any>(implementation?: T): Mock<T>;
+export function createSpy<T extends (...args: any[]) => any>(object: any, method: string): Mock<T>;
+
+export function cleanup(): void;
+
+export interface Within {
+  getByText(text: string | RegExp): Element;
+  getByRole(role: string, options?: { name?: string | RegExp }): Element;
+  getByLabelText(text: string | RegExp): Element;
+  getByPlaceholderText(text: string | RegExp): Element;
+  getByTestId(testId: string): Element;
+  queryByText(text: string | RegExp): Element | null;
+  queryByRole(role: string, options?: { name?: string | RegExp }): Element | null;
+  queryAllByText(text: string | RegExp): Element[];
+  findByText(text: string | RegExp): Promise<Element>;
+  findAllByText(text: string | RegExp): Promise<Element[]>;
+}
+
+export function within(element: Element): Within;
+export const screen: Within;
+
+export const userEvent: {
+  click(element: Element): Promise<void>;
+  dblClick(element: Element): Promise<void>;
+  type(element: Element, text: string, options?: { delay?: number }): Promise<void>;
+  clear(element: Element): Promise<void>;
+  selectOptions(element: Element, values: string | string[]): Promise<void>;
+  tab(options?: { shift?: boolean }): Promise<void>;
+  hover(element: Element): Promise<void>;
+  unhover(element: Element): Promise<void>;
+  upload(element: Element, files: File | File[]): Promise<void>;
+  paste(element: Element, text: string): Promise<void>;
+};
+
+// ===== Matchers Types =====
+
+export interface CustomMatchers<R = void> {
+  toHaveHTML(html: string): R;
+  toContainHTML(html: string): R;
+  toHaveTextContent(text: string | RegExp): R;
+  toHaveAttribute(attr: string, value?: string): R;
+  toHaveClass(className: string): R;
+  toBeInTheDocument(): R;
+  toBeVisible(): R;
+  toBeDisabled(): R;
+  toBeEnabled(): R;
+  toHaveValue(value: any): R;
+  toHaveStyle(style: Record<string, any>): R;
+  toHaveFocus(): R;
+  toBeChecked(): R;
+  toBeValid(): R;
+  toBeInvalid(): R;
+}
+
+export const customMatchers: CustomMatchers;
+
+export function extendExpect(matchers: Record<string, (...args: any[]) => any>): void;
+
+export const assertions: {
+  assertElement(element: any): asserts element is Element;
+  assertHTMLElement(element: any): asserts element is HTMLElement;
+  assertInDocument(element: Element | null): asserts element is Element;
+  assertVisible(element: Element): void;
+  assertHasAttribute(element: Element, attr: string): void;
+  assertHasClass(element: Element, className: string): void;
+};
+
+// Extend Jest/Vitest expect
+declare global {
+  namespace Vi {
+    interface Matchers<R = void> extends CustomMatchers<R> {}
+    interface AsymmetricMatchers extends CustomMatchers {}
+  }
+  namespace jest {
+    interface Matchers<R = void> extends CustomMatchers<R> {}
+    interface Expect extends CustomMatchers {}
+  }
+}