sibujs 1.0.0-beta.1

package/dist/testing.d.cts

@@ -0,0 +1,491 @@
+/**
+ * Accessibility testing utilities for SibuJS.
+ * Provides automated a11y checks and WCAG compliance validation.
+ */
+type A11yViolationLevel = "error" | "warning" | "info";
+interface A11yViolation {
+    rule: string;
+    level: A11yViolationLevel;
+    message: string;
+    element?: Element;
+    selector?: string;
+}
+interface A11yCheckResult {
+    passed: boolean;
+    violations: A11yViolation[];
+    warnings: A11yViolation[];
+    info: A11yViolation[];
+    summary: string;
+}
+/**
+ * Check that all images have alt text.
+ */
+declare function checkImageAlt(root: Element): A11yViolation[];
+/**
+ * Check that form inputs have associated labels.
+ * Checks for: <label for="id">, aria-label, aria-labelledby, wrapping <label>.
+ */
+declare function checkFormLabels(root: Element): A11yViolation[];
+/**
+ * Check heading hierarchy (h1-h6 should not skip levels).
+ */
+declare function checkHeadingHierarchy(root: Element): A11yViolation[];
+/**
+ * Check for sufficient color contrast ratios.
+ * Since we can't compute actual colors in jsdom, checks for known issues:
+ * - Text with no color/background set
+ * - Elements with role but no accessible name
+ */
+declare function checkColorContrast(root: Element): A11yViolation[];
+/**
+ * Check that interactive elements are keyboard accessible.
+ * Elements with click handlers should have tabindex, role, and key handlers.
+ */
+declare function checkKeyboardAccess(root: Element): A11yViolation[];
+/**
+ * Check ARIA attribute validity.
+ * - role attributes use valid ARIA roles
+ * - aria-* attributes are valid
+ * - Required aria properties are present for roles
+ */
+declare function checkAriaAttributes(root: Element): A11yViolation[];
+/**
+ * Check that the page has proper landmark regions.
+ */
+declare function checkLandmarks(root: Element): A11yViolation[];
+/**
+ * Check link and button accessibility.
+ * - Links should have discernible text
+ * - Buttons should have accessible names
+ * - Links with target="_blank" should warn about new window
+ */
+declare function checkLinksAndButtons(root: Element): A11yViolation[];
+/**
+ * Check that lists use proper semantic markup.
+ */
+declare function checkListSemantics(root: Element): A11yViolation[];
+/**
+ * Check for tab order issues.
+ * - Positive tabindex values (anti-pattern)
+ * - Focus traps without escape mechanism
+ */
+declare function checkTabOrder(root: Element): A11yViolation[];
+type CheckName = "images" | "forms" | "headings" | "contrast" | "keyboard" | "aria" | "landmarks" | "links" | "lists" | "tabOrder";
+/**
+ * Run all accessibility checks on an element.
+ * Returns a comprehensive report.
+ */
+declare function checkA11y(root: Element, options?: {
+    /** Which checks to run (default: all) */
+    checks?: CheckName[];
+    /** Minimum violation level to report */
+    level?: A11yViolationLevel;
+}): A11yCheckResult;
+/**
+ * Assert that an element has no accessibility violations.
+ * Throws with a detailed report if violations are found.
+ */
+declare function assertA11y(root: Element, options?: Parameters<typeof checkA11y>[1]): void;
+
+/**
+ * Testing framework adapters for SibuJS.
+ * Provides integration with Jest, Cypress, and Playwright.
+ */
+/**
+ * Create a Jest-compatible test environment for SibuJS.
+ * Returns beforeEach/afterEach hooks and custom matchers.
+ */
+declare function createJestAdapter(): {
+    /** Call in beforeEach to set up DOM container */
+    setup(): HTMLElement;
+    /** Call in afterEach to clean up */
+    teardown(): void;
+    /** Render a component into the test container */
+    render(component: (() => HTMLElement) | HTMLElement): {
+        element: HTMLElement;
+        container: HTMLElement;
+    };
+    /** Custom Jest matchers */
+    matchers: {
+        /** Check if element has specific text content */
+        toHaveTextContent(element: Element, expected: string): {
+            pass: boolean;
+            message: () => string;
+        };
+        /** Check if element has specific attribute */
+        toHaveAttribute(element: Element, attr: string, value?: string): {
+            pass: boolean;
+            message: () => string;
+        };
+        /** Check if element has specific class */
+        toHaveClass(element: Element, className: string): {
+            pass: boolean;
+            message: () => string;
+        };
+        /** Check if element is visible (no display:none, visibility:hidden, hidden attr) */
+        toBeVisible(element: Element): {
+            pass: boolean;
+            message: () => string;
+        };
+        /** Check if element is disabled */
+        toBeDisabled(element: Element): {
+            pass: boolean;
+            message: () => string;
+        };
+        /** Check if element has focus */
+        toHaveFocus(element: Element): {
+            pass: boolean;
+            message: () => string;
+        };
+        /** Check if element has specific style */
+        toHaveStyle(element: HTMLElement, style: Record<string, string>): {
+            pass: boolean;
+            message: () => string;
+        };
+    };
+};
+/**
+ * Create a Cypress-compatible component mounting helper.
+ * Returns utilities for mounting SibuJS components in Cypress tests.
+ */
+declare function createCypressAdapter(): {
+    /** Mount a component for Cypress component testing */
+    mount(component: (() => HTMLElement) | HTMLElement, options?: {
+        container?: HTMLElement;
+    }): {
+        element: HTMLElement;
+        container: HTMLElement;
+    };
+    /** Generate Cypress custom commands for SibuJS */
+    commands: {
+        /** Find by data-testid */
+        getByTestId: (id: string) => string;
+        /** Find by text */
+        getByText: (text: string) => string;
+        /** Find by role */
+        getByRole: (role: string) => string;
+    };
+};
+/**
+ * Create a Playwright-compatible test helper.
+ * Provides page object patterns for SibuJS components.
+ */
+declare function createPlaywrightAdapter(): {
+    /** Selectors for common SibuJS patterns */
+    selectors: {
+        byTestId: (id: string) => string;
+        byRole: (role: string) => string;
+        byAriaLabel: (label: string) => string;
+        byDataAttr: (attr: string, value?: string) => string;
+    };
+    /** Generate a page object for a SibuJS component */
+    createPageObject(name: string, selectors: Record<string, string>): {
+        name: string;
+        getSelector: (key: string) => string;
+        allSelectors: () => Record<string, string>;
+    };
+};
+/**
+ * Framework-agnostic test adapter that works with any testing framework.
+ */
+declare function createUniversalAdapter(): {
+    /** Setup test environment */
+    setup(): HTMLElement;
+    /** Teardown test environment */
+    teardown(): void;
+    /** Render component */
+    render(component: (() => HTMLElement) | HTMLElement): {
+        element: HTMLElement;
+        container: HTMLElement;
+    };
+    /** Query helpers */
+    queries: {
+        byTestId(container: Element, id: string): Element | null;
+        byRole(container: Element, role: string): Element | null;
+        byText(container: Element, text: string): Element | null;
+        byLabelText(container: Element, label: string): Element | null;
+        allByRole(container: Element, role: string): Element[];
+    };
+    /** Assertion helpers */
+    assert: {
+        textContent(el: Element, expected: string): void;
+        attribute(el: Element, attr: string, value?: string): void;
+        visible(el: Element): void;
+        disabled(el: Element): void;
+        className(el: Element, name: string): void;
+    };
+};
+
+/**
+ * E2E testing utilities and mocks for SibuJS.
+ * Provides DOM fakes, HTTP mocks, and testing helpers for CI/CD integration.
+ */
+interface MockResponse {
+    status?: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    /** Delay before responding in ms */
+    delay?: number;
+}
+interface MockRoute {
+    method?: string;
+    url: string | RegExp;
+    response: MockResponse | ((req: {
+        url: string;
+        method: string;
+        body: unknown;
+        headers: Headers;
+    }) => MockResponse | Promise<MockResponse>);
+}
+/**
+ * Create an HTTP mock server that intercepts fetch calls.
+ * Useful for testing components that make API calls.
+ */
+declare function createHttpMock(routes?: MockRoute[]): {
+    /** Install the mock (replace global fetch) */
+    install(): void;
+    /** Restore original fetch */
+    restore(): void;
+    /** Add a mock route */
+    addRoute(route: MockRoute): void;
+    /** Remove all mock routes */
+    clearRoutes(): void;
+    /** Get the request log */
+    getRequests(): {
+        url: string;
+        method: string;
+        body: unknown;
+        timestamp: number;
+    }[];
+    /** Clear the request log */
+    clearLog(): void;
+    /** Assert that a URL was called */
+    assertCalled(url: string, method?: string): void;
+    /** Assert that a URL was NOT called */
+    assertNotCalled(url: string, method?: string): void;
+    /** Get number of times a URL was called */
+    callCount(url: string, method?: string): number;
+};
+/**
+ * Create a fake timer system for testing time-dependent code.
+ * Mocks setTimeout, setInterval, requestAnimationFrame.
+ */
+declare function createTimerMock(): {
+    install(): void;
+    restore(): void;
+    /** Advance time by a given number of ms, running any timers that fire */
+    advance(ms: number): void;
+    /** Run all pending timers immediately */
+    flush(): void;
+    /** Get current fake time */
+    now(): number;
+    /** Get number of pending timers */
+    pendingCount(): number;
+};
+/**
+ * Create a serializable snapshot of a DOM element for comparison testing.
+ */
+declare function createDOMSnapshot(element: Element): string;
+/**
+ * Assert that two DOM trees are structurally equivalent.
+ */
+declare function assertDOMEquals(actual: Element, expected: Element): void;
+/**
+ * Wrap a component for isolated testing with automatic cleanup.
+ */
+declare function testComponent(component: (() => HTMLElement) | HTMLElement, options?: {
+    container?: HTMLElement;
+}): {
+    element: HTMLElement;
+    container: HTMLElement;
+    /** Find element by test ID (data-testid attribute) */
+    getByTestId: (id: string) => Element | null;
+    /** Find all elements by test ID */
+    getAllByTestId: (id: string) => Element[];
+    /** Find by text content */
+    getByText: (text: string) => Element | null;
+    /** Simulate click */
+    click: (el: Element) => void;
+    /** Simulate input */
+    type: (el: HTMLInputElement, value: string) => void;
+    /** Wait for reactive updates */
+    waitForUpdate: () => Promise<void>;
+    /** Clean up */
+    destroy: () => void;
+};
+
+/**
+ * Snapshot testing utilities for SibuJS components.
+ * Capture and compare component output over time.
+ */
+/**
+ * Snapshot store for managing saved snapshots.
+ * In a real environment, these would be persisted to disk by the test framework.
+ * This provides the in-memory API that adapters can hook into.
+ */
+declare function createSnapshotStore(): {
+    /** Save a snapshot with a given name */
+    save: (name: string, snapshot: string) => void;
+    /** Get a saved snapshot */
+    get: (name: string) => string | undefined;
+    /** Check if a snapshot exists */
+    has: (name: string) => boolean;
+    /** Compare a snapshot against a saved one. Returns null if match, diff string if mismatch */
+    compare: (name: string, current: string) => {
+        match: boolean;
+        diff?: string;
+    };
+    /** Update a saved snapshot */
+    update: (name: string, snapshot: string) => void;
+    /** Delete a snapshot */
+    delete: (name: string) => void;
+    /** List all snapshot names */
+    list: () => string[];
+    /** Clear all snapshots */
+    clear: () => void;
+};
+/**
+ * Create a serialized snapshot of a SibuJS component.
+ * Renders the component and serializes the DOM tree to a deterministic string.
+ */
+declare function snapshotComponent(component: () => HTMLElement): string;
+/**
+ * Assert that a component matches its saved snapshot.
+ * On first run (no saved snapshot), saves the snapshot.
+ * On subsequent runs, compares against the saved snapshot.
+ *
+ * @param store    - The snapshot store to read/write from
+ * @param name     - A unique name identifying this snapshot
+ * @param component - A factory function that creates the component element
+ * @param options  - Optional: set `update: true` to forcibly overwrite the saved snapshot
+ * @returns An object with `passed`, the rendered `snapshot`, and an optional `diff`
+ */
+declare function matchSnapshot(store: ReturnType<typeof createSnapshotStore>, name: string, component: () => HTMLElement, options?: {
+    update?: boolean;
+}): {
+    passed: boolean;
+    snapshot: string;
+    diff?: string;
+};
+/**
+ * Create a snapshot matcher that auto-generates names based on describe/test context.
+ * Provides a convenient API similar to Jest's `toMatchSnapshot()`.
+ *
+ * @param store - The snapshot store to use for saving/comparing
+ */
+declare function createSnapshotMatcher(store: ReturnType<typeof createSnapshotStore>): {
+    /** Assert current component output matches saved snapshot */
+    toMatchSnapshot: (component: () => HTMLElement, name?: string) => void;
+    /** Update all snapshots in this matcher */
+    updateAll: () => void;
+};
+
+/**
+ * Visual regression testing utilities for SibuJS.
+ * Provides structural comparison of component output for detecting UI regressions.
+ * In environments without a real browser, uses DOM structure and computed styles.
+ */
+interface VisualFingerprint {
+    /** Serialized DOM structure */
+    structure: string;
+    /** All text content */
+    textContent: string;
+    /** Count of elements by tag */
+    elementCounts: Record<string, number>;
+    /** All unique class names used */
+    classNames: string[];
+    /** All inline styles */
+    inlineStyles: string[];
+    /** Data attributes */
+    dataAttributes: Record<string, string>;
+    /** Computed hash of the fingerprint */
+    hash: string;
+}
+/**
+ * Capture a visual fingerprint of a component.
+ * Includes DOM structure, attributes, text content, and inline styles.
+ */
+declare function captureFingerprint(element: Element): VisualFingerprint;
+interface FingerprintChange {
+    type: "structure" | "text" | "class" | "style" | "data" | "elements";
+    description: string;
+}
+/**
+ * Compare two visual fingerprints and report differences.
+ */
+declare function compareFingerprints(baseline: VisualFingerprint, current: VisualFingerprint): {
+    match: boolean;
+    changes: FingerprintChange[];
+};
+/**
+ * Create a visual regression test suite.
+ * Manages baseline fingerprints and comparison.
+ */
+declare function createVisualSuite(): {
+    /** Capture and save a baseline for a component */
+    baseline: (name: string, element: Element) => void;
+    /** Compare current element against saved baseline */
+    check: (name: string, element: Element) => {
+        match: boolean;
+        changes: FingerprintChange[];
+    };
+    /** Update a baseline */
+    updateBaseline: (name: string, element: Element) => void;
+    /** List all baselines */
+    list: () => string[];
+    /** Clear all baselines */
+    clear: () => void;
+};
+
+/**
+ * render mounts a component into a test container and returns helpers.
+ */
+declare function render(component: () => HTMLElement): {
+    container: HTMLElement;
+    element: HTMLElement;
+    getByText: (text: string) => HTMLElement | null;
+    getByTestId: (testId: string) => HTMLElement | null;
+    getByRole: (role: string) => HTMLElement | null;
+    queryAll: (selector: string) => HTMLElement[];
+    unmount: () => void;
+};
+/**
+ * fireEvent dispatches a DOM event on an element.
+ */
+declare function fireEvent(element: HTMLElement, eventName: string, eventInit?: EventInit): boolean;
+declare namespace fireEvent {
+    var click: (element: HTMLElement) => boolean;
+    var input: (element: HTMLElement, value?: string) => boolean;
+    var change: (element: HTMLElement, value?: string) => boolean;
+    var submit: (element: HTMLElement) => boolean;
+    var keyDown: (element: HTMLElement, key: string, init?: KeyboardEventInit) => boolean;
+    var keyUp: (element: HTMLElement, key: string, init?: KeyboardEventInit) => boolean;
+    var focus: (element: HTMLElement) => void;
+    var blur: (element: HTMLElement) => void;
+}
+/**
+ * waitFor retries an assertion until it passes or times out.
+ */
+declare function waitFor(callback: () => void, options?: {
+    timeout?: number;
+    interval?: number;
+}): Promise<void>;
+/**
+ * mockRouter creates a mock router for testing route-dependent components.
+ */
+declare function mockRouter(initialPath?: string): {
+    currentPath: () => string;
+    navigate: (path: string) => void;
+    history: string[];
+};
+/**
+ * Creates a mock store for testing.
+ */
+declare function mockStore<T extends Record<string, unknown>>(initialState: T): {
+    getState: () => T;
+    setState: (patch: Partial<T>) => void;
+    reset: () => void;
+};
+
+export { type A11yCheckResult, type A11yViolation, type A11yViolationLevel, type FingerprintChange, type MockResponse, type MockRoute, type VisualFingerprint, assertA11y, assertDOMEquals, captureFingerprint, checkA11y, checkAriaAttributes, checkColorContrast, checkFormLabels, checkHeadingHierarchy, checkImageAlt, checkKeyboardAccess, checkLandmarks, checkLinksAndButtons, checkListSemantics, checkTabOrder, compareFingerprints, createCypressAdapter, createDOMSnapshot, createHttpMock, createJestAdapter, createPlaywrightAdapter, createSnapshotMatcher, createSnapshotStore, createTimerMock, createUniversalAdapter, createVisualSuite, fireEvent, matchSnapshot, mockRouter, mockStore, render, snapshotComponent, testComponent, waitFor };